Reference

Conceptual Model

Test suites are behavioral specifications. Every level of the hierarchy maps to a concept.

Naming conventions at the struct and method level, plus string descriptions in When and It, form a complete specification. The tool generates the wiring and can render the full spec in human-readable form:

This isn't a separate reporting layer — it's the same test hierarchy rendered differently. The spec view and the test output always agree because they come from the same source.

Naming Conventions

The naming conventions are the entire API. There are no config files, struct tags, or annotations.

Types

Methods

Prefixes

Suite Lifecycle

Predictable execution order with guaranteed cleanup — even on panics and fatal errors.

Execution order

All hooks are optional. Unimplemented hooks are no-ops. AfterAll is registered before BeforeAll runs, so cleanup happens even if setup fails. AfterEach is deferred, so it runs even on t.Fatal().

Hook signatures

Every hook accepts either *gotest.T (full DSL access) or *testing.T (plain stdlib). Mix freely within the same suite:

func (s *MySuite) BeforeAll(t *gotest.T)   {}  // full DSL
func (s *MySuite) BeforeEach(t *testing.T) {}  // plain stdlib
func (s *MySuite) TestPlain(t *testing.T)  {}  // no gotest import needed
func (s *MySuite) TestRich(t *gotest.T)    {}  // When, It, MatchSnapshot

Per-test context

When BeforeEach returns a value, each test receives its own isolated context. This enables safe method-level parallelism without shared mutable state:

func (s *MySuite) BeforeEach(t *gotest.T) *TestCtx {
    return &TestCtx{conn: s.pool.Acquire()}
}

func (s *MySuite) AfterEach(t *gotest.T, ctx *TestCtx) {
    ctx.conn.Release()
}

func (s *MySuite) TestCreate(t *gotest.T, ctx *TestCtx) {
    // ctx.conn is unique to this test
}

Parallel execution

Suite-level: Each suite runs as a separate subprocess — full process isolation with zero shared state between suites. This is automatic.

Method-level: Opt-in via SuiteConfig{Parallel: true}. Requires a returning BeforeEach so each parallel test gets its own state.

Test DSL

Methods on *gotest.T for structuring tests. Every method maps to t.Run — the DSL adds semantics, not runtime machinery.

When / It

When groups context. It specifies behavior. Nest them freely to build a specification tree:

func (s *MySuite) TestCreate(t *gotest.T) {
    t.When("email is valid", func(w *gotest.T) {
        w.It("creates the user", func(it *gotest.T) {
            err := s.svc.Create(ctx, validUser)
            gotest.NoError(it, err)
        })
    })

    t.When("email already exists", func(w *gotest.T) {
        w.It("returns ErrDuplicate", func(it *gotest.T) {
            s.svc.Create(ctx, validUser)
            err := s.svc.Create(ctx, validUser)
            gotest.ErrorIs(it, err, ErrDuplicate)
        })
    })
}

Data-driven tests

Iterator API — range over test entries with compile-time type safety:

for it, tc := range gotest.Each(t, []struct {
    Desc  string
    Input string
    Want  int
}{
    {Desc: "single digit", Input: "5", Want: 5},
    {Desc: "negative",     Input: "-3", Want: -3},
}) {
    gotest.Equal(it, tc.Want, parse(tc.Input))
}

Callback API — same semantics, different style:

t.Each(cases, func(it *gotest.T, tc Case) {
    gotest.Equal(it, tc.Want, parse(tc.Input))
})

Snapshot testing

Capture expected output once, verify it on every subsequent run:

t.MatchSnapshot(render(input))              // auto-named from test path
t.MatchSnapshot(render(other), "variant")  // explicit snapshot name

On first run, the snapshot is created. On subsequent runs, the output is compared and failures include a diff. Update all snapshots with gotest --update-snapshots ./....

Async polling

Two forms — a simple boolean check, or rich assertion polling with the full assertion library:

gotest.Eventually(t, func() bool {
    return s.svc.IsReady()
}, 5*time.Second, 100*time.Millisecond)

t.Eventually(5*time.Second, 100*time.Millisecond, func(poll *gotest.T) {
    result, err := s.store.Get("key")
    gotest.NoError(poll, err)
    gotest.Equal(poll, "completed", result.Status)
})

The method form collects intermediate failures without propagating them. On timeout, the last poll's assertion failures are reported. Consistently works the same way — it asserts a condition holds for the full duration and fails on the first violation.

Helpers

Fixtures

Expensive setup — databases, containers, external services — defined once, shared across suites.

Package fixtures

Any struct ending in Fixture is a package fixture. Suites reference it via a named pointer field:

type E2EFixture struct {
    Pool *pgxpool.Pool
}

func (f *E2EFixture) BeforeAll(ctx context.Context) error {
    // start database, populate f.Pool
}

type BatchTestSuite struct {
    Fixture *E2EFixture  // automatically wired
}

Fixture hooks use (ctx context.Context) error signatures. Errors are reported with automatic attribution — E2EFixture.BeforeAll failed: connection refused.

Package fixtures support all four lifecycle hooks. BeforeEach/AfterEach wrap every individual test case, running outside the suite's own hooks:

Nesting

Fixtures compose through named pointer fields — the same pattern suites use to reference fixtures. A child fixture points to its parent, and the generator wires the lifecycle automatically:

type InfraFixture struct {
    Pool *pgxpool.Pool
}

func (f *InfraFixture) BeforeAll(ctx context.Context) error {
    // start database container, populate f.Pool
}

type APIFixture struct {
    Infra     *InfraFixture // named field — wired automatically
    ServerURL string
}

func (f *APIFixture) BeforeAll(ctx context.Context) error {
    // start API server using f.Infra.Pool
}

type OrderTestSuite struct {
    Fixture *APIFixture // accesses f.Infra.Pool and f.ServerURL
}

The parent's hooks run first, wrapping the child's. The suite sees the fully initialized fixture chain:

Shared fixtures

Structs ending in SharedFixture run in a subprocess and share state across packages via JSON serialization. Resources that can't serialize (connection pools, caches) are reconstructed in each test process via Hydrate:

type PostgresSharedFixture struct {
    ConnStr string        // serialized — transfers across processes
    Pool    *pgxpool.Pool // local — reconstructed via Hydrate
}

func (f *PostgresSharedFixture) Hydrate(ctx context.Context) error {
    var err error
    f.Pool, err = pgxpool.New(ctx, f.ConnStr)
    return err
}

Assertions

Type-safe generics with compile-time checking. Zero external dependencies. Works with both *gotest.T and *testing.T.

Equality & identity

Errors

Collections

Comparison & numeric

Strings, time & other

Async

Configuration

Sensible defaults. Override only what you need via marker methods.

Suite configuration

Fixture configuration

Presets

Start with a preset, override individual fields:

Coverage

Statement-weighted coverage from the Go coverage profile. One source of truth, no heuristics.

How it's calculated

The Go compiler instruments code into basic blocks. Each block records how many statements it contains and how many times it was executed. Coverage at any scope — file, directory, workspace — is:

A directory's percentage is the weighted sum of its children, weighted by statement count. This means a parent's number is always derivable from its children — no rounding surprises, no averaging artifacts.

Breadth indicator

Coverage percentage answers: "How well-tested is the code my tests reach?"

The breadth indicator answers a complementary question: "How much of my codebase do my tests reach at all?" It shows profiled source files vs. total source files per directory. A file at 0% still counts as reached — it was instrumented.

Cross-package coverage

Test-only packages (no production code) run with -coverpkg=./..., which instruments the entire module. These cross-package profiles are supplementary — they can increase coverage for files already in scope, but don't expand the file scope. This prevents integration test packages from inflating coverage numbers for code they touch incidentally.

CLI Reference

One command, multiple modes. All go test flags pass through unchanged.

Commands

Flags