Add <$testcase> widget

[Jermolene]

This PR adds a new <$testcase> widget to try to solve a problem with the examples that we feature in the documentation. The existing macros are workable for simple, self-contained examples, but can be extremely hard to follow in cases where the examples are also using additional tiddlers. The <$testcase> widget solves that problem by displaying interactive examples that show the output together with a tabbed display of the constituent tiddlers that produce it:

Try out the Vercel preview

The testcase widget is essentially a lightweight version of the existing <$innerwiki> plugin. It constructs an entirely separate wiki store object, fills it with the required tiddlers, and then renders a template that by default provides the tabbed view of the source tiddlers alongside the output.

The example above was generated with:

<$testcase>
<$data title="Description" text="How to calculate 2 plus 2"/>
<$data title="FirstNumber" text="2"/>
<$data title="SecondNumber" text="2"/>
<$data title="Output" text="<$text text={{{ [{FirstNumber}add{SecondNumber}] }}}/>"/>
</$testcase>

The <$data> widget that originated in the <$innerwiki> plugin is moved into the core and extended with support for reading tiddlers from "compound tiddlers", which are the special format used by the test suite for embedding multiple tiddlers within a single tiddler. Here is an example.

Our test cases are a useful form of documentation. The ultimate goal of this work is to be able to include our wikitext tests suite within the main documentation of TiddlyWiki. Advanced users wondering how \function works could dig down into potentially dozens of test cases to explore the behaviour of edge cases.

Progress:

• Update some of the existing tw5.com examples to use the <$testcase> widget

This PR was cherry picked from #7406.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
tiddlywiki5	✅ Ready (Inspect)	Visit Preview	May 15, 2024 11:40am

[pmario]

Looks good. Will need to run some tests.

[Jermolene]

Thanks @pmario I've pushed an update to fix those issues

[CodaCodr]

RSOE
You can see the cursor in the screenshot

[Jermolene]

Thanks @CodaCodr I've just pushed a fix.

[CodaCodr]

Thanks @CodaCodr I've just pushed a fix.

confirmed.

[CodaCodr]

Look Mum! No ActionWidgets!

[DesignThinkerer]

CSS affect tiddlers outside of the testcase, is that intended?

[Jermolene]

CSS affect tiddlers outside of the testcase, is that intended?

The testcase widget shares the same rendering context as the main wiki and so CSS and other globla DOM properties are shared. In such cases the innerwiki widget can be used to create an entirely separate embedded wiki.

The purpose of the testcase widget is to be a lighter weight and more performant version of the innerwiki widget. It wouldn't be practical to use the innerwiki widget for hundreds of documentation examples; each of those iframes would overwhelm a mobile device.

The documentation needs to clarify the limitations and constraints of the testcase widget.

[btheado]

when used elsewhere it renders a JSON representation of the payload tiddlers

I'm not able to get this behavior to work. Outside of the testcase widget, I find the data widget to render empty.

[Jermolene]

Thanks @btheado I had replaced that feature of the data widget with the ability for the testcase widget to display its payload in JSON via a special template. I've pushed an update with the docs in 0db4c44 that explains how to do that. I've also added the JSON output feature back to the data widget in 1d89c79 with tests in 0db4c44

[btheado]

Mention the other core provided template $:/core/ui/testcases/RawJSONTemplate as being useful for troubleshooting $data widgets?

[btheado]

It might be useful to add a linkcatcher widget here and select the tab corresponding to the clicked link?

[Jermolene]

Thank you @btheado I've belatedly implemented your suggestion in Thank you @btheado in 648855e

[btheado]

Thanks. Works great!

[btheado]

@Jermolene, nice improvements! I like that test case tiddler titles are links to open the tiddler separately. Very useful. I also like the new Narrative feature.

The test case tiddlers and test case widget seem like a really good replacement for the wikitext-example-without-html macro. Having the widget examples be live-editable will be a great improvement. One nice feature of the wikitext-example macro is the "copy to clipboard" button. Have any thoughts about the equivalent for the test case widget?

Being able to easily copy the text of the example is useful. In addition or instead, maybe an easy way to get the json for all the tiddlers in the test case widget?

Tagging @AnthonyMuscio as I've seen him advocate for more use of "copy to clipboard" in the past.

[btheado]

Originally I was thinking all the uses of wikitext-example-without-html would be converted to test case tiddlers. Maybe that isn't necessary. A least as a first step is much easier to change the macro to use the test case widget.

For example, at https://tiddlywiki5-git-testcase-widget-jermolenes-projects.vercel.app/#%24%3A%2Feditions%2Ftw5.com%2Fwikitext-macros

Change this

\procedure wikitext-example-without-html(src)
<div class="doc-example">
	<$macrocall $name="copy-to-clipboard-above-right" src=<<src>>/>
	<$codeblock code=<<src>>/>
	<p>
		That renders as:
	</p>
	<$transclude $variable="src" $mode="block"/>
</div>
\end

to this

\procedure wikitext-example-without-html(src)
    <$macrocall $name="copy-to-clipboard-above-right" src=<<src>>/>
    <$testcase>
        <$data title="Output" text=<<src>>/>
    </$testcase>
\end

[btheado]

I'm seeing some strange rendering behavior regarding <<currentTiddler>> variable

With the following test case tiddler, the test case is passing. It must be finding <<currentTiddler>> to match Output

However, visibly I see it rendered as TestCases/TestCaseTiddler/currentTiddler rather than Output.

created: 20240510013024332
description: currentTiddler should be properly set
modified: 20240510013609588
tags: $:/tags/wiki-test-spec
title: TestCases/TestCaseTiddler/currentTiddler
type: text/vnd.tiddlywiki-multiple

title: Narrative

currentTiddler variable in Output tiddler should be "Output"
+
title: Output

<$text text=<<currentTiddler>>>
+
title: ExpectedResult

<p>Output</p>

Here is a json attachement of the tiddler: TestCases_TestCaseTiddler_currentTiddler.json

Edit: I see the same issue (not surprisingly) by directly using the testcase widget

<$testcase testOutput="Output" testExpectedResult="ExpectedResult">
  <$data title="Description" text="<<currentTiddler>> should render as 'Output'"/>
  <$data title="Output" text="<<currentTiddler>>"/>
  <$data title="ExpectedResult" text="<p>Output</p>"/>
</$testcase>

[Jermolene]

Thanks @btheado

The test case tiddlers and test case widget seem like a really good replacement for the wikitext-example-without-html macro.

Yes, although given that these examples only have a single payload tiddler perhaps it would be nicer to use a more streamlined template.

Having the widget examples be live-editable will be a great improvement. One nice feature of the wikitext-example macro is the "copy to clipboard" button. Have any thoughts about the equivalent for the test case widget?

Being able to easily copy the text of the example is useful. In addition or instead, maybe an easy way to get the json for all the tiddlers in the test case widget?

Great idea, I agree. We should have both a "copy to clipboard" button on each source tiddler, and a way to drag and drop the tiddlers to another wiki (or the host wiki), and to save the JSON directly.

Originally I was thinking all the uses of wikitext-example-without-html would be converted to test case tiddlers. Maybe that isn't necessary. A least as a first step is much easier to change the macro to use the test case widget.

Yes, that's an excellent idea. We should still aim to convert the usages to test case tiddlers so that we can specify ExpectedResult, and hence run them as tests.

I'm seeing some strange rendering behavior regarding <<currentTiddler>> variable

Ouch, I will investigate. I'm not surprised to see this kind of wrinkle; the testcase widget mixes widgets from different wikis in a way that hasn't been tested before.

[btheado]

Yes, although given that these examples only have a single payload tiddler perhaps it would be nicer to use a more streamlined template.

There are still many examples for which the default template is very instructive. Whenever an example such as the RevealWidget creates a tiddler, a new tab appears. For a learner, that makes it easy to see what changes are happening.

A least as a first step is much easier to change the macro to use the test case widget.

But even this approach requires caution. There are many examples which depend on tiddlers in the main wiki. For example (just a partial list):

• DiffTextWidget - uses SampleTiddlerFirst and SampleTiddlerSecond tiddlers
• SetMultipleVariablesWidget - assumes presence of HelloThere tiddler
• SetWidget - a few of these examples assume presence of tiddlers tagged HelloThere.
• Conditional Shortcut Syntax tiddler assumes the presence of $:/info/url/protocol tiddler, but no [prefix[$:/info]] tiddlers are propagated to the subwiki by default.

[Jermolene]

I'm seeing some strange rendering behavior regarding <<currentTiddler>> variable

Thanks @btheado this is now fixed in eb4e9d8

There are still many examples for which the default template is very instructive

Yes, that's very true.

But even this approach requires caution

Good point. My instinct is to merge this quite soon, and then we can tackle updating the examples gradually. One advantage of the structure introduced in this PR is that the testcases are part of the tw5.com wiki, and can thus be updated directly to tiddlywiki.com because they are part of the documentation.

[btheado]

Thanks @btheado this is now fixed in eb4e9d8

Great, thanks.

My instinct is to merge this quite soon, and then we can tackle updating the examples gradually

For sure, I agree.