Template:Test case/doc
This page is a template. It contains some standardized, often used text, which can be transcluded inside other pages. As this template is widely used in our wiki, it may be protected in which case only staff members can change it. Use the discussion page to propose enhancements or fixes, or to voice your opinion.
This template is used to illustrate the proper (and maybe improper) usage of a template and its parameters on the template's /testcases subpage. It is a replacement for the {{Testcase}} template that avoids table wiki markup. (Illustrating template usage inside a table is problematic because the pipe character, |, tends to get interpreted as table markup in that context.)
If used to show incorrect usage, it's probably a good idea to collect those cases under a section heading like ===Incorrect===. (See, for example, the documentation of {{Package}}.)
Parameters
| Parameter name | Required? | Default value | Description |
|---|---|---|---|
title |
Yes | (n/a) | Brief description of the testcase (e.g., "One anonymous parameter") |
Anonymous parameter 1 |
Yes | (n/a) | Example wikicode (template call) inside a <nowiki> element.
|
Anonymous parameter 2 |
Yes | (n/a) | Same wikicode without <nowiki>.
|
Anonymous parameter 3 |
Yes | (n/a) | Same wikicode without <nowiki>, using "/sandbox" after the template name.
|
error |
No | (n/a) | Describes the error being illustrated in a test case showing incorrect usage. |
code |
No | (n/a) | Can be set to pre to allow for multiline examples.
|
background-color |
No | (n/a) | Background color in the title bar (default explained below). |
text-color |
No | white |
Text color in the title bar. |
While omitting the third anonymous parameter does not give an error, it would not allow editors to see how the sandbox version of the template compares to the main version. Please use all three parameters, even if there is currently no sandbox version of the template being documented.
The default value of background-color is usually #54487A, which matches the purple color scheme used throughout the wiki). However, if the parameter error is set to any string, then the default background color is #323, a purplish black, as seen in the testcases below.
The value of error is displayed in parentheses after title in the title bar, so it should be descriptive (not, for example, the word yes). If you have no better description of the error being illustrated, you can just use, for example, error=error.
Avoid including links (or using templates that provide links) in the
title parameter. The colors used by this template make such links very hard to see. (The background color can be changed using background, but this should be avoided for the sake of consistency. Note that the text-color parameter would not affect the color of a link.)Usage
Typical:
{{Test case
|title=Descriptive title
|<nowiki>{{Template call}}</nowiki>
| {{Template call}}
|{{Template/sandbox call}}
}}
{{Test case
|title=Descriptive title
|error=Brief description of error
|<nowiki>{{Template call}}</nowiki>
| {{Template call}}
|{{Template/sandbox call}}
}}
All parameters:
{{Test case
|title=
|error=
|code=pre
|background-color=
|text-color=
|<nowiki>{{}}</nowiki>
| {{}}
|{{/sandbox}}
}}
See the template's testcases:
Illustrating correct usage
These cases show how this template could be used to document proper use of the template {{Package}}.
The wikicode:
{{Test case
|title=One unnamed parameter
|<nowiki>{{Package|sys-apps/portage}}</nowiki>
| {{Package|sys-apps/portage}}
|{{Package/sandbox|sys-apps/portage}}
}}
Results in:
{{Package|sys-apps/portage}}
Using the sandbox version (Test case/sandbox):
{{Test case/sandbox
|title=One unnamed parameter
|<nowiki>{{Package|sys-apps/portage}}</nowiki>
| {{Package|sys-apps/portage}}
|{{Package/sandbox|sys-apps/portage}}
}}
Results in:
{{Package|sys-apps/portage}}
Illustrating incorrect usage
These cases show how this template could be used to document improper use of the template {{Package}}.
The wikicode:
{{Test case
|title=No parameter
|error=error message
|<nowiki>{{Package}}</nowiki>
| {{Package}}
|{{Package/sandbox}}
}}
Results in:
{{Package}}
1 parameter.1 parameter.Using the sandbox version (Test case/sandbox):
{{Test case/sandbox
|title=No parameter
|error=error message
|<nowiki>{{Package}}</nowiki>
| {{Package}}
|{{Package/sandbox}}
}}
Results in:
{{Package}}
1 parameter.1 parameter.Cases with multiline wikicode
Some templates are best illustrated with multiline sample wikicode (because that's how they are best used in practice). In such cases, the value of the first anonymous parameter will contain newlines. Here are some examples showing what this looks like. They show how the template {{InfoBox stack}} might be documented.
Notice how the newlines between the <nowiki> and </nowiki> tags have been turned into spaces in the resulting "Wiki code". This might be acceptable in some cases but not in others.
{{Clear}} is used here to fix formatting problems that arise when a test case involves right-floated content.
The wikicode:
{{Test case
|title=One unnamed parameter
|<nowiki>{{InfoBox stack
| {{InfoBox homepage|http://www.samba.org|header=true}}
}}</nowiki>
|{{InfoBox stack
| {{InfoBox homepage|http://www.samba.org|header=true}}
}}{{Clear}}
|{{InfoBox stack/sandbox
| {{InfoBox homepage|http://www.samba.org|header=true}}
}}{{Clear}}
}}
Results in:
Using the sandbox version (Test case/sandbox):
{{Test case/sandbox
|title=One unnamed parameter
|<nowiki>{{InfoBox stack
| {{InfoBox homepage|http://www.samba.org|header=true}}
}}</nowiki>
|{{InfoBox stack
| {{InfoBox homepage|http://www.samba.org|header=true}}
}}{{Clear}}
|{{InfoBox stack/sandbox
| {{InfoBox homepage|http://www.samba.org|header=true}}
}}{{Clear}}
}}
Results in:
Using code=pre
Newlines in the first anonymous parameter can be preserved if the code=pre is used, as in the following example that is otherwise identical to the previous one.
Notice that the resulting "Wiki code" is shown as a block of preformatted text (because the usual <code> element has been turned into a <pre> element). This is generally preferable to having the newlines replaced by spaces.
The wikicode:
{{Test case
|title=One unnamed parameter
|code=pre
|<nowiki>{{InfoBox stack
| {{InfoBox homepage|http://www.samba.org|header=true}}
}}</nowiki>
|{{InfoBox stack
| {{InfoBox homepage|http://www.samba.org|header=true}}
}}{{Clear}}
|{{InfoBox stack/sandbox
| {{InfoBox homepage|http://www.samba.org|header=true}}
}}{{Clear}}
}}
Results in:
Using the sandbox version (Test case/sandbox):
{{Test case/sandbox
|title=One unnamed parameter
|code=pre
|<nowiki>{{InfoBox stack
| {{InfoBox homepage|http://www.samba.org|header=true}}
}}</nowiki>
|{{InfoBox stack
| {{InfoBox homepage|http://www.samba.org|header=true}}
}}{{Clear}}
|{{InfoBox stack/sandbox
| {{InfoBox homepage|http://www.samba.org|header=true}}
}}{{Clear}}
}}
Results in:
See also
- Help:Template sandbox and test cases
- {{Testcase}} – the original template that this one was based on
- {{Test case note}} – can be used to append an explanatory note after a test case