detest

package
v0.0.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 27, 2021 License: BSD-3-Clause Imports: 18 Imported by: 0

Documentation

Overview

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

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

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.

Types

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{}, args ...interface{}) 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 arguments are the assertion name. If you provide a single argument, this should be a string naming the assertion. If you provide more than one argument, they will be formatted using fmt.Sprintf(args[0], args[1]...). If you do not provide a name then one will be generated.

Under the hood this is implemented with the ExactEqualityComparer.

func (*D) IsNot added in v0.0.6 

func (d *D) IsNot(actual, expect interface{}, args ...interface{}) bool

IsNot tests that two variables are not exactly equal. The first variable is the actual variable and the second is what is expected. The `expect` must be a literal value.

The final arguments follow the same rules as `d.Is`.

Under the hood this is implemented with the ExactInequalityComparer.

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) NotEqual added in v0.0.6 

func (d *D) NotEqual(expect interface{}) ExactInequalityComparer

NotEqual takes an expected literal value and returns an ExactInequalityComparer for later use.

func (*D) Passes added in v0.0.2 

func (d *D) Passes(actual interface{}, expect Comparer, args ...interface{}) bool

Passes tests that the given value passes the comparison given. The first variable is the actual variable and the second is what is expected. The `expect` argument must implement the detest.Comparer interface.

The final arguments follow the same rules as `d.Is`.

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) Require added in v0.0.2 

func (d *D) Require(ok bool, args ...interface{})

Require takes a boolean and calls t.Fatal if it's false. The typical use is to write something like: 

d.Require(
    d.Is(...),
    "got expected test case data",
)

or ... 

d.Require(
    d.Passes(...)),
    "got array with 3 or 4 elements",
)

The final arguments follow the same rules as `d.Is`.

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) Struct 

func (d *D) Struct(with func(*StructTester)) StructComparer

Struct takes a function which will be called to do further comparisons of the struct's contents. Note that you must pass a struct _pointer_ to this method if you want to access private fields with the StructComparer.Field() method.

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{}, args ...interface{}) 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 final arguments follow the same rules as `d.Is`.

If the two variables to be compared 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, checking that they're equal.

func (ExactEqualityComparer) Compare 

func (eec ExactEqualityComparer) Compare(d *D)

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

type ExactInequalityComparer added in v0.0.6 

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

ExactInequalityComparer implements exact comparison of two values, checking that they're not equal.

func (ExactInequalityComparer) Compare added in v0.0.6 

func (eic ExactInequalityComparer) 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 StructComparer 

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

StructComparer implements comparison of struct values.

func (StructComparer) Compare 

func (sc StructComparer) Compare(d *D)

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

type StructTester 

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

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

func (*StructTester) Field 

func (st *StructTester) Field(field string, expect interface{})

Field takes a field name and an expected value for that field. If the field does not exist, this is considered a failure.

type TestingT 

type TestingT interface {
	Fail()
	Fatal(args ...interface{})
}

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().

Source Files

View all Source files

Directories

Path Synopsis
internal
ansi
term
testhelper

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.