quicktest

README

quicktest

A collection of Go helpers for writing tests.

Installation

To install the package, run go get github.com/frankban/quicktest.

Usage

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(numbers, qt.DeepEquals, []int{42, 47})
        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))
    })
}

The library provides some base checkers like Equals, DeepEquals, Matches, ErrorMatches, IsNil and others. More can be added by implementing the Checker interface.

See the go documentation for this library.

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(numbers, qt.DeepEquals, []int{42, 47})
        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))
    })
}

The library provides some base checkers like Equals, DeepEquals, Matches, ErrorMatches, IsNil and others. More can be added by implementing the Checker interface.

Index

• Variables
• func BadCheckf(format string, a ...interface{}) error
• func IsBadCheck(err error) bool
• type C
  • func New(t testing.TB) *C
  • func (c *C) AddCleanup(f func())
  • 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) Cleanup()
  • 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) Setenv(name, val string)
• type Checker
  • func CmpEquals(opts ...cmp.Option) Checker
  • func Not(checker Checker) Checker
• type Comment
  • func Commentf(format string, args ...interface{}) Comment
  • func (c Comment) String() string
• 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. For instance:

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.

Functions

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

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")
})

func (*C) AddCleanup

func (c *C) AddCleanup(f func())

AddCleanup is the old name for Defer. Deprecated: this will be removed in a subsequent version.

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

func (c *C) Cleanup()

Cleanup is the old name for Done. Deprecated: this will be removed in a subsequent version.

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.

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.

func (*C) Mkdir

func (c *C) Mkdir() string

Mkdir makes a temporary directory and returns its name.

The directory and its contents will be removed when c.Done is called.

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 (until c.Done is called).

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.

When c.Done is called, the destination is set 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 *testing.T.Run that provides the quicktest checker to f. When the function completes, c.Done will be called to run any functions registered with c.Defer.

For instance:

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 Run, for instance if TB's concrete type is a benchmark.

func (*C) Setenv

func (c *C) Setenv(name, val string)

Setenv sets an environment variable to a temporary value for the duration of the test (until c.Done is called).

When c.Done is called, the environment variable will be returned to its original value.

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 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 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 .*")

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 IsNil Checker = &isNilChecker{
	argNames: []string{"got"},
}

IsNil is a Checker checking that the provided value is nil. For instance:

c.Assert(got, qt.IsNil)

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.*")

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 .*")

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 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. For instance:

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

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