Help:Template sandbox and test cases

From Gentoo Wiki
Jump to:navigation Jump to:search

Templates are pages in the Template: namespace that exist for the purpose of being transcluded in other pages. 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.

Before reading these instructions, create a template and a documentation subpage. See Help:Templates, especially Help:Templates#Adding documentation and categories.

How to create /sandbox subpages

Follow these steps to create a template sandbox.

  1. Suppose a 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 Template:X to Template:X/sandbox. Make sure the {{Template sandbox notice}} line inside the <noinclude> element immediately follows the active template code. The result should look like this:

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

Note
Any spaces or newlines between the 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.

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 the template):

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

How to create /testcases subpages

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

  1. As before, suppose the 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 to show incorrect usage (for debugging purposes), 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. It may be surrounded by blank lines:

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

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

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

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

=== Incorrect ===

{{Testcase
|title=Named parameter foo with no value (not supported)
|&lt;nowiki>{{X|foo=}}&lt;/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 the template, the following can be done from time to time:

  • 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.

Editors 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.

See also

Retrieved from "https://wiki.gentoo.org/index.php?title=Help:Template_sandbox_and_test_cases&oldid=1296366"