模板:Test case/doc

  关于the legacy syntax version of this template，请见“Template:Testcase”。

这个模板生成两个或更多模板的测试用例。每个模板都使用相同的参数调用，测试用例可以以各种不同的格式显示。

传递给这个模板的所有参数都会传递到测试用例模板，除了以下划线字符（"_"）开头的参数，这些参数被保留供内部使用。

如果没有显式指定模板，模块将使用当前页面的基本页面作为第一个模板，以及其/sandbox子页面作为第二个模板。如果只显式指定了一个模板，则使用其/sandbox子页面作为第二个模板。

Usage

Basic syntax

{{test case
| [param1] = [value1]
| [param2] = [value2]
| [param3] = [value3]
...
}}

Common syntax

以下选项适用于所有不同的测试用例格式。

{{test case
| _format      = 
| _output      = 
| _collapsible = 
| _resetRefs   = 
| _code        = 
| _showcode    = 

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

| [param1] = [value1]
| [param2] = [value2]
| [param3] = [value3]
...
}}

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

Common parameters

Parameter	Description
_format	The format used to display the test cases. This can be "columns", "rows", "tablerows", "inline" or "default".
_output	Allows changes in how the template's output is displayed. The default output is displayed when the _output parameter is not specified or when it is set to any unsupported value. A nowiki version of the template's output is displayed when |_output=nowiki; this is helpful when there are differences in the underlying wikitext which are not visible in the default output. Both the default output and nowiki version are displayed when |_output=nowiki+.
_collapsible	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.
_template1, _template2, _template3...	要处理的模板的名称。默认情况下，_template1 是当前页面的基本页面。如果指定了 _template1，则 _template2 的默认值是其 /sandbox 子页面；如果没有指定 _template1，则 _template2 的默认值是当前页面的基本页面的 /sandbox 子页面。模板名称应该按照在正常模板调用中使用的方式输入，即"3x"，而不是"Template:3x"。如果需要测试主名称空间中的页面，可以使用冒号前缀，即":文章名称"。
_template	作为 _template1 的别名。如果同时指定了 _template 和 _template1，则 _template 会优先使用。
_showtemplate1, _showtemplate2, _showtemplate3...	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.
_heading1, _heading2, _heading3...	Custom headings for each of the templates.
_showheader	If this is set to "n" or "no", then no headers are shown.
_before, _after	Optional text to display before and after the output of each template.
_resetRefs	If set to "y" or "yes", any references generated by the templates tested are reset after each template is expanded.
_showcode	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	用于在 <nowiki>...</nowiki> 标签内指定模板代码。这与 _showcode 选项一起使用，以显示模板调用并保留空格。您必须使用魔术词 "__TEMPLATENAME__" 而不是模板名称。例如：| _code = <nowiki>{{__TEMPLATENAME__|first|second|foo=bar}}</nowiki>。如果您发现自己经常使用此选项，可以考虑使用 {{test case nowiki}}，它允许您从 nowiki 标签中的模板代码生成整个测试用例，避免您两次键入所有参数。注意：由于 nowiki 标签的工作方式，当与此参数一起使用时，模板将把 HTML 实体 &lt;、&gt; 和 &quot; 视为文字字符 <、> 和 "。

Test case formats

Default format

当未指定 _format 或指定 |_format=default 时使用此格式。它不包含任何额外的参数。

Example

{{ombox}}

{{ombox/sandbox}}

Columns format

使用 |_format=columns 将测试用例以表格形式并排放置。这对于比较长而窄的模板，如信息框，非常有用。它具有以下额外的参数：

参数	描述
_class	表格的HTML类。使用 |_class=wikitable 将表格格式化为 wikitable。
_style	表格的自定义内联 CSS。
_caption	表格的自定义标题。默认为 "Side by side comparison"。
_rowheader	包含模板的行的额外标题。
_heading0	如果提供了 _rowheader，则是模板行中它上方的可选标题。

示例

左右对比

{{ombox}}	{{ombox/sandbox}}

Rows and tablerows formats

使用 |_format=rows 或 |_format=tablerows 将测试用例以表格形式一个在另一个上方排列。这两种格式在标题的放置上有所不同：rows 将它们放在上方，而tablerows 将它们放在模板输出的左侧。它具有以下额外的参数：

参数	描述
_class	表格的HTML类。使用 |_class=wikitable 以将表格格式化为wikitable。
_style	表格的自定义内联CSS。
_caption	表格的自定义标题。

Example – rows

{{ombox}}

{{ombox/sandbox}}

Example – tablerows

{{ombox}}	→
{{ombox/sandbox}}	→

Inline format

使用 |_format=inline 可以将测试用例完全显示在一行上。如果与显示多行的模板一起使用，可能会产生意外的结果。该格式通过在每行输出前放置 * 来创建一个项目符号列表。它具有以下额外的参数：

参数	描述
_addline	在列表中，模板输出后要添加的文本。
_prefix	替换每行输出前的 * 的字符。使用 |_prefix=# 将显示一个编号列表。

注意：由于 bug 14974 的原因，由于这个格式以一个项目符号开始，模板输出的开头将始终插入一个换行符。

• • 示例**（使用Template:3x)

默认:

• Lorem ipsum Lorem ipsum Lorem ipsum
• Lorem ipsum Lorem ipsum Lorem ipsum

使用|_showcode=yes：

• {{3x|Lorem ipsum }} → Lorem ipsum Lorem ipsum Lorem ipsum
• {{3x/sandbox|Lorem ipsum }} → Lorem ipsum Lorem ipsum Lorem ipsum

• • 示例**（使用Template:Height)

使用|_prefix=#和|_addline=：

1. {{Height|m=1.51}} → 1.51米（4英尺11¹⁄₂英寸）
2. {{Height/sandbox|m=1.51}} → 1.51米（4英尺11¹⁄₂英寸）
3. {{Cvt|1.51|m|frac=2}} → 1.51米（4英尺11¹⁄₂英寸）

输出

_output 参数允许更改模板输出的显示方式。它应该适用于任何测试用例格式；以下示例使用|format=tablerows。

默认输出

默认输出在未指定_output参数或将其设置为任何不受支持的值时显示；此示例使用|_output=default。

{{URL}}	→	example.com
{{Official website}}	→	example.com

Nowiki 输出

当使用|_output=nowiki时，显示模板输出的nowiki版本。如果在默认输出中看不到的底层wikitext存在差异，这将非常有帮助。

{{URL}}	→	<span class="url">[https://www.example.com example.com]</span>
{{Official website}}	→	<span class="official-website"><span class="url">[https://www.example.com example.com]</span></span>

Nowiki+ 输出

当使用|_output=nowiki+时，同时显示默认输出和nowiki版本。

{{URL}}	→	example.com <span class="url">[https://www.example.com example.com]</span>
{{Official website}}	→	example.com <span class="official-website"><span class="url">[https://www.example.com example.com]</span></span>

Collapsible test cases

如果 _collapsible 设置为 "y" 或 "yes"，则测试用例将变为可折叠。如果所有模板输出相同，测试用例会折叠并显示一个绿色标题。如果任何模板输出不同，测试用例将展开并显示一个黄色标题。它具有以下额外的参数：

参数	描述
_title	使用 |_title= 显示可折叠测试用例的自定义标题。
_titlecode	使用 |_titlecode=yes 将模板代码显示为可折叠测试用例的标题。
_notcollapsed	如果设置为 y 或 yes，在加载页面时测试用例将始终展开。如果设置为 n 或 no，在加载页面时测试用例将始终折叠。此设置覆盖默认功能，即除非两个或更多输出不匹配，否则测试用例将被折叠。

Examples

Default title

{{ombox}}

{{ombox}}

{{ombox/sandbox}}

With _title

Using the columns format

左右对比

{{ombox}}	{{ombox/sandbox}}

Using the rows format

{{ombox}}

{{ombox/sandbox}}

Example of differing output

{{ombox}}

{{tmbox}}

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 |_title= and |_showcode=yes. For actual tests implemented with |_titlecode=yes, see Template:URL/testcases.

{{URL|www.example.com}}

{{URL}}	→	www.example.com <span class="url">[http://www.example.com www<wbr/>.example<wbr/>.com]</span>
{{URL/sandbox}}	→	www.example.com <span class="url">[http://www.example.com www<wbr/>.example<wbr/>.com]</span>

With _notcollapsed=yes

If |_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:

Example of same output

{{ombox}}

{{ombox}}

With _notcollapsed=no

If |_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:

Example of differing output

{{ombox}}

{{tmbox}}

附加示例

使用 _showcode

用法

{{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.}}

输出

{{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.}}

{{ombox}}

{{ombox/sandbox}}

使用 _showcode，通过 _code 使用 nowiki 调用

用法

{{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.
}}

输出

{{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.
}}

{{ombox}}

{{ombox/sandbox}}

使用 _showcode 和 _collapsible

用法

{{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.}}

输出

{{ombox}}

{{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.}}

{{ombox}}

{{ombox/sandbox}}

Technical limitations

该模板具有以下已知的技术限制：

• 如果处理整个页面的时间超过10秒，将生成错误。这是基于 Module:Template test case的Scribunto扩展中的一个故意设置的限制。如果一个测试用例页面加载时间超过10秒，可能需要将其拆分为不同的页面。

• 在生成与 |_showcode=一起使用的模板代码时，命名参数中的空格被忽略，而像|1=这样的编号参数可能会被错误地显示为位置参数，重复的参数也会被忽略。这是因为模板参数在传递给Module:Template test case之前的处理方式。
• When using a template invocation inside nowiki tags with the |_code= parameter, the HTML entities &lt;, &gt; and &quot; are converted to the literal characters <, > and ". This is due to the way nowiki tags work.
• For collapsible test cases, all text inside each extension tag (e.g. <ref>, <references>, <gallery> or <nowiki>) is treated as equal. These tags are converted to 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 <ref>...</ref> tags are treated as though they are equal, but should be adequate for most uses.

参见

调用Module:Template test case的模板：

• Template:Testcase rows – 以行形式排列的测试用例表
• Template:Testcase table – 以列形式排列的测试用例表
• Template:Inline test case – 用于具有小调用和小输出的测试用例
• Template:Collapsible test case – 如果结果相同，则默认折叠的测试用例
• Template:Test case nowiki – 用于在<nowiki>...</nowiki>标签中封装的模板调用的测试用例
• Template:Nowiki template demo – 用于模板文档中