Testmark
{Docs = Fixtures = Data = Codeblocks} ∈ markdown
hi
i'm warpfork
github.com/warpfork
twitter.com/warpfork
slides.com/warpfork
(this is going to be the simplest talk ever)
Testmark
========
It's regular markdown!
[testmark]:# (the-data-name/goes-here.json)
```json
{"this is": "your data block",
"as big": "as you like"}
```
That codeblock is readable -- and patchable! --
using testmark libraries.
Testmark
========
It's regular markdown!
[testmark]:# (the-data-name/goes-here.json)
```json
{"this is": "your data block",
"as big": "as you like"}
```
That codeblock is readable -- and patchable! --
using testmark libraries.
Seriously, it's... regular markdown.
h1
text
codeblock
Testmark
========
It's regular markdown!
[testmark]:# (the-data-name/goes-here.json)
```json
{"this is": "your data block",
"as big": "as you like"}
```
That codeblock is readable -- and patchable! --
using testmark libraries.
This is the testmark data hunk body.
Testmark
========
It's regular markdown!
[testmark]:# (the-data-name/goes-here.json)
```json
{"this is": "your data block",
"as big": "as you like"}
```
That codeblock is readable -- and patchable! --
using testmark libraries.
This is a markdown "comment".
This is where we put the data block label, in testmark.
Testmark
========
It's regular markdown!
[testmark]:# (the-data-name/goes-here.json)
```json
{"this is": "your data block",
"as big": "as you like"}
```
That codeblock is readable -- and patchable! --
using testmark libraries.
Testmark is just... libraries for parsing this bit.
WHY!?
it filled a big burning hole in my heart.
- I need to write docs!
- The docs need to contain examples!
- The examples get out of date
if they aren't part of the test suite!
- Duplicating the test suites into the docs
manually sucks!
- Out of date docs kill projects!
...that basically spelled "markdown"
- I wanted something simple.
- I want it to be something people already use.
- I want it to be easy to get into a website.
- I want it to be easy to get into github.
Where are the libraries?
Three libraries exist to date:
Add one for your language too!
How is it implemented?
1. split by line
3. look for [testmark]:#
before the tripletick
2. seek for ```
(toggle mode when you find it)
1. split by line
3. look for [testmark]#
before the tripletick
2. seek for ```
(toggle mode when you find it)
This is a very easy parser.
It's also entirely correct.
And if you just remember line numbers of tripletick...
It's enough to do patching.
Patching
Let's say I want to regenerate some fixture data!
That should be easy.
Patching
(works best when it's simple)
Patching
1. Only alter the inside of code blocks.
2. Alter nothing else.
3. Hooray: it won't reformat your markdown. Foolproof. Extension-proof!
Patching
In golang, we made a convention of enabling fixture regen by running:
go test ./... -testmark.regen
Makes maintaining large suites of test fixtures easy: make changes; run that; then just review the `git diff` to see the effects.
Testmark
========
It's regular markdown!
[testmark]:# (the-data-name/goes-here.json)
```json
{"this is": "your data block",
"as big": "as you like"}
```
That codeblock is readable -- and patchable! --
using testmark libraries.
(...moment of zen...)
Bonus Conventions
& Extensions
Data hunk names as a filesystem
Some testmark libraries have helper functions for walking "dirs", globbing, etc.
Often useful for organizing suites of related tests!
You can name things like filesystems.
[testmark]:# (some/dirs/filename.json)
```json
{"data": "data!"}
```
[testmark]:# (some/dirs/otherfile.wat)
```text
no sweat
```
Libraries can help with this.
(Depends on the library.)
testexec!
(currently only in golang)
Use a callback if you want control. Or just use exec to the shell!
Auto-regen of output is built-in!
Test scripts easily:
[testmark]:# (using-stdin/input)
```
this is stdin and will be echoed
```
Note the "filenames" in a "dir" together:
[testmark]:# (using-stdin/script)
```
cat - | sed 's/ is/ was/' | sed s/will/should/
```
And this is the assertion:
[testmark]:# (using-stdin/output)
```
this was stdin and should be echoed
```Usage in the Wild!
The IPLD specs use Testmark.
The IPLD tests use Testmark.
Warpforge uses Testmark.
Warpforge uses Testmark.
Compared to...
campoy/embedmd
Kinda goes the opposite direction: you write lots of files; embedmd yeets them into your md files.
I used to use it! Personally, I found it caused me a lot of headaches; I keep wanting to edit the md file, and then stubbing my toe hard.
just json files?
Okay for fixtures.
(Still not super fun to read.)
((Multiline docs, ow.))
Not great for human-readable docs or website emission (without a lot more tooling).
txtar?
A neat little format for putting multiple files into one file, popular in golang.
Comparable, in a way.
But I find testmark can produce pretty results,
and encourage me to write good narrative docs.
txtar doesn't.
comment1
txtar
comment2
-- file1 --
File 1 text.
-- foo ---
More file 1 text.
-- file 2 --
File 2 text.
-- empty --
-- file 3 --
File 3 text.... in general?
If you want something that encourages you to write a story and real examples at the same time...
Then testmark may be what you're looking for.
Testmark
========
It's regular markdown!
[testmark]:# (the-data-name/goes-here.json)
```json
{"this is": "your data block",
"as big": "as you like"}
```
That codeblock is readable -- and patchable! --
using testmark libraries.
Please Enjoy!
testmark
By warpfork
testmark
Brief intro to the Testmark file format, for test fixture data and living documentation together in markdown. First airs at GPN2022.
