mdtest

Documentation

Overview

Package mdtest finds example shell commands in Markdown files and runs them, checking for expected output and exit status.

Example inputs, commands, and outputs are specified in fenced code blocks whose info string (https://spec.commonmark.org/0.29/#info-string) has mdtest-input, mdtest-command, or mdtest-output as the first word. The mdtest-command and mdtest-output blocks must be paired.

```mdtest-input file.txt
hello
```
```mdtest-command [dir=...] [fails]
cat file.txt
```
```mdtest-output [head]
hello
```

The content of each mdtest-command block is fed to "bash -e -o pipefail" on standard input.

The shell's working directory is a temporary directory populated with files described by any mdtest-input blocks in the same Markdown file and shared by other tests in the same file. Alternatively, if the mdtest-command block's info string contains a word prefixed with "dir=", the rest of that word specifies the shell's working directory as a path relative to the repository root, and files desribed by mdtest-input blocks are not available.

The shell's exit status must indicate success (i.e., be zero) unless the mdtest-command block's info string contains the word "fails", in which case the exit status must indicate failure (i.e. be nonzero).

The shell's combined standard output and standard error must exactly match the content of the following mdtest-output block unless that block's info string contains the word "head", in which case any "...\n" suffix of the block content is ignored, and what remains must be a prefix of the shell output.

```mdtest-command
echo hello
echo goodbye
```
```mdtest-output head
hello
...
```

Index

• type File
  • func Load() ([]*File, error)
  • func (f *File) Run(t *testing.T)
• type Test
  • func (t *Test) Run() error

Types

type File

type File struct {
	Path   string
	Inputs map[string]string
	Tests  []*Test
}

File represents a Markdown file and the tests it contains.

func Load

func Load() ([]*File, error)

Load walks the file tree rooted at the current working directory, looking for Markdown files containing tests. Any file whose name ends with ".md" is considered a Markdown file. Files containing no tests are ignored.

func (*File) Run

func (f *File) Run(t *testing.T)

Run runs the file's tests. It runs relative-directory-style tests (Test.Dir != "") in parallel, with the shell working directory set to Test.Dir, and it runs temporary-directory-style tests (Test.Dir == "") sequentially, with the shell working directory set to a shared temporary directory.

type Test

type Test struct {
	Command   string
	Dir       string
	Expected  string
	Fails     bool
	Head      bool
	Line      int
	GoExample string
}

Test represents a single test in a Markdown file.

func (*Test) Run

func (t *Test) Run() error

Run runs the test, returning nil on success.