Introduction
The $testcase widget is designed to present interactive example test cases that are useful for learning and testing. It functions by creating an independent subwiki loaded with the specified payload tiddlers and then rendering a specified template from within the subwiki. The $testcase widget can optionally also be used to run and verify test results within the subwiki.
This makes it possible to run independent tests that also serve as documentation examples.
The $testcase widget can be used directly as documented below, but it is generally easier to create TestCaseTiddlers. These are special CompoundTiddlers that can contain multiple payload tiddlers making up a test case.
Features
Here is an example of a test case showing the default split view with the source tiddlers on the left and the tiddler titled Output rendered on the right.
This test case demonstrates transclusion of and links to other tiddlers.
<p>Good morning, my <a class="tc-tiddlylink tc-tiddlylink-resolves" href="#Name.html">name</a> is Robert Rabbit and I <a class="tc-tiddlylink tc-tiddlylink-resolves" href="#Address.html">live in</a> 14 Carrot Street, Vegetabletown</p>Notice also that clicking on links within the output pane will switch to the tab containing that tiddler.
The text of the payload tiddlers listed on the left are editable, with the results being immediately reflected in the preview pane on the right. However, if the $testcase widget is refreshed then the modifications are lost.
There is a dropdown menu at the top right of the menu that has two options:
- Export the payload tiddlers to a file in the usual export formats
- Import the payload tiddlers into the host wiki. This option loads the payload tiddlers into the $:/Import tiddler so that they can be renamed and/or individually selected
The green tick at the top left of a test case indicates that a test has been set up and that it passes.
If the test fails, a red cross is shown, and there is a display of the differences between the actual results and the expected results:
This test case intentionally fails (in order to show how failures are displayed). The expected result is set to <p>The sum is not 8.</p>, but the result computes to <p>The sum is 4.</p>
<p>The sum is not 84.</p>| title | Output |
The sum is 4.
Limitations
The $testcase widget creates a lightweight TiddlyWiki environment that is a parasite of the main wiki. Because it is not a full, independent TiddlyWiki environment, there are some important limitations:
- Output is rendered into a DIV, and so cannot be styled independently of the host wiki
- Any changes to the wiki made interactively by the user are volatile, and are lost when the
$testcasewidget is refreshed - Startup actions are not supported
- Only plugins available in the host wiki can be included in the test case
If these limitations are a problem, the Innerwiki Plugin offers the ability to embed a fully independent subwiki via an <iframe> element, but without the testing related features of the $testcase widget.
Content and Attributes
The content of the <$testcase> widget is not displayed but instead is scanned for $data widgets that define the payload tiddlers to be included in the test case.
| Attribute | Description |
|---|---|
template | Optional title of the template used to display the test case (defaults to $:/core/ui/testcases/DefaultTemplate). Note that custom templates will need to be explicitly added to the payload |
testOutput | Optional title of the tiddler whose output should be subject to testing (note that both testOutput and testExpectedResult must be provided in order for testing to occur) |
testExpectedResult | Optional title of the tiddler whose content is the expected result of rendering the output tiddler (note that both testOutput and testExpectedResult must be provided in order for testing to occur) |
testActions | Optional title of the tiddler containing actions that should be executed before the test occurs |
testHideIfPass | If set to "yes", hides the $testcase widget if the test passes |
Payload Tiddlers
The payload tiddlers are the tiddler values that are loaded into the subwiki that is created to run the tests. They are created via $data widgets within the body of the <$testcase> widget. The $:/core plugin is automatically included in the payload.
Testcase Templates
The template attribute defaults to $:/core/ui/testcases/DefaultTemplate
The default test case template assigns special meanings to a number of payload tiddlers:
| Tiddler | Description |
|---|---|
| Description | Descriptive heading for the test, intended to make it easy to identify the test |
| Narrative | Narrative description of the test, intended to explain the purpose and operation of the test |
| Output | The tiddler that produces the test output |
| ExpectedResult | HTML of expected result of rendering the Output tiddler |
The test case wiki will inherit variables that are visible to the $testcase widget itself. The default template uses several variables that can be set by the user:
| Variable | Description |
|---|---|
linkTarget | Causes the test case description to be rendered as a link to the current tiddler |
displayFormat | Defaults to "wikitext", can also be "plaintext" to force plain text display |
testcaseTiddler | Title of the tiddler to be used as a link target for the testcase description |
A custom template can be specified for special purposes. For example, the provided template $:/core/ui/testcases/RawJSONTemplate just displays the payload tiddlers in JSON, which can be used for debugging purposes.
Test Case Template Variables
The $testcase widget makes the following variables available within the rendered template:
| Variable | Description |
|---|---|
transclusion | A hash that reflects the names and values of all the payload tiddlers. This makes it easier for test case templates to create unique state tiddler titles using the qualify Macro or QualifyWidget |
payloadTiddlers | JSON array of payload tiddler fields |
outputHTML | The actual output HTML if running tests |
expectedHTML | The expected output HTML if running tests |
testResult | The tests result if running tests (may be "pass" or "fail") |
Example
Here is an example of setting up a test case that includes expected test results:
Example of a test case with expected results
| title | Output |
How to calculate 2 plus 2
<p>84</p>| title | Output |
4