96 lines
5.7 KiB
Plaintext
96 lines
5.7 KiB
Plaintext
caption: testcase
|
|
created: 20230406161341763
|
|
modified: 20230406161341763
|
|
tags: Widgets
|
|
title: TestCaseWidget
|
|
type: text/vnd.tiddlywiki
|
|
|
|
! Introduction
|
|
|
|
The <<.wid 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 <<.wid 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.
|
|
|
|
!! Features
|
|
|
|
Here is an example of a testcase showing the default split view with the source tiddlers on the left and the tiddler titled `Output` rendered on the right. It also displays the tiddler titled `Description` as the heading.
|
|
|
|
<<testcase "TestCases/TranscludeWidget/SimpleTransclusion">>
|
|
|
|
The payload tiddlers listed in the tabs on the left are editable, with the results being immediately reflected in the preview pane on the right. However, if the <<.wid testcase>> widget is refreshed then the modifications are lost.
|
|
|
|
The green tick at the top left of a testcase 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:
|
|
|
|
<<testcase "TestCases/TestCaseWidget/FailingTest">>
|
|
|
|
!! Usage
|
|
|
|
The <<.wid testcase>> widget can be used directly as documented below, but it is generally easier and more flexible to create [[TestCaseTiddlers]]. These are special, self contained tiddlers that can contain multiple payload tiddlers making up a testcase.
|
|
|
|
Note that the testcase wiki will inherit variables that are visible to the <<.wid testcase>> widget itself.
|
|
|
|
! Limitations
|
|
|
|
The <<.wid 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 <<.wid testcase>> widget is refreshed
|
|
* Startup actions are not supported
|
|
* Only plugins available in the host wiki can be included in the testcase
|
|
|
|
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 <<.wid testcase>> widget.
|
|
|
|
! Content and Attributes
|
|
|
|
The content of the `<$testcase>` widget is not displayed but instead is scanned for <<.wlink DataWidget>> widgets that define the payload tiddlers to be included in the testcase.
|
|
|
|
|!Attribute |!Description |
|
|
|<<.attr template>> |Optional title of the template used to display the testcase (defaults to $:/core/ui/testcases/DefaultTemplate). Note that custom templates will need to be explicitly added to the payload |
|
|
|<<.attr testOutput>> |Optional title of the tiddler whose output should be subject to testing (note that both <<.attr testOutput>> and <<.attr testExpectedResult>> must be provided in order for testing to occur) |
|
|
|<<.attr testExpectedResult>> |Optional title of the tiddler whose content is the expected result of rendering the output tiddler (note that both <<.attr testOutput>> and <<.attr testExpectedResult>> must be provided in order for testing to occur) |
|
|
|<<.attr testActions>> |Optional title of the tiddler containing actions that should be executed before the test occurs |
|
|
|<<.attr testHideIfPass>> |If set to "yes", hides the <<.wid 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 <<.wlink DataWidget>> widgets within the body of the `<$testcase>` widget. The `$:/core` plugin is automatically included in the payload.
|
|
|
|
! Testcase Templates
|
|
|
|
The <<.attr template>> attribute defaults to $:/core/ui/testcases/DefaultTemplate
|
|
|
|
The default template uses several variables that can be set by the user:
|
|
|
|
|!Variable |!Description |
|
|
|<<.var linkTarget>> |Causes the testcase description to be rendered as a link to the current tiddler |
|
|
|<<.var displayFormat>> |Defaults to "wikitext", can also be "plaintext" to force plain text display |
|
|
|
|
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.
|
|
|
|
! Testcase Template Variables
|
|
|
|
The <<.wid testcase>> widget makes the following variables available within the rendered template:
|
|
|
|
|!Variable |!Description |
|
|
|<<.var transclusion>> |A hash that reflects the names and values of all the payload tiddlers. This makes it easier for testcase templates to create unique state tiddler titles using the [[qualify Macro]] or QualifyWidget |
|
|
|<<.var payloadTiddlers>> |JSON array of payload tiddler fields |
|
|
|<<.var outputHTML>> |The actual output HTML if running tests |
|
|
|<<.var expectedHTML>> |The expected output HTML if running tests |
|
|
|<<.var testResult>> |The tests result if running tests (may be "pass" or "fail") |
|
|
|
|
! Examples
|
|
|
|
Here is an example of setting up a testcase that includes expected test results:
|
|
|
|
<$testcase>
|
|
<$data title="Description" text="Example of a testcase with expected results"/>
|
|
<$data title="Output" text="""<$testcase testOutput="Output" testExpectedResult="ExpectedResult">
|
|
<$data title="Description" text="How to calculate 2 plus 2"/>
|
|
<$data title="Output" text="<$text text={{{ [[2]add[2]] }}}/>"/>
|
|
<$data title="ExpectedResult" text="<p>8</p>"/>
|
|
</$testcase>
|
|
"""/>
|
|
</$testcase>
|