I’ve started to sketch out the first Subplot document for Subplot. The goal is to have Subplot to test itself. The approach is to run the program with specific inputs, and examine the results. The inputs will be the Markdown, YAML, and Python files that Subplot needs to do its thing. This raises the question how those files should be stored. A few possible approaches:
Provide the files adjacent to the subplot.md file that is the Subplot self-testing file. This would mean the acceptance tests use test data that’s not evident in the output document of Subplot, making them hard to examine unless one has access to the document source code.
Embed the file data into the scenarios. This is what Subplot’s predecessor yarn did. It tends to result in tediously long scenarios. Tedious to read, tedious to write, tedious to change. On the other hand, this would make the test data evident and not require changes to current Subplot code.
Embed the file data in the Markdown document, and have Subplot extract it for the generated test program. This would require changing Subplot to support that, but seems otherwise ideal. Markdown, as implemented Pandoc, is fairly good at this, and Pandoc can even do syntax highlighting if, for example, the data is in a YAML format.
I’m leaning strongly towards the last approach. It seems like the best approach for editing comfort, while keeping the test data evident to all stakeholders.
The syntax would look something like below, which is an example of a test data file containing a Subplot document.
~~~~~{.file #simple.md .markdown numberLines}
---
title: Test scenario
bindings: b.yaml
functions: f.py
...
# Simple
This is the simplest possible test scenario
```subplot
given precondition foo
when I do bar
then bar was done
```
~~~~~Pandoc allows attributes to fenced code blocks. Above, we declare the block is a file, in markdown, and its lines should be numbered. Subplot would require the .file attribute to recognize it as a file. The #simple.md identifier is used to give the name of the file, so it can be referred to from test scenarios. The generated test program will know how to get the file contents using the identifier.
The rest of the attributes are optional, but allow Pandoc to typeset the file nicely.