Editing Module:Convert/tester/doc

This module runs unit tests to compare template output with expected text. In addition, the module can output the results of expanding templates.

While intended for testing [[Module:Convert]], the tester should be useful with other templates that require many tests using a simple format for the test input.

==Testcases example==
*[[Module:Convert/sandbox/testcases]] • templates to be tested, with expected outputs
*[[Module talk:Convert/sandbox/testcases]] • view test results

It is not necessary to save the testcases page before viewing test results. For example, [[Module:Convert/sandbox/testcases]] could be edited to change the tests. While still editing that page, paste {{nowrap|"<code>Module talk:Convert/sandbox/testcases</code>"}} (without quotes) into the page title box under "Preview page with this template", then click "Show preview".

The testcases talk page (for example, [[Module talk:Convert/sandbox/testcases]]) contains:
<pre>
{{#invoke:convert/sandbox/testcases|run_tests}}
</pre>

The testcases module page (for example, [[Module:Convert/sandbox/testcases]]) may contain:
<syntaxhighlight lang=lua>
local tests = [==[

A template to be tested must be at the start of a line.
Lines which do not start with a template are ignored.
{{convert/sandbox|1|acre|lk=on}}            1 [[acre]] (0.40&amp;nbsp;[[hectare|ha]])
{{convert/sandbox|1|m2|acres|lk=on}}        1 [[square metre]] (0.00025 [[acre]]s)
{{convert/sandbox|0.16|/l|2|disp=table}}    align="right"|0.16\n|align="right"|0.61

]==]

local p = require('Module:Convert/tester')
p.tests = tests
return p
</syntaxhighlight>

If wanted, the tests can be run using a template different from the one specified in the tests. For example, the following would run the tests from [[Module:Convert/sandbox/testcases]], but would change the name of each template found on that page to "<code>convert/sandbox2</code>".
<pre>
{{#invoke:convert/sandbox/testcases|run_tests|template=convert/sandbox2}}
</pre>

==Format==
Tests are extracted from a multiline string. Any line that does not start with a template is ignored. Each processed line starts with a template, and is followed by whitespace, then the wikitext which should result from expanding the template.

The expected output must be entered in a single line. If the template outputs multiple lines, those lines must be joined with "\n" (two characters—backslash&nbsp;<code>n</code>).

The templates do not have to be the same, for example, the following tests would work:
<syntaxhighlight lang=lua>
local tests = [==[

{{convert|12|m}}                            12 metres (39&amp;nbsp;ft)
{{convert/sandbox|12|m}}                    12 metres (39&amp;nbsp;ft)
{{age|1989|7|23|2003|7|14}}                 13
{{age in days|2007|5|24|2008|4|23}}         335

]==]
</syntaxhighlight>

In the results, the status column shows "Pass" if the output from the template exactly matches the expected text. If there is no expected text, the template output is shown in the Actual column with a blank status. If the given expected text differs from the template output, the template output is shown in the Actual column with status "Fail", and the number of fails is shown at the top of the page. Searching the page for "Fail" will find each problem. Any "Fail" result is followed by a row showing the nowiki actual and expected wikitext.

==Specifying tests==
If using a testcases module (as in the [[#Testcases example|above example]]), the test text is assigned to <code>p.tests</code> before executing <code>run_tests</code>.

Alternatively, the test text can be read from any page, or from any section on any page. For example, the following wikitext could be entered in a sandbox:
<pre>
&#61;= Mixed tests ==
&lt;pre>
{{convert|12|m}}                            12 metres (39&nbsp;ft)
{{convert/sandbox|0.16|/l|2|disp=table}}    align="right"|0.16\n|align="right"|0.61
{{age in days|2007|5|24|2008|4|23}}         335
--- The following line is incorrect to demonstrate a "fail".
{{convert|12|m|lk=on}}                      12 [[meter|metres]] (39&nbsp;[[Foot|ft]])
The following line demonstrates the result when no expected text is provided.
{{convert/sandbox|1|-|5|in|mm|lk=on}}
&lt;/pre>
</pre>

Given the above, the tests can be run as shown in the [[#Running tests from any page|following section]].

Instead of specifying the tests with a multiline string, it is possible to assign a table to <code>p.tests</code> as shown in the following testcases module.
<syntaxhighlight lang=lua>
local tests = {
    -- Each test item is of form { template, expected }.
    { '{{convert|12|m}}', '12 metres (39&nbsp;ft)' },
    { '{{convert/sandbox|0.16|/l|2|disp=table}}', 'align="right"|0.16\n|align="right"|0.61' },
    { '{{age in days|2007|5|24|2008|4|23}}', '335' },
    { '{{convert|12|m|lk=on}}', '12 [[meter|metres]] (39&nbsp;[[Foot|ft]])' },
    { '{{convert/sandbox|1|-|5|in|mm|lk=on}}' },
}

local p = require('Module:Convert/tester')
p.tests = tests
return p
</syntaxhighlight>

This example provides the same results as the multiline string at "Mixed tests" above.

==Running tests from any page==
Entering either of the following lines of wikitext in a sandbox or talk page would run the tests found at the specified location. The first line would show all tests on page "Template talk:Example", while the second would show only those tests on that page that are in the "Mixed tests" section.
<pre>
{{#invoke:convert/tester|run_tests|page=Template talk:Example}}
{{#invoke:convert/tester|run_tests|page=Template talk:Example|section=Mixed tests}}
</pre>

As a demonstration, the following line is used to produce the table shown below, including the comment that starts with three dashes.
<pre>
{{#invoke:convert/tester|run_tests|page=Module:Convert/tester/doc|section=Specifying tests|show=all}}
</pre>

{{#invoke:convert/tester|run_tests|page=Module:Convert/tester/doc|section=Specifying tests|show=all}}

==Making expected results==
Function <code>make_tests</code> can be used to create tests in the format expected by <code>run_tests</code>. For example, previewing either of the following in a sandbox would show the results from expanding each template found on the specified page.
<pre>
{{#invoke:convert/tester|make_tests|page=Template talk:Example}}
{{#invoke:convert/tester|make_tests|page=Template talk:Example|show=all}}
</pre>

When using <code>make_tests</code>, any expected results in the input are ignored. Instead, the module shows each template and its actual output as plain text which can be copied to make a testcases page. The templates to be processed can be specified by setting <code>p.tests</code> or by specifying a page with an optional section.

If <code>|show=all</code> is included, any non-template lines are included in the result. The output could then be copied and used to replace the page with the tests in order to update the expected text for each template, but without changing non-template lines.

As a demonstration, the following line is used to produce the text shown below.
<pre>
{{#invoke:convert/tester|make_tests|page=Module:Convert/tester/doc|section=Specifying tests}}
</pre>

{{#invoke:convert/tester|make_tests|page=Module:Convert/tester/doc|section=Specifying tests}}

==Using show=all==
The <code>|show=all</code> option can be used with <code>make_tests</code> and with <code>run_tests</code>.

An example using <code>make_tests</code> is shown in the [[#Making expected results|previous section]].

Using <code>|show=all</code> with <code>run_tests</code> allows comment lines to be displayed in the output table—not ''all'' lines are shown, only those that start with three dashes. For example, the testcases may include the following.
<pre>
Added 12 January 2014.
--- The following tests check the widget option.
{{example|1|2|widget=on}}          ...(expected output)...
</pre>

The table produced by <code>run_tests</code> would show "The following tests check the widget option." as a comment line, but only if <code>|show=all</code> is used. Comments have a distinctive background color, but also show "Cmnt" in the status column so they can be found by searching.

==Comparing a module with its sandbox==
When viewing a module, the documentation page is displayed; if the module has a sandbox, the documentation includes "Editors can experiment in this module's sandbox" with a link to [[WP:DIFF|diff]] the module and its sandbox.

The tester module provides a <code>compare</code> function which can check a series of modules, and compare each with its sandbox. A table is displayed showing whether the content is different, with a diff link.

For example, the following wikitext could be used.
<pre>
{{#invoke:convert/tester|compare|Example|Example/data}}
</pre>

The names "Example" and "Example/data" do not include a colon (<code>:</code>), so "Module:" is assumed. The command compares '''Module:Example''' with '''Module:Example/sandbox''', and '''Module:Example/data''' with '''Module:Example/data/sandbox'''.

It is also possible for a module to define pairs of page titles in <code>p.pairs</code> (a table), and to use the tester module to generate a table for each pair of titles.

As a convenience, certain keywords are defined. If a keyword is recognized, the list of pairs comes from the module rather than the parameters. For example, the following uses the "convert" keyword to get the list of pairs of pages related to Module:Convert.
<pre>
{{#invoke:convert/tester|compare|convert}}
</pre>

The following text is a sample showing output that may result from the above.
*[[Module:Convert]] • [[Module:Convert/sandbox]] • <span style="color:darkred;">different</span> (<span class="plainlinks">[https://en.wikipedia.org/w/index.php?title=Special%3AComparePages&page1=Module%3AConvert&page2=Module%3AConvert%2Fsandbox diff]</span>)
*[[Module:Convert/data]] • [[Module:Convert/data/sandbox]] • <span style="color:green;">same content</span>
*[[Module:Convert/text]] • [[Module:Convert/text/sandbox]] • <span style="color:darkred;">different</span> (<span class="plainlinks">[https://en.wikipedia.org/w/index.php?title=Special%3AComparePages&page1=Module%3AConvert%2Ftext&page2=Module%3AConvert%2Ftext%2Fsandbox diff]</span>)
*[[Module:Convert/extra]] • [[Module:Convert/extra/sandbox]] • <span style="color:darkred;">different</span> (<span class="plainlinks">[https://en.wikipedia.org/w/index.php?title=Special%3AComparePages&page1=Module%3AConvert%2Fextra&page2=Module%3AConvert%2Fextra%2Fsandbox diff]</span>)

By default, each output line is prefixed with '<code>*</code>' to give a bulleted list. An alternative prefix can be specified with the <code>prefix</code> parameter. For example, the following gives an indented bulleted list.
<pre>
{{#invoke:convert/tester|compare|convert|prefix=:*}}
</pre>

<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox||
[[Category:Modules for test tools]]
[[Category:Modules that check for strip markers‎]]
}}</includeonly><noinclude>
[[Category:Module documentation pages]]
</noinclude>