From 0db4c449397c0b30498c5e052e9fcb80bed90541 Mon Sep 17 00:00:00 2001
From: Jeremy Ruston
Date: Mon, 6 May 2024 15:37:03 +0100
Subject: [PATCH] Clearer testcases for data widget, and docs tweaks
---
.../tests/data/data-widget/ImportFilter.tid | 25 ----------
.../tests/data/data-widget/ImportTiddler.tid | 20 --------
.../tests/data/data-widget/Simple.tid | 15 ------
.../testcases/DataWidget}/ImportCompound.tid | 18 +++++--
.../testcases/DataWidget/ImportedFilter.tid | 48 +++++++++++++++++++
.../testcases/DataWidget/ImportedTiddler.tid | 28 +++++++++++
.../testcases/DataWidget/SimpleTiddler.tid | 21 ++++++++
.../tw5.com/tiddlers/widgets/DataWidget.tid | 18 +++----
.../tiddlers/widgets/TestCaseWidget.tid | 41 +++++++---------
9 files changed, 135 insertions(+), 99 deletions(-)
delete mode 100644 editions/test/tiddlers/tests/data/data-widget/ImportFilter.tid
delete mode 100644 editions/test/tiddlers/tests/data/data-widget/ImportTiddler.tid
delete mode 100644 editions/test/tiddlers/tests/data/data-widget/Simple.tid
rename editions/{test/tiddlers/tests/data/data-widget => tw5.com/tiddlers/testcases/DataWidget}/ImportCompound.tid (60%)
create mode 100644 editions/tw5.com/tiddlers/testcases/DataWidget/ImportedFilter.tid
create mode 100644 editions/tw5.com/tiddlers/testcases/DataWidget/ImportedTiddler.tid
create mode 100644 editions/tw5.com/tiddlers/testcases/DataWidget/SimpleTiddler.tid
diff --git a/editions/test/tiddlers/tests/data/data-widget/ImportFilter.tid b/editions/test/tiddlers/tests/data/data-widget/ImportFilter.tid
deleted file mode 100644
index 318445d69..000000000
--- a/editions/test/tiddlers/tests/data/data-widget/ImportFilter.tid
+++ /dev/null
@@ -1,25 +0,0 @@
-title: Data/ImportFilter
-type: text/vnd.tiddlywiki-multiple
-tags: [[$:/tags/wiki-test-spec]]
-description: Importing a payload filter and adding custom fields
-
-title: Output
-
-\whitespace trim
-<$testcase template="$:/core/ui/testcases/RawJSONTemplate">
-<$data $filter="[tag[Definitions]]" custom="Alpha"/>
-$testcase>
-+
-title: HelloThere
-tags: Definitions
-
-This is the tiddler HelloThere
-+
-title: AnotherDefinition
-tags: Definitions
-
-This is the tiddler AnotherDefinition
-+
-title: ExpectedResult
-
-[{"title":"AnotherDefinition","tags":"Definitions","text":"This is the tiddler AnotherDefinition","custom":"Alpha"},{"title":"HelloThere","tags":"Definitions","text":"This is the tiddler HelloThere","custom":"Alpha"}]
\ No newline at end of file
diff --git a/editions/test/tiddlers/tests/data/data-widget/ImportTiddler.tid b/editions/test/tiddlers/tests/data/data-widget/ImportTiddler.tid
deleted file mode 100644
index 99bb0ce3a..000000000
--- a/editions/test/tiddlers/tests/data/data-widget/ImportTiddler.tid
+++ /dev/null
@@ -1,20 +0,0 @@
-title: Data/ImportTiddler
-type: text/vnd.tiddlywiki-multiple
-tags: [[$:/tags/wiki-test-spec]]
-description: Importing a payload tiddler and adding custom fields
-
-title: Output
-
-\whitespace trim
-<$testcase template="$:/core/ui/testcases/RawJSONTemplate">
-<$data $tiddler="HelloThere" custom="Alpha"/>
-$testcase>
-+
-title: HelloThere
-tags: Definitions
-
-This is the tiddler HelloThere
-+
-title: ExpectedResult
-
-[{"title":"HelloThere","tags":"Definitions","text":"This is the tiddler HelloThere","custom":"Alpha"}]
\ No newline at end of file
diff --git a/editions/test/tiddlers/tests/data/data-widget/Simple.tid b/editions/test/tiddlers/tests/data/data-widget/Simple.tid
deleted file mode 100644
index ae63f40cf..000000000
--- a/editions/test/tiddlers/tests/data/data-widget/Simple.tid
+++ /dev/null
@@ -1,15 +0,0 @@
-title: Data/Simple
-type: text/vnd.tiddlywiki-multiple
-tags: [[$:/tags/wiki-test-spec]]
-description: Standalone data widget to create individual tiddlers
-
-title: Output
-
-\whitespace trim
-<$testcase template="$:/core/ui/testcases/RawJSONTemplate">
-<$data title="Epsilon" text="Theta"/>
-$testcase>
-+
-title: ExpectedResult
-
-[{"title":"Epsilon","text":"Theta"}]
\ No newline at end of file
diff --git a/editions/test/tiddlers/tests/data/data-widget/ImportCompound.tid b/editions/tw5.com/tiddlers/testcases/DataWidget/ImportCompound.tid
similarity index 60%
rename from editions/test/tiddlers/tests/data/data-widget/ImportCompound.tid
rename to editions/tw5.com/tiddlers/testcases/DataWidget/ImportCompound.tid
index 174469009..b7f80629c 100644
--- a/editions/test/tiddlers/tests/data/data-widget/ImportCompound.tid
+++ b/editions/tw5.com/tiddlers/testcases/DataWidget/ImportCompound.tid
@@ -1,14 +1,13 @@
-title: Data/ImportCompound
+title: TestCases/DataWidget/ImportCompound
type: text/vnd.tiddlywiki-multiple
tags: [[$:/tags/wiki-test-spec]]
description: Importing a compound payload tiddler and adding custom fields
title: Output
-\whitespace trim
-<$testcase template="$:/core/ui/testcases/RawJSONTemplate">
+
<$data $compound-tiddler="Compound" custom="Alpha"/>
-$testcase>
+
+
title: Compound
type: text/vnd.tiddlywiki-multiple
@@ -21,4 +20,13 @@ This is a payload tiddler from a compound tiddler
+
title: ExpectedResult
-[{"title":"Payload Tiddler","tags":"Alpha Beta Gamma","text":"This is a payload tiddler from a compound tiddler","custom":"Alpha"}]
\ No newline at end of file
+
+[
+ {
+ "title": "Payload Tiddler",
+ "tags": "Alpha Beta Gamma",
+ "text": "This is a payload tiddler from a compound tiddler",
+ "custom": "Alpha"
+ }
+]
+
\ No newline at end of file
diff --git a/editions/tw5.com/tiddlers/testcases/DataWidget/ImportedFilter.tid b/editions/tw5.com/tiddlers/testcases/DataWidget/ImportedFilter.tid
new file mode 100644
index 000000000..024fbaaba
--- /dev/null
+++ b/editions/tw5.com/tiddlers/testcases/DataWidget/ImportedFilter.tid
@@ -0,0 +1,48 @@
+title: TestCases/DataWidget/ImportedFilter
+type: text/vnd.tiddlywiki-multiple
+tags: [[$:/tags/wiki-test-spec]]
+description: Imported filter definition
+
+title: Output
+
+
+<$data $filter="[prefix[Day: T]]" custom="Beta"/>
+
++
+title: Day: Monday
+text: Today is Monday
++
+title: Day: Tuesday
+text: Today is Tuesday
++
+title: Day: Wednesday
+text: Today is Wednesday
++
+title: Day: Thursday
+text: Today is Thursday
++
+title: Day: Friday
+text: Today is Friday
++
+title: Day: Saturday
+text: Today is Saturday
++
+title: Day: Sunday
+text: Today is Sunday
++
+title: ExpectedResult
+
+
+[
+ {
+ "title": "Day: Thursday",
+ "text": "Today is Thursday",
+ "custom": "Beta"
+ },
+ {
+ "title": "Day: Tuesday",
+ "text": "Today is Tuesday",
+ "custom": "Beta"
+ }
+]
+
\ No newline at end of file
diff --git a/editions/tw5.com/tiddlers/testcases/DataWidget/ImportedTiddler.tid b/editions/tw5.com/tiddlers/testcases/DataWidget/ImportedTiddler.tid
new file mode 100644
index 000000000..88be0a4a7
--- /dev/null
+++ b/editions/tw5.com/tiddlers/testcases/DataWidget/ImportedTiddler.tid
@@ -0,0 +1,28 @@
+title: TestCases/DataWidget/ImportedTiddler
+type: text/vnd.tiddlywiki-multiple
+tags: [[$:/tags/wiki-test-spec]]
+description: Imported tiddler definition
+
+title: Output
+
+
+<$data $tiddler="HelloThere" custom="Alpha"/>
+
++
+title: HelloThere
+modifier: JoeBloggs
+
+This is the HelloThere tiddler
++
+title: ExpectedResult
+
+
+[
+ {
+ "title": "HelloThere",
+ "modifier": "JoeBloggs",
+ "text": "This is the HelloThere tiddler",
+ "custom": "Alpha"
+ }
+]
+
\ No newline at end of file
diff --git a/editions/tw5.com/tiddlers/testcases/DataWidget/SimpleTiddler.tid b/editions/tw5.com/tiddlers/testcases/DataWidget/SimpleTiddler.tid
new file mode 100644
index 000000000..cc7a64585
--- /dev/null
+++ b/editions/tw5.com/tiddlers/testcases/DataWidget/SimpleTiddler.tid
@@ -0,0 +1,21 @@
+title: TestCases/DataWidget/SimpleTiddler
+type: text/vnd.tiddlywiki-multiple
+tags: [[$:/tags/wiki-test-spec]]
+description: Simple tiddler definition
+
+title: Output
+
+
+<$data title="Epsilon" text="Theta"/>
+
++
+title: ExpectedResult
+
+
+[
+ {
+ "title": "Epsilon",
+ "text": "Theta"
+ }
+]
+
\ No newline at end of file
diff --git a/editions/tw5.com/tiddlers/widgets/DataWidget.tid b/editions/tw5.com/tiddlers/widgets/DataWidget.tid
index 143d462d4..c162f44b6 100644
--- a/editions/tw5.com/tiddlers/widgets/DataWidget.tid
+++ b/editions/tw5.com/tiddlers/widgets/DataWidget.tid
@@ -23,29 +23,25 @@ The data widget is not rendered when used within the <<.wlink TestCaseWidget>> w
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:
-```
-<$data title="Epsilon" text="Theta"/>
-```
+<>
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":
-```
-<$data $tiddler="HelloThere" custom="Alpha"/>
-```
+<>
This example injects all image tiddlers with the addition of the field "custom" set to "Beta":
-```
-<$data $filter="[is[image]]" custom="Beta"/>
-```
+<>
! 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.
-For example:
+<>
+
+Here is a more complex example of the content of a compound tiddler:
```
title: First
@@ -62,4 +58,4 @@ title: third
tags: five six
This is the third tiddler
-```
\ No newline at end of file
+```
diff --git a/editions/tw5.com/tiddlers/widgets/TestCaseWidget.tid b/editions/tw5.com/tiddlers/widgets/TestCaseWidget.tid
index aefac685b..faf488c4b 100644
--- a/editions/tw5.com/tiddlers/widgets/TestCaseWidget.tid
+++ b/editions/tw5.com/tiddlers/widgets/TestCaseWidget.tid
@@ -9,33 +9,21 @@ type: text/vnd.tiddlywiki
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.
-The default template 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. This makes it possible to run independent tests that also serve as documentation examples.
-
-For example:
-
-{{TestCases/TranscludeWidget/SimpleTransclusion||$:/core/ui/TestCaseTemplate}}
+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.
+
+<>
+
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 it a test has been set up and that it passes.
+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, then the differences are shown:
+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:
-{{TestCases/TestCaseWidget/FailingTest||$:/core/ui/TestCaseTemplate}}
-
-To be more precise, the rendered HTML output matches the expected test results.
-
-<$testcase>
-<$data title="Description" text="Simple 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="8
"/>
-$testcase>
-"""/>
-$testcase>
+<>
!! Usage
@@ -67,6 +55,10 @@ The content of the `<$testcase>` widget is not displayed but instead is scanned
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 but can be used to specify a custom template for special purposes. The provided template $:/core/ui/testcases/RawJSONTemplate can be used for debugging purposes to display all of the payload widgets in JSON.
+
! Testcase Template Variables
The <<.wid testcase>> widget makes the following variables available within the rendered template:
@@ -78,13 +70,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") |
-! Example
+! Examples
+
+Here is an example of setting up a testcase that includes expected test results:
<$testcase>
-<$data title="Description" text="Simple example of a testcase"/>
-<$data title="Output" text="""<$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="8
"/>
$testcase>
"""/>
$testcase>