testmd

README

Test

Test is a simple golang test utils package.

test.File

test.File implements a simple file testing utility that:

1. reads input file in the testdata/ directory into a string
2. runs this against the provided test function
3. compares against the contents of the output file (also in the testdata/ directory)
4. reports discrepancies in the diff format (such as the one used by git)

It also accepts a -golden flag which when specified skips the comparison and instead saves the output provided by the function into the output file. This makes creation of initial output files and updates relatively easy

test.Markdown

Markdown() converts a set of code snippets in markdown into test cases. For example:

if len("hello") != 5 {
	fmt.Println("This should not happen")
}

// Output:

The above snippet is converted to an ExampleXXX() which runs the code.

Snippets can also be named, with ability to import code from elsewhere:

// import runtime
_, fname, _, _ := runtime.Caller(1)
if fname == "" {
	t.Error("Could not find caller info")
}

The name of the snippet must be TestXYZ or ExampleXYZ or just a plain function (presumably for use in other snippets). Two sepcial cases are "skip" to indicate the fence block should not be considered testable and "global" to indicate the fence block is a global variable:

   // this has sample code that is not expected to compile
   booya

fmt.Println("ok", stranger())

// Output: ok stranger

If the info name has a dot in it, the word before the dot is compared to the package name. If they don't match the fence block is skipped. This allows a single markdown to have multiple fence blocks destined for different packages:

...

...

Documentation

Overview

Command testmd generates test files out of markdown snippets

$ go get github.com/tvastar/test/cmd/testmd

This is useful when writing tutorials in markdown and making sure all the tutorials remain valid as the code underneath changes

If no output file is specified (via -o), a temporary go file is generated and it is immediately run via `go test`. Any additional arguments are passed through to go test.

If a package name is provided and it does not include '_test', it will be assumed to be a runnable go program and "go run" will be used instead of "go test".

The snippets of code must use the markdown code fence with an info string starting with "go" (i.e. go or golang)

Additional fields on the info string can provide the name of the test:

```golang TestSomething
   ..some stuff here..
```

If the name starts with anything but Test, an empty function with no args is produced which conveniently works for Examples

Global variables can be introduced by using the special name of global:

```golang global
var hidden := flag.Bool("hidden", false, "is it hidden?")
```

Snippets can be marked to be ignored:

```golang skip
   ..some stuff here..
```

A single markdown can be used to generate multiple package entries. A snippet can be designated as being limited to a specific package by using the name of the package:

```golang script_one.global
   ..some stuff here..
```

The snippet above will only be included if the package name is script_one. This is useful when describing multiple main package options in one tutorial.

Snippets can indicate import paths via a comment:

```golang
// import fmt
..some stuf here..
```

Usage:

$ testmd -pkg readme_test -o readme_test.go *.md
$ testmd README.md -v

Note: all options must come before the markdown file names.

Any options provided after the markdown file names will be passed through to `go test` (if no output is specified).