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}. Per-test state lives in the context a returning BeforeEach provides, never on the shared suite struct; the generator rejects a BeforeEach that returns nothing in a parallel suite, and a suite without per-test state needs none.

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 new", 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))
}

Snapshot testing

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

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

Snapshots are stored in testdata/__snapshots__/ next to the test file. On first run, the snapshot is created. On subsequent runs, the output is compared and failures include a diff. Snapshot entries are written in deterministic order and are thread-safe — parallel test methods can use MatchSnapshot without coordination.

Update all snapshots with gotest --update-snapshots ./....

Async polling

Package-level functions for polling conditions. Callbacks receive *gotest.R — an assertion recorder that captures failures without propagating them:

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

gotest.Consistently(t, 2*time.Second, 100*time.Millisecond, func(poll *gotest.R) {
    gotest.True(poll, s.cache.IsValid())
})

On each tick the callback runs; if any assertion fails, it retries on the next tick. On timeout, the last failure is reported. Consistently inverts the logic — it fails on the first assertion failure.

Helpers

Fixtures

Expensive setup — databases, containers, external services — defined once, wired into every suite that needs it.

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.

A package fixture lives as long as the suite that binds it: set up before the suite's BeforeAll, torn down after its AfterAll, also when a test panics or the run is stopped. Setup that must happen once per run belongs in a shared fixture. A suite sets up only the fixtures it binds and their dependencies, so a fixture it does not use never delays or fails it.

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 fixture can depend on multiple other fixtures. The generator resolves dependencies and wires the lifecycle automatically:

type DBFixture struct {
    Pool *pgxpool.Pool
}

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

type CacheFixture struct {
    Client *redis.Client
}

func (f *CacheFixture) BeforeAll(ctx context.Context) error {
    // start Redis container, populate f.Client
}

type APIFixture struct {
    DB        *DBFixture    // dependency — wired automatically
    Cache     *CacheFixture // dependency — wired automatically
    ServerURL string
}

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

type OrderTestSuite struct {
    Fixture *APIFixture // accesses DB, Cache, and ServerURL
}

Dependencies are set up first. Independent fixtures set up in parallel; teardown runs in reverse:

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) BeforeAll(ctx context.Context) error {
    f.ConnStr = startPostgres(ctx)
    return f.connect(ctx)
}

func (f *PostgresSharedFixture) Hydrate(ctx context.Context) error   { return f.connect(ctx) }
func (f *PostgresSharedFixture) Dehydrate(ctx context.Context) error { f.Pool.Close(); return nil }

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

SharedFixture dependencies

SharedFixtures can depend on other SharedFixtures via pointer fields — the same pattern used by package fixtures. BeforeAll runs in dependency order (parents first, independent fixtures in parallel). Cyclic dependencies are rejected at generation time.

type SchemaSharedFixture struct {
    Postgres *PostgresSharedFixture  // dependency — Postgres starts first
    Version  string
}

func (f *SchemaSharedFixture) BeforeAll(ctx context.Context) error {
    // f.Postgres.ConnStr is available
    return migrate(f.Postgres.ConnStr)
}

Suites are dispatched as soon as their specific shared fixture dependencies are ready — they don't wait for unrelated fixtures. Transitive dependencies are included automatically: if a suite needs SchemaSharedFixture, it also gets PostgresSharedFixture.

Assertions

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

Equality & identity

Errors

Collections

Comparison & numeric

Strings, time & other

Async

Configuration

Sensible defaults. Override only what you need — via project file, marker methods, or CLI flags.

Precedence

There are two independent configuration scopes:

Project scope — CLI flags override the project file. These control the test runner itself:

Code scope — marker methods override built-in presets. These control individual suites and fixtures:

The two scopes are independent — they don't override each other. For shared fixture timeouts specifically, --setup-timeout is an outer wall-clock budget on the entire setup phase, while SharedFixtureConfig().Timeout is an inner per-fixture deadline. Both run concurrently — whichever fires first wins. When --setup-timeout is omitted, the default outer budget of 2 minutes applies; set it to 0 to disable the outer budget and let only the per-fixture timeouts govern.

Project file — .gotest.yml

Place a .gotest.yml in your project root. gotest finds it by walking up from the working directory, stopping at the first match or at a go.mod boundary. CLI flags always take precedence; zero or omitted fields use defaults.

tags: integration
setup-timeout: 2m
min-coverage: 80
parallel: 12
debounce: 500ms
lint:
  skip:
    - testify

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.

Merged and cross-package profiles

Merged profiles — concatenated per-suite profiles, or overlapping -coverpkg runs — can repeat the same block. Each unique file and range is counted once, keeping the maximum execution count, matching go tool cover behavior. -coverpkg itself is a standard go test flag and passes through unchanged.

Benchmarking

Benchmarks are suite methods. A baseline is a file. A gate is a number.

Writing benchmarks

A Benchmark-prefixed method on any suite takes a *gotest.B. The suite's fixtures and lifecycle hooks apply as they do to tests, so setup happens where it always does — outside the measured loop.

func (s *CacheTestSuite) BenchmarkGetHit(b *gotest.B) {
    key := s.Corpus.Keys[0]        // read fixture state above the loop
    for b.Loop() {
        s.cache.Get(key)
    }
}

Running them

Baselines, deltas, and the gate

In .gotest.yml, bench.baseline and bench.gate set the defaults, so CI and a laptop agree on what a regression is without repeating flags.

Fuzzing

Fuzz targets are suite methods, and their inputs are Go types — including structs the engine cannot take.

Writing a fuzz target

A Fuzz-prefixed method takes a *gotest.F. Seeds go in with f.Add, the property goes in f.Fuzz, and the generator emits one Fuzz<SuiteName>_<MethodName> wrapper per method.

func (s *FrameCodecTestSuite) FuzzFrameRoundTrip(f *gotest.F) {
    f.Add(Frame{Version: 1, Topic: "orders.created", Payload: []byte(`{"id":1}`)})
    f.Fuzz(func(t *gotest.T, in Frame) {
        out, err := Decode(Encode(in))
        gotest.NoError(t, err)
        gotest.Equal(t, in, out)   // property: round trip
    })
}

Struct inputs

Go's fuzzing engine accepts fifteen types, none of them a struct. gotest fans a struct into one engine argument per leaf field at generation time and reassembles the value before each execution. Two consequences follow: a type the fan cannot express is refused when you generate, not hours into a session, and a seed stays an ordinary Go literal instead of a byte blob.

Sessions

Exit codes: 0 when the budget ran out with nothing found, 1 for a finding — a failing target or a new crasher file — and 2 when the session could not run as asked.

Crashers

A crasher whose method cannot be located with confidence is left in place with a warning; promote never partially edits source.

CLI Reference

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

Commands

Flags

Linter

Twenty-eight rules in three tiers. A rule's tier determines how it may be suppressed.

Integrity rules

Violations can make test outcomes unreliable or leak resources. These rules can only be suppressed per line — never project-wide.

Expressiveness rules

The test is correct but its syntax can be improved. These rules can be suppressed per line or project-wide via lint.skip; -fix applies the safe rewrites in one run, overlapping ones included, then reports what it could not fix (exit 3 while findings remain); -diff prints exactly what -fix would write, as a unified diff with paths relative to the current directory, and writes nothing — gotest lint -diff ./... | git apply applies it (a file outside that directory needs git apply --unsafe-paths; a symlink is named by the file it leads to, which -fix writes).

Migration rules

Adoption aids for codebases moving to gotest — coexistence is legitimate. These rules can be suppressed per line or project-wide via lint.skip.

Suppression

Silence a single diagnostic with //nolint:<rule> on its line or in a comment block of its own ending on the line directly above it; on the package line it applies file-wide. Non-integrity rules can also be disabled per run (-skip-<rule>) or project-wide (.gotest.yml → lint.skip).

Exit codes

CI Integration

Failure-focused summaries, inline PR annotations, and coverage reports — out of the box.

gotest summary

The summary subcommand shows only failing tests with their assertion output, filtering out === RUN, === CONT, --- PASS noise. When all tests pass, it prints a single success line:

147 tests passed (2.3s)
Coverage: 82.4%

3 of 147 tests failed

FAIL  pkg/foo TestValidateInput / empty string (12ms)
      foo_test.go:42: expected error, got nil

FAIL  pkg/bar TestProcessOrder / concurrent writes (1.2s)
      bar_test.go:88:
        expected: []string{"a", "b", "c"}
             got: []string{"a", "c", "b"}

In GitHub Actions, --github (auto-detected via $GITHUB_ACTIONS) emits ::error annotations that appear inline on PR diffs and writes a markdown summary to the job summary panel.

GitHub Action

The repository includes a composite action at mvrahden/go-test@v1 that wraps gotest summary --github:

- uses: actions/checkout@v7
- uses: actions/setup-go@v7
  with:
    go-version-file: go.mod

- uses: mvrahden/go-test@v1
  with:
    packages: ./...
    race: true
    coverage: true
    min-coverage: 80

Action inputs

Action outputs

Version resolution

By default (version: gomod), the action runs the gotest your project's go.mod selects: go tool when the tool is declared there, go run otherwise. This keeps the CLI version in sync with the library you already depend on — no version drift between CI and local development.

Set version: latest or a specific tag (e.g. v1.2.0) to install a standalone binary via go install instead. This is useful when your project doesn't depend on go-test as a library.

Manual CI setup

For non-GitHub CI systems, run gotest summary directly:

gotest summary ./... -race -coverprofile=coverage.out

Or pipe from go test -json to summarize existing output without re-running tests:

go test -json ./... | gotest summary --input=-