is

README

is

Professional lightweight testing mini-framework for Go.

• Easy to write and read
• Beautifully simple API with everything you need: is.Equal, is.True, is.NoErr, and is.Fail
• Use comments to add descriptions (which show up when tests fail)

Failures are very easy to read:

Usage

The following code shows a range of useful ways you can use the helper methods:

func Test(t *testing.T) {

	is := is.New(t)

	signedin, err := isSignedIn(ctx)
	is.NoErr(err)            // isSignedIn error
	is.Equal(signedin, true) // must be signed in

	body := readBody(r)
	is.True(strings.Contains(body, "Hi there"))

}

Color

To turn off the colors, run go test with the -nocolor flag, or with the env var NO_COLOR (with any value).

go test -nocolor

NO_COLOR=1 go test

Documentation

Overview

Package is provides a lightweight extension to the standard library's testing capabilities.

Comments on the assertion lines are used to add a description.

The following failing test:

func Test(t *testing.T) {
	is := is.New(t)
	a, b := 1, 2
	is.Equal(a, b) // expect to be the same
}

Will output:

your_test.go:123: 1 != 2 // expect to be the same

Usage

The following code shows a range of useful ways you can use the helper methods:

func Test(t *testing.T) {
	// always start tests with this
	is := is.New(t)

	signedin, err := isSignedIn(ctx)
	is.NoErr(err)            // isSignedIn error
	is.Equal(signedin, true) // must be signed in

	body := readBody(r)
	is.True(strings.Contains(body, "Hi there"))
}

Index

• type I
  • func New(t T) *I
  • func NewRelaxed(t T) *I
  • func (is *I) Equal(a, b interface{})
  • func (is *I) Fail()
  • func (is *I) Helper()
  • func (is *I) New(t T) *I
  • func (is *I) NewRelaxed(t T) *I
  • func (is *I) NoErr(err error)
  • func (is *I) True(expression bool)
• type T

Types

type I

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

I is the test helper harness.

func New

func New(t T) *I

New makes a new testing helper using the specified T through which failures will be reported. In strict mode, failures call T.FailNow causing the test to be aborted. See NewRelaxed for alternative behavior.

func NewRelaxed

func NewRelaxed(t T) *I

NewRelaxed makes a new testing helper using the specified T through which failures will be reported. In relaxed mode, failures call T.Fail allowing multiple failures per test.

func (*I) Equal

func (is *I) Equal(a, b interface{})

Equal asserts that a and b are equal.

func Test(t *testing.T) {
	is := is.New(t)
	a := greet("Mat")
	is.Equal(a, "Hi Mat") // greeting
}

Will output:

your_test.go:123: Hey Mat != Hi Mat // greeting

func (*I) Fail

func (is *I) Fail()

Fail immediately fails the test.

func Test(t *testing.T) {
	is := is.New(t)
	is.Fail() // TODO: write this test
}

In relaxed mode, execution will continue after a call to Fail, but that test will still fail.

func (*I) Helper

func (is *I) Helper()

Helper marks the calling function as a test helper function. When printing file and line information, that function will be skipped.

Available with Go 1.7 and later.

func (*I) New

func (is *I) New(t T) *I

New is a method wrapper around the New function. It allows you to write subtests using a similar pattern:

func Test(t *testing.T) {
	is := is.New(t)
	t.Run("sub", func(t *testing.T) {
		is := is.New(t)
		// TODO: test
	})
}

func (*I) NewRelaxed

func (is *I) NewRelaxed(t T) *I

NewRelaxed is a method wrapper around the NewRelaxed method. It allows you to write subtests using a similar pattern:

func Test(t *testing.T) {
	is := is.NewRelaxed(t)
	t.Run("sub", func(t *testing.T) {
		is := is.NewRelaxed(t)
		// TODO: test
	})
}

func (*I) NoErr

func (is *I) NoErr(err error)

NoErr asserts that err is nil.

func Test(t *testing.T) {
	is := is.New(t)
	val, err := getVal()
	is.NoErr(err)        // getVal error
	is.True(len(val) > 10) // val cannot be short
}

Will output:

your_test.go:123: err: not found // getVal error

func (*I) True

func (is *I) True(expression bool)

True asserts that the expression is true. The expression code itself will be reported if the assertion fails.

func Test(t *testing.T) {
	is := is.New(t)
	val := method()
	is.True(val != nil) // val should never be nil
}

Will output:

your_test.go:123: not true: val != nil

type T

type T interface {
	// Fail indicates that the test has failed but
	// allowed execution to continue.
	// Fail is called in relaxed mode (via NewRelaxed).
	Fail()
	// FailNow indicates that the test has failed and
	// aborts the test.
	// FailNow is called in strict mode (via New).
	FailNow()
}

T reports when failures occur. testing.T implements this interface.