Documentation
¶
Overview ¶
Package test contains testing utilities.
Package test contains helper functions for testing.
Index ¶
- Variables
- func AssertError(t T, fn func(T))
- func AssertErrorFatal(t T, fn func(T))
- func AssertErrorN(t T, fn func(T), numCalls uint)
- func AssertErrorNFatal(t T, fn func(T), numCalls uint)
- func AssertExit(t T, exit *func(int), fn func(), code int)
- func AssertFatal(t T, fn func(T))
- func AssertNoExit(t T, exit *func(int), fn func())
- func CheckGoexit(function func()) bool
- func CheckPanic(function func()) (didPanic bool, value interface{})
- func Eventually(t T, test func(T), within, pause time.Duration)
- func OnlyOnce(t Skipper)
- func Prng(t interface{ ... }, args ...interface{}) *rand.Rand
- func Seed(seed string, args ...interface{}) int64
- func VerifyClone(t *testing.T, x interface{})
- type Abort
- type ConcT
- type ConcurrentT
- func (t *ConcurrentT) Barrier(name string)
- func (t *ConcurrentT) BarrierN(name string, n int)
- func (t *ConcurrentT) FailBarrier(name string)
- func (t *ConcurrentT) FailBarrierN(name string, n int)
- func (t *ConcurrentT) FailNow()
- func (t *ConcurrentT) Stage(name string, fn func(ConcT))
- func (t *ConcurrentT) StageN(name string, goroutines int, fn func(ConcT))
- func (t *ConcurrentT) Wait(names ...string)
- type EventuallyTest
- type Exit
- type Goexit
- type NameStr
- type Panic
- type Skipper
- type T
- type Tester
- type WrapMock
Constants ¶
This section is empty.
Variables ¶
var Within100ms = NewEventually(within100msTimeout, within100msPause)
Within100ms is an EventuallyTest that runs the test every 5ms up to 100ms.
var Within10s = NewEventually(within10sTimeout, within10sPause)
Within10s is an EventuallyTest that runs the test every 200ms up to 10s.
var Within1s = NewEventually(within1sTimeout, within1sPause)
Within1s is an EventuallyTest that runs the test every 20ms up to 1s.
Functions ¶
func AssertError ¶
AssertError checks that the passed function fn calls T.Errorf() on the T object it calls fn with. Errors are reported on t.
func AssertErrorFatal ¶
AssertErrorFatal checks that the passed function fn calls T.Errorf() and T.FailNow() on the T object it calls fn with. Errors are reported on t.
func AssertErrorN ¶
AssertErrorN checks that the passed function fn calls T.Errorf() numCalls times on the T object it calls fn with. Errors are reported on t.
func AssertErrorNFatal ¶
AssertErrorNFatal checks that the passed function fn calls T.Errorf() numCalls times and T.FailNow() on the T object it calls fn with. Errors are reported on t.
func AssertExit ¶
AssertExit asserts that fn calls the provided exit function with the given code. Usually, exit is a package global function variable that is set to os.Exit by default. The exit function is temporarily modified during the test.
func AssertFatal ¶
AssertFatal checks that the passed function fn calls T.FailNow() on the T object it calls fn with. Errors are reported on t.
func AssertNoExit ¶
AssertNoExit asserts that fn does not call the provided exit function. Usually, exit is a package global function variable that is set to os.Exit by default. The exit function is temporarily modified during the test.
func CheckGoexit ¶
func CheckGoexit(function func()) bool
CheckGoexit tests whether a supplied function calls runtime.Goexit during its execution. Rethrows panics, but wrapped into a Panic object to preserve the stack trace and value passed to panic(). Returns whether the supplied function did call runtime.Goexit.
func CheckPanic ¶
func CheckPanic(function func()) (didPanic bool, value interface{})
CheckPanic tests whether a supplied function panics during its execution. Returns whether the supplied function did panic, and if so, also returns the value passed to panic().
func Eventually ¶
Eventually runs the test `test` until it stops failing for the duration `within` while sleeping for `pause` in between test executions. The final call to `test` with the actual test object `t` is guaranteed to be run exactly at time time.Now().Add(within).
The test should be a read-only test that can safely be run several times without changing the tested objects. Until the final test call, any call to Error or Fail aborts execution of the test function by panicking, to avoid running unnecessary checks.
Eventually does not start any go routines.
func OnlyOnce ¶
func OnlyOnce(t Skipper)
OnlyOnce records a test case and skips it if it already executed once. Test case identification is done by observing the stack. Calls SkipNow() on tests that have already been executed. OnlyOnce() has to be called directly from the test's function, as its first action.
func Prng ¶
Prng returns a pseudo-RNG that is seeded with the output of the `Seed` function by passing it `t.Name()`. Use it in tests with: rng := pkgtest.Prng(t).
func Seed ¶
Seed generates a seed that is dependent on the rootSeed and the passed seed argument. To fix this seed, set the GOTESTSEED environment variable. Example: GOTESTSEED=123 go test ./... Does not work with function pointers or structs without public fields.
func VerifyClone ¶
VerifyClone attempts to recognize improper cloning. Initially, this function will clone its input `x` by calling `x.Clone()`, where `x` is an instance of a struct (or a reference). Then it attempts to detect improper clones by taking the following steps: * Run `reflect.DeepEqual` and terminate with an error if it returns false.
Then, for every exported field of `x`:
- If the field of type `T` is itself is a cloneable, then this value is checked recursively.
- If the field has kind pointer or slice and if it has a `cloneable:"shallow"` tag, it is checked that the pointer or slice value are the same.
- If the field has kind array or slice and a `cloneable:"shallowElements"` tag, it is checked that the the array and slice values shallow copies.
Tags attached to inappropriate fields as well as unknown `cloneable` tags cause an error. The code was not tested with some possible kinds (e.g., channels, maps, and unsafe pointers) and will immediately panic when seeing these types.
Types ¶
type Abort ¶
type Abort interface {
// Stack returns the stack trace of the termination's cause.
Stack() string
// String returns a textual representation of the Abort cause.
String() string
}
Abort describes the reason for an extraordinary function termination. It is either of type Panic or Goexit, or nil.
func CheckAbort ¶
func CheckAbort(function func()) Abort
CheckAbort calls CheckAbortCtx with context.Background.
func CheckAbortCtx ¶
CheckAbortCtx tests whether a supplied function terminates within a context, and whether it is aborted early using panic() or runtime.Goexit(). Returns whether the function terminated before the expiry of the context and if so, a
descriptor of the termination cause or nil if it terminated normally.
type ConcT ¶
type ConcT struct {
require.TestingT // The stage's T object.
// contains filtered or unexported fields
}
ConcT is a testing object used by ConcurrentT stages. It can access the parent ConcurrentT's barrier and wait functions. This way, it can wait for sibling stages and barriers under the same parent ConcurrentT.
func (ConcT) Barrier ¶
Barrier creates a barrier visible to all sibling stages. See ConcurrentT.Barrier.
func (ConcT) BarrierN ¶
BarrierN creates a barrier visible to all sibling stages. See ConcurrentT.BarrierN.
func (ConcT) FailBarrier ¶
FailBarrier marks a barrier visible to all sibling stages as failed. See ConcurrentT.FailBarrier.
func (ConcT) FailBarrierN ¶
FailBarrierN marks a barrier visible to all sibling stages as failed. See ConcurrentT.FailBarrierN.
type ConcurrentT ¶
type ConcurrentT struct {
// contains filtered or unexported fields
}
ConcurrentT is a testing object that can be used in multiple goroutines. Specifically, using the helper objects created by the Stage/StageN calls, FailNow can be called by any goroutine (however, the helper objects must not be used in multiple goroutines).
func NewConcurrent ¶
func NewConcurrent(t require.TestingT) *ConcurrentT
NewConcurrent creates a new concurrent testing object.
func NewConcurrentCtx ¶
func NewConcurrentCtx(ctx context.Context, t require.TestingT) *ConcurrentT
NewConcurrentCtx creates a new concurrent testing object controlled by a context. If that context expires, any ongoing stages and wait calls will fail.
func (*ConcurrentT) Barrier ¶
func (t *ConcurrentT) Barrier(name string)
Barrier is a shorthand notation for Barrier(name, 1).
func (*ConcurrentT) BarrierN ¶
func (t *ConcurrentT) BarrierN(name string, n int)
BarrierN creates a barrier that can be waited on by other goroutines using Wait(). After n calls to BarrierN have been made, all waiting goroutines continue. Similar to Stage and StageN, all calls to the same barrier must share the same n and there must be at most n calls to BarrierN or FailBarrierN for each barrier name.
func (*ConcurrentT) FailBarrier ¶
func (t *ConcurrentT) FailBarrier(name string)
FailBarrier creates a synchronisation point and marks it as failed, so that waiting goroutines will terminate.
func (*ConcurrentT) FailBarrierN ¶
func (t *ConcurrentT) FailBarrierN(name string, n int)
FailBarrierN marks a barrier as failed. It terminates the current test and all goroutines waiting for the barrier.
func (*ConcurrentT) Stage ¶
func (t *ConcurrentT) Stage(name string, fn func(ConcT))
Stage creates a named execution stage. It is a shorthand notation for StageN(name, 1, fn).
func (*ConcurrentT) StageN ¶
func (t *ConcurrentT) StageN(name string, goroutines int, fn func(ConcT))
StageN creates a named execution stage. The parameter goroutines specifies the number of goroutines that share the stage. This number must be consistent across all StageN calls with the same stage name and exactly match the number of times StageN is called for that name. Executes fn. If fn calls FailNow on the supplied T object, the stage fails. fn must not spawn any goroutines or pass along the T object to goroutines that call T.Fatal. To achieve this, make other goroutines call ConcurrentT.StageN() instead. If the test's context expires before the call returns, fails the test.
func (*ConcurrentT) Wait ¶
func (t *ConcurrentT) Wait(names ...string)
Wait waits until the stages and barriers with the requested names terminate or the test's context expires. If the context expires, fails the test. If any stage or barrier fails, terminates the current goroutine or test.
type EventuallyTest ¶
type EventuallyTest struct {
// contains filtered or unexported fields
}
An EventuallyTest has fixed `within` and `pause` duration parameters so that a test for eventual success can be run by just passing the testing object and the test function to method Eventually.
func NewEventually ¶
func NewEventually(within, pause time.Duration) *EventuallyTest
NewEventually creates a new EventuallyTest object which fixes the `within` and `pause` duration parameters.
func (*EventuallyTest) Eventually ¶
func (et *EventuallyTest) Eventually(t T, assertion func(T))
Eventually does the same as the free function of the same name but with the duration parameters `within` and `pause` taken from the EventuallyTest `et`.
type Exit ¶
type Exit struct {
// contains filtered or unexported fields
}
Exit can test calls to an exit function, which is usually a package global set to os.Exit by default.
func NewExit ¶
NewExit creates a new Exit tester. The exit function pointer should usually be the address of a global exit function variable that is set to os.Exit by default. The exit function is temporarily modified during Assert tests.
func (*Exit) AssertExit ¶
AssertExit asserts that fn calls the exit function that was passed to NewExit with the given code. Usually, exit is a package global function variable that is set to os.Exit by default. The exit function is temporarily modified during the test.
func (*Exit) AssertNoExit ¶
func (e *Exit) AssertNoExit(fn func())
AssertNoExit asserts that fn does not call the exit function that was passed to NewExit. Usually, exit is a package global function variable that is set to os.Exit by default. The exit function is temporarily modified during the test.
type Goexit ¶
type Goexit struct {
// contains filtered or unexported fields
}
Goexit describes a recovered runtime.Goexit().
type NameStr ¶
type NameStr string
NameStr endows a string with a function `Name() string` that returns itself. This is helpful for using strings as a first argument to `Prng`.
type Panic ¶
type Panic struct {
// contains filtered or unexported fields
}
Panic describes a recovered runtime.Goexit() or panic(), containing the original message (in case of a panic) and the stack trace that caused the panic().
type Skipper ¶
type Skipper interface {
SkipNow()
}
Skipper is a subset of the testing.T functionality needed by OnlyOnce().
type T ¶
type T interface {
Errorf(string, ...interface{})
FailNow()
Helper()
}
T is part of the interface that testing.T implements. Receive this type instead of *testing.T if you want to test your tests with the Tester.
type Tester ¶
type Tester struct {
// T is the testing object that should be used to report failures of tests.
// Usually, this is a *testing.T.
T
}
Tester is a testing.T mock to test tests. Create new instances of it with NewTester(t), passing it the actual *testing.T that the mock should call if an assertion fails. Then let the tests you want to test receive test.T instead of *testing.T and call your tests inside Tester.AssertX() calls.
func NewTester ¶
NewTester creates a new test tester, wrapping the passed actual test and calling t.Errorf() on it if a test test fails.
func (*Tester) AssertError ¶
AssertError checks that the passed function fn calls T.Errorf() on the T object it calls fn with.
func (*Tester) AssertErrorFatal ¶
AssertErrorFatal checks that the passed function fn calls T.Errorf() and T.FailNow() on the T object it calls fn with.
func (*Tester) AssertErrorN ¶
AssertErrorN checks that the passed function fn calls T.Errorf() numCalls times on the T object it calls fn with.
func (*Tester) AssertErrorNFatal ¶
AssertErrorNFatal checks that the passed function fn calls T.Errorf() numCalls times and T.FailNow() on the T object it calls fn with.
func (*Tester) AssertFatal ¶
AssertFatal checks that the passed function fn calls T.FailNow() on the T object it calls fn with.
type WrapMock ¶
type WrapMock struct {
// contains filtered or unexported fields
}
WrapMock is a mocking object to test whether an object's methods are called by an outer function with the same name, thus being wrapped. This is particularly useful for global objects like the global logger that have wrapped package function calls.
func NewWrapMock ¶
NewWrapMock creates a new mock for wrapped objects.
func (*WrapMock) AssertCalled ¶
func (w *WrapMock) AssertCalled()
AssertCalled asserts that the object was called and resets the called flag afterwards.
func (*WrapMock) AssertWrapped ¶
func (w *WrapMock) AssertWrapped()
AssertWrapped asserts that the two function names in the stack above AssertWrapped() are the same. This means that the mocked object's method calling AssertWrapped() is wrapped. The fact that the method was called is also recorded and can be asserted with AssertCalled().
All method implementations of the object should just call this method.
Source Files