tester

Documentation

Overview

Package tester implements a test runner compatible with testing.T

Usage:

t := tester.New()
tester.Run(t, "testA", func(t *tester.T) { ... })
results := tester.Results(t)

This package implements a subset of the testing.T type. In particular, it implements the testing.TB interface and also provides helpers to run subtests using tester.Run.

The package is intended to help build test suites that can not only run with `go test` but can also be run to validate things in production code. The intention is to be able to write production validation code (which is meant to be compiled into command line tools or service binaries) in much the same way as regular tests.

Individual tests can use t.Error, t.Errorf etc (as well as gotest.tools/v3/assert functions, for instance, or the stretchr/testify set of helpers).

Unfortunately, indvidual tests written with the standard signature of `TestXYZ(t *testing.T)` cannot be used with tester.New() as the testing.T type is concrete and tester.New() does not return a type compatible with this.. Instead, the suggested approach is for test suites to be written against tester.T like so:

func TestXYZ(t *tester.T) { .... }

And then, a TestAll function can be written that will work properly with testing.T:

func TestAll(t *testing.T) {
    tester.Run("TestXYZ", TestXYZ)
    ...
}

When tester.Run is used in a `go test` type situation, it simply maps it to t.Run. But when it is used with a `tester.New()` instance, it correctly creates a sub task on that type.

This allows tests written in the style of testing.T (but using the subset of methods in tester.T) to be executed either in a test environment (using testing.T) or in a production environment (using tester.New()).

The main export of this package is the New() function.

You can log test results using LogResults.

Index

• func LogResults(t T)
• func Run(t T, name string, f interface{}) bool
• func RunTest(t T, f func(testing.TB))
• type Option
  • func WithLogWriter(logfunc func(name, message string)) Option
  • func WithName(name string) Option
• type T
  • func New(opts ...Option) T
• type TestFailure
• type TestResults
  • func Results(t T) *TestResults

Functions

func LogResults

func LogResults(t T)

LogResults logs the results of the tests using log.Error.

func Run

func Run(t T, name string, f interface{}) bool

Run is a polymorphic function where t is either *testing.T or tester.T. f is of type func(t *testing.T) or func(t tester.T) or some subset of tester.T.

This is convenience function so that test code written with this will work with both `go test` and production scenarios (which use tester.T).

func RunTest

func RunTest(t T, f func(testing.TB))

RunTest executes a single test.

Types

type Option

type Option func(t *tester)

Option defines a test option.

func WithLogWriter

func WithLogWriter(logfunc func(name, message string)) Option

WithLogWriter configures the logging function. The default is to use log.Info.

func WithName

func WithName(name string) Option

WithName configures the test name. The default name is "test."

type T

type T interface {
	testing.TB
	Parallel()
}

T is the interface implemented by this package. It is a superset of testing.TB and a subset of *testing.T.

func New

func New(opts ...Option) T

New returns an implementation of a T (which includes testing.TB).

Individual tests can be run using the Run and the final results can be obtained using Results.

You can customize the root test name using WithName. The default is "test".

You can customize how intermediate test information is logged. The default is log.Info (use the LogResults function to summarize log results into meaningful log.Error statements).

type TestFailure

type TestFailure struct {
	TestName, Failure string
}

TestFailure contains information about the test that failed.

type TestResults

type TestResults struct {
	Failed   bool
	Failures []*TestFailure
}

TestResults contains the test results.

func Results

func Results(t T) *TestResults

Results returns the results of the tests so far.