Wikipedia:Template sandbox and test cases: Difference between revisions

Revision as of 11:07, 2 December 2016

Revision as of 02:05, 18 December 2016

Line 1:

{{Wikipedia how to|WP:TEMPTEST|WP:TESTCASE|WP:TESTCASES}}

[[Help:Template|Templates]] are a very powerful feature of the [[WikiMedia]] software used for [[Wikipedia]], but mistakes can be easily made, even by experienced users. Complex templates should therefore be accompanied by [[Sandbox (software development)|sandboxes]] and [[test case]]s to prevent bugs. Temporary sandboxes [[Template:X1|X1]]-[[Template:X20|X20]] or the [[Template:Template_sandbox|Template Sandbox]] may be useful places to try new experiments or for users new to template development.

== Sandbox and testcases subpage naming ==

Most protected templates already have a sandbox subpage and testcases subpage. The names of these pages are default. At the bottom of each template's page are links to create\edit the template's sandbox and testcases pages.

For example, here are the subpages for '''{{tl|FlagIOCmedalist}}''':

{|class="wikitable"

!Template

!Link

|-

| Main template || [[Template:FlagIOCmedalist]]

|-

| Template's sandbox || [[Template:FlagIOCmedalist/sandbox]]

|-

| Template's testcases page || [[Template:FlagIOCmedalist/testcases]]

|}

== What kind of templates should you use sandbox for ==

It is highly recommended to apply the test case pattern to templates using [[mw:Help:Extension:ParserFunctions|ParserFunctions]] that can generate very different looking output, such as ones that take many parameters, or the ones that have many branches of the <code>#switch</code> operator.

For navigational boxes with mostly identical results on each transcluding page, the benefit may not outweigh the time and effort to create a sandbox page, but if in doubt, sandbox it. Any template that is marked as a [[Wikipedia:High-risk templates|High-risk Template]] should always be tested before an edit is made. With other pages, you should still check which pages use the template (via the "What Links Here" link in the Tools section of the linkbar at the left side of the screen).

== How to create /sandbox and /testcases subpages ==

# Suppose your template is named <code>Template:X</code>. Create a subpage with the name <code>Template:X/sandbox</code>. If the main template is using the {{tl|documentation}} template, you can do this from a link at the bottom of the blue documentation box on the template main page. 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 <code><nowiki><noinclude></nowiki></code> tags and the {{tl|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 <code><nowiki><noinclude></nowiki></code>, and their contents, will be missing. It's best just to copy and paste manually.

# Create another subpage with the name <code>Template:X/testcases</code>. 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 {{tl|testcases notice}} template at the top of the page, add some test cases (see below), and save the page.

# Add your experimental code to <code>Template:X/sandbox</code>. To test your code, save the page, and go to the /testcases page. Often you will need to [[WP:PURGE|purge]] the /testcases page to see the updated results; there is a link to do that included in the {{tl|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.

# [[WP:PURGE|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 {{para|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, {{para|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 {{tl|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'' ==

&nbsp;

* &lt;code&gt;&lt;nowiki&gt;&#123;&#123;''template''&#124;''param1''=''value1''&#124;''param2''=''value2''&#125;&#125;&lt;/nowiki&gt;&lt;/code&gt;

&nbsp;

<nowiki>'''Main'''</nowiki>

&nbsp;

&#123;&#123;''template''&#124;''param1''=''value1''&#124;''param2''=''value2''&#125;&#125;

&nbsp;

<nowiki>'''Sandbox'''</nowiki>

&nbsp;

&#123;&#123;''template''/sandbox&#124;''param1''=''value1''&#124;''param2''=''value2''&#125;&#125;

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

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

== ''Descriptive title'' ==

&nbsp;

* &lt;code&gt;&lt;nowiki&gt;&#123;&#123;''template''&#124;''param1''=''value1''&#124;''param2''=''value2''&#125;&#125;&lt;/nowiki&gt;&lt;/code&gt;

&nbsp;

<nowiki>'''Main'''</nowiki>

&nbsp;

&#123;&#123;''template''&#124;''param1''=''value1''&#124;''param2''=''value2''&#125;&#125;

&nbsp;

&#123;&#123;clear&#125;&#125;

&nbsp;

<nowiki>'''Sandbox'''</nowiki>

&nbsp;

&#123;&#123;''template''/sandbox&#124;''param1''=''value1''&#124;''param2''=''value2''&#125;&#125;

&nbsp;

&#123;&#123;clear&#125;&#125;

==== 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:

&#123;&#124; class="wikitable"

&#124;-

! Code

! Main

! Sandbox

Each new test case can be added like this:

|-

| &lt;code&gt;&lt;nowiki&gt;&#123;&#123;''template''&#124;''param1''=''value1''&#124;''param2''=''value2''&#125;&#125;&lt;/nowiki&gt;&lt;/code&gt;

| &#123;&#123;''template''&#124;''param1''=''value1''&#124;''param2''=''value2''&#125;&#125;

| &#123;&#123;''template''/sandbox&#124;''param1''=''value1''&#124;''param2''=''value2''&#125;&#125;

Finish the table like this:

&#124;&#125;

=== 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]]

== See also ==

* [[Wikipedia:High-risk templates]]

* [[Help:Template]] - general help with template code

* [[Wikipedia:Template limits]] - technical limitations on template use

* {{tl|Template sandbox}} - sandbox for use in testing templates

{{Wikipedia technical help|collapsed}}

[[Category:Wikipedia templates|{{PAGENAME}}]]