Back to godoc.org
github.com/houseabsolute/detest

Package detest

v0.0.0-...-2d25a64
Latest Go to latest

The latest major version is .

Published: Sep 28, 2019 | License: BSD-3-Clause | Module: github.com/houseabsolute/detest

Overview

Package detest implements a DSL-ish interface for testing complicated Go data structure, as well as structured output on test failures.

Index

func RegisterPackage

func RegisterPackage()

RegisterPackage adds the caller's package to the list of "internal" packages for the purposes of presenting paths in test failure output. Specifically, when a function in a registered package is found as the caller for a path, detest will use the function name as the caller rather than showing the file and line where the call occurred.

type CollectionEnding

type CollectionEnding int

CollectionEnding is an enum for collection ending checks, where we either check that all elements have been tested or allow extra untested elements.

const (
	// Unset means that the caller did not specify how to check the ending.
	Unset CollectionEnding = iota
	// Etc means that additional unchecked elements are allowed.
	Etc
	// End means that all elements must be checked or the test fails.
	End
)

type Comparer

type Comparer interface {
	// Compare is called with one argument, the current `*detest.D`
	// object. You can call `d.Actual()` to get the value being tested.
	Compare(*D)
}

Comparer is the interface for anything that implements the `Compare` method.

type D

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

D contains state for the current set of tests. You should create a new `D` in every `Test*` function or subtest.

func New

func New(t TestingT) *D

New takes any implementer of the `TestingT` interface and returns a new `*detest.D`. A `*D` created this way will send its output to `os.Stdout`.

func NewWithOutput

func NewWithOutput(t TestingT, o StringWriter) *D

NewWithOutput takes any implementer of the `TestingT` interface and a `StringWriter` implementer and returns a new `*detest.D`. This is provided primarily for the benefit of testing code that wants to capture the output from detest.

func (*D) Actual

func (d *D) Actual() interface{}

Actual returns the top actual value from the stack of values being tested.

func (*D) AddResult

func (d *D) AddResult(r result)

AddResult adds a test result. At the end of a test any result which is marked as failing is displayed as its own table.

func (*D) AddWarning

func (d *D) AddWarning(w string)

AddWarning adds a warning. At the end of a test these warnings will be displayed. Note that adding a warning does not cause the test to fail.

func (*D) Equal

func (d *D) Equal(expect interface{}) ExactEqualityComparer

Equal takes an expected literal value and returns an ExactEqualityComparer for later use.

func (*D) Func

func (d *D) Func(with interface{}) (FuncComparer, error)

Func takes a function and returns a new FuncComparer using that function. The function provided must accept one value and return one or two values. The first return value must be a bool. If the function returns two values, the second must be a string describing a failure.

func (*D) FuncFor

func (d *D) FuncFor(with interface{}, called string) (FuncComparer, error)

FuncFor works like Func but uses the given name in error messages about the function (accepts the wrong number of values, etc.). This is useful for things like the slice AllValues() operation, which wants to be able to return an error like "The function passed to AllValues must take 1 value, yours takes 2".

func (*D) Is

func (d *D) Is(actual, expect interface{}, name string) bool

Is tests that two variables are exactly equal. The first variable is the actual variable and the second is what is expected. The `expect` argument can be either a literal value or anything that implements the detest.Comparer interface. The final argument is the test name.

Under the hood this is implemented with the ExactEqualityComparer.

func (*D) Map

func (d *D) Map(with func(*MapTester)) MapComparer

Map takes a function which will be called to do further comparisons of the map's contents.

func (*D) NamedFunc

func (d *D) NamedFunc(with interface{}, name string) (FuncComparer, error)

NamedFunc works like Func but uses the given name in the data path for test output.

func (*D) NewPath

func (d *D) NewPath(data string, skip int, function string) Path

NewPath takes a data path element, the number of frames to skip, and an optional function name. It returns a new `Path` struct. If the function name is given, then this is used as the called function rather than looking at the call frames .

When the desired frame is from a package marked as internal to detest, then the caller's line and file is replaced with a function name so that we don't show (unhelpful) information about the detest internals when displaying the path.

func (*D) PopActual

func (d *D) PopActual()

PopActual removes the top element from the current stack of values being tested.

func (*D) PopPath

func (d *D) PopPath()

PopPath removes the top path from the current path stack.

func (*D) PushActual

func (d *D) PushActual(actual interface{})

PushActual adds an actual value being tested to the current stack of values.

func (*D) PushPath

func (d *D) PushPath(path Path)

PushPath adds a path to the current path stack.

func (*D) ResetState

func (d *D) ResetState()

ResetState resets the internal state of the `*detest.D` struct. This is public for the benefit of test packages that want to provide their own comparers or test functions like `detest.Is`.

func (*D) Slice

func (d *D) Slice(with func(*SliceTester)) SliceComparer

Slice takes a function which will be called to do further comparisons of the slice's contents.

func (*D) ValueEqual

func (d *D) ValueEqual(expect interface{}) ValueEqualityComparer

ValueEqual takes an expected literal value and returns a ValueEqualityComparer for later use.

func (*D) ValueIs

func (d *D) ValueIs(actual, expect interface{}, name string) bool

ValueIs tests that two variables contain the same value. The first variable is the actual variable and the second is what is expected. The `expect` argument can be either a literal value or anything that implements the detest.Comparer interface. The final argument is the test name.

If the two variables are of different types this is fine as long as one type can be converted to the other (for example `int32` and `int64`).

Under the hood this is implemented with the ValueEqualityComparer.

type ExactEqualityComparer

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

ExactEqualityComparer implements exact comparison of two values.

func (ExactEqualityComparer) Compare

func (eec ExactEqualityComparer) Compare(d *D)

Compare compares the value in d.Actual() to the expected value passed to Equal().

type FuncComparer

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

FuncComparer implements comparison using a user-defined function.

func (FuncComparer) Compare

func (fc FuncComparer) Compare(d *D)

Compare calls the user-provided function with the value currently in `d.Actual()`. The function is expected to return a boolean indicating success or failure.

type MapComparer

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

MapComparer implements comparison of map values.

func (MapComparer) Compare

func (mc MapComparer) Compare(d *D)

Compare compares the map value in d.Actual() by calling the function passed to `Map()`, which is in turn expected to further tests of the map's content.

type MapTester

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

MapTester is the struct that will be passed to the test function passed to detest.Map. This struct implements the map-specific testing methods such as Idx() and AllValues().

func (*MapTester) AllValues

func (mt *MapTester) AllValues(check interface{})

AllValues takes a function and turns it into a `FuncComparer`. It then passes every map value to that comparer in turn. The function must take exactly one value matching the map key's type and return a single boolean value.

func (*MapTester) End

func (mt *MapTester) End()

End means that all elements of the map must be tested or else the test will fail.

func (*MapTester) Etc

func (mt *MapTester) Etc()

Etc means that not all elements of the map will be tested.

func (*MapTester) Key

func (mt *MapTester) Key(key interface{}, expect interface{})

Key takes a key and an expected value for that key. If the key does not exist, this is considered a failure.

type Path

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

Path is used to track the data path as a test goes through a complex data structure. It records a place in a data structure along with information about the call stack at that particular point in the data path.

func (Path) CalledAt

func (p Path) CalledAt() string

CalledAt returns a string describing the function, file, and line for this path element.

type SliceComparer

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

SliceComparer implements comparison of slice values.

func (SliceComparer) Compare

func (sc SliceComparer) Compare(d *D)

Compare compares the slice value in d.Actual() by calling the function passed to `Slice()`, which is in turn expected to further tests of the slice's content.

type SliceTester

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

SliceTester is the struct that will be passed to the test function passed to detest.Slice. This struct implements the slice-specific testing methods such as Idx() and AllValues().

func (*SliceTester) AllValues

func (st *SliceTester) AllValues(check interface{})

AllValues takes a function and turns it into a `FuncComparer`. It then passes every slice value to that comparer in turn. The function must take exactly one value matching the slice values' type and return a single boolean value.

func (*SliceTester) End

func (st *SliceTester) End()

End means that all elements of the slice must be tested or else the test will fail.

func (*SliceTester) Etc

func (st *SliceTester) Etc()

Etc means that not all elements of the slice will be tested.

func (*SliceTester) Idx

func (st *SliceTester) Idx(idx int, expect interface{})

Idx takes a slice index and an expected value for that index. If the index is past the end of the array, this is considered a failure.

type StringWriter

type StringWriter interface {
	WriteString(string) (int, error)
}

StringWriter is an interface used for writing strings.

type TestingT

type TestingT interface {
	Fail()
}

TestingT is an interface wrapper around `*testing.T` for the portion of its API that we care about.

type ValueEqualityComparer

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

ValueEqualityComparer implements value-based comparison of two values.

func (ValueEqualityComparer) Compare

func (vec ValueEqualityComparer) Compare(d *D)

Compare compares the value in d.Actual() to the expected value passed to ValueEqual().

Package Files

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier