README
¶
testctx
*testing.Twithcontext.Contextand middleware
Package testctx aims to represent what *testing.T might have looked like if
context.Context existed at the time it was created.
The main benefit of joining these two packages is support for test middleware,
which can greatly cut down on repetition (t.Parallel()) and allow for
transparent test instrumentation.
differences from Go 1.24 t.Context()
Go 1.24 adds a t.Context() accessor which provides a context.Context that
will be canceled when the test completes, just before t.Cleanup-registered
funcs are executed. However, it does not provide any way to modify the
context.
By contrast, this package provides both a t.Context() and a
t.WithContext(ctx) for modifying the context that is passed to sub-tests, and
additionally passes the t.Context() value as a ctx argument to tests.
Documentation
¶
Overview ¶
Package testctx provides a context-aware wrapper around testing.T and testing.B with support for middleware and context propagation. It aims to represent what *testing.T might have looked like if context.Context existed at the time it was created.
Index ¶
- type B
- type BenchFunc
- type Logger
- type Middleware
- type MiddlewareB
- type MiddlewareT
- type RunFunc
- type Runner
- type T
- type TestFunc
- type W
- func (w *W[T]) BaseName() string
- func (w *W[T]) Context() context.Context
- func (w *W[T]) Error(args ...any)
- func (w *W[T]) Errorf(format string, args ...any)
- func (w *W[T]) Fatal(args ...any)
- func (w *W[T]) Fatalf(format string, args ...any)
- func (w *W[T]) Log(args ...any)
- func (w *W[T]) Logf(format string, args ...any)
- func (w *W[T]) Run(name string, fn RunFunc[T]) bool
- func (w *W[T]) RunSuite(s any)
- func (w *W[T]) Skip(args ...any)
- func (w *W[T]) Skipf(format string, args ...any)
- func (w *W[T]) Unwrap() T
- func (w *W[T]) Using(m ...Middleware[T]) *W[T]
- func (w *W[T]) WithContext(ctx context.Context) *W[T]
- func (w *W[T]) WithLogger(l Logger) *W[T]
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Logger ¶ added in v0.0.2
type Logger interface {
Log(args ...any)
Logf(format string, args ...any)
Error(args ...any)
Errorf(format string, args ...any)
}
Logger represents something that can receive test log messages
type Middleware ¶
Middleware represents a function that can wrap a test function
func WithParallel ¶
func WithParallel() Middleware[*testing.T]
WithParallel creates middleware that runs tests in parallel
func WithTimeout ¶
func WithTimeout[T Runner[T]](d time.Duration) Middleware[T]
WithTimeout creates middleware that adds a timeout to the test context
type MiddlewareB ¶ added in v0.0.3
type MiddlewareB = Middleware[*testing.B]
MiddlewareB is a middleware function that takes a context and B
type MiddlewareT ¶ added in v0.0.3
type MiddlewareT = Middleware[*testing.T]
MiddlewareT is a middleware function that takes a context and T
type W ¶
type W[T Runner[T]] struct { // we have to embed testing.TB to become a testing.TB ourselves, // since it has a private method testing.TB // contains filtered or unexported fields }
W is a context-aware wrapper for test/benchmark types that supports middleware and context propagation
func New ¶
func New[T Runner[T]](t T, middleware ...Middleware[T]) *W[T]
New creates a context-aware test wrapper. The wrapper provides:
- Context propagation through test hierarchies
- Middleware support for test instrumentation
- Logging interception via WithLogger
The context is automatically canceled when the test completes. See Using() for details on middleware behavior.
func (*W[T]) Error ¶
Error calls through to the underlying test/benchmark type and logs if a logger is set
func (*W[T]) Errorf ¶
Errorf calls through to the underlying test/benchmark type and logs if a logger is set
func (*W[T]) Fatal ¶
Fatal calls through to the underlying test/benchmark type and logs if a logger is set
func (*W[T]) Fatalf ¶
Fatalf calls through to the underlying test/benchmark type and logs if a logger is set
func (*W[T]) Log ¶
Log calls through to the underlying test/benchmark type and logs if a logger is set
func (*W[T]) Logf ¶
Logf calls through to the underlying test/benchmark type and logs if a logger is set
func (*W[T]) Run ¶
Run runs a subtest with the given name and function. The function will be wrapped by any middleware registered via Using() or New(), with middleware executing in the order described by Using().
func (*W[T]) RunSuite ¶
RunSuite runs all methods on s that match the test method pattern:
- Name starts with "Test"
- Takes (context.Context, *W[T]) parameters
For example:
type MySuite struct{}
func (s *MySuite) TestFoo(ctx context.Context, t *testctx.T) {}
func TestSuite(t *testing.T) {
testctx.New(t).RunSuite(&MySuite{})
}
func (*W[T]) Skip ¶
Skip calls through to the underlying test/benchmark type and logs if a logger is set
func (*W[T]) Skipf ¶
Skipf calls through to the underlying test/benchmark type and logs if a logger is set
func (*W[T]) Using ¶ added in v0.0.2
func (w *W[T]) Using(m ...Middleware[T]) *W[T]
Using adds middleware to the wrapper. Middleware are executed in a nested pattern: the first middleware added becomes the outermost wrapper, the last middleware added becomes the innermost wrapper. For example:
t.Using(first, second, third)
Results in the execution order:
first {
second {
third {
test
}
}
}
This pattern ensures that: 1. "before" middleware code executes from outside-in (first -> third) 2. The test executes 3. "after" middleware code executes from inside-out (third -> first)
This matches the behavior of other middleware systems like net/http handlers and allows middleware to properly wrap both the setup and cleanup of resources.
func (*W[T]) WithContext ¶
WithContext creates a new wrapper with the given context
func (*W[T]) WithLogger ¶ added in v0.0.2
WithLogger returns a new wrapper with the given logger. The logger will receive copies of all test log messages (Log, Logf), errors (Error, Errorf), fatal errors (Fatal, Fatalf), and skip notifications (Skip, Skipf). This allows test output to be captured or redirected while still maintaining the original test behavior.
Source Files
Directories