caption: testcase
created: 20230406161341763
modified: 20230406161341763
tags: Widgets
title: TestCaseWidget
type: text/vnd.tiddlywiki

! Introduction

The testcase widget creates an independent subwiki loaded with specified tiddlers and then renders a template that can display and render tiddlers from within the subwiki. This makes it possible to run independent tests that also serve as documentation examples.

! 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 test case.

|!Attribute |!Description |
|<<.attr testcase-tiddler>> |Optional title of a tiddler containing a test case in `text/vnd.tiddlywiki-multiple` format (see below) |
|<<.attr template>> |Optional title of the template used to display the testcase (defaults to $:/core/ui/testcases/DefaultTemplate) |

! Payload Tiddlers

The payload tiddlers are the tiddler values that are loaded into the subwiki that is created to run the tests.

The payload tiddlers can be created in two different ways:

* Tiddlers values specfied via <<.wlink DataWidget>> widgets within the body of the `<$testcase>` widget
* As multiple tiddlers embedded within a single tiddler of type `text/vnd.tiddlywiki-multiple` whose title is given in the <<.attr testcase-tiddler>> attribute

The special tiddler type `text/vnd.tiddlywiki-multiple` is intended to simplify creating test cases that require several tiddlers. The text field consists of a series of tiddlers in the same format as `.tid` files, each separated by a line containing a single `+` character.

For example:

```
title: First
tags: one two

This is the first tiddler
+
title: Second
tags: three four

This is the second tiddler
+
title: third
tags: five six

This is the third tiddler
```

! Test Case Templates

The test case template specified in the <<.attr template>> attribute can display and render tiddlers from the subwiki using the <<.wlink TestCaseTranscludeWidget>> and <<.wlink TestCaseViewWidget>> widgets.

The default test case template $:/core/ui/testcases/DefaultTemplate displays a split view with the source tiddlers on the left and the rendered tiddler titled `Output` on the right. It also displays the tiddler titled `Description` as the heading.

The `<$testcase>` widget assigns a value to the `transclusion` variable that depends on the combined values of all the payload tiddlers. This means that using the `<<qualify>>` macro within a test case template will generate a unique value for each of multiple test cases within the same tiddler.

The `<$testcase>` widget also assigns a block of information about the subwiki in JSON format to a the variable `testcaseInfo`. It contains the following properties:

* ''titles'': an array of the titles of all the tiddlers in the subwiki (excluding shadow tiddlers)

! Test Case Conventions

The following conventions are used for test case tiddlers:

* `Description` contains a brief description of the test (rendered in inline mode)
* `Output` contains the tiddler text to be rendered. It can also reference other tiddlers
* `ExpectedResult` contains the HTML that should match the rendering of the tiddler `Output`

! Example

<$testcase>
<$data $tiddler="$:/core/ui/testcases/DefaultTemplate"/>
<$data $tiddler="$:/core/ui/testcases/DefaultTemplate/Source"/>
<$data title="Description" text="Simple example of a test case"/>
<$data title="Output" text="""<$testcase>
<$data title="Description" text="How to calculate 2 plus 2"/>
<$data title="Output" text="<$text text={{{ =2 =[add[2]] }}}/>"/>
</$testcase>
"""/>
</$testcase>