tst

README

tst

tst is a collection of small, focused helpers designed to make Go tests leaner, more readable, and easier to maintain. It provides intuitive functions for common testing patterns, reducing boilerplate and making the intent of your tests clearer.

Key Features

• Lean Error Handling: Reduce if err != nil { t.Fatalf(...) } blocks to a single line.
• Value Unwrapping: Extract values from functions that return (value V, err error) or (value V, ok bool) directly in your assertions.
• Deep Equality: Built-in support for google/go-cmp for powerful, expressive and readable diffs.
• Cascading Failure Prevention: Easily stop tests early if a critical assertion fails.
• Concurrency Helpers: Shorthand for parallel tests and context management.

Installation

go get github.com/empijei/tst

Usage Examples

Error Handling and Value Unwrapping

Instead of:

f, err := os.Open("config.json")
if err != nil {
    t.Fatalf("failed to open config: %v", err)
}
defer f.Close()

Use:

f := tst.Do(os.Open("config.json"))(t)
defer f.Close()

Deep Equality with tst.Is

tst.Is uses go-cmp to provide detailed diffs when values don't match.

want := &User{Name: "Alice", Age: 30}
got := FetchUser(1)
tst.Is(want, got, t)

Asserting Errors with tst.Err

Verify that an error is not nil and optionally contains a specific substring.

_, err := ProcessData(invalidInput)
tst.Err("invalid input", err, t)

Stopping Tests Early with tst.Ko

Prevent a flood of error messages by stopping the test if a previous assertion failed.

tst.Is(expectedHeader, actualHeader, t)
tst.Ko(t) // Stop here if header check failed, as subsequent tests might be meaningless.

tst.Is(expectedBody, actualBody, t)

Parallel Tests and Context

tst.Go is a convenient shorthand for t.Parallel() that also returns the test context.

func TestSomething(t *testing.T) {
    ctx := tst.Go(t)
    // Run your test using ctx...
}

API Reference

Do[V any](v V, err error) func(t Test) V

Unwraps a result and stops the test immediately (t.Fatalf) if an error occurred.

Do2[V1, V2 any](v1 V1, v2 V2, err error) func(t Test) (V1, V2)

Like Do, but for functions that return two values and an error.

DoB[V any](v V, ok bool) func(t Test) V

Unwraps a result and stops the test immediately (t.Fatalf) if ok is false.

No(err error, t Test)

Stops the test immediately (t.Fatalf) if the provided error is not nil.

Be(ok bool, t Test)

Stops the test immediately (t.Fatalf) if ok is false.

Is[T any](want, got T, t Test, opts ...cmp.Option)

Checks that want matches got via cmp.Diff. Calls t.Errorf if there's a mismatch.

Err(errorSubMessage string, err error, t Test)

Checks if the provided error is not nil and contains an optional message.

Ko(t Test)

Stops the test immediately (t.Fatalf) if the test has already failed.

Go(t PTest) context.Context

Shorthand for t.Parallel() and returns the test context.

Documentation

Overview

Package tst provides a collection of small, focused helpers designed to make Go tests leaner and more readable. It aims for a minimal learning curve by providing intuitive functions for common testing patterns like error handling, value unwrapping, and deep equality checks.

Index

• func Be(ok bool, t Test)
• func Do[V any](v V, err error) func(t Test) V
• func Do2[V1, V2 any](v1 V1, v2 V2, err error) func(t Test) (V1, V2)
• func DoB[V any](v V, ok bool) func(t Test) V
• func Err(errorSubMessage string, err error, t Test)
• func Go(t PTest) context.Context
• func Is[T any](want, got T, t Test, opts ...cmp.Option)
• func IsSubString(want, got string, t Test)
• func Ko(t Test)
• func LoadGolden[V any](name string, t Test) V
• func No(err error, t Test)
• func RecordGolden(name string, v any, t Test)
• func With[T any](val *T, temp T, t Test)
• type PTest
• type Test

Functions

func Be

func Be(ok bool, t Test)

Be stops the test immediately (t.Fatalf) if ok is false.

Example:

tst.Be(len(list) > 0, t)

func Do

func Do[V any](v V, err error) func(t Test) V

Do unwraps a result and stops the test immediately (t.Fatalf) if an error occurred.

Example:

f := tst.Do(os.Open("file.txt"))(t)
defer f.Close()

func Do2

func Do2[V1, V2 any](v1 V1, v2 V2, err error) func(t Test) (V1, V2)

Do2 is like Do, but for functions that return two values and an error.

Example:

v1, v2 := tst.Do2(returnsTwoValuesAndError())(t)

func DoB

func DoB[V any](v V, ok bool) func(t Test) V

DoB unwraps a result and stops the test immediately (t.Fatalf) if ok is false.

Example:

val := tst.DoB(syncMap.Load("foo"))(t)

func Err

func Err(errorSubMessage string, err error, t Test)

Err checks if the provided error is not nil and contains an optional message.

It calls t.Fatalf if err is nil, and t.Errorf if the message doesn't match. If no message is passed, it just checks that an error occurred.

Example:

tst.Err("permission denied", err, t)

func Go

func Go(t PTest) context.Context

Go is a shorthand for t.Parallel() and returns the test context.

Example:

ctx := tst.Go(t)

func Is

func Is[T any](want, got T, t Test, opts ...cmp.Option)

Is checks that want matches got via cmp.Diff using the options provided. It calls t.Errorf if there's a mismatch. Errors are compared with cmpopts.EquateErrors by default.

Options can be found in both cmp and cmpopts packages.

Example:

tst.Is(want, got, t)

func IsSubString

func IsSubString(want, got string, t Test)

IsSubString is a specialized version of Is to check that want is a substring of got.

func Ko

func Ko(t Test)

Ko stops the test immediately (t.Fatalf) if the test has already failed. This is useful to prevent cascading errors if a previous check failed.

Example:

tst.Is(want, got, t)
tst.Ko(t) // Stop here if Is failed.

func LoadGolden

func LoadGolden[V any](name string, t Test) V

LoadGolden loads a previously recorded golden file.

func No

func No(err error, t Test)

No stops the test immediately (t.Fatalf) if the provided error is not nil.

Example:

tst.No(err, t)

func RecordGolden

func RecordGolden(name string, v any, t Test)

RecordGolden records a golden file and makes the test fail after printing its value.

func With

func With[T any](val *T, temp T, t Test)

With replaces the value pointed by val with temp, and resets it after the test is done running.

Types

type PTest

type PTest interface {
	Test
	Context() context.Context
	Parallel()
}

PTest is an abstraction over *testing.T that includes Parallel and Context.

type Test

type Test interface {
	Helper()
	Name() string
	Fatalf(string, ...any)
	Errorf(string, ...any)
	Failed() bool
	Cleanup(func())
}

Test is an abstraction over *testing.(T|B|F). It allows tst helpers to work with different testing types.