# gotest > A go test code generator. Struct-based suites with lifecycle hooks, BDD structure, and spec output for AI-assisted workflows. Zero reflection, zero runtime deps. gotest is a code-generation framework for Go test suites: you write `*TestSuite` structs with lifecycle methods, and `go tool gotest` generates the harness. Run it via Go's tool directive (`go get -tool github.com/mvrahden/go-test/cmd/gotest@`, then `go tool gotest`), never a global binary. `go test` alone does not run suites. ## Docs - [README](https://github.com/mvrahden/go-test/blob/main/README.md): install, suites, fixtures, assertions, CLI, CI - [Agent reference](https://github.com/mvrahden/go-test/blob/main/AGENTS.md): the rules an agent must follow, and the full assertion list - [Reference](https://mvrahden.github.io/go-test/reference/): naming conventions, lifecycle, fixture model, assertions, coverage - [Agent skill](https://github.com/mvrahden/go-test/tree/main/skills/writing-gotest-tests): `writing-gotest-tests`, installable with `npx skills add mvrahden/go-test` or, from v1.34.0, `go tool gotest skill install`, which writes the copy matching the pinned version - [API](https://pkg.go.dev/github.com/mvrahden/go-test): package documentation ## Blog - [Teach Your Coding Agent gotest](https://mvrahden.github.io/go-test/blog/teach-your-coding-agent-gotest/): Coding agents write Go tests from stdlib and testify habits. The writing-gotest-tests skill teaches them gotest's rules, matched to your pinned version. - [From Crasher to Regression Test: Triaging Go Fuzz Failures](https://mvrahden.github.io/go-test/blog/fuzz-crasher-triage/): A Go fuzz session found something. What the corpus file is, how to re-run it, why an unverified re-run proves nothing, and how to promote it to a seed. - [Fuzzing Go Structs: Past the Fifteen Types the Engine Accepts](https://mvrahden.github.io/go-test/blog/fuzzing-go-structs/): Go's fuzzing engine takes fifteen primitive types, none of them a struct. How gotest fans a struct into engine arguments and keeps seeds readable. - [Failing a Pull Request on a Go Benchmark Regression](https://mvrahden.github.io/go-test/blog/benchmark-regression-gate/): Turn Go benchmarks into a CI gate: save a baseline, compare a branch against it, and fail the build when a regression is statistically real. - [How Go Actually Tests: Data From 1,000 Repositories](https://mvrahden.github.io/go-test/blog/how-go-actually-tests/): We parsed 720,118 test functions across the 1,000 most-starred Go repos. What the data says about parallelism, sleeps, golden files, and containers. - [gotest VS Code Extension: Suite-Aware Go Testing](https://mvrahden.github.io/go-test/blog/your-editor-knows-your-tests/): The gotest VS Code extension makes Go test suites visible in your editor: discovery, run/debug at any level, spec view, coverage gutters, and watch mode. - [Go Tests in GitHub Actions: The gotest CI Setup Guide](https://mvrahden.github.io/go-test/blog/gotest-in-ci/): Run Go tests in GitHub Actions with the gotest action: failure-focused summaries, inline PR annotations, coverage thresholds, and the focus-prefix guard. - [Contract Testing Go Interfaces with Generic Test Suites](https://mvrahden.github.io/go-test/blog/contract-testing-generics/): Go interface contract testing with generics: define the contract in one test suite, instantiate it for every implementation, and catch drift as it happens. - [Advanced Go Test Fixtures: Composition, Containers, Config](https://mvrahden.github.io/go-test/blog/advanced-fixture-patterns/): Go test fixture patterns at scale: composition, container-backed fixtures, per-test isolation, thread-safe state, and per-environment configuration. - [Sharing Test Fixtures Across Go Packages](https://mvrahden.github.io/go-test/blog/shared-fixtures/): go test runs each package in a separate OS process. How do you share a database container across packages? gotest's SharedFixture model solves it. - [Go Tests as Living Documentation: The Spec View](https://mvrahden.github.io/go-test/blog/tests-as-documentation/): Tests as documentation that can't drift: gotest's spec view turns Go tests into living specification documents in terminal, markdown, and JSON. - [Snapshot Testing in Go](https://mvrahden.github.io/go-test/blog/snapshot-testing-in-go/): Snapshot testing in Go without boilerplate: gotest.MatchSnapshot stores golden files, diffs on mismatch, works in parallel tests, and is read-only in CI. - [Testing Async Code in Go Without time.Sleep](https://mvrahden.github.io/go-test/blog/testing-async-go/): Go async tests without time.Sleep: Eventually and Consistently separate how long to wait from how often to check, so tests stay fast and stop flaking. - [Go Test Watch Mode and Focused Tests: The Inner Loop](https://mvrahden.github.io/go-test/blog/the-inner-loop/): Go test watch mode, F_ focus prefixes, and spec output: how gotest compresses the change-test-read cycle from 30 seconds to under one. - [Go Test Lifecycle: Setup, Teardown, and Execution Order](https://mvrahden.github.io/go-test/blog/go-test-lifecycle/): Go test setup and teardown, in order: suite hooks, fixture hooks, cleanup guarantees, and retries — the full gotest lifecycle from BeforeAll to AfterAll. - [BDD in Go: What Behavior-Driven Development Actually Means](https://mvrahden.github.io/go-test/blog/what-bdd-means-in-go/): BDD in Go isn't syntax — it's communication. How Go's type system maps to behavior-driven development without describe/context/it ceremony or a DSL. - [Your First Go Test Suite in 10 Minutes: A gotest Tutorial](https://mvrahden.github.io/go-test/blog/zero-to-suite/): Go test suite tutorial: from an empty module to a running gotest suite with lifecycle hooks, BDD structure, and readable spec output — in 10 minutes. - [Why Your Go Tests Are Slow (and What to Do About It)](https://mvrahden.github.io/go-test/blog/go-testing-at-scale/): Most slow Go test suites aren't slow because of slow tests. Sequential execution, redundant setup, and shared state are what prevent parallelism. - [Migrating from `testify/suite` to gotest](https://mvrahden.github.io/go-test/blog/testify-migration-guide/): A practical guide to migrating Go test suites from testify/suite to gotest: before-and-after examples, automated migration, and what needs manual review. - [Code Generation vs Reflection in Go Test Frameworks](https://mvrahden.github.io/go-test/blog/code-generation-not-reflection/): Most Go test frameworks use reflection to find suites at runtime. gotest uses AST-based code generation with overlay filesystem injection instead. - [Readable Go Tests with BDD-Style Subtests](https://mvrahden.github.io/go-test/blog/readable-tests-with-bdd/): Test names like TestCreateUser_WhenEmailInvalid_ReturnsError are hard to scan. BDD-style labeled subtests turn Go tests into living documentation. - [Test Fixtures in Go: Patterns That Scale](https://mvrahden.github.io/go-test/blog/test-fixtures-in-go/): Every growing Go project needs shared test infrastructure. Fixture patterns from global vars to DAG-based lifecycle management, and when to use each. - [Organizing Go Tests Beyond `func TestX`](https://mvrahden.github.io/go-test/blog/organizing-go-tests/): Why flat Go test functions, table-driven tests, and subtests each solve part of the organization problem — and what happens when you need all three at once. - [Why Go's testing Package Needs a Suite Layer](https://mvrahden.github.io/go-test/blog/why-gotest/): Go's testing package is deliberately minimal. Where growing projects hit its gaps, and the five principles behind gotest's suite layer.