assert

package
v0.8.11 Latest Latest
Warning

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

 Go to latest Published: Oct 21, 2022 License: MIT Imports: 9 Imported by: 59

Documentation

Overview

Package assert includes runtime assertion helpers both for normal execution as well as a assertion package for Go's testing. What makes solution unique is its capable to support both modes with same API. Only thing you need to do is to add following two lines at the beginning of your unit tests: 

func TestInvite(t *testing.T) {
	assert.PushTester(t) // push testing variable t beginning of any test
	defer assert.PopTester()

	alice.Node = root1.Invite(alice.Node, root1.Key, alice.PubKey, 1)
	assert.Equal(alice.Len(), 1) // assert anything normally

Especially powerful feature is that even if some assertion violation happens during the execution of called functions like inside of the Invite() function instead of the actual Test function, it's reported correctly as normal test failure!

Instead of mocking or other mechanisms we can integrate our preconditions and raise up quality of our software. 

"Assertsions are active comments"

The package offers a convenient way to set preconditions to code which allow us detect programming errors and API violations faster. Still allowing production-time error handling if needed. When used with the err2 package panics can be turned to normal Go's error values by using proper Asserter like P: 

assert.P.True(s != "", "sub-command cannot be empty")

Please see the code examples for more information.

Note. assert.That's performance is equal to the if-statement. Most of the generics-based versions are as fast, but some of them (Equal, SLen, MLen) aren't. If your algorithm is performance-critical please run `make bench` in the err2 repo and decide case by case.

Note. Format string functions need to be own instances because of Go's vet and test tool integration.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	// P is a production Asserter that sets panic objects to errors which
	// allows err2 handlers to catch them.
	P = AsserterToError

	// D is a development Asserter that sets panic objects to strings that
	// doesn't by caught by err2 handlers.
	D Asserter = AsserterDebug

	// DefaultAsserter is a default asserter used for package-level functions
	// like assert.That(). It is the same as the production asserter P, which
	// treats assert failures as Go errors, but in addition to that, it formats
	// the assertion message properly. Naturally, only if err2 handlers are
	// found in the call stack, these errors are caught.
	//
	// You are free to set it according to your current preferences. For
	// example, it might be better to panic about every assertion fault during
	// the tests. When in other cases, throw an error.
	DefaultAsserter = AsserterToError | AsserterFormattedCallerInfo
)

Functions

func CNotNil added in v0.8.0 

func CNotNil[T any](c chan T, a ...any)

CNotNil asserts that the channel is not nil. If it is it panics/errors (default Asserter) with the given message.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func(c chan byte) (err error) {
		defer err2.Returnf(&err, "sample")

		assert.CNotNil(c)
		return err
	}
	var c chan byte
	err := sample(c)
	fmt.Printf("%v", err)
}

Output:

sample: assert_test.go:90 ExampleCNotNil.func1 assertion violation: channel is nil

func DeepEqual added in v0.8.9 

func DeepEqual(val, want any, a ...any)

DeepEqual asserts that the (whatever) values are equal. If not it panics/errors (current Asserter) with the given message.

func Empty added in v0.8.9 

func Empty(obj string, a ...any)

Empty asserts that the string is empty. If it is NOT, it panics/errors (current Asserter) with the given message.

func Equal added in v0.8.0 

func Equal[T comparable](val, want T, a ...any)

Equal asserts that the values are equal. If not it panics/errors (current Asserter) with the given message.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func(b []byte) (err error) {
		defer err2.Returnf(&err, "sample")

		assert.Equal(len(b), 3)
		return err
	}
	err := sample([]byte{1, 2})
	fmt.Printf("%v", err)
}

Output:

sample: assert_test.go:116 ExampleEqual.func1 assertion violation: got 2, want 3

func Error added in v0.8.8 

func Error(err error, a ...any)

Error asserts that the err is not nil. If it is it panics with the given formatting string. Thanks to inlining, the performance penalty is equal to a single 'if-statement' that is almost nothing.

func INil added in v0.8.10 

func INil(i any, a ...any)

INil asserts that the interface value IS nil. If it is it panics/errors (default Asserter) with the given message.

func INotNil added in v0.8.9 

func INotNil(i any, a ...any)

INotNil asserts that the interface value is NOT nil. If it is it panics/errors (default Asserter) with the given message.

func MKeyExists added in v0.8.10 

func MKeyExists[T comparable, U any](obj map[T]U, key T, a ...any) (val U)

MKeyExists asserts that the map key exists. If not it panics/errors (current Asserter) with the given message.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func(b string) (err error) {
		defer err2.Returnf(&err, "sample")

		m := map[string]string{
			"1": "one",
		}
		v := assert.MKeyExists(m, "1")
		assert.Equal(v, "one")
		_ = assert.MKeyExists(m, b)
		return err
	}
	err := sample("2")
	fmt.Printf("%v", err)
}

Output:

sample: assert_test.go:211 ExampleMKeyExists.func1 assertion violation: key '2' doesn't exist

func MLen added in v0.8.0 

func MLen[T comparable, U any](obj map[T]U, length int, a ...any)

MLen asserts that the length of the map is equal to the given. If not it panics/errors (current Asserter) with the given message. Note! This is reasonably fast but not as fast as 'That' because of lacking inlining for the current implementation of Go's type parametric functions.

func MNotEmpty added in v0.8.3 

func MNotEmpty[T comparable, U any](obj map[T]U, a ...any)

MNotEmpty asserts that the map is not empty. If it is, it panics/errors (current Asserter) with the given message. Note! This is reasonably fast but not as fast as 'That' because of lacking inlining for the current implementation of Go's type parametric functions.

func MNotNil added in v0.8.0 

func MNotNil[T comparable, U any](m map[T]U, a ...any)

MNotNil asserts that the map is not nil. If it is it panics/errors (default Asserter) with the given message.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func(b map[string]byte) (err error) {
		defer err2.Returnf(&err, "sample")

		assert.MNotNil(b)
		return err
	}
	var b map[string]byte
	err := sample(b)
	fmt.Printf("%v", err)
}

Output:

sample: assert_test.go:77 ExampleMNotNil.func1 assertion violation: map is nil

func NoError added in v0.8.8 

func NoError(err error, a ...any)

NoError asserts that the error is nil. If is not it panics with the given formatting string. Thanks to inlining, the performance penalty is equal to a single 'if-statement' that is almost nothing.

func NotDeepEqual added in v0.8.10 

func NotDeepEqual(val, want any, a ...any)

NotDeepEqual asserts that the (whatever) values are equal. If not it panics/errors (current Asserter) with the given message. NOTE, it uses reflect.DeepEqual which means that also the types must be the same: 

assert.DeepEqual(pubKey, ed25519.PublicKey(pubKeyBytes))

func NotEmpty added in v0.8.3 

func NotEmpty(obj string, a ...any)

NotEmpty asserts that the string is not empty. If it is, it panics/errors (current Asserter) with the given message.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func(b string) (err error) {
		defer err2.Returnf(&err, "sample")

		assert.Empty(b)
		assert.NotEmpty(b)
		return err
	}
	err := sample("")
	fmt.Printf("%v", err)
}

Output:

sample: assert_test.go:194 ExampleNotEmpty.func1 assertion violation: string shouldn't be empty

func NotEqual added in v0.8.0 

func NotEqual[T comparable](val, want T, a ...any)

NotEqual asserts that the values aren't equal. If they are it panics/errors (current Asserter) with the given message.

func NotImplemented added in v0.8.3 

func NotImplemented(a ...any)

NotImplemented always panics with 'not implemented' assertion message.

func NotNil added in v0.8.0 

func NotNil[T any](p *T, a ...any)

NotNil asserts that the value is not nil. If it is it panics/errors (default Asserter) with the given message.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func(b *byte) (err error) {
		defer err2.Returnf(&err, "sample")

		assert.NotNil(b)
		return err
	}
	var b *byte
	err := sample(b)
	fmt.Printf("%v", err)
}

Output:

sample: assert_test.go:64 ExampleNotNil.func1 assertion violation: pointer is nil

func PopTester added in v0.8.8 

func PopTester()

PopTester pops the testing context reference from the memory. This isn't totally necessary, but if you want play by book, please do it. Usually done by defer after PushTester. 

for _, tt := range tests {
	t.Run(tt.name, func(t *testing.T) {
		assert.PushTester(t) // <- important!
		defer assert.PopTester() // <- for good girls and not so bad boys
		...
		assert.That(something, "test won't work")
	})
}

func PushTester added in v0.8.8 

func PushTester(t testing.TB)

PushTester sets the current testing context for default asserter. This must be called at the beginning of every test. 

for _, tt := range tests {
	t.Run(tt.name, func(t *testing.T) {
		assert.PushTester(t) // <- IMPORTANT!
		defer assert.PopTester()
		...
		assert.That(something, "test won't work")
	})
}

func SLen added in v0.8.0 

func SLen[T any](obj []T, length int, a ...any)

SLen asserts that the length of the slice is equal to the given. If not it panics/errors (current Asserter) with the given message. Note! This is reasonably fast but not as fast as 'That' because of lacking inlining for the current implementation of Go's type parametric functions.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func(b []byte) (err error) {
		defer err2.Returnf(&err, "sample")

		assert.SLen(b, 3)
		return err
	}
	err := sample([]byte{1, 2})
	fmt.Printf("%v", err)
}

Output:

sample: assert_test.go:128 ExampleSLen.func1 assertion violation: got 2, want 3

func SNil added in v0.8.8 

func SNil[T any](s []T, a ...any)

SNil asserts that the slice IS nil. If it is it panics/errors (default Asserter) with the given message.

func SNotEmpty added in v0.8.3 

func SNotEmpty[T any](obj []T, a ...any)

SNotEmpty asserts that the slice is not empty. If it is, it panics/errors (current Asserter) with the given message. Note! This is reasonably fast but not as fast as 'That' because of lacking inlining for the current implementation of Go's type parametric functions.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func(b []byte) (err error) {
		defer err2.Returnf(&err, "sample")

		assert.SNotEmpty(b)
		return err
	}
	err := sample([]byte{})
	fmt.Printf("%v", err)
}

Output:

sample: assert_test.go:181 ExampleSNotEmpty.func1 assertion violation: slice shouldn't be empty

func SNotNil added in v0.8.0 

func SNotNil[T any](s []T, a ...any)

SNotNil asserts that the slice is not nil. If it is it panics/errors (default Asserter) with the given message.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func(b []byte) (err error) {
		defer err2.Returnf(&err, "sample")

		assert.SNotNil(b)
		return err
	}
	var b []byte
	err := sample(b)
	fmt.Printf("%v", err)
}

Output:

sample: assert_test.go:103 ExampleSNotNil.func1 assertion violation: slice is nil

func That added in v0.8.0 

func That(term bool, a ...any)

That asserts that the term is true. If not it panics with the given formatting string. Thanks to inlining, the performance penalty is equal to a single 'if-statement' that is almost nothing.

func ThatNot added in v0.8.8 

func ThatNot(term bool, a ...any)

ThatNot asserts that the term is NOT true. If is it panics with the given formatting string. Thanks to inlining, the performance penalty is equal to a single 'if-statement' that is almost nothing.

Types

type Asserter 

type Asserter uint32

Asserter is type for asserter object guided by its flags. 

const (
	// AsserterDebug is the default mode where all asserts are treaded as
	// panics
	AsserterDebug Asserter = 0

	// AsserterToError is Asserter flag to guide asserter to use Go's error
	// type for panics.
	AsserterToError Asserter = 1 << iota

	// AsserterStackTrace is Asserter flag to print call stack to stdout.
	AsserterStackTrace

	// AsserterCallerInfo is an asserter flag to add info of the function
	// asserting. It includes filename, line number and function name.
	AsserterCallerInfo

	// AsserterFormattedCallerInfo is an asserter flag to add info of the function
	// asserting. It includes filename, line number and function name in
	// multi-line formatted string output.
	AsserterFormattedCallerInfo

	// AsserterUnitTesting is an asserter only for unit testing. It's exclusive.
	AsserterUnitTesting
)

func (Asserter) Empty 

func (asserter Asserter) Empty(obj any, msg ...any)

Empty asserts that length of the object is zero. If not it panics with the given formatting string. Note! This is slow.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func(b []byte) (err error) {
		defer err2.Returnf(&err, "sample")

		assert.P.Empty(b)
		return err
	}
	err := sample([]byte{1, 2})
	fmt.Printf("%v", err)
}

Output:

sample: got 2, want == 0

func (Asserter) EqualInt 

func (asserter Asserter) EqualInt(val, want int, a ...any)

EqualInt asserts that integers are equal. If not it panics/errors (current Asserter) with the given msg.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func(b []byte) (err error) {
		defer err2.Returnf(&err, "sample")

		assert.P.EqualInt(len(b), 3)
		return err
	}
	err := sample([]byte{1, 2})
	fmt.Printf("%v", err)
}

Output:

sample: got 2, want 3

func (Asserter) Len 

func (asserter Asserter) Len(obj any, length int, a ...any)

Len asserts that length of the object is equal to given. If not it panics/errors (current Asserter) with the given msg. Note! This is very slow (before we have generics). If you need performance use EqualInt. It's not so convenient, though.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func(b []byte) (err error) {
		defer err2.Returnf(&err, "sample")

		assert.P.Len(b, 3)
		return err
	}
	err := sample([]byte{1, 2})
	fmt.Printf("%v", err)
}

Output:

sample: got 2, want 3

func (Asserter) Lenf 

func (asserter Asserter) Lenf(obj any, length int, format string, a ...any)

Lenf asserts that length of the object is equal to given. If not it panics/errors (current Asserter) with the given msg. Note! This is very slow (before we have generics). If you need performance use EqualInt. It's not so convenient, though.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func(b []byte) (err error) {
		defer err2.Returnf(&err, "sample")

		assert.P.Lenf(b, 3, "actual len = %d", len(b))
		return err
	}
	err := sample([]byte{1, 2})
	fmt.Printf("%v", err)
}

Output:

sample: actual len = 2

func (Asserter) NoImplementation 

func (asserter Asserter) NoImplementation(a ...any)

NoImplementation always fails with no implementation.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func(m int) (err error) {
		defer err2.Returnf(&err, "sample")

		switch m {
		case 1:
			return nil
		default:
			assert.P.NoImplementation()
		}
		return err
	}
	err := sample(0)
	fmt.Printf("%v", err)
}

Output:

sample: not implemented

func (Asserter) NotEmpty 

func (asserter Asserter) NotEmpty(obj any, msg ...any)

NotEmpty asserts that length of the object greater than zero. If not it panics with the given formatting string. Note! This is slow.

func (Asserter) NotEmptyf 

func (asserter Asserter) NotEmptyf(obj any, format string, msg ...any)

NotEmptyf asserts that length of the object greater than zero. If not it panics with the given formatting string. Note! This is slow.

func (Asserter) True 

func (asserter Asserter) True(term bool, a ...any)

True asserts that term is true. If not it panics with the given formatting string. Note! This and Truef are the most performant of all the assertion functions.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func() (err error) {
		defer err2.Returnf(&err, "sample")

		assert.P.True(false, "assertion test")
		return err
	}
	err := sample()
	fmt.Printf("%v", err)
}

Output:

sample: assertion test

func (Asserter) Truef 

func (asserter Asserter) Truef(term bool, format string, a ...any)

Truef asserts that term is true. If not it panics with the given formatting string.

Example 
package main

import (
	"fmt"

	"github.com/lainio/err2"
	"github.com/lainio/err2/assert"
)

func main() {
	sample := func() (err error) {
		defer err2.Returnf(&err, "sample")

		assert.P.Truef(false, "assertion test %d", 2)
		return err
	}
	err := sample()
	fmt.Printf("%v", err)
}

Output:

sample: assertion test 2

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.