2021pedia:TESTCASES

<languages/> Template:ExtensionTypes

<translate> Extensions let you customize how MediaWiki looks and works. </translate>

• <translate> Wiki users can [[<tvar name=cat>Special:MyLanguage/Category:Extensions by category</tvar>|browse through extensions]].</translate>
• <translate> System administrators can [[<tvar name=1>#Installing an extension</tvar>|install]] (or remove) extensions on the MediaWiki installations that they manage.</translate>
• <translate> Developers can [[<tvar name=man>Special:MyLanguage/Manual:Developing extensions</tvar>|write new extensions]] or [[<tvar name=cat>Special:MyLanguage/Category:Unmaintained extensions</tvar>|improve or maintain extensions]]. </translate>

<translate> While some extensions are maintained by MediaWiki developers, others were written by third-party developers.</translate> <translate> As a result, many have bugs, and they are not all guaranteed to be compatible with each other.</translate> <translate> Some are unmaintained; not all extensions work on all versions of MediaWiki.</translate> <translate> Use any extension, especially those tagged as insecure, at your own risk.</translate> <translate> If you are using an extension that requires patches to the core software, be sure to backup your database.</translate> <translate> This helps avoid the risk of breaking your wiki.</translate>

<translate>

Types of extensions

</translate>

Template:InfoCard Template:InfoCard

<translate>

Browsing extensions

</translate> <translate> You can browse <tvar name=cat></tvar> to see the full range of extensions that have already been written.</translate> <translate> For information on installing these extensions or writing your own, see below.</translate>

<translate>

Checking installed extensions

</translate> <translate> Only someone with administration access to the filesystem (and often the database too) on a server can install extensions for MediaWiki, but anyone can check which extensions are active on an instance of MediaWiki by accessing the <tvar name=special>Special:Version</tvar> page.</translate> <translate> For example, these extensions are active in the English Wikipedia.</translate>

<translate>

Installing an extension

</translate> <translate> MediaWiki is ready to accept extensions just after [[<tvar name=man>Special:MyLanguage/Manual:Installation</tvar>|installation]] is finished.</translate> <translate> To add an extension follow these steps:</translate>

1. <translate> Before you start</translate>

   <translate> Many extensions provide instructions designed for installation using unix commands.</translate> <translate> You require shell access (SSH) to enter these commands listed on the extension help pages.</translate>

2. <translate> Download your extension.</translate>

   <translate> [[<tvar name=special>Special:ExtensionDistributor</tvar>|Extension Distributor]] helps you to select and download most of the popular extensions.</translate>

   <translate> Extensions are usually distributed as modular packages.</translate> <translate> They generally go in their own subdirectory of <tvar name=IP>/extensions/</tvar>.</translate> <translate> A list of extensions stored in the Wikimedia [[<tvar name=gerrit>Special:MyLanguage/Gerrit</tvar>|Git repository]] is located at <tvar name=extensions>git:mediawiki/extensions</tvar>.</translate> <translate> Some extensions [[<tvar name=cat>Special:MyLanguage/Category:Extensions which host their code in-wiki</tvar>|don't use version control]] and are not recommended.</translate>

   <translate> Some extensions are also available in [[<tvar name=1>Special:MyLanguage/Software bundles</tvar>|bundles]], <tvar name=composer></tvar> or [[<tvar name=2>Special:MyLanguage/Comparison of extensions in distributions</tvar>|package repositories]].</translate>

3. <translate> Install your extension.</translate>.

   <translate> At the end of the <tvar name=LocalSettings></tvar> file, add:</translate>

   wfLoadExtension( 'ExtensionName' );
   

   <translate> This line forces the PHP interpreter to read the extension file, and thereby make it accessible to MediaWiki.</translate>

   <translate> Some extensions can conflict with maintenance scripts, for example if they directly access $_SERVER (not recommended).</translate>

   <translate> In this case they can be wrapped in the conditional so maintenance scripts can still run.</translate>

if ( !$wgCommandLineMode ) {
   wfLoadExtension ( 'ExtensionName' );
}

<translate> : The maintenance script <tvar name=ImportDump></tvar> will fail for any extension which requires customized namespaces which is included inside the conditional above such as <tvar name=1></tvar>, <tvar name=2></tvar>.</translate>

<span class="citation wikicite" id="endnote_<translate> Ensure that required permissions are set for extensions!</translate>">^

<span class="citation wikicite" id="endnote_<translate> While this installation procedure is sufficient for most extensions, some require a different installation procedure.</translate> <translate> Check your extension's documentation for details.</translate>">^

<span class="citation wikicite" id="endnote_<translate> If you want to alter configuration variables in LocalSettings.php, you have to do this typically after including the extension.</translate> <translate> Otherwise defaults defined in the extension will overwrite your settings.</translate>">^

<translate>

Upgrading an extension

</translate> <translate> Some extensions require to be updated whenever you update MediaWiki, while others work with multiple versions.</translate> <translate> To upgrade to a new version of an extension:</translate>

<translate>

1. Download the new version of the extension</translate>

<translate>

1. Replace all the extension files in the extension/ExtensionName directory with the new files.</translate> <translate> Do not remove the extension configuration present in LocalSettings.php</translate>

<translate>

1. If the extension requires changes to the MediaWiki database, you will need to run the Update.php maintenance script.</translate> <translate> Most extensions will mention if this script needs to be run or not.</translate> <translate> (Perform backup of your data before executing the script).</translate> <translate> If you don't have command line access, you can also use the [[<tvar name=man>Special:MyLanguage/Manual:Upgrading#Web_updater</tvar>|web updater]].</translate>

<span class="citation wikicite" id="endnote_<translate> These instructions cover 99% of extensions.</translate> <translate> If the specific extension you are upgrading has instructions that differ from these, you should probably follow the specific extension's instructions</translate>">^

<translate>

Uninstalling an extension

Remove the line from LocalSettings.php with the extension name to uninstall it: </translate>

wfLoadExtension( 'ExtensionName' );

<translate>

• You must remove any lines pertaining to the configuration of the extension.

See also

</translate>

• - <translate> Information about translating extensions.</translate>

[[Category:Customization techniques{{#translation:}}|TESTCASES]] [[Category:Extension creation{{#translation:}}]]

The ShortDescription extension allows wikis to add short descriptions to wikitext pages, similar to the implementation on Wikipedia and Wikibase. On top of that, it replaces the site tagline with short description on pages with short description.

Installation

Note that the latest version is located in the GitHub repo instead of Gerrit. Template:ExtensionInstall

Features

• Define short description on the page with the magic word {{SHORTDESC}}, same as the implementation on Wikipedia
• Retrieve short description on any wiki pages with the magic word {{GETSHORTDESC}}
• Add short description underneath the page title on most skins, if the skin supports site tagline (#siteSub)
  • Note that the short description with replace the default site tagline message on pages with short description
  • Does not apply to Skin:Citizen and Skin:Minerva Neue, as they have native support
• Allow short description to be accessed through the Action API
• Provide description to the REST API search endpoint
• Add short description to page information (&action=info)
• Provide description for extensions such as MobileFrontend, RelatedArticles

Configurations

The extension works out of the box without any configurations. The config flags allow more customization on the specific features in the extension.

Name	Description	Values	Default
Template:Phpi	Enables short descritption in site tagline	Template:Phpi - enable; Template:Phpi - disable	Template:Phpi
Template:Phpi	Provide short description to the Opensearch API module	Template:Phpi - enable; Template:Phpi - disable	Template:Phpi

Usage

Add short description

To add Bacon ipsum dolor amet turkey as short description, simply add {{SHORTDESC:Bacon ipsum dolor amet turkey}} on the page.

Retrive short description on wikipage

To retrive the short description on the page Bacon, simply add {{GETSHORTDESC:Bacon}} on the page. If you are retrieving the short description on the same page (e.g. getting the short description of Bacon on the Bacon page), simply add {{GETSHORTDESC:}}.

Retrieve short description through Action API

The short description can be called through the description property in query action in the Action API (e.g.api.php?action=query&prop=description). It is also accessible through the shortdesc property inside pageprops.

Retrieve short description through REST API

The short description can be accessed through the description property in the search endpoint in the REST API.

Screenshots

• 

  ShortDescription on Skin:Citizen

• 

  ShortDescription on Skin:Minerva

• 

  ShortDescription on Skin:Monobook

• 

  ShortDescription on Skin:Timeless

• 

  ShortDescription on Skin:Vector

See also

• T184000 - Magic word on English WP to override display of Wikidata short description
• Extension:Wikibase Client - provide the description functionality on Wikimedia projects
• Extension:RelatedArticles - Use the description from this extension under wikidata mode
• Extension:Description2 - An extension that adds a description meta tag generated automatically from the first paragraph of the page, or manually overridden.

Templates are a very powerful feature of the MediaWiki software used for Wikipedia, but mistakes can be easily made, even by experienced users. Edits to complex templates should therefore be carried out in sandboxes and accompanied by test cases to prevent bugs. Temporary sandboxes X1-X52 or the Template Sandbox may be useful places to try new experiments or for users new to template development.

For the development of entirely new templates, user sandboxes are appropriate.

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 {{FlagIOCmedalist}}:

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 ParserFunctions that can generate very different looking output, such as ones that take many parameters, or the ones that have many branches of the #switch 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 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

1. 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 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.
2. 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.
3. 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.
4. Put the {{testcases notice}} template at the top of the page, add some test cases (see below), and save the page.
5. 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.

1. 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".
2. Have fun editing the sandbox. When you have some code you want to test, save the page.
3. 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.
4. Purge the /testcases page to update the results.
5. 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 and Template:Quote/testcases

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
• {{Template sandbox}} - sandbox for use in testing templates
• Special:ExpandTemplates
• Special:TemplateSandbox