testmatrix

Documentation

Index

• Variables
• type Binding
• type Context
• type Dimension
• type Fixture
• type FixtureFactory
• type LateFixture
  • func (lf *LateFixture) Set(f Fixture)
• type Matrix
  • func New(dimensions ...Dimension) Matrix
  • func (m *Matrix) AddDimension(name, desc string, values map[string]interface{})
  • func (m Matrix) FixedDimension(dimensionName, valueName string) Matrix
  • func (m Matrix) PrintDimensions()
• type Runner
  • func (pf *Runner) Run(name string, test Test)
  • func (pf *Runner) RunScenario(name string, test ScenarioTest)
• type Scenario
  • func (c Scenario) Map() map[string]interface{}
  • func (c Scenario) String() string
  • func (c Scenario) Value(dimension string) interface{}
• type ScenarioTest
• type Supervisor
  • func Init(defaultMatrix func() Matrix, f FixtureFactory, beforeAll func() error) *Supervisor
  • func NewSupervisor(ff FixtureFactory) *Supervisor
  • func (pfs *Supervisor) NewRunner(t *testing.T, m Matrix) *Runner
  • func (pfs *Supervisor) PrintSummary()
  • func (pfs *Supervisor) TestCount() int
• type Test

Variables

var Flags = struct {
	PrintMatrix     bool
	PrintDimensions bool
}{}

Flags are extra go test flags you can pass to testmatrix.

var Quiet bool

Quiet causes less output to be produced if set to true. You must not change the value of Quiet after calling Init.

Types

type Binding

type Binding struct {
	Dimension, Name string
	Value           interface{}
}

Binding is a named value belonging to a particular dimension.

type Context

type Context struct {
	Scenario Scenario
	// F is the fixture returned from FixtureFactory.
	F interface{}
}

Context is passed to each test case.

type Dimension

type Dimension struct {
	// Name is the name of this dimension, used to look up values in calculated
	// Scenarios.
	Name string
	// Desc is used in help text when using the -matrix flag.
	Desc string
	// Values is a map of named possible values for this Dimension.
	// The name used here forms part of the sub-test path.
	Values map[string]interface{}
}

Dimension represents a dimension in the test matrix.

type Fixture

type Fixture interface {
	Teardown(*testing.T) <-chan error
}

Fixture Teardown func is called after each test has finished.

type FixtureFactory

type FixtureFactory func(*testing.T, Scenario) Fixture

FixtureFactory generates Fixtures from test and combination.

type LateFixture

type LateFixture struct {
	// contains filtered or unexported fields
}

LateFixture wraps a *Fixture and allows the test body to create a fixture and pass it back up to testmatrix to perform teardown.

func (*LateFixture) Set

func (lf *LateFixture) Set(f Fixture)

Set sets the fixture.

type Matrix

type Matrix struct {
	// contains filtered or unexported fields
}

Matrix is a set of named dimensions and possible values, the Cartesian product of these values is used to produce Scenarios which are handed down to your tests.

func New

func New(dimensions ...Dimension) Matrix

New returns a new Matrix.

func (*Matrix) AddDimension

func (m *Matrix) AddDimension(name, desc string, values map[string]interface{})

AddDimension adds a new dimension to this matrix with the provided name and desc which is used in help text when using -matrix flag on 'go test'. The values are a map of short value names to concrete representations, which are passed to tests. The names of values map to parts of the sub-test path for 'go test -run' flag.

func (Matrix) FixedDimension

func (m Matrix) FixedDimension(dimensionName, valueName string) Matrix

FixedDimension returns a matrixDef based on m with one of its dimensions fixed to a particular value. This can be used when writing tests where only a single value for one particular dimension is appropriate.

func (Matrix) PrintDimensions

func (m Matrix) PrintDimensions()

PrintDimensions writes the dimensions an allowed values to stdout.

type Runner

type Runner struct {
	// contains filtered or unexported fields
}

Runner runs tests defined in a Matrix.

func (*Runner) Run

func (pf *Runner) Run(name string, test Test)

Run is analogous to *testing.T.Run, but takes a method that includes a Context as well as *testing.T. Run runs the defined test with all possible matrix combinations in parallel.

func (*Runner) RunScenario

func (pf *Runner) RunScenario(name string, test ScenarioTest)

RunScenario is similar to Run but is passed a ScenarioTest instead of a Test.

type Scenario

type Scenario []Binding

Scenario is a single combination of values from a Matrix.

func (Scenario) Map

func (c Scenario) Map() map[string]interface{}

Map returns a map of dimension name to specific value for this Scenario. This is useful where we want to look up a value by dimension name.

func (Scenario) String

func (c Scenario) String() string

String returns the sub-test path of this Scenario. E.g. dim1ValueName/dim2ValueName[/...].

func (Scenario) Value

func (c Scenario) Value(dimension string) interface{}

Value returns the value for the named dimension in this Scenario.

type ScenarioTest

type ScenarioTest func(*testing.T, Scenario, *LateFixture)

ScenarioTest is a test accepting a raw scenario instead of a fixture.

type Supervisor

type Supervisor struct {
	GetAddrs func(int) []string
	// contains filtered or unexported fields
}

Supervisor supervises a set of Runners, and collates their results. There should be exactly one global Supervisor in every package that uses testmatrix.

func Init

func Init(defaultMatrix func() Matrix, f FixtureFactory, beforeAll func() error) *Supervisor

Init must be called from TestMain after flag.Parse, to initialise a new Supervisor. If Init returns nil, then tests will not be run this time (e.g. because we are just listing tests or printing the matrix def etc.)

func NewSupervisor

func NewSupervisor(ff FixtureFactory) *Supervisor

NewSupervisor returns a new *Supervisor ready to produce test fixtures for your tests using ff. NewSupervisor should be called at most once per package. Calline NewSupervisor more than once will split up test summaries and lead to less useful output. In future it may panic to prevent this.

func (*Supervisor) NewRunner

func (pfs *Supervisor) NewRunner(t *testing.T, m Matrix) *Runner

NewRunner returns a new *Runner ready to run tests with all possible combinations of the provided Matrix. NewRunner should be called exactly once in each top-level TestXXX(t *testing.T) function in your package. Calling it more than once per top-level test may cause undefined behaviour and may panic.

func (*Supervisor) PrintSummary

func (pfs *Supervisor) PrintSummary()

PrintSummary prints a summary of tests run by top-level test and as a sum total. It reports tests failed, skipped, passed, and missing (when a test has failed to report back any status, which should not happen under normal circumstances.

func (*Supervisor) TestCount

func (pfs *Supervisor) TestCount() int

TestCount returns the number of tests that have been registered so far.

type Test

type Test func(*testing.T, Context)

Test is a test.