quicktest

README

quicktest

go get github.com/frankban/quicktest@latest

Package quicktest provides a collection of Go helpers for writing tests.

Quicktest helpers can be easily integrated inside regular Go tests, for instance:

import qt "github.com/frankban/quicktest"

func TestFoo(t *testing.T) {
    t.Run("numbers", func(t *testing.T) {
        c := qt.New(t)
        numbers, err := somepackage.Numbers()
        c.Assert(err, qt.IsNil)
        c.Assert(numbers, qt.DeepEquals, []int{42, 47})
    })
    t.Run("bad wolf error", func(t *testing.T) {
        c := qt.New(t)
        numbers, err := somepackage.Numbers()
        c.Assert(err, qt.ErrorMatches, "bad wolf")
    })
    t.Run("nil", func(t *testing.T) {
        c := qt.New(t)
        got := somepackage.MaybeNil()
        c.Assert(got, qt.IsNil, qt.Commentf("value: %v", somepackage.Value))
    })
}

Assertions

An assertion looks like this, where qt.Equals could be replaced by any available checker. If the assertion fails, the underlying Fatal method is called to describe the error and abort the test.

c := qt.New(t)
c.Assert(someValue, qt.Equals, wantValue)

If you don’t want to abort on failure, use Check instead, which calls Error instead of Fatal:

c.Check(someValue, qt.Equals, wantValue)

For really short tests, the extra line for instantiating *qt.C can be avoided:

qt.Assert(t, someValue, qt.Equals, wantValue)
qt.Check(t, someValue, qt.Equals, wantValue)

The library provides some base checkers like Equals, DeepEquals, Matches, ErrorMatches, IsNil and others. More can be added by implementing the Checker interface. Below, we list the checkers implemented by the package in alphabetical order.

All

All returns a Checker that uses the given checker to check elements of slice or array or the values of a map. It succeeds if all elements pass the check. On failure it prints the error from the first index that failed.

For example:

c.Assert([]int{3, 5, 8}, qt.All(qt.Not(qt.Equals)), 0)
c.Assert([][]string{{"a", "b"}, {"a", "b"}}, qt.All(qt.DeepEquals), []string{"c", "d"})

See also Any and Contains.

Any

Any returns a Checker that uses the given checker to check elements of a slice or array or the values from a map. It succeeds if any element passes the check.

For example:

c.Assert([]int{3,5,7,99}, qt.Any(qt.Equals), 7)
c.Assert([][]string{{"a", "b"}, {"c", "d"}}, qt.Any(qt.DeepEquals), []string{"c", "d"})

See also All and Contains.

CmpEquals

CmpEquals checks equality of two arbitrary values according to the provided compare options. DeepEquals is more commonly used when no compare options are required.

Example calls:

c.Assert(list, qt.CmpEquals(cmpopts.SortSlices), []int{42, 47})
c.Assert(got, qt.CmpEquals(), []int{42, 47}) // Same as qt.DeepEquals.

CodecEquals

CodecEquals returns a checker that checks for codec value equivalence.

func CodecEquals(
    marshal func(interface{}) ([]byte, error),
    unmarshal func([]byte, interface{}) error,
    opts ...cmp.Option,
) Checker

It expects two arguments: a byte slice or a string containing some codec-marshaled data, and a Go value.

It uses unmarshal to unmarshal the data into an interface{} value. It marshals the Go value using marshal, then unmarshals the result into an interface{} value.

It then checks that the two interface{} values are deep-equal to one another, using CmpEquals(opts) to perform the check.

See JSONEquals for an example of this in use.

Contains

Contains checks that a map, slice, array or string contains a value. It's the same as using Any(Equals), except that it has a special case for strings - if the first argument is a string, the second argument must also be a string and strings.Contains will be used.

For example:

c.Assert("hello world", qt.Contains, "world")
c.Assert([]int{3,5,7,99}, qt.Contains, 7)

ContentEquals

ContentEquals is is like DeepEquals but any slices in the compared values will be sorted before being compared.

For example:

c.Assert([]string{"c", "a", "b"}, qt.ContentEquals, []string{"a", "b", "c"})

DeepEquals

DeepEquals checks that two arbitrary values are deeply equal. The comparison is done using the github.com/google/go-cmp/cmp package. When comparing structs, by default no exported fields are allowed. If a more sophisticated comparison is required, use CmpEquals (see below).

Example call:

c.Assert(got, qt.DeepEquals, []int{42, 47})

Equals

Equals checks that two values are equal, as compared with Go's == operator.

For instance:

c.Assert(answer, qt.Equals, 42)

Note that the following will fail:

c.Assert((*sometype)(nil), qt.Equals, nil)

Use the IsNil checker below for this kind of nil check.

ErrorAs

ErrorAs checks that the error is or wraps a specific error type. If so, it assigns it to the provided pointer. This is analogous to calling errors.As.

For instance:

// Checking for a specific error type
c.Assert(err, qt.ErrorAs, new(*os.PathError))

// Checking fields on a specific error type
var pathError *os.PathError
if c.Check(err, qt.ErrorAs, &pathError) {
    c.Assert(pathError.Path, Equals, "some_path")
}

ErrorIs

ErrorIs checks that the error is or wraps a specific error value. This is analogous to calling errors.Is.

For instance:

c.Assert(err, qt.ErrorIs, os.ErrNotExist)

ErrorMatches

ErrorMatches checks that the provided value is an error whose message matches the provided regular expression.

For instance:

c.Assert(err, qt.ErrorMatches, `bad wolf .*`)

HasLen

HasLen checks that the provided value has the given length.

For instance:

c.Assert([]int{42, 47}, qt.HasLen, 2)
c.Assert(myMap, qt.HasLen, 42)

Implements

Implements checks that the provided value implements an interface. The interface is specified with a pointer to an interface variable.

For instance:

var rc io.ReadCloser
c.Assert(myReader, qt.Implements, &rc)

IsFalse

IsFalse checks that the provided value is false. The value must have a boolean underlying type.

For instance:

c.Assert(false, qt.IsFalse)
c.Assert(IsValid(), qt.IsFalse)

IsNil

IsNil checks that the provided value is nil.

For instance:

c.Assert(got, qt.IsNil)

As a special case, if the value is nil but implements the error interface, it is still considered to be non-nil. This means that IsNil will fail on an error value that happens to have an underlying nil value, because that's invariably a mistake. See https://golang.org/doc/faq#nil_error.

So it's just fine to check an error like this:

c.Assert(err, qt.IsNil)

IsNotNil

IsNotNil is a Checker checking that the provided value is not nil. IsNotNil is the equivalent of qt.Not(qt.IsNil)

For instance:

c.Assert(got, qt.IsNotNil)

IsTrue

IsTrue checks that the provided value is true. The value must have a boolean underlying type.

For instance:

c.Assert(true, qt.IsTrue)
c.Assert(myBoolean(false), qt.IsTrue)

JSONEquals

JSONEquals checks whether a byte slice or string is JSON-equivalent to a Go value. See CodecEquals for more information.

It uses DeepEquals to do the comparison. If a more sophisticated comparison is required, use CodecEquals directly.

For instance:

c.Assert(`{"First": 47.11}`, qt.JSONEquals, &MyStruct{First: 47.11})

Matches

Matches checks that a string or result of calling the String method (if the value implements fmt.Stringer) matches the provided regular expression.

For instance:

c.Assert("these are the voyages", qt.Matches, `these are .*`)
c.Assert(net.ParseIP("1.2.3.4"), qt.Matches, `1.*`)

Not

Not returns a Checker negating the given Checker.

For instance:

c.Assert(got, qt.Not(qt.IsNil))
c.Assert(answer, qt.Not(qt.Equals), 42)

PanicMatches

PanicMatches checks that the provided function panics with a message matching the provided regular expression.

For instance:

c.Assert(func() {panic("bad wolf ...")}, qt.PanicMatches, `bad wolf .*`)

Satisfies

Satisfies checks that the provided value, when used as argument of the provided predicate function, causes the function to return true. The function must be of type func(T) bool, having got assignable to T.

For instance:

// Check that an error from os.Open satisfies os.IsNotExist.
c.Assert(err, qt.Satisfies, os.IsNotExist)

// Check that a floating point number is a not-a-number.
c.Assert(f, qt.Satisfies, math.IsNaN)

Deferred Execution

The testing.TB.Cleanup helper provides the ability to defer the execution of functions that will be run when the test completes. This is often useful for creating OS-level resources such as temporary directories (see c.Mkdir).

When targeting Go versions that don't have Cleanup (< 1.14), the same can be achieved using c.Defer. In this case, to trigger the deferred behavior, calling c.Done is required. For instance, if you create a *C instance at the top level, you’ll have to add a defer to trigger the cleanups at the end of the test:

defer c.Done()

However, if you use quicktest to create a subtest, Done will be called automatically at the end of that subtest. For example:

func TestFoo(t *testing.T) {
    c := qt.New(t)
    c.Run("subtest", func(c *qt.C) {
        c.Setenv("HOME", c.Mkdir())
        // Here $HOME is set the path to a newly created directory.
        // At the end of the test the directory will be removed
        // and HOME set back to its original value.
    })
}

The c.Patch, c.Setenv, c.Unsetenv and c.Mkdir helpers use t.Cleanup for cleaning up resources when available, and fall back to Defer otherwise.

For a complete API reference, see the package documentation.

Documentation

Overview

Package quicktest provides a collection of Go helpers for writing tests.

Quicktest helpers can be easily integrated inside regular Go tests, for instance:

import qt "github.com/frankban/quicktest"

func TestFoo(t *testing.T) {
    t.Run("numbers", func(t *testing.T) {
        c := qt.New(t)
        numbers, err := somepackage.Numbers()
        c.Assert(err, qt.IsNil)
        c.Assert(numbers, qt.DeepEquals, []int{42, 47})
    })
    t.Run("bad wolf error", func(t *testing.T) {
        c := qt.New(t)
        numbers, err := somepackage.Numbers()
        c.Assert(err, qt.ErrorMatches, "bad wolf")
    })
    t.Run("nil", func(t *testing.T) {
        c := qt.New(t)
        got := somepackage.MaybeNil()
        c.Assert(got, qt.IsNil, qt.Commentf("value: %v", somepackage.Value))
    })
}

Assertions

An assertion looks like this, where qt.Equals could be replaced by any available checker. If the assertion fails, the underlying Fatal method is called to describe the error and abort the test.

c := qt.New(t)
c.Assert(someValue, qt.Equals, wantValue)

If you don’t want to abort on failure, use Check instead, which calls Error instead of Fatal:

c.Check(someValue, qt.Equals, wantValue)

For really short tests, the extra line for instantiating *qt.C can be avoided:

qt.Assert(t, someValue, qt.Equals, wantValue)
qt.Check(t, someValue, qt.Equals, wantValue)

The library provides some base checkers like Equals, DeepEquals, Matches, ErrorMatches, IsNil and others. More can be added by implementing the Checker interface. Below, we list the checkers implemented by the package in alphabetical order.

All

All returns a Checker that uses the given checker to check elements of slice or array or the values of a map. It succeeds if all elements pass the check. On failure it prints the error from the first index that failed.

For example:

c.Assert([]int{3, 5, 8}, qt.All(qt.Not(qt.Equals)), 0)
c.Assert([][]string{{"a", "b"}, {"a", "b"}}, qt.All(qt.DeepEquals), []string{"c", "d"})

See also Any and Contains.

Any

Any returns a Checker that uses the given checker to check elements of a slice or array or the values from a map. It succeeds if any element passes the check.

For example:

c.Assert([]int{3,5,7,99}, qt.Any(qt.Equals), 7)
c.Assert([][]string{{"a", "b"}, {"c", "d"}}, qt.Any(qt.DeepEquals), []string{"c", "d"})

See also All and Contains.

CmpEquals

CmpEquals checks equality of two arbitrary values according to the provided compare options. DeepEquals is more commonly used when no compare options are required.

Example calls:

c.Assert(list, qt.CmpEquals(cmpopts.SortSlices), []int{42, 47})
c.Assert(got, qt.CmpEquals(), []int{42, 47}) // Same as qt.DeepEquals.

CodecEquals

CodecEquals returns a checker that checks for codec value equivalence.

func CodecEquals(
    marshal func(interface{}) ([]byte, error),
    unmarshal func([]byte, interface{}) error,
    opts ...cmp.Option,
) Checker

It expects two arguments: a byte slice or a string containing some codec-marshaled data, and a Go value.

It uses unmarshal to unmarshal the data into an interface{} value. It marshals the Go value using marshal, then unmarshals the result into an interface{} value.

It then checks that the two interface{} values are deep-equal to one another, using CmpEquals(opts) to perform the check.

See JSONEquals for an example of this in use.

Contains

Contains checks that a map, slice, array or string contains a value. It's the same as using Any(Equals), except that it has a special case for strings - if the first argument is a string, the second argument must also be a string and strings.Contains will be used.

For example:

c.Assert("hello world", qt.Contains, "world")
c.Assert([]int{3,5,7,99}, qt.Contains, 7)

ContentEquals

ContentEquals is is like DeepEquals but any slices in the compared values will be sorted before being compared.

For example:

c.Assert([]string{"c", "a", "b"}, qt.ContentEquals, []string{"a", "b", "c"})

DeepEquals

DeepEquals checks that two arbitrary values are deeply equal. The comparison is done using the github.com/google/go-cmp/cmp package. When comparing structs, by default no exported fields are allowed. If a more sophisticated comparison is required, use CmpEquals (see below).

Example call:

c.Assert(got, qt.DeepEquals, []int{42, 47})

Equals

Equals checks that two values are equal, as compared with Go's == operator.

For instance:

c.Assert(answer, qt.Equals, 42)

Note that the following will fail:

c.Assert((*sometype)(nil), qt.Equals, nil)

Use the IsNil checker below for this kind of nil check.

ErrorAs

ErrorAs checks that the error is or wraps a specific error type. If so, it assigns it to the provided pointer. This is analogous to calling errors.As.

For instance:

// Checking for a specific error type
c.Assert(err, qt.ErrorAs, new(*os.PathError))

// Checking fields on a specific error type
var pathError *os.PathError
if c.Check(err, qt.ErrorAs, &pathError) {
    c.Assert(pathError.Path, Equals, "some_path")
}

ErrorIs

ErrorIs checks that the error is or wraps a specific error value. This is analogous to calling errors.Is.

For instance:

c.Assert(err, qt.ErrorIs, os.ErrNotExist)

ErrorMatches

ErrorMatches checks that the provided value is an error whose message matches the provided regular expression.

For instance:

c.Assert(err, qt.ErrorMatches, `bad wolf .*`)

HasLen

HasLen checks that the provided value has the given length.

For instance:

c.Assert([]int{42, 47}, qt.HasLen, 2)
c.Assert(myMap, qt.HasLen, 42)

Implements

Implements checks that the provided value implements an interface. The interface is specified with a pointer to an interface variable.

For instance:

var rc io.ReadCloser
c.Assert(myReader, qt.Implements, &rc)

IsFalse

IsFalse checks that the provided value is false. The value must have a boolean underlying type.

For instance:

c.Assert(false, qt.IsFalse)
c.Assert(IsValid(), qt.IsFalse)

IsNil

IsNil checks that the provided value is nil.

For instance:

c.Assert(got, qt.IsNil)

As a special case, if the value is nil but implements the error interface, it is still considered to be non-nil. This means that IsNil will fail on an error value that happens to have an underlying nil value, because that's invariably a mistake. See https://golang.org/doc/faq#nil_error.

So it's just fine to check an error like this:

c.Assert(err, qt.IsNil)

IsNotNil

IsNotNil is a Checker checking that the provided value is not nil. IsNotNil is the equivalent of qt.Not(qt.IsNil)

For instance:

c.Assert(got, qt.IsNotNil)

IsTrue

IsTrue checks that the provided value is true. The value must have a boolean underlying type.

For instance:

c.Assert(true, qt.IsTrue)
c.Assert(myBoolean(false), qt.IsTrue)

JSONEquals

JSONEquals checks whether a byte slice or string is JSON-equivalent to a Go value. See CodecEquals for more information.

It uses DeepEquals to do the comparison. If a more sophisticated comparison is required, use CodecEquals directly.

For instance:

c.Assert(`{"First": 47.11}`, qt.JSONEquals, &MyStruct{First: 47.11})

Matches

Matches checks that a string or result of calling the String method (if the value implements fmt.Stringer) matches the provided regular expression.

For instance:

c.Assert("these are the voyages", qt.Matches, `these are .*`)
c.Assert(net.ParseIP("1.2.3.4"), qt.Matches, `1.*`)

Not

Not returns a Checker negating the given Checker.

For instance:

c.Assert(got, qt.Not(qt.IsNil))
c.Assert(answer, qt.Not(qt.Equals), 42)

PanicMatches

PanicMatches checks that the provided function panics with a message matching the provided regular expression.

For instance:

c.Assert(func() {panic("bad wolf ...")}, qt.PanicMatches, `bad wolf .*`)

Satisfies

Satisfies checks that the provided value, when used as argument of the provided predicate function, causes the function to return true. The function must be of type func(T) bool, having got assignable to T.

For instance:

// Check that an error from os.Open satisfies os.IsNotExist.
c.Assert(err, qt.Satisfies, os.IsNotExist)

// Check that a floating point number is a not-a-number.
c.Assert(f, qt.Satisfies, math.IsNaN)

Deferred Execution

The testing.TB.Cleanup helper provides the ability to defer the execution of functions that will be run when the test completes. This is often useful for creating OS-level resources such as temporary directories (see c.Mkdir).

When targeting Go versions that don't have Cleanup (< 1.14), the same can be achieved using c.Defer. In this case, to trigger the deferred behavior, calling c.Done is required. For instance, if you create a *C instance at the top level, you’ll have to add a defer to trigger the cleanups at the end of the test:

defer c.Done()

However, if you use quicktest to create a subtest, Done will be called automatically at the end of that subtest. For example:

func TestFoo(t *testing.T) {
    c := qt.New(t)
    c.Run("subtest", func(c *qt.C) {
        c.Setenv("HOME", c.Mkdir())
        // Here $HOME is set the path to a newly created directory.
        // At the end of the test the directory will be removed
        // and HOME set back to its original value.
    })
}

The c.Patch, c.Setenv, c.Unsetenv and c.Mkdir helpers use t.Cleanup for cleaning up resources when available, and fall back to Defer otherwise.

Index

• Variables
• func Assert(t testing.TB, got interface{}, checker Checker, args ...interface{}) bool
• func BadCheckf(format string, a ...interface{}) error
• func Check(t testing.TB, got interface{}, checker Checker, args ...interface{}) bool
• func Format(v interface{}) string
• func IsBadCheck(err error) bool
• func Patch(t testing.TB, dest, value interface{})
• func Setenv(t testing.TB, name, val string)
• func Unsetenv(t testing.TB, name string)
• type C
  • func New(t testing.TB) *C
  • func (c *C) Assert(got interface{}, checker Checker, args ...interface{}) bool
  • func (c *C) Check(got interface{}, checker Checker, args ...interface{}) bool
  • func (c *C) Defer(f func())
  • func (c *C) Done()
  • func (c *C) Mkdir() string
  • func (c *C) Parallel()
  • func (c *C) Patch(dest, value interface{})
  • func (c *C) Run(name string, f func(c *C)) bool
  • func (c *C) SetFormat(format func(interface{}) string)
  • func (c *C) Unsetenv(name string)
• type Checker
  • func All(c Checker) Checker
  • func Any(c Checker) Checker
  • func CmpEquals(opts ...cmp.Option) Checker
  • func CodecEquals(marshal func(interface{}) ([]byte, error), ...) Checker
  • func Not(checker Checker) Checker
• type Comment
  • func Commentf(format string, args ...interface{}) Comment
  • func (c Comment) String() string
• type SuppressedIfLong
• type Unquoted

Variables

var ContentEquals = CmpEquals(cmpopts.SortSlices(func(x, y interface{}) bool {

	return pretty.Sprint(x) < pretty.Sprint(y)
}))

ContentEquals is like DeepEquals but any slices in the compared values will be sorted before being compared.

var DeepEquals = CmpEquals()

DeepEquals is a Checker deeply checking equality of two arbitrary values. The comparison is done using the github.com/google/go-cmp/cmp package. When comparing structs, by default no exported fields are allowed. CmpEquals can be used when more customized compare options are required.

Example call:

c.Assert(got, qt.DeepEquals, []int{42, 47})

var ErrSilent = fmt.Errorf("silent failure")

ErrSilent is the error used when there is no need to include in the failure output the "error" and "check" keys and all the keys automatically added for args. This helper can be used when implementing checkers.

var JSONEquals = CodecEquals(json.Marshal, json.Unmarshal)

JSONEquals is a checker that checks whether a byte slice or string is JSON-equivalent to a Go value. See CodecEquals for more information.

It uses DeepEquals to do the comparison. If a more sophisticated comparison is required, use CodecEquals directly.

For instance:

c.Assert(`{"First": 47.11}`, qt.JSONEquals, &MyStruct{First: 47.11})

Functions

func Assert

func Assert(t testing.TB, got interface{}, checker Checker, args ...interface{}) bool

Assert runs the given check using the provided t and stops execution in case of failure. For instance:

qt.Assert(t, got, qt.DeepEquals, []int{42, 47})
qt.Assert(t, got, qt.ErrorMatches, "bad wolf .*", qt.Commentf("a comment"))

Additional args (not consumed by the checker), when provided, are included as comments in the failure output when the check fails.

func BadCheckf

func BadCheckf(format string, a ...interface{}) error

BadCheckf returns an error used to report a problem with the checker invocation or testing execution itself (like wrong number or type of arguments) rather than a real Check or Assert failure. This helper can be used when implementing checkers.

func Check

func Check(t testing.TB, got interface{}, checker Checker, args ...interface{}) bool

Check runs the given check using the provided t and continues execution in case of failure. For instance:

qt.Check(t, answer, qt.Equals, 42)
qt.Check(t, got, qt.IsNil, qt.Commentf("iteration %d", i))

Additional args (not consumed by the checker), when provided, are included as comments in the failure output when the check fails.

func Format

func Format(v interface{}) string

Format formats the given value as a string. It is used to print values in test failures unless that's changed by calling C.SetFormat.

func IsBadCheck

func IsBadCheck(err error) bool

IsBadCheck reports whether the given error has been created by BadCheckf. This helper can be used when implementing checkers.

func Patch

func Patch(t testing.TB, dest, value interface{})

Patch sets a variable to a temporary value for the duration of the test.

It sets the value pointed to by the given destination to the given value, which must be assignable to the element type of the destination.

At the end of the test the destination is set back to its original value using t.Cleanup.

The top level Patch function is only available on Go >= 1.14. Use (*C).Patch when on prior versions.

func Setenv

func Setenv(t testing.TB, name, val string)

Setenv sets an environment variable to a temporary value for the duration of the test.

At the end of the test the environment variable is returned to its original value using t.Cleanup.

The top level Setenv function is only available on Go >= 1.14. Use (*C).Setenv when on prior versions.

func Unsetenv

func Unsetenv(t testing.TB, name string)

Unsetenv unsets an environment variable for the duration of a test.

The top level Unsetenv function is only available on Go >= 1.14. Use (*C).Unsetenv when on prior versions.

Types

type C

type C struct {
	testing.TB
	// contains filtered or unexported fields
}

C is a quicktest checker. It embeds a testing.TB value and provides additional checking functionality. If an Assert or Check operation fails, it uses the wrapped TB value to fail the test appropriately.

func New

func New(t testing.TB) *C

New returns a new checker instance that uses t to fail the test when checks fail. It only ever calls the Fatal, Error and (when available) Run methods of t. For instance.

func TestFoo(t *testing.T) {
    t.Run("A=42", func(t *testing.T) {
        c := qt.New(t)
        c.Assert(a, qt.Equals, 42)
    })
}

The library already provides some base checkers, and more can be added by implementing the Checker interface.

If there is a likelihood that Defer will be called, then a call to Done should be deferred after calling New. For example:

func TestFoo(t *testing.T) {
        c := qt.New(t)
        defer c.Done()
        c.Setenv("HOME", "/non-existent")
        c.Assert(os.Getenv("HOME"), qt.Equals, "/non-existent")
})

A value of C that's has a non-nil TB field but is otherwise zero is valid. So:

c := &qt.C{TB: t}

is valid a way to create a C value; it's exactly the same as:

c := qt.New(t)

Methods on C may be called concurrently, assuming the underlying `testing.TB` implementation also allows that.

func (*C) Assert

func (c *C) Assert(got interface{}, checker Checker, args ...interface{}) bool

Assert runs the given check and stops execution in case of failure. For instance:

c.Assert(got, qt.DeepEquals, []int{42, 47})
c.Assert(got, qt.ErrorMatches, "bad wolf .*", qt.Commentf("a comment"))

Additional args (not consumed by the checker), when provided, are included as comments in the failure output when the check fails.

func (*C) Check

func (c *C) Check(got interface{}, checker Checker, args ...interface{}) bool

Check runs the given check and continues execution in case of failure. For instance:

c.Check(answer, qt.Equals, 42)
c.Check(got, qt.IsNil, qt.Commentf("iteration %d", i))

Additional args (not consumed by the checker), when provided, are included as comments in the failure output when the check fails.

func (*C) Defer

func (c *C) Defer(f func())

Defer registers a function to be called when c.Done is called. Deferred functions will be called in last added, first called order. If c.Done is not called by the end of the test, the test may panic. Note that if Cleanup is called, there is no need to call Done.

Deprecated: in Go >= 1.14 use testing.TB.Cleanup instead.

func (*C) Done

func (c *C) Done()

Done calls all the functions registered by Defer in reverse registration order. After it's called, the functions are unregistered, so calling Done twice will only call them once.

When a test function is called by Run, Done will be called automatically on the C value passed into it.

Deprecated: in Go >= 1.14 this is no longer needed if using testing.TB.Cleanup.

func (*C) Mkdir

func (c *C) Mkdir() string

Mkdir makes a temporary directory and returns its name.

At the end of the test (see "Deferred execution" in the package docs), the directory and its contents are removed.

Deprecated: in Go >= 1.15 use testing.TB.TempDir instead.

func (*C) Parallel

func (c *C) Parallel()

Parallel signals that this test is to be run in parallel with (and only with) other parallel tests. It's a wrapper around *testing.T.Parallel.

A panic is raised when Parallel is called and the embedded concrete type does not implement Parallel, for instance if TB's concrete type is a benchmark.

func (*C) Patch

func (c *C) Patch(dest, value interface{})

Patch sets a variable to a temporary value for the duration of the test.

It sets the value pointed to by the given destination to the given value, which must be assignable to the element type of the destination.

At the end of the test (see "Deferred execution" in the package docs), the destination is set back to its original value.

func (*C) Run

func (c *C) Run(name string, f func(c *C)) bool

Run runs f as a subtest of t called name. It's a wrapper around the Run method of c.TB that provides the quicktest checker to f. When the function completes, c.Done will be called to run any functions registered with c.Defer.

c.TB must implement a Run method of the following form:

Run(string, func(T)) bool

where T is any type that is assignable to testing.TB. Implementations include *testing.T, *testing.B and *C itself.

The TB field in the subtest will hold the value passed by Run to its argument function.

func TestFoo(t *testing.T) {
    c := qt.New(t)
    c.Run("A=42", func(c *qt.C) {
        // This assertion only stops the current subtest.
        c.Assert(a, qt.Equals, 42)
    })
}

A panic is raised when Run is called and the embedded concrete type does not implement a Run method with a correct signature.

func (*C) SetFormat

func (c *C) SetFormat(format func(interface{}) string)

SetFormat sets the function used to print values in test failures. By default Format is used. Any subsequent subtests invoked with c.Run will also use this function by default.

func (*C) Unsetenv

func (c *C) Unsetenv(name string)

Unsetenv unsets an environment variable for the duration of a test.

type Checker

type Checker interface {
	// Check checks that the obtained value (got) is correct with respect to
	// the checker's arguments (args). On failure, the returned error is
	// printed along with the checker arguments and any key-value pairs added
	// by calling the note function. Values are pretty-printed unless they are
	// of type Unquoted.
	//
	// When the check arguments are invalid, Check may return a BadCheck error,
	// which suppresses printing of the checker arguments. Values added with
	// note are still printed.
	//
	// If Check returns ErrSilent, neither the checker arguments nor the error
	// are printed. Again, values added with note are still printed.
	Check(got interface{}, args []interface{}, note func(key string, value interface{})) error

	// ArgNames returns the names of all required arguments, including the
	// mandatory got argument and any additional args.
	ArgNames() []string
}

Checker is implemented by types used as part of Check/Assert invocations.

var Contains Checker = &containsChecker{
	argNames: []string{"container", "want"},
}

Contains is a checker that checks that a map, slice, array or string contains a value. It's the same as using Any(Equals), except that it has a special case for strings - if the first argument is a string, the second argument must also be a string and strings.Contains will be used.

For example:

c.Assert("hello world", qt.Contains, "world")
c.Assert([]int{3,5,7,99}, qt.Contains, 7)

var Equals Checker = &equalsChecker{
	argNames: []string{"got", "want"},
}

Equals is a Checker checking equality of two comparable values.

For instance:

c.Assert(answer, qt.Equals, 42)

Note that the following will fail:

c.Assert((*sometype)(nil), qt.Equals, nil)

Use the IsNil checker below for this kind of nil check.

var ErrorAs Checker = &errorAsChecker{
	argNames: []string{"got", "as"},
}

ErrorAs checks that the error is or wraps a specific error type. If so, it assigns it to the provided pointer. This is analogous to calling errors.As.

For instance:

// Checking for a specific error type
c.Assert(err, qt.ErrorAs, new(*os.PathError))

// Checking fields on a specific error type
var pathError *os.PathError
if c.Check(err, qt.ErrorAs, &pathError) {
    c.Assert(pathError.Path, qt.Equals, "some_path")
}

var ErrorIs Checker = &errorIsChecker{
	argNames: []string{"got", "want"},
}

ErrorIs checks that the error is or wraps a specific error value. This is analogous to calling errors.Is.

For instance:

c.Assert(err, qt.ErrorIs, os.ErrNotExist)

var ErrorMatches Checker = &errorMatchesChecker{
	argNames: []string{"got error", "regexp"},
}

ErrorMatches is a Checker checking that the provided value is an error whose message matches the provided regular expression pattern.

For instance:

c.Assert(err, qt.ErrorMatches, "bad wolf .*")
c.Assert(err, qt.ErrorMatches, regexp.MustCompile("bad wolf .*"))

var HasLen Checker = &hasLenChecker{
	argNames: []string{"got", "want length"},
}

HasLen is a Checker checking that the provided value has the given length.

For instance:

c.Assert([]int{42, 47}, qt.HasLen, 2)
c.Assert(myMap, qt.HasLen, 42)

var Implements Checker = &implementsChecker{
	argNames: []string{"got", "want interface pointer"},
}

Implements checks that the provided value implements an interface. The interface is specified with a pointer to an interface variable.

For instance:

var rc io.ReadCloser
c.Assert(myReader, qt.Implements, &rc)

var IsFalse Checker = &boolChecker{
	want: false,
}

IsFalse is a Checker checking that the provided value is false. The value must have a boolean underlying type.

For instance:

c.Assert(false, qt.IsFalse)
c.Assert(IsValid(), qt.IsFalse)

var IsNil Checker = &isNilChecker{
	argNames: []string{"got"},
}

IsNil is a Checker checking that the provided value is nil.

For instance:

c.Assert(got, qt.IsNil)

As a special case, if the value is nil but implements the error interface, it is still considered to be non-nil. This means that IsNil will fail on an error value that happens to have an underlying nil value, because that's invariably a mistake. See https://golang.org/doc/faq#nil_error.

var IsNotNil Checker = &notChecker{
	Checker: IsNil,
}

IsNotNil is a Checker checking that the provided value is not nil. IsNotNil is the equivalent of qt.Not(qt.IsNil)

For instance:

c.Assert(got, qt.IsNotNil)

var IsTrue Checker = &boolChecker{
	want: true,
}

IsTrue is a Checker checking that the provided value is true. The value must have a boolean underlying type.

For instance:

c.Assert(true, qt.IsTrue)
c.Assert(myBoolean(false), qt.IsTrue)

var Matches Checker = &matchesChecker{
	argNames: []string{"got value", "regexp"},
}

Matches is a Checker checking that the provided string or fmt.Stringer matches the provided regular expression pattern.

For instance:

c.Assert("these are the voyages", qt.Matches, "these are .*")
c.Assert(net.ParseIP("1.2.3.4"), qt.Matches, "1.*")
c.Assert("my multi-line\nnumber", qt.Matches, regexp.MustCompile(`my multi-line\n(string|number)`))

var PanicMatches Checker = &panicMatchesChecker{
	argNames: []string{"function", "regexp"},
}

PanicMatches is a Checker checking that the provided function panics with a message matching the provided regular expression pattern.

For instance:

c.Assert(func() {panic("bad wolf ...")}, qt.PanicMatches, "bad wolf .*")
c.Assert(func() {panic("bad wolf ...")}, qt.PanicMatches, regexp.MustCompile(`bad wolf .*`))

var Satisfies Checker = &satisfiesChecker{
	argNames: []string{"arg", "predicate function"},
}

Satisfies is a Checker checking that the provided value, when used as argument of the provided predicate function, causes the function to return true. The function must be of type func(T) bool, having got assignable to T.

For instance:

// Check that an error from os.Open satisfies os.IsNotExist.
c.Assert(err, qt.Satisfies, os.IsNotExist)

// Check that a floating point number is a not-a-number.
c.Assert(f, qt.Satisfies, math.IsNaN)

func All

func All(c Checker) Checker

All returns a Checker that uses the given checker to check elements of slice or array or the values of a map. It succeeds if all elements pass the check. On failure it prints the error from the first index that failed.

For example:

c.Assert([]int{3, 5, 8}, qt.All(qt.Not(qt.Equals)), 0)
c.Assert([][]string{{"a", "b"}, {"a", "b"}}, qt.All(qt.DeepEquals), []string{"c", "d"})

See also Any and Contains.

func Any

func Any(c Checker) Checker

Any returns a Checker that uses the given checker to check elements of a slice or array or the values from a map. It succeeds if any element passes the check.

For example:

c.Assert([]int{3,5,7,99}, qt.Any(qt.Equals), 7)
c.Assert([][]string{{"a", "b"}, {"c", "d"}}, qt.Any(qt.DeepEquals), []string{"c", "d"})

See also All and Contains.

func CmpEquals

func CmpEquals(opts ...cmp.Option) Checker

CmpEquals returns a Checker checking equality of two arbitrary values according to the provided compare options. See DeepEquals as an example of such a checker, commonly used when no compare options are required.

Example calls:

c.Assert(list, qt.CmpEquals(cmpopts.SortSlices), []int{42, 47})
c.Assert(got, qt.CmpEquals(), []int{42, 47}) // Same as qt.DeepEquals.

func CodecEquals

func CodecEquals(
	marshal func(interface{}) ([]byte, error),
	unmarshal func([]byte, interface{}) error,
	opts ...cmp.Option,
) Checker

CodecEquals returns a checker that checks for codec value equivalence.

It expects two arguments: a byte slice or a string containing some codec-marshaled data, and a Go value.

It uses unmarshal to unmarshal the data into an interface{} value. It marshals the Go value using marshal, then unmarshals the result into an interface{} value.

It then checks that the two interface{} values are deep-equal to one another, using CmpEquals(opts) to perform the check.

See JSONEquals for an example of this in use.

func Not

func Not(checker Checker) Checker

Not returns a Checker negating the given Checker.

For instance:

c.Assert(got, qt.Not(qt.IsNil))
c.Assert(answer, qt.Not(qt.Equals), 42)

type Comment

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

Comment represents additional information on a check or an assertion which is displayed when the check or assertion fails.

func Commentf

func Commentf(format string, args ...interface{}) Comment

Commentf returns a test comment whose output is formatted according to the given format specifier and args. It may be provided as the last argument to any check or assertion and will be displayed if the check or assertion fails. For instance:

c.Assert(a, qt.Equals, 42, qt.Commentf("answer is not %d", 42))

func (Comment) String

func (c Comment) String() string

String outputs a string formatted according to the stored format specifier and args.

type SuppressedIfLong

type SuppressedIfLong struct {
	// Value holds the original annotated value.
	Value interface{}
}

SuppressedIfLong indicates that the value must be suppressed if verbose testing is off and the pretty printed version of the value is long. This is useful when a checker calls note and does not want the provided value to be printed in non-verbose test runs if the value is too long.

type Unquoted

type Unquoted string

Unquoted indicates that the string must not be pretty printed in the failure output. This is useful when a checker calls note and does not want the provided value to be quoted.