Help:Template sandbox and test cases

This article needs to be updated according to the standards found in the Guidelines.

Templates are a very powerful feature of MediaWiki, but mistakes can be easily made, even by experienced users. All templates should therefore be accompanied by sandboxes and test cases to prevent bugs. Testcases are also transcluded in the template's documentation to showcase the usage of the template.

These instructions assume you already have a template created along with its documentation subpage. If you haven't done this yet, see Help:Templates and especially Help:Templates#Adding documentation and categories.

How to create /sandbox subpages

Follow these steps to create a template sandbox.

1. Suppose your template is named Template:X. Create a /sandbox subpage by clicking on the appropriate "create" link in the Note box under the documentation. The subpage will have the name Template:X/sandbox and be preloaded with some default contents (the preloading only happens when the subpage is created through the "create" link). Once the subpage is present, the Note box will automatically provide a link to it. Note that "/sandbox" is spelled in all lower-case.
2. Copy only the active code (everything that is not surrounded by <noinclude>) from your Template:X to Template:X/sandbox. Make sure the {{Template sandbox notice}} line inside the <noinclude> element immediately follows your active template code. The result should look like this:

[-- active template code --]<noinclude>
{{Template sandbox notice}}
</noinclude>

Note
Any spaces or newlines between your template code and the opening <noinclude> tag may cause the sandbox template to render unwanted spaces or newlines when it is used.

Do not place {{Documentation}} anywhere on the template sandbox page, otherwise the sandbox version of the template will appear alongside the regular (non-sandbox) template in its category. Template sandboxes should appear only in Category:Template sandboxes, not in "normal" template categories, since the sandbox versions are not for normal, everyday use.

If you want to see the testcases on the template sandbox page (instead of having to continually reload the main template page or its documentation subpage after saving a new sandbox version), just include {{X/testcases}} before the template sandbox notice inside the <noinclude> element. If this is done, the subpage will look like this (remember to replace "X" with the actual name of your template):

[-- active template code --]<noinclude>
{{X/testcases}}
{{Template sandbox notice}}
</noinclude>

How to create /testcases subpages

You should provide at least one testcase for each parameter, illustrating its proper use. Do this as follows:

1. As before, suppose your template is named Template:X. Create the /testcases subpage by clicking on the appropriate "create" link in the Note box under the documentation. The subpage will have the name Template:X/testcases and be preloaded with some default contents (the preloading only happens when the subpage is created through the "create" link). Once the subpage is present, the Note box will automatically provide a link to it. Note that "/testcases" is spelled in all lower-case.
2. Create at least one testcase for each parameter using the {{Testcase}} template, as shown below. The /testcases subpage is transcluded by the /doc subpage under the level-2 section heading "==Usage==", so if you want to show incorrect usage (for debugging purposes), you should probably list them under a level-3 heading called, say, "===Incorrect===". Cases showing incorrect usage are beneficial to editors modifying the sandox version of the template but can also be useful to editors who are debugging their own (mistaken) uses of the regular version of the template. Place the following line at the very beginning of the /testcase subpage. You don't have to worry if there are blank lines surrounding it:

<noinclude>{{Template testcases notice}}</noinclude>

Thus your Template:X/testcases may end up looking like this:

<noinclude>{{Template testcases notice}}</noinclude>
{{Testcase
|title=No parameter
|<nowiki>{{X}}</nowiki>
|        {{X}}
|{{X/sandbox}}
}}

{{Testcase
|title=Unnamed parameter with value foo
|<nowiki>{{X|foo}}</nowiki>
|        {{X|foo}}
|{{X/sandbox|foo}}
}}

=== Incorrect ===

{{Testcase
|title=Named parameter foo with no value (not supported)
|<nowiki>{{X|foo=}}</nowiki>
|        {{X|foo=}}
|{{X/sandbox|foo=}}
}}

Be careful when adding or changing a testcase to pass exactly the same parameters in all three template calls ("nowiki" version, regular template version, and sandbox version)!

How to use them subsequently

Once the subpages exist for your template, from time to time you can:

• Sync the sandbox from the regular template (i.e. /sandbox instructions step 2 above);
• Have fun editing the sandbox;
• Verify the test cases;
• If everything looks good, copy the code from the sandbox to the regular template.

Note that if you use a tabbed browser, you may want to open different tabs for the /testcase subpage before and after changing the sandbox template in order to compare the results more precisely.

Examples

These templates use testcases showing both correct and incorrect usage.

• {{Path}}
• {{Unsigned}}

See also

• {{Template sandbox notice}} – This is placed at the bottom of /sandbox subpages.
• {{Template testcases notice}} – This is placed on top of /testcases subpages.
• {{Documentation}} – This template provides access to both types of template subpages.