Add support for narrative tiddlers in test cases

core/ui/TestCases/DefaultTemplate.tid

@@ -33,6 +33,11 @@ title: $:/core/ui/testcases/DefaultTemplate
 				</$genesis>
 			</h2>
 		</div>
+		<%if [[Narrative]is[tiddler]] %>
+			<div class="tc-testcase-narrative">
+				<$transclude $tiddler="Narrative" mode="block"/>
+			</div>
+		<%endif%>
 		<%if [<testResult>match[fail]] %>
 			<div class="tc-testcase-result-fail">
 				<div class="tc-testcase-result-fail-header">
@@ -45,7 +50,7 @@ title: $:/core/ui/testcases/DefaultTemplate
 		<%endif%>
 		<div class="tc-testcase-panes">
 			<div class="tc-testcase-source">
-				<$macrocall $name="tabs" tabsList="[all[tiddlers]sort[]] -[prefix<state>] -Description -ExpectedResult -Output Output +[putfirst[]] -[has[plugin-type]]" state=<<state>> default="Output" template="$:/core/ui/testcases/DefaultTemplate/Source"/>
+				<$macrocall $name="tabs" tabsList="[all[tiddlers]sort[]] -[prefix<state>] -Description -Narrative -ExpectedResult -Output Output +[putfirst[]] -[has[plugin-type]]" state=<<state>> default="Output" template="$:/core/ui/testcases/DefaultTemplate/Source"/>
 			</div>
 			<div class="tc-testcase-divider">
 			</div>

editions/tw5.com/tiddlers/testcases/DataWidget/ImportCompound.tid

@@ -4,6 +4,10 @@ tags: [[$:/tags/wiki-test-spec]]
 description: Importing a compound payload tiddler and adding custom fields
 display-format: plaintext
 
+title: Narrative
+
+Using the data widget to import a tiddler stored in a compound tiddler
++
 title: Output
 
 <$data $compound-tiddler="Compound" custom="Alpha"/>

editions/tw5.com/tiddlers/testcases/DataWidget/ImportedFilter.tid

@@ -4,6 +4,10 @@ tags: [[$:/tags/wiki-test-spec]]
 description: Imported filter definition
 display-format: plaintext
 
+title: Narrative
+
+Using the data widget to create copies of all the tiddlers with the title prefix "Day: T", adding the field "custom" set to "Beta"
++
 title: Output
 
 <$data $filter="[prefix[Day: T]]" custom="Beta"/>

editions/tw5.com/tiddlers/testcases/DataWidget/ImportedTiddler.tid

@@ -4,22 +4,26 @@ tags: [[$:/tags/wiki-test-spec]]
 description: Imported tiddler definition
 display-format: plaintext
 
+title: Narrative
+
+Using the data widget to create a tiddler that is a copy of the tiddler "Hello" with the addition of the field "custom" set to "Alpha"
++
 title: Output
 
-<$data $tiddler="HelloThere" custom="Alpha"/>
+<$data $tiddler="Hello" custom="Alpha"/>
 +
-title: HelloThere
+title: Hello
 modifier: JoeBloggs
 
-This is the HelloThere tiddler
+This is the Hello tiddler
 +
 title: ExpectedResult
 
 <p>[
     {
-        "title": "HelloThere",
+        "title": "Hello",
         "modifier": "JoeBloggs",
-        "text": "This is the HelloThere tiddler",
+        "text": "This is the Hello tiddler",
         "custom": "Alpha"
     }
 ]</p>

editions/tw5.com/tiddlers/testcases/DataWidget/Refreshing.tid

@@ -4,6 +4,10 @@ tags: [[$:/tags/wiki-test-spec]]
 description: Refreshing the data widget
 display-format: plaintext
 
+title: Narrative
+
+Verifying that the JSON output of the data widget is correctly refreshed when the data changes
++
 title: Output
 
 <$data title="Epsilon" text={{Subject}}/>

editions/tw5.com/tiddlers/testcases/DataWidget/SimpleTiddler.tid

@@ -4,6 +4,10 @@ tags: [[$:/tags/wiki-test-spec]]
 description: Simple tiddler definition
 display-format: plaintext
 
+title: Narrative
+
+Using the data widget to create a tiddler with the title "Epsilon" and the text "Theta"
++
 title: Output
 
 <$data title="Epsilon" text="Theta"/>

editions/tw5.com/tiddlers/testcases/TestCaseWidget/FailingTest.tid

@@ -3,6 +3,10 @@ type: text/vnd.tiddlywiki-multiple
 tags: [[$:/tags/wiki-test-spec-failing]]
 description: An example of a failing test
 
+title: Narrative
+
+This testcase intentionally fails to show how failures are displayed.
++
 title: Output
 
 The sum is <$text text={{{ [[2]add[2]] }}}/>.

editions/tw5.com/tiddlers/testcases/TranscludeWidget/SimpleTransclusion.tid

@@ -3,6 +3,10 @@ type: text/vnd.tiddlywiki-multiple
 tags: [[$:/tags/wiki-test-spec]]
 description: Simple transclusion
 
+title: Narrative
+
+This testcase demonstrates transclusion of and links to other tiddlers.
++
 title: Output
 
 Good morning, my [[name|Name]] is {{Name}} and I [[live in|Address]] {{Address}}

editions/tw5.com/tiddlers/widgets/DataWidget.tid

@@ -1,6 +1,6 @@
 caption: data
-created: 20230406161341763
-modified: 20230406161341763
+created: 20240507221902644
+modified: 20240507221902644
 tags: Widgets
 title: DataWidget
 type: text/vnd.tiddlywiki
@@ -21,23 +21,23 @@ The content of the data widget is ignored. It supports the following attributes:
 
 The data widget is not rendered when used within the <<.wlink TestCaseWidget>> widget or the [[Innerwiki Plugin]] but for ease of testing, when used elsewhere it renders a JSON representation of the payload tiddlers.
 
-Without any of the attributes <<.attr $tiddler>>, <<.attr $filter>> or <<.attr $compound-tiddler>>, any attributes whose name does not start with $ are used as the field values for creating a single new tiddler. For example, here a tiddler with the title "Epsilon" and the text "Theta" is created:
+Without any of the attributes <<.attr $tiddler>>, <<.attr $filter>> or <<.attr $compound-tiddler>>, any attributes whose name does not start with $ are used as the field values for creating a single new tiddler.
 
 <<testcase "TestCases/DataWidget/SimpleTiddler">>
 
 If any of the attributes <<.attr $tiddler>>, <<.attr $filter>> or <<.attr $compound-tiddler>> are specified then they are used to generate base tiddlers that are then modified with the addition of fields derived from any attributes whose name does not start with $.
 
-This example, here we specify a copy of the "HelloThere" tiddler with the addition of the field "custom" set to "Alpha":
+The attribute <<.attr $tiddler>> is used to ingest a single tiddler from the wiki containing the data widget:
 
 <<testcase "TestCases/DataWidget/ImportedTiddler">>
 
-This example injects all image tiddlers with the addition of the field "custom" set to "Beta":
+The attribute <<.attr $filter>> is used to ingest multiple tiddlers from the wiki containing the data widget:
 
 <<testcase "TestCases/DataWidget/ImportedFilter">>
 
 ! Compound Tiddlers
 
-Compound tiddlers provide a way to easily create multiple tiddlers from within a single tiddler. They are contained in tiddlers of type `text/vnd.tiddlywiki-multiple`. 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.
+[[Compound tiddlers|CompoundTiddlers]] provide a way to easily create multiple tiddlers from within a single tiddler. They are contained in tiddlers of type `text/vnd.tiddlywiki-multiple`. 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.
 
 <<testcase "TestCases/DataWidget/ImportCompound">>
 

editions/tw5.com/tiddlers/widgets/TestCaseWidget.tid

@@ -1,6 +1,6 @@
 caption: testcase
-created: 20230406161341763
-modified: 20230406161341763
+created: 20240507221902644
+modified: 20240507221902644
 tags: Widgets
 title: TestCaseWidget
 type: text/vnd.tiddlywiki
@@ -13,14 +13,14 @@ This makes it possible to run independent tests that also serve as documentation
 
 !! 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.
+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.
 
 <<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.
-
 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 <<.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:
@@ -29,9 +29,9 @@ If the test fails, a red cross is shown, and there is a display of the differenc
 
 !! 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.
+The <<.wid 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 testcase.
 
-Note that the testcase wiki will inherit variables that are visible to the <<.wid testcase>> widget itself.
+Note that the rendering of the testcase wiki will inherit variables that are visible to the <<.wid testcase>> widget itself.
 
 ! Limitations
 
@@ -63,6 +63,14 @@ The payload tiddlers are the tiddler values that are loaded into the subwiki tha
 
 The <<.attr template>> attribute defaults to $:/core/ui/testcases/DefaultTemplate
 
+The default testcase 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 default template uses several variables that can be set by the user:
 
 |!Variable |!Description |
@@ -82,16 +90,16 @@ The <<.wid testcase>> widget makes the following variables available within the
 |<<.var expectedHTML>> |The expected output HTML if running tests |
 |<<.var testResult>> |The tests result if running tests (may be "pass" or "fail") |
 
-! Examples
+! Example
 
 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>"/>
+    <$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>

themes/tiddlywiki/vanilla/base.tid

@@ -3232,6 +3232,11 @@ span.tc-translink > a:first-child {
 	border-radius: 6px;
 }
 
+.tc-tiddler-frame .tc-testcase-wrapper {
+	margin-left: -0.5em;
+	margin-right: -0.5em;
+}
+
 .tc-testcase-wrapper {
 	background-color: <<colour testcase-accent-level-1>>;
 }
@@ -3295,8 +3300,10 @@ span.tc-translink > a:first-child {
 }
 
 .tc-testcase-result-fail-header {
-	background: <<colour foreground>>;
-	color: <<colour background>>;
+	background: <<colour diff-delete-background>>;
+	color: <<colour diff-delete-foreground>>;
+	border-top-left-radius: 4px;
+	border-top-right-radius: 4px;
 	padding: 4px;
 }
 
@@ -3308,6 +3315,10 @@ span.tc-translink > a:first-child {
 	height: 100%;
 }
 
+.tc-testcase-narrative {
+	padding: 0.5em;
+}
+
 .tc-testcase-panes {
 	display: flex;
 	align-items: stretch;
@@ -3354,7 +3365,7 @@ span.tc-translink > a:first-child {
 	border: 1px solid <<colour foreground>>;
 	flex: 1 0 49%;
 	min-width: 250px;
-	padding: 0.25em;
+	padding: 0.25em 1em;
 }
 
 /*