User:Wlgrin/Sandbox/TTestMini/doc

{{User:Wlgrin/Sandbox/TTestMini}} is a small collection of simple templates that can be used to present test cases in a tabular format. This is useful to developers of templates interested in testing their code.

Overview

Purpose

{{User:Wlgrin/Sandbox/TTestMini}} is not a template but, rather, a small collection of related templates that help produce test reports when testing other templates.

By convention, a test suite (a collection of test cases) can be stored in the “/testcases” sub-page of a template (see, for example, the “testcases” sub-page of this template page). At a minimum, a test case consists of some sample Wiki markup that references (either substituting or transcluding) the template to be tested. The output from the markup code (called here the actual result) can then be visually inspected.

Often, a test case will also include:

• Hand-crafted markup code producing the expected result, which can be used as a reference when appraising the correctness of the actual result. To constitute a valid reference for comparison, it must be entirely hand-crafted rather than generated by templates. In particular, it should not be made by copying the output from Special:ExpandTemplates, since that would result in a rather tautological comparison of the tested template with itself.
• A readable copy of the markup code used in the test, to help the reader understand what to expect. To prevent execution of that copy, it must be contained in a <nowiki></nowiki> element.
• A description which may provide additional information about the test case and relevant details of the output that warrant minute inspection.

The {{User:Wlgrin/Sandbox/TTestMini}} templates help laying out those test cases in tables. Additionally, it performs an automatic comparison of the expected result with the actual result and displays an appraisal value (Pass or Fail). A test suite table looks like this (size reduced):

This is a sample test suite; this caption is optional

Id	Description	Code	Appraisal
001	The description of the test case.	{{#ifeq:{{#expr: 1 + 1}}|2 |MediaWiki can count! |MediaWiki should go back to school… }}	Pass
	expected MediaWiki can count! actual MediaWiki can count!
002	Linking to first-level sub-page (this will fail when the parameters passed to #titleparts are wrong; remember to inspect not only the resulting display, but also the linked URL, visible by hovering over the link)	[[{{#titleparts:namespace:page/subpage/subsubpage|1|2}}|Somewhere]]	Fail
	expected Somewhere actual Somewhere

Test case 002 from the example above failed because the link was not pointing to the expected page.

Code for the example above (click to expand)

{{TTestMini/i/Header |caption=This is a sample test suite; this caption is optional }} <!-- -------------------------------------------------- --> {{TTestMini/i/Case |id=001 |description=The description of the test case. |code= <nowiki> {{#ifeq:{{#expr: 1 + 1}}|2 |MediaWiki can count! |MediaWiki should go back to school… }} </nowiki> |expected=MediaWiki can count! |actual= {{#ifeq:{{#expr: 1 + 1}}|2 |MediaWiki can count! |MediaWiki should go back to school… }} }} <!-- -------------------------------------------------- --> {{TTestMini/i/Case |id=002 |description=Linking to first-level sub-page<br/><small style="line-height:1.3em;">(this will fail when the parameters passed to #titleparts are wrong; remember to inspect not only the resulting display, but also the linked URL, visible by hovering over the link)</small> |code= <nowiki> [[{{#titleparts:namespace:page/subpage/subsubpage|1|2}}|Somewhere]] </nowiki> |expected=[[namespace:page/subpage|Somewhere]] |actual=[[{{#titleparts:namespace:page/subpage/subsubpage|1|2}}|Somewhere]] }} <!-- -------------------------------------------------- --> {{TTestMini/i/Footer}}

Applicability

While {{Wlgrin/Sandbox/TTestMini}} aims to provide some convenience, it is not a necessity: you may, of course, prefer laying out your test cases in a custom manner. Nor is it adequate for all purposes:

• Visual templates may require more space than a table could comfortably accommodate.
• The automatic comparison of expected and actual results will fail in certain circumstances, because of current limitations in MediaWiki. In particular, any output containing custom HTML tags (including <nowiki>, <ref>, <math>, <poem>, etc.) will contain, after expansion, marker tags that are unique to each instance and therefore not comparable. For those cases, {{Wlgrin/Sandbox/TTestMini}} can still be used as a layout helper, by disabling automatic appraisal (parameter auto-appraise).
• Complex templates rely on many sub-templates and generate a lot of code, possibly including hidden elements, inline style attributes, etc. Creating the correct expected result for such templates is difficult. Furthermore, a slight change (for example, swapping the order of attributes in an HTML element) in a single sub-template is enough to render the expected result obsolete and cause it to no longer match the actual result. On the other hand, such test cases could be viewed as useful in so far as they help developers assess the oft-undetected impact of changes in sub-templates.

Generally speaking, {{Wlgrin/Sandbox/TTestMini}} is best suited to test relatively simple templates that generate text strings and that are not expected to frequently change.

Usage

The collection includes three templates:

• {{Wlgrin/Sandbox/TTestMini/i/Header}} and {{Wlgrin/Sandbox/TTestMini/i/Footer}}, which are used to bracket the test cases and generate a table to contain them.
• {{Wlgrin/Sandbox/TTestMini/i/Case}}, used to generate a row for one test case in the table.

A table of test cases therefore consists of the following sequence:

{{User:Wlgrin/Sandbox/TTestMini/i/Header}}
{{User:Wlgrin/Sandbox/TTestMini/i/Case}}
{{User:Wlgrin/Sandbox/TTestMini/i/Case}}
{{User:Wlgrin/Sandbox/TTestMini/i/Case}}
 ·
 ·
{{User:Wlgrin/Sandbox/TTestMini/i/Case}}
{{User:Wlgrin/Sandbox/TTestMini/i/Footer}}

Any number of test case tables can appear on a page. However, keep in mind that a large number of test cases, each invoking complex templates, may generate too large a page for MediaWiki to handle.

MediaWiki imposes constraints on the maximal size of markup code (after template expansion) and template arguments and on the use of expensive parser functions within a single rendered page. Once the limits are reached, MediaWiki displays an error message on the page, template expansion no longer occurs and the rest of the page is incorrectly rendered. To see how close to those limits a page is, you can browse its HTML source and, within it, search for a comment automatically inserted by MediaWiki that displays usage statistics (search for “NewPP limit report”). To avoid the problem, consider breaking up large test suites into multiple sub-pages.

{{Wlgrin/Sandbox/TTestMini/i/Header}}

Purpose

{{Wlgrin/Sandbox/TTestMini/i/Header}} opens the table of test cases, optionally adding a caption. It must immediately precede the series of test cases. It must be balanced with a closing call to {{Wlgrin/Sandbox/TTestMini/i/Footer}}.

Parameters

caption

A caption displayed above the table.

Using several tables helps organise test cases into families (for example: error conditions; normal use; etc.).

Optional. Default value: no caption.

Examples

1. caption=Input errors

{{Wlgrin/Sandbox/TTestMini/i/Footer}}

Purpose

{{Wlgrin/Sandbox/TTestMini/i/Footer}} closes the table of test cases. It must immediately follow the series of test cases. It must be balanced with an opening call to {{Wlgrin/Sandbox/TTestMini/i/Header}}.

Parameters

None.

{{Wlgrin/Sandbox/TTestMini/i/Case}}

Purpose

{{Wlgrin/Sandbox/TTestMini/i/Case}} creates a row for a single test case in the table of test cases. It must immediately follow the series of test cases. It must be balanced with an opening call to {{Wlgrin/Sandbox/TTestMini/i/Header}}.

Parameters

id

A free-form, short identifier that can be used to quickly locate a test case.

Optional. Default value: no identifier.

Examples

1. id=2.03

description

The name or description of the test case.

If you wish, you can write a one-line name first, and add more information below in smaller characters, for example by using <br/><small style="line-height:1.3em;">…</small> (see example below).

Optional. Default value: no description.

Examples

description=Invalid value for parameter '<tt>weekday</tt>'.<br/><small style="line-height:1.3em;">Parameter '<tt>weekday</tt>' takes values in the three-letter abbreviated form (<tt>Mon</tt>, <tt>Tue</tt>, etc.).</small>

This example is really wonderful. It makes me feel warm and fuzzy inside. I just love this example and I so totally wish that there would be many more of these.

1. description=Invalid value for parameter '<tt>weekday</tt>'.<br/><small style="line-height:1.3em;">Parameter '<tt>weekday</tt>' takes values in the three-letter abbreviated form (<tt>Mon</tt>, <tt>Tue</tt>, etc.).</small>

   This example is really wonderful. It makes me feel warm and fuzzy inside. I just love this example and I so totally wish that there would be many more of these.