Template sandbox and test cases: change a template safely

Why templates need a sandbox

One edit to a template changes every page that uses it, and mistakes are easy even for experienced editors. Before touching a live template, open What links here to see how many pages depend on it. The English Wikipedia's guidance is to test in a sandbox with test cases, and always to test templates marked high-risk.

• Always worth it: templates built with ParserFunctions whose output varies, especially those with many parameters or a long #switch.
• Often not worth it: navigation boxes that show nearly the same thing on every page, though the advice is still if in doubt, sandbox it.
• For a brand-new template: build it in your own user space first, then move it.

The two subpages

Both names are all lowercase, and testcases is one word. Most protected templates on the English Wikipedia already have both subpages, linked from the foot of their documentation box.

Creating /sandbox and /testcases

The quickest way is the create and mirror links at the foot of the template's documentation box, which build the subpages for you. By hand it takes five steps:

1. Create Template:X/sandbox and paste in the whole main template, including its noinclude tags and documentation call. Use an edit summary such as create sandbox version of Template:X.
2. Create Template:X/testcases. It is linked from the documentation box only once it exists, so type its name in the search box.
3. Put {{testcases notice}} at the top and add test cases (see below).
4. Make your change on the sandbox and save it.
5. Open the testcases page, purge it so the results update, and compare the two versions. If everything matches what you expect, copy the sandbox code to the main template.

Changing a template that already has a sandbox

Someone may have edited the main template since the sandbox was last used, so the first step is always to sync: copy the whole main template into the sandbox and save it with the summary Sync. Then make your change, add test cases for any new parameter or behaviour, purge the testcases page and check every result before copying the code back.

Writing good test cases

Write one test case for each thing the template does differently. If a banner template has a plain message, an italic=yes option and a date parameter, that is three test cases. Testing every combination is rarely practical, so pick the ones editors really use.

Templates that type the parameters once are safer: with hand-written cases, a typo in one call can look like a bug in the template. For worked examples, see the subpages of {{Quote}}, {{Diff}} and {{Infobox settlement}}.

What a testcases page cannot show

Some behaviour depends on where a template is used: output that appears only in articles, or that differs on subpages. For these, use Preview page with this template, shown under the edit window on template pages: it previews another page using the code in your edit window, before you save anything. Special:TemplateSandbox does the same from its own form, and Special:ExpandTemplates shows the wikitext a call turns into. Leave a note on the testcases page about anything you could not test there.

Throwaway pages for template experiments

• {{X1}} to {{X20}} and {{Template sandbox}}: temporary templates anyone can overwrite.
• {{TemplateStyles sandbox}}: for stylesheets with the sanitized-css content model, which can only be created in the Template namespace.
• Category:X1 to Category:X9: for testing how templates add categories.
• Lua modules have their own sandboxes and unit tests; see Lua modules and Scribunto.