Wikimedia:Template sandbox and test cases

Template:Wikipedia how to

Templates are a very powerful feature of MediaWiki, but mistakes can be easily made, even by experienced users. Complex templates should therefore be accompanied by sandboxes and test cases to prevent bugs.

For what kind of templates

It is recommended to apply the test case pattern to templates using ParserFunctions that can generate very different looking output, such as the ones that take many parameters, or the ones that have many branches of the #switch operator.

For navigational boxes, of which the outputs are almost identical on each transcluding page, the benefit may not outweigh the time and effort.

Any template that is transcluded in thousands of pages should of course be tested before an edit is made.

How to create /sandbox and /testcases subpages

Suppose your template is named Template:X. Create a subpage with the name Template:X/sandbox. If the main template is using the {{documentation}} template, you can do this from a link at the bottom of the blue documentation box. Or you can type it into the search box, or directly into the URL bar of your browser. Note that "/sandbox" is all lowercase.
Copy the entire contents of the main template, including <noinclude> tags and the {{documentation}} template if present, paste it into the edit window of the /sandbox subpage, and save the page. Your edit summary should be something like "create sandbox version of Template:X".
- Note: if you use the "mirror" link at the bottom of the blue documentation box, tags like <noinclude>, and their contents, will be missing. It's best just to copy and paste manually.
Create another subpage with the name Template:X/testcases. This page is only linked from the bottom of the blue documentation box if it actually exists, so to create it you will need to create it by typing the page name into the search box or into the URL bar of your browser. Again, note that "/testcases" is all lowercase, and all one word.
Put the {{testcases notice}} template at the top of the page, add some test cases (see below), and save the page.
Add your experimental code to Template:X/sandbox. To test your code, save the page, and go to the /testcases page. Often you will need to purge the /testcases page to see the updated results; there is a link to do that included in the {{testcases notice}} template. After you've purged the page, compare the results for the main template with the results from the sandbox, and if everything looks okay, you can update the main template. However, be wary of missing test cases and of code that can only be tested in certain namespaces or on certain pages.

How to update existing /sandbox and /testcases subpages

To make a change to a template which already has /sandbox and /testcases subpages, the process is similar to the above.

The /sandbox may not have the latest version of the template code in it, so before you make a change, you need to synchronize it with the main template. Copy the entire contents of the main template to the /sandbox subpage, and save the page. Your edit summary should be something like "synchronize with the main template", or simply "sync".
Have fun editing the sandbox. When you have some code you want to test, save the page.
If you have added any new features or changed any parameters, you should add new test cases to the /testcases subpage so that they can be tested. Also, bear in mind that the existing test cases may not be complete. It's okay to rewrite the test cases if they aren't useful for what you're trying to achieve, but also consider editors who may use the test cases after you.
Purge the /testcases page to update the results.
Verify that the test case results are correct. If everything looks good, copy the code from the sandbox to the main template.

Adding test cases

On the /testcases page, there should be one test case for each different behaviour of your template. For example, if your template outputs a banner message, and if the parameter |italic=yes makes that message italicized, you should add one test case for the normal message and one for the italicized message. If that template has another parameter, |date=, where the user inserts the date, then there should be a third test case for that. You should try and be thorough and make cases for all the ways users might use your template; however, it is often impractical to add test cases for every single parameter combination, so you should choose the most relevant ones wisely.

There are quite a few different styles of test case that you can use. Which one you choose depends on the nature of the template you are working on. For example, for short template output that fits on one line, it can be useful to put the test cases inside a wikitable, and for long and thin templates such as infoboxes, it is often best to display them side by side by using {{testcase table}}.

Manual formatting

Manually formatting gives you a great deal of flexibility, but care must be taken to ensure that all the template parameters are entered correctly. An error in one of the test cases is often harder to find than an error in the template itself.

Basic format

This format works well for banner templates and for lengthy text, e.g. citations. Note that you can format these kinds of test automatically using Template:Test case and other similar templates.

== Descriptive title ==
 
* <code><nowiki>{{template|param1=value1|param2=value2}}</nowiki></code>
 
'''Main'''
 
{{template|param1=value1|param2=value2}}
 
'''Sandbox'''
 
{{template/sandbox|param1=value1|param2=value2}}

Each value of template, param1, value1 etc. must be identical.

For templates that use the "float" CSS attribute, you will need to use the {{clear}} template to stop the results from bunching together:

== Descriptive title ==
 
* <code><nowiki>{{template|param1=value1|param2=value2}}</nowiki></code>
 
'''Main'''
 
{{template|param1=value1|param2=value2}}
 
{{clear}}
 
'''Sandbox'''
 
{{template/sandbox|param1=value1|param2=value2}}
 
{{clear}}

Wikitable

Using a wikitable to format test cases is often useful for templates with short output that need to be lined up correctly.

Start the table like this:

{| class="wikitable"
|-
! Code
! Main
! Sandbox

Each new test case can be added like this:

|-
| <code><nowiki>{{template|param1=value1|param2=value2}}</nowiki></code>
| {{template|param1=value1|param2=value2}}
| {{template/sandbox|param1=value1|param2=value2}}

Finish the table like this:

|}

Automatic formatting

There are various templates that help you to format test cases automatically. With these templates, parameters and values are only entered once, but are still tested for both the main template and the sandbox templates. This avoids the problem of errors in test case parameters, and makes it easier to maintain test case pages. These templates include:

Template:Test case, for general-purpose test cases
Template:Testcase table, for long and thin templates such as infoboxes
Template:Inline test case, for long and thin templates such as infoboxes
Template:Test case nowiki, for templates with complex invocations
Template:Collapsible test case, to collapse test cases when the main and sandbox templates produce the same result

Note that all of these templates can produce collapsible test cases, but Template:Collapsible test case has this feature turned on by default. For detailed documentation, see the individual template pages.

Tests that can't be made on /testcases pages

Some template features can't be tested on /testcases pages. For example, a template may only output certain text when in the main namespace, or it may output different things when it is used on a base page and when it is used on a subpage. For these kinds of tests, you can use the "Preview page with this template" feature that you can see underneath the edit window on template pages. To make this feature even more powerful, you can install User:Jackmcbarn/advancedtemplatesandbox.js, which makes it usable in any namespace, and lets you specify the title of the template as well as the page to preview it on. This means that you can edit the sandbox template, but preview pages as if you were actually editing the main template.

If you can think of any tests that can't be made on the /testcases page, it may be helpful to leave a note at the top of the /testcases page outlining what else needs testing, so that future editors of that template are also aware.

Examples

Basic format: Template:Quote, Template:Quote/sandbox, Template:Quote/testcases, and Template:Unicode_chart/footer/sandbox
Wikitable: Template:Diff, Template:Diff/sandbox and Template:Diff/testcases
Testcase table: Template:Infobox settlement, Template:Infobox settlement/sandbox and Template:Infobox settlement/testcases