View source for Template:Test case/doc

{{Documentation subpage}}
{{For|the legacy syntax version of this template|Template:Testcase}}
{{Lua|Module:Template test case}}
<!-- Please place categories where indicated at the bottom of this page and interwikis at Wikidata (see [[Wikipedia:Wikidata]]) -->

This template generates a test case for two or more templates. Each template is called with the same parameters, and the test case can be displayed in various different formats.

All parameters passed to this template are passed through to the test-case templates, with the exception of parameters starting with an underscore character ("_"), which are reserved for internal use.

If no templates are specified explicitly, the module uses the base page of the current page as the first template, and its /sandbox subpage as the second template. If only one template is specified explicitly, its /sandbox subpage is used as the second template.

== Usage ==

'''Basic syntax'''

<pre>
{{test case
| [param1] = [value1]
| [param2] = [value2]
| [param3] = [value3]
...
}}
</pre>

'''Common syntax'''

The following options will work with all different test case formats.

<pre>
{{test case
| _format      = 
| _output      = 
| _collapsible = 
| _resetRefs   = 
| _code        = 
| _showcode    = 

| _template  = 
| _template1 = 
| _heading1  = 
| _template2 = 
| _heading2  = 
| _template3 = 
| _heading3  = 
...

| [param1] = [value1]
| [param2] = [value2]
| [param3] = [value3]
...
}}
</pre>

Some test case formats accept additional parameters as well. See their sections for documentation.

== Common parameters ==

{| class="wikitable"
|-
! Parameter !! Description
|-
| <code>_format</code> || The format used to display the test cases. This can be "[[#Columns|columns]]", "[[#Rows and tablerows|rows]]", "[[#Rows and tablerows|tablerows]]", "[[#Inline|inline]]" or "[[#Default|default]]".
|-
| <code>_output</code> || Allows changes in how the template's output is displayed. The default output is displayed when the {{code|_output}} parameter is not specified or when it is set to any unsupported value. A [[WP:NOWIKI|nowiki]] version of the template's output is displayed when {{para|_output|nowiki}}; this is helpful when there are differences in the underlying [[Help:Wikitext|wikitext]] which are not visible in the default output. Both the default output and nowiki version are displayed when {{para|_output|nowiki+}}.
|-
| <code>_collapsible</code> || If set to "y" or "yes", the test case is made collapsible. The test case is collapsed and given a green heading if all the template outputs are the same. If any of the template outputs differ, the test case is expanded and given a yellow heading. See [[#Collapsible test cases]] for other parameters which only work when _collapsible is enabled.
|-
| <code>_template1</code>, <code>_template2</code>, <code>_template3</code>... || The names of the templates to be processed. The default of _template1 is the base page of the current page. If _template1 is specified, the default for _template2 is its /sandbox subpage; if not, the default for _template2 is the /sandbox subpage of the base page of the current page. Template names should be entered as you would use them in a normal template invocation, i.e. "3x", not "Template:3x". If you need to test a page in the main namespace you can use a colon prefix, i.e. ":''article name''".
|-
| <code>_template</code> || An alias for _template1. If both _template and _template1 are specified, _template will take precedence.
|-
| <code>_showtemplate1</code>, <code>_showtemplate2</code>, <code>_showtemplate3</code>... || If this is set to "no", then no output is shown for that template. This is useful if you only want to show the main template, or if you only want to show the sandbox template.
|-
| <code>_heading1</code>, <code>_heading2</code>, <code>_heading3</code>... || Custom headings for each of the templates.
|-
| <code>_showheader</code> || If this is set to "n" or "no", then no headers are shown.
|-
| <code>_before</code>, <code>_after</code> || Optional text to display before and after the output of each template.
|-
| <code>_resetRefs</code> || If set to "y" or "yes", any references generated by the templates tested are reset after each template is expanded.
|-
| <code>_showcode</code> || Show the template code used to make the test case. If an invocation is specified with the _code parameter, then that is used. Otherwise, an approximation is generated from the arguments. This approximation is not perfect - white space in named arguments is lost, and duplicate arguments are ignored - but it should be fine for template code that is input all on one line without spaces between parameters.
|-
| <code>_code</code> || Used to specify template code inside {{tag|nowiki}} tags. This is used with the _showcode option to display the template invocation while preserving white space. You must use the magic word "__TEMPLATENAME__" instead of the template name. For example: <code><nowiki>| _code = &lt;nowiki&gt;{{__TEMPLATENAME__|first|second|foo=bar}}&lt;/nowiki&gt;</nowiki></code>. If you find yourself using this option a lot, you may want to consider using {{tl|test case nowiki}}, which allows you to generate the entire test case from template code in nowiki tags, saving you from typing in all the arguments twice. <p>Note: due to the way nowiki tags work, the template treats the [[HTML entities]] &amp;lt;, &amp;gt; and &amp;quot; as if they were the literal characters &lt;, &gt; and &quot; when used with this parameter.</p>
|}

== <div id="Test case formats" ></div>Test case formats ==

=== <div id="Default" ></div>Default format ===

This format is used when '''{{code|_format}}''' is not specified or when '''{{para|_format|default}}'''. It does not have any extra parameters.

'''Example'''

{{test case|_template1=ombox|text=Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.}}

=== <div id="Columns" ></div>Columns format ===

Use '''{{para|_format|columns}}''' to arrange the test cases side by side in a table. This is useful for comparing long and thin templates such as infoboxes. It has the following extra parameters:

{| class="wikitable"
|-
! Parameter !! Description
|-
| <code>_class</code> || HTML classes for the table. Use {{para|_class|wikitable}} to format the table as a wikitable.
|-
| <code>_style</code> || Custom inline CSS for the table.
|-
| <code>_caption</code> || Custom caption for the table. The default is "Side by side comparison".
|-
| <code>_rowheader</code> || An extra heading for the row containing the templates.
|-
| <code>_heading0</code> || If _rowheader is supplied, this is an optional heading above it in the template row.
|}

'''Example'''

{{test case|_template1=ombox|_format=columns|text=Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.}}

=== <div id="Rows and tablerows" ></div>Rows and tablerows formats ===

Use '''{{para|_format|rows}}''' or '''{{para|_format|tablerows}}''' to arrange the test cases one above another in a table. These two formats differ in the placement of the headings: '''{{code|rows}}''' puts them above, whereas '''{{code|tablerows}}''' to the left of the template outputs. It has the following extra parameters:

{| class="wikitable"
|-
! Parameter !! Description
|-
| <code>_class</code> || HTML classes for the table. Use {{para|_class|wikitable}} to format the table as a wikitable.
|-
| <code>_style</code> || Custom inline CSS for the table.
|-
| <code>_caption</code> || Custom caption for the table.
|}

'''Example – rows'''

{{test case|_template1=ombox|_format=rows|text=Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.}}

'''Example – tablerows'''

{{test case|_template1=ombox|_format=tablerows|text=Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.}}

=== <div id="Inline" ></div>Inline format ===

Use '''{{Para|_format|inline}}''' for test cases that can be displayed entirely on one line. If used with templates that display on multiple lines it may produce unexpected results. This format creates a [[Help:Wikitext#Unordered lists|bulleted list]] by placing <code>*</code> before each line of output. It has the following extra parameters:

{| class="wikitable"
|-
! Parameter !! Description
|-
| <code>_addline</code> || Text to be added as last line in list, after the template output. 
|-
| <code>_prefix</code> || Character to replace <code>*</code> before each line of output. Using {{para|_prefix|#}} would display a [[Help:Wikitext#Ordered lists|numbered list]].
|}

Note: As this format starts with a bullet, a newline will always be inserted at the start of the template output due to [[phab:T14974|bug 14974]].

'''Examples''' (using [[Template:3x]])

Default:
{{test case|_format=inline|_template1=3x|Lorem ipsum }}

With '''{{para|_showcode|yes}}''':
{{test case|_format=inline|_showcode=yes|_template1=3x|Lorem ipsum }}

'''Example''' (using [[Template:Height]])

With '''{{para|_prefix|#}}''' and '''{{para|_addline}}''':
{{test case |_format=inline |_prefix=# |_showcode=yes |_template=Height |m=1.51 |_addline=<code><nowiki>{{Cvt|1.51|m|frac=2}}</nowiki></code> → {{Cvt|1.51|m|frac=2}} }}

== Output ==

The '''{{code|_output}}''' parameter allows changes in how the template's output is displayed. It should work with any of the [[#Test case formats|test case formats]]; the following examples use '''{{para|format|tablerows}}'''.

=== Default output ===

The default output is displayed when the '''{{code|_output}}''' parameter is not specified or when it is set to any unsupported value; this example uses '''{{para|_output|default}}'''.

{{test case|_format=tablerows|_output=XXX|_template1=URL|_template2=Official website|https://www.example.com|example.com}}

=== Nowiki output ===

A [[WP:NOWIKI|nowiki]] version of the template's output is displayed when '''{{para|_output|nowiki}}'''. This is helpful if there are differences in the underlying [[Help:Wikitext|wikitext]] which are not visible in the default output.

{{test case|_format=tablerows|_output=nowiki|_template1=URL|_template2=Official website|https://www.example.com|example.com}}

=== Nowiki+ output ===

Both the default output and nowiki version are displayed when '''{{para|_output|nowiki+}}'''.

{{test case|_format=tablerows|_output=nowiki+|_template1=URL|_template2=Official&nbsp;website|https://www.example.com|example.com}}

== <div id="Collapsible test cases" ></div>Collapsible test cases ==

If <code>_collapsible</code> is set to "y" or "yes", the test case is made collapsible. The test case is collapsed and given a green heading if all the template outputs are the same. If any of the template outputs differ, the test case is expanded and given a yellow heading. It has the following extra parameters:

{| class="wikitable"
|-
! Parameter !! Description
|-
| <code>_title</code> || Use {{para|_title}} to display a custom title for collapsible test cases.
|-
| <code>_titlecode</code> || Use {{para|_titlecode|yes}} to display the template's code as the title of a  collapsible test case.
|-
| <code>_notcollapsed</code> || If set to <code>y</code> or <code>yes</code>, the test case will always be expanded upon loading the page. If set to <code>n</code> or <code>no</code>, it will always be collapsed upon loading the page. This setting overrides the default functionality in which the test case is collapsed unless two or more outputs do not match.
|}

'''Examples'''

=== Default title ===

{{test case|_template1=ombox|_collapsible=yes|text=Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.}}

=== With _title ===

{{test case|_template1=ombox|_collapsible=yes|_format=columns|_title=Using the columns format|text=Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.}}

{{test case|_template1=ombox|_collapsible=yes|_format=rows|_title=Using the rows format|text=Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.}}

{{test case|_template1=ombox|_template2=tmbox|_collapsible=yes|_title=Example of differing output|text=Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.}}

=== With _titlecode=yes ===

This is useful for templates with a small number of parameters. It displays the template code in the title, eliminating the need for both '''{{para|_title}}''' and '''{{para|_showcode|yes}}'''. For actual tests implemented with '''{{para|_titlecode|yes}}''', see [[Template:URL/testcases]].

{{test case|_collapsible=yes|_titlecode=yes|_format=tablerows|_output=nowiki+|_template1=URL|www.example.com}}

=== With _notcollapsed=yes ===

If '''{{para|_notcollapsed|yes}}''', the test case will always be expanded upon loading the page. This setting overrides the default functionality in which the test case is collapsed unless two or more outputs do not match. The following example would normally be collapsed, as indicated by green background of title:

{{test case|_template1=ombox|_template2=ombox|_collapsible=yes|_notcollapsed=yes|_title=Example of same output|text=Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.}}

=== With _notcollapsed=no ===

If '''{{para|_notcollapsed|no}}''', the test case will always be collapsed upon loading the page. This setting overrides the default functionality in which the test case is collapsed unless two or more outputs do not match. The following would normally be expanded, as indicated by yellow background of title:

{{test case|_template1=ombox|_template2=tmbox|_collapsible=yes|_notcollapsed=no|_title=Example of differing output|text=Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.}}

== Additional examples ==

=== With _showcode ===

;Usage
<pre style="overflow:auto; background-color:#eee;">
{{test case|_template1=ombox|_showcode=yes|text=Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.}}
</pre>

;Output
{{test case|_template1=ombox|_showcode=yes|text=Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.}}

=== With _showcode, using a nowiki invocation via _code ===

;Usage
<pre style="overflow:auto; background-color:#eee;">
{{test case|_template1=ombox|_showcode=yes
|_code = 
&lt;nowiki&gt;{{__TEMPLATENAME__
| text = Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
}}&lt;/nowiki&gt;
|text=Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
}}
</pre>

;Output
{{test case|_template1=ombox|_showcode=yes
|_code = 
<nowiki>{{__TEMPLATENAME__
| text = Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
}}</nowiki>
|text=Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
}}

=== With _showcode and _collapsible ===

;Usage
<pre style="overflow:auto; background-color:#eee;">
{{test case|_template1=ombox|_showcode=yes|_collapsible=yes|text=Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.}}
</pre>

;Output
{{test case|_template1=ombox|_showcode=yes|_collapsible=yes|text=Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.}}

== Technical limitations ==

The template has the following known technical limitations:
* An error will be generated if processing the entire page takes more than 10 seconds. This is an intentional limit in the [[mw:Extension:Scribunto|Scribunto]] extension that runs [[Module:Template test case]], on which this template is based. If a test cases page takes more than 10 seconds to load, you may need to split it up into different pages.
* When generating the template code used with {{para|_showcode}} whitespace in named parameters is ignored, numbered parameters like {{para|1}} may be incorrectly displayed as positional parameters, and duplicate parameters are ignored. This is due to how template parameters are processed before they are passed to [[Module:Template test case]].
* When using a template invocation inside nowiki tags with the {{para|_code}} parameter, the [[HTML entities]] &amp;lt;, &amp;gt; and &amp;quot; are converted to the literal characters &lt;, &gt; and &quot;. This is due to the way nowiki tags work.
* For collapsible test cases, all text inside each extension tag (e.g. {{tag|ref|o}}, {{tag|references|o}}, {{tag|gallery|o}} or {{tag|nowiki|o}}) is treated as equal. These tags are converted to [[Help:Strip markers|strip markers]] before they are passed to the template, and all strip markers include a unique hexadecimal string. Even if strip markers were unstripped before being compared, the same wikitext would not be guaranteed to result in exactly the same unstripped code. So this module ignores the content of strip markers for the purposes of testing equality. This has the unwanted side effect that e.g. all {{tag|ref}} tags are treated as though they are equal, but should be adequate for most uses.

== See also ==

Templates invoking [[Module:Template test case]]:
* [[Template:Testcase rows]] – for a table of test cases arranged in rows
* [[Template:Testcase table]] – for a table of test cases arranged in columns
* [[Template:Inline test case]] – for test cases with small invocations and small output
* [[Template:Collapsible test case]] – for test cases collapsed by default if the results are the same
* [[Template:Test case nowiki]] – for test cases from template invocations enclosed in {{tag|nowiki}} tags
* [[Template:Nowiki template demo]] – for use in template documentation

<includeonly>{{Sandbox other||
<!-- Categories below this line, please; interwikis at Wikidata -->
[[Category:Template test cases| ]]
[[Category:Template namespace templates]]
}}</includeonly>