test

README

Test

Test is a simple golang test utils package.

test.Artifact

test.Artifact allows a simple way to test artifacts against recorded golden files.

The golden files are stored in testdata/ folder of the caller of the API and are expected to contain the JSON version of the value being tested. The go-cmp package is used for better quality diffs.

test.File

This is deprecated in favor of test.Artifact.

test.Markdown

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

```go
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:

```go  TestBoo
// 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:

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

```go global
func stranger() string {
	return "stranger"
}
```

```go Example_UsingSomethingDefinedInGlobal
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:

```go firstPackage.DoSomething
...
```

```go secondPackage.
...
```

Documentation

Overview

Package test implements simple test utilities.

Index

• func Artifact(errorf Errorf, outputFile string, value interface{})
• func File(errorf Errorf, inputFile string, outputFile string, fn interface{})
• func Markdown(src []string, dest, pkg string) (err error)
• type Errorf

Functions

func Artifact

func Artifact(errorf Errorf, outputFile string, value interface{})

Artifact implements comparing an artifact against a golden file.

The goldenFile is expected to be relative to the testdata/ folder of the caller of this API. The storage format is JSON for readability of the output.

If the tests are run with -golden flag, the output is not compared but instead the output files are generated.

Example Usage:

test.File(t.Fatal, "golden_xyz.json", func() interface{} {
   ... do some tests and return any serializable type...
})

func File

func File(errorf Errorf, inputFile string, outputFile string, fn interface{})

File implements testing against input/output files

The input and output file names are relative to the testdata/ folder of the caller.

The provided function is one of these two forms:

func (input someType) (output someOtherType)
func (input someType) (output someOtherType,  err error)

The input file is read and the contents passed through this function. For input arguments of type string, []byte or []rune the contents of the files are passed as is. For other types, the contents are assumed to be JSON encoded. The output is similarly JSON encoded for such types.

The discrepancies are reported using regular diff format via the error function (which sports the same signature as testing.T.Error or testing.T.Fatal)

If the tests are run with -golden flag, the output is not compared but instead the output files are created to match the output provided by the test.

Example Usage:

test.File(t.Fatal, "input.txt", "output.txt",
   func(input string) string { .... },
)

func Markdown

func Markdown(src []string, dest, pkg string) (err error)

Markdown generates test code by compiling together snippets in the provided markdown file names. The output is written to the provided output file name.

Fenced blocks can also specify the test/example name in the info string. The first word of the infostring must be go or golang

A fenced block can "import" other modules by simply placing a comment of the form `// import path`.

See https://github.com/tvastar/test/blob/master/testdata/markdown.md for a sample markdown and https://github.com/tvastar/test/blob/master/testdata/markdown_test.go for example generated tests.

Types

type Errorf

type Errorf func(args ...interface{})

Errorf is the type of the function used for reporting errors.

This is typically testing.T.Error or testing.T.Fatal