check

package module
v0.9.0 Latest Latest
Warning

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

 Go to latest Published: Dec 25, 2017 License: MIT Imports: 21 Imported by: 5

README

check GoDoc Go Report Card CircleCI

Helpers to complement Go testing package.

Write tests with ease and fun!

This package is like testify/assert on steroids. :)

Features

  • Compelling output from failed tests:
    • Very easy-to-read dumps for expected and actual values.
    • Same text diff you loved in testify/assert.
    • Also visual diff in GoConvey web UI, if you use it (recommended).
  • Statistics with amount of passed/failed checks.
  • Colored output in terminal.
  • 100% compatible with testing package - check package just provide convenient wrappers for *testing.T methods and doesn't introduce new concepts like BDD, custom test suite or unusual execution flow.
  • All checks you may ever need! :)
  • Very easy to add your own check functions.
  • Concise, handy and consistent API, without dot-import!

Quickstart

Just wrap each (including subtests) *testing.T in check.T and write tests as usually with testing package. Call new methods provided by this package to have more clean/concise test code and cool dump/diff.

import "github.com/powerman/check"

func TestSomething(tt *testing.T) {
	t := check.T{tt}
	t.Equal(2, 2)
	t.Log("You can use new t just like usual *testing.T")
	t.Run("Subtests/Parallel example", func(tt *testing.T) {
		t := check.T{tt}
		t.Parallel()
		t.NotEqual(2, 3, "should not be 3!")
		obj, err := NewObj()
		if t.Nil(err) {
			t.Match(obj.field, `^\d+$`)
		}
	})
}

To get optional statistics about executed checkers add:

func TestMain(m *testing.M) { check.TestMain(m) }

When use goconvey tool, to get nice diff in web UI add:

import _ "github.com/smartystreets/goconvey/convey"

Installation

Require Go 1.9.

go get github.com/powerman/check

Documentation

Overview

Package check provide helpers to complement Go testing package.

Features

This package is like testify/assert on steroids. :)

  • Compelling output from failed tests:
  • Very easy-to-read dumps for expected and actual values.
  • Same text diff you loved in testify/assert.
  • Also visual diff in GoConvey web UI, if you use it (recommended).
  • Statistics with amount of passed/failed checks.
  • Colored output in terminal.
  • 100% compatible with testing package - check package just provide convenient wrappers for *testing.T methods and doesn't introduce new concepts like BDD, custom test suite or unusual execution flow.
  • All checks you may ever need! :)
  • Very easy to add your own check functions.
  • Concise, handy and consistent API, without dot-import!

Quickstart

Just wrap each (including subtests) *testing.T in check.T and write tests as usually with testing package. Call new methods provided by this package to have more clean/concise test code and cool dump/diff. 

import "github.com/powerman/check"

func TestSomething(tt *testing.T) {
	t := check.T{tt}
	t.Equal(2, 2)
	t.Log("You can use new t just like usual *testing.T")
	t.Run("Subtests/Parallel example", func(tt *testing.T) {
		t := check.T{tt}
		t.Parallel()
		t.NotEqual(2, 3, "should not be 3!")
		obj, err := NewObj()
		if t.Nil(err) {
			t.Match(obj.field, `^\d+$`)
		}
	})
}

To get optional statistics about executed checkers add: 

func TestMain(m *testing.M) { check.TestMain(m) }

When use goconvey tool, to get nice diff in web UI add: 

import _ "github.com/smartystreets/goconvey/convey"

Hints

★ How to check for errors: 

// If you just want nil:
t.Nil(err)
t.Err(err, nil)

// Check for (absence of) concrete error:
t.Err(err, io.EOF)
t.NotErr(err, io.EOF) // nil is not io.EOF, so it's ok too

// When need to match by error's text:
t.Match(err, "file.*permission")

// Use Equal ONLY when checking for same instance:
t.Equal(io.EOF, io.EOF)                // this works
t.Equal(io.EOF, errors.New("EOF"))     // this doesn't work!
t.Err(io.EOF, errors.New("EOF"))       // this works
t.DeepEqual(io.EOF, errors.New("EOF")) // this works too

★ Each check returns bool, so you can easily skip problematic code: 

if t.Nil(err) {
	t.Match(obj.field, `^\d+$`)
}

★ You can turn any check into assertion to stop test immediately: 

t.Must(t.Nil(err))

★ You can provide extra description to each check: 

t.Equal(got, want, "Just msg: will Print(), % isn't special")
t.Equal(got, want, "Msg with args: will Printf(): %v", extra)

★ There are short synonyms for checks implementing usual ==, !=, etc.: 

t.EQ(got, want) // same as t.Equal
t.NE(got, want) // same as t.NotEqual
t.LT(got, want) // same as t.Less
t.LE(got, want) // same as t.LessOrEqual
t.GT(got, want) // same as t.Greater
t.GE(got, want) // same as t.GreaterOrEqual

★ If you need custom check, which isn't available out-of-box - see Should checker, it'll let you plug in your own checker with ease.

★ It will panic when called with arg of wrong type - because this means bug in your test.

Contents

There are few special functions (assertions and custom checkers). 

Must
Should

Everything else are just trivial (mostly) checkers which works in obvious way and accept values of any types which makes sense (and panics on everything else). 

Nil             NotNil
Zero            NotZero
True            False

Equal           NotEqual           EQ  NE
DeepEqual       NotDeepEqual
Err             NotErr
BytesEqual      NotBytesEqual
JSONEqual

Greater         LessOrEqual        GT  LE
Less            GreaterOrEqual     LT  GE
Between         NotBetween
BetweenOrEqual  NotBetweenOrEqual
InDelta         NotInDelta
InSMAPE         NotInSMAPE

Len             NotLen
Match           NotMatch
HasPrefix       NotHasPrefix
HasSuffix       NotHasSuffix
HasKey          NotHasKey
Contains        NotContains

HasType         NotHasType
Implements      NotImplements

Panic           NotPanic
PanicMatch      PanicNotMatch

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Report 

func Report()

Report output statistics about passed/failed checks. It should be called from TestMain after m.Run(), for ex.: 

func TestMain(m *testing.M) {
	code := m.Run()
	check.Report()
	os.Exit(code)
}

If this is all you need - just use TestMain instead.

func TestMain 

func TestMain(m *testing.M)

TestMain provides same default implementation as used by testing package with extra Report call to output statistics. Usage: 

func TestMain(m *testing.M) { check.TestMain(m) }

Types

type ShouldFunc1 

type ShouldFunc1 func(t *T, actual interface{}) bool

ShouldFunc1 is like Nil or Zero.

type ShouldFunc2 

type ShouldFunc2 func(t *T, actual, expected interface{}) bool

ShouldFunc2 is like Equal or Match.

type T 

type T struct {
	*testing.T
}

T wraps *testing.T to make it convenient to call checkers in test.

It's convenient to rename Test function's arg from t to something else, create wrapped variable with usual name t and use only t: 

func TestSomething(tt *testing.T) {
	t := check.T{tt}
	// use only t in test and don't touch tt anymore
}

func (*T) Between 

func (t *T) Between(actual, min, max interface{}, msg ...interface{}) bool

Between checks for min < actual < max.

All three actual, min and max must be either:

  • signed integers
  • unsigned integers
  • floats
  • strings
  • time.Time

func (*T) BetweenOrEqual 

func (t *T) BetweenOrEqual(actual, min, max interface{}, msg ...interface{}) bool

BetweenOrEqual checks for min <= actual <= max.

All three actual, min and max must be either:

  • signed integers
  • unsigned integers
  • floats
  • strings
  • time.Time

func (*T) BytesEqual 

func (t *T) BytesEqual(actual, expected []byte, msg ...interface{}) bool

BytesEqual checks for bytes.Equal(actual, expected).

Hint: BytesEqual([]byte{}, []byte(nil)) is true (unlike DeepEqual).

func (*T) Contains 

func (t *T) Contains(actual, expected interface{}, msg ...interface{}) bool

Contains checks is actual contains substring/element expected.

Element of array/slice/map is checked using == expected.

Type of expected depends on type of actual:

  • if actual is a string, then expected should be a string
  • if actual is an array, then expected should have array's element type
  • if actual is a slice, then expected should have slice's element type
  • if actual is a map, then expected should have map's value type

Hint: In a map it looks for a value, if you need to look for a key - use HasKey instead.

func (*T) DeepEqual 

func (t *T) DeepEqual(actual, expected interface{}, msg ...interface{}) bool

DeepEqual checks for reflect.DeepEqual(actual, expected).

func (*T) EQ 

func (t *T) EQ(actual, expected interface{}, msg ...interface{}) bool

EQ is a synonym for Equal.

func (*T) Equal 

func (t *T) Equal(actual, expected interface{}, msg ...interface{}) bool

Equal checks for actual == expected.

Note: For time.Time it uses actual.Equal(expected) instead.

func (*T) Err 

func (t *T) Err(actual, expected error, msg ...interface{}) bool

Err checks is actual error is the same as expected error.

They may be a different instances, but must have same type and value.

Checking for nil is okay, but using Nil(actual) instead is more clean.

func (*T) False 

func (t *T) False(cond bool, msg ...interface{}) bool

False checks for cond == false.

func (*T) GE 

func (t *T) GE(actual, expected interface{}, msg ...interface{}) bool

GE is a synonym for GreaterOrEqual.

func (*T) GT 

func (t *T) GT(actual, expected interface{}, msg ...interface{}) bool

GT is a synonym for Greater.

func (*T) Greater 

func (t *T) Greater(actual, expected interface{}, msg ...interface{}) bool

Greater checks for actual > expected.

Both actual and expected must be either:

  • signed integers
  • unsigned integers
  • floats
  • strings
  • time.Time

func (*T) GreaterOrEqual 

func (t *T) GreaterOrEqual(actual, expected interface{}, msg ...interface{}) bool

GreaterOrEqual checks for actual >= expected.

Both actual and expected must be either:

  • signed integers
  • unsigned integers
  • floats
  • strings
  • time.Time

func (*T) HasKey 

func (t *T) HasKey(actual, expected interface{}, msg ...interface{}) bool

HasKey checks is actual has key expected.

func (*T) HasPrefix 

func (t *T) HasPrefix(actual, expected interface{}, msg ...interface{}) bool

HasPrefix checks for strings.HasPrefix(actual, expected).

Both actual and expected may have any of these types:

  • string - will use as is
  • []byte - will convert with string()
  • []rune - will convert with string()
  • fmt.Stringer - will convert with actual.String()
  • error - will convert with actual.Error()
  • nil - check will always fail

func (*T) HasSuffix 

func (t *T) HasSuffix(actual, expected interface{}, msg ...interface{}) bool

HasSuffix checks for strings.HasSuffix(actual, expected).

Both actual and expected may have any of these types:

  • string - will use as is
  • []byte - will convert with string()
  • []rune - will convert with string()
  • fmt.Stringer - will convert with actual.String()
  • error - will convert with actual.Error()
  • nil - check will always fail

func (*T) HasType 

func (t *T) HasType(actual, expected interface{}, msg ...interface{}) bool

HasType checks is actual has same type as expected.

func (*T) Implements 

func (t *T) Implements(actual, expected interface{}, msg ...interface{}) bool

Implements checks is actual implements interface pointed by expected.

You must use pointer to interface type in expected: 

t.Implements(os.Stdin, (*io.Reader)(nil))

func (*T) InDelta 

func (t *T) InDelta(actual, expected, delta interface{}, msg ...interface{}) bool

InDelta checks for expected-delta <= actual <= expected+delta.

All three actual, expected and delta must be either:

  • signed integers
  • unsigned integers
  • floats
  • time.Time (in this case delta must be time.Duration)

func (*T) InSMAPE 

func (t *T) InSMAPE(actual, expected interface{}, smape float64, msg ...interface{}) bool

InSMAPE checks that actual and expected have a symmetric mean absolute percentage error (SMAPE) is less than given smape.

Both actual and expected must be either:

  • signed integers
  • unsigned integers
  • floats

Allowed smape values are: 0.0 < smape < 100.0.

Used formula returns SMAPE value between 0 and 100 (percents):

  • 0.0 when actual == expected
  • ~0.5 when they differs in ~1%
  • ~5 when they differs in ~10%
  • ~20 when they differs in 1.5 times
  • ~33 when they differs in 2 times
  • 50.0 when they differs in 3 times
  • ~82 when they differs in 10 times
  • 99.0+ when actual and expected differs in 200+ times
  • 100.0 when only one of actual or expected is 0 or one of them is positive while another is negative

func (*T) JSONEqual 

func (t *T) JSONEqual(actual, expected interface{}, msg ...interface{}) bool

JSONEqual normalize formatting of actual and expected (if they're valid JSON) and then checks for bytes.Equal(actual, expected).

Both actual and expected may have any of these types:

  • string
  • []byte
  • json.RawMessage
  • *json.RawMessage
  • nil

In case any of actual or expected is nil, "" or (for string, []byte or []rune) is invalid JSON - check will fail.

func (*T) LE 

func (t *T) LE(actual, expected interface{}, msg ...interface{}) bool

LE is a synonym for LessOrEqual.

func (*T) LT 

func (t *T) LT(actual, expected interface{}, msg ...interface{}) bool

LT is a synonym for Less.

func (*T) Len 

func (t *T) Len(actual interface{}, expected int, msg ...interface{}) bool

Len checks is len(actual) == expected.

func (*T) Less 

func (t *T) Less(actual, expected interface{}, msg ...interface{}) bool

Less checks for actual < expected.

Both actual and expected must be either:

  • signed integers
  • unsigned integers
  • floats
  • strings
  • time.Time

func (*T) LessOrEqual 

func (t *T) LessOrEqual(actual, expected interface{}, msg ...interface{}) bool

LessOrEqual checks for actual <= expected.

Both actual and expected must be either:

  • signed integers
  • unsigned integers
  • floats
  • strings
  • time.Time

func (*T) Match 

func (t *T) Match(actual, regex interface{}, msg ...interface{}) bool

Match checks for regex.MatchString(actual).

Regex type can be either *regexp.Regexp or string.

Actual type can be:

  • string - will match with actual
  • []byte - will match with string(actual)
  • []rune - will match with string(actual)
  • fmt.Stringer - will match with actual.String()
  • error - will match with actual.Error()
  • nil - will not match (even with empty regex)

func (*T) Must 

func (t *T) Must(continueTest bool)

Must interrupt test using t.FailNow if called with false value.

This provides easy way to turn any check into assertion: 

t.Must(t.Nil(err))

func (*T) NE 

func (t *T) NE(actual, expected interface{}, msg ...interface{}) bool

NE is a synonym for NotEqual.

func (*T) Nil 

func (t *T) Nil(actual interface{}, msg ...interface{}) bool

Nil checks for actual == nil.

There is one subtle difference between this check and Go `== nil` (if this surprises you then you should read https://golang.org/doc/faq#nil_error first): 

var intPtr *int
var empty interface{}
var notEmpty interface{} = intPtr
t.True(intPtr == nil)   // TRUE
t.True(empty == nil)    // TRUE
t.True(notEmpty == nil) // FALSE

When you call this function your actual value will be stored in interface{} argument, and this makes any typed nil pointer value `!= nil` inside this function (just like in example above happens with notEmpty variable).

As it is very common case to check some typed pointer using Nil this check has to work around and detect nil even if usual `== nil` return false. But this has nasty side effect: if actual value already was of interface type and contains some typed nil pointer (which is usually bad thing and should be avoid) then Nil check will pass (which may be not what you want/expect): 

t.Nil(nil)              // TRUE
t.Nil(intPtr)           // TRUE
t.Nil(empty)            // TRUE
t.Nil(notEmpty)         // WARNING: also TRUE!

Second subtle case is less usual: uintptr(0) is sorta nil, but not really, so Nil(uintptr(0)) will fail. Nil(unsafe.Pointer(nil)) will also fail, for the same reason. Please do not use this and consider this behaviour undefined, because it may change in the future.

func (*T) NotBetween 

func (t *T) NotBetween(actual, min, max interface{}, msg ...interface{}) bool

NotBetween checks for actual <= min or max <= actual.

All three actual, min and max must be either:

  • signed integers
  • unsigned integers
  • floats
  • strings
  • time.Time

func (*T) NotBetweenOrEqual 

func (t *T) NotBetweenOrEqual(actual, min, max interface{}, msg ...interface{}) bool

NotBetweenOrEqual checks for actual < min or max < actual.

All three actual, min and max must be either:

  • signed integers
  • unsigned integers
  • floats
  • strings
  • time.Time

func (*T) NotBytesEqual 

func (t *T) NotBytesEqual(actual, expected []byte, msg ...interface{}) bool

NotBytesEqual checks for !bytes.Equal(actual, expected).

Hint: NotBytesEqual([]byte{}, []byte(nil)) is false (unlike NotDeepEqual).

func (*T) NotContains 

func (t *T) NotContains(actual, expected interface{}, msg ...interface{}) bool

NotContains checks is actual not contains substring/element expected.

See Contains about supported actual/expected types and check logic.

func (*T) NotDeepEqual 

func (t *T) NotDeepEqual(actual, expected interface{}, msg ...interface{}) bool

NotDeepEqual checks for !reflect.DeepEqual(actual, expected).

func (*T) NotEqual 

func (t *T) NotEqual(actual, expected interface{}, msg ...interface{}) bool

NotEqual checks for actual != expected.

func (*T) NotErr 

func (t *T) NotErr(actual, expected error, msg ...interface{}) bool

NotErr checks is actual error is not the same as expected error.

They must have either different types or values (or one should be nil). Different instances with same type and value will be considered the same error, and so is both nil.

func (*T) NotHasKey 

func (t *T) NotHasKey(actual, expected interface{}, msg ...interface{}) bool

NotHasKey checks is actual has no key expected.

func (*T) NotHasPrefix 

func (t *T) NotHasPrefix(actual, expected interface{}, msg ...interface{}) bool

NotHasPrefix checks for !strings.HasPrefix(actual, expected).

See HasPrefix about supported actual/expected types and check logic.

func (*T) NotHasSuffix 

func (t *T) NotHasSuffix(actual, expected interface{}, msg ...interface{}) bool

NotHasSuffix checks for !strings.HasSuffix(actual, expected).

See HasSuffix about supported actual/expected types and check logic.

func (*T) NotHasType 

func (t *T) NotHasType(actual, expected interface{}, msg ...interface{}) bool

NotHasType checks is actual has not same type as expected.

func (*T) NotImplements 

func (t *T) NotImplements(actual, expected interface{}, msg ...interface{}) bool

NotImplements checks is actual does not implements interface pointed by expected.

You must use pointer to interface type in expected: 

t.NotImplements(os.Stdin, (*fmt.Stringer)(nil))

func (*T) NotInDelta 

func (t *T) NotInDelta(actual, expected, delta interface{}, msg ...interface{}) bool

NotInDelta checks for actual < expected-delta or expected+delta < actual.

All three actual, expected and delta must be either:

  • signed integers
  • unsigned integers
  • floats
  • time.Time (in this case delta must be time.Duration)

func (*T) NotInSMAPE 

func (t *T) NotInSMAPE(actual, expected interface{}, smape float64, msg ...interface{}) bool

NotInSMAPE checks that actual and expected have a symmetric mean absolute percentage error (SMAPE) is greater than or equal to given smape.

See InSMAPE about supported actual/expected types and check logic.

func (*T) NotLen 

func (t *T) NotLen(actual interface{}, expected int, msg ...interface{}) bool

NotLen checks is len(actual) != expected.

func (*T) NotMatch 

func (t *T) NotMatch(actual, regex interface{}, msg ...interface{}) bool

NotMatch checks for !regex.MatchString(actual).

See Match about supported actual/regex types and check logic.

func (*T) NotNil 

func (t *T) NotNil(actual interface{}, msg ...interface{}) bool

NotNil checks for actual != nil.

See Nil about subtle case in check logic.

func (*T) NotPanic 

func (t *T) NotPanic(actual func(), msg ...interface{}) bool

NotPanic checks is actual() don't panics.

It is able to detect panic(nil)… but you should try to avoid using this.

func (*T) NotZero 

func (t *T) NotZero(actual interface{}, msg ...interface{}) bool

NotZero checks is actual is not zero value of it's type.

func (*T) Panic 

func (t *T) Panic(actual func(), msg ...interface{}) bool

Panic checks is actual() panics.

It is able to detect panic(nil)… but you should try to avoid using this.

func (*T) PanicMatch 

func (t *T) PanicMatch(actual func(), regex interface{}, msg ...interface{}) bool

PanicMatch checks is actual() panics and panic text match regex.

Regex type can be either *regexp.Regexp or string.

In case of panic(nil) it will match like panic("<nil>").

func (*T) PanicNotMatch 

func (t *T) PanicNotMatch(actual func(), regex interface{}, msg ...interface{}) bool

PanicNotMatch checks is actual() panics and panic text not match regex.

Regex type can be either *regexp.Regexp or string.

In case of panic(nil) it will match like panic("<nil>").

func (*T) Parallel 

func (t *T) Parallel()

Parallel implements an internal workaround which have no visible effect, so you should just call t.Parallel() as you usually do - it will work as expected.

func (*T) Should 

func (t *T) Should(anyShouldFunc interface{}, args ...interface{}) bool

Should use user-provided check function to do actual check.

anyShouldFunc must have type ShouldFunc1 or ShouldFunc2. It should return it's name and true if check was successful. There is no need to call t.Error in anyShouldFunc - this will be done automatically when it returns.

args must contain at least 1 element for ShouldFunc1 and at least 2 elements for ShouldFunc2. Rest of elements will be processed as usual msg ...interface{} param.

Example: 

func bePositive(_ *check.T, actual interface{}) bool {
	return actual.(int) > 0
}
func TestCustomCheck(tt *testing.T) {
	t := check.T{tt}
	t.Should(bePositive, 42, "custom check!!!")
}

func (*T) True 

func (t *T) True(cond bool, msg ...interface{}) bool

True checks for cond == true.

This can be useful to use your own custom checks, but this way you won't get nice dump/diff for actual/expected values. You'll still have statistics about passed/failed checks and it's shorter than usual: 

if !cond {
	t.Errorf(msg...)
}

func (*T) Zero 

func (t *T) Zero(actual interface{}, msg ...interface{}) bool

Zero checks is actual is zero value of it's type.

Source Files

View all Source files

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.