Blog on gotest

How Go Actually Tests: Data From 1,000 Repositories

Fri, 24 Jul 2026 00:00:00 +0000

The tests of the 1,000 most-starred Go repositories spend at least 251 hours asleep. Not blocked on I/O, not waiting for a condition. Sleeping, in time.Sleep calls with constant durations, written into test code on purpose. That is ten and a half days of deliberate waiting per full run of the corpus, and it is a floor: we could only count durations that are compile-time constants.

We measured this because we couldn’t find anyone who had. There is no shortage of opinions about how Go tests should be written. There is very little data about how they are written. So we parsed them.

gotest VS Code Extension: Suite-Aware Go Testing

Thu, 23 Jul 2026 00:00:00 +0000

You write gotest suites, open VS Code’s Testing sidebar — and it’s empty. No test tree, no CodeLens Run buttons above your suite methods, nothing to debug. Standard Go tooling has nothing to show you, because as far as gopls and the Go Test Explorer are concerned, your suites aren’t tests at all.

The gotest VS Code extension exists to close this gap. Because it’s purpose-built for suite-based testing rather than a generic test runner, it can surface things standard tooling can’t: the suite hierarchy, the behavioral spec view, and coverage that survives across runs.

Go Tests in GitHub Actions: The gotest CI Setup Guide

Wed, 22 Jul 2026 00:00:00 +0000

Running gotest locally is straightforward. Making it work well in CI — with clear failure output, PR annotations, coverage enforcement, and safety guards — takes a bit of setup. This post covers the official GitHub Action, the summary command, coverage thresholds, and the CI mode that catches debugging artifacts before they reach your main branch.

If you haven’t written a gotest suite yet, start with Your First Go Test Suite in 10 Minutes and come back — everything here builds on that workflow.

Contract Testing Go Interfaces with Generic Test Suites

Tue, 21 Jul 2026 00:00:00 +0000

Go interfaces define contracts. An io.Reader promises Read(p []byte) (n int, err error). A Storage interface promises Get, Put, Delete. But who verifies that every implementation actually honors the contract? Usually, each implementation has its own tests, written independently, checking slightly different things. The contract drifts.

Generic suites fix this. Write one test suite parameterized by a type, then instantiate it for every implementation. The same behaviors are verified against every implementation. If you add a contract requirement, every implementation is tested. If an implementation deviates, the specific behavior that fails is named in the spec.

Advanced Go Test Fixtures: Composition, Containers, Config

Mon, 20 Jul 2026 00:00:00 +0000

A single fixture gets you started: start a thing, stop a thing, point your tests at it. Real projects need more. Fixtures that compose into dependency graphs, containers that survive flaky startup, per-test isolation that keeps parallel tests from stepping on each other, and configuration that adapts to each environment. These are the patterns that emerge when fixtures grow beyond a single struct with two hooks.

If you are new to gotest fixtures, Test Fixtures in Go covers the fundamentals: struct types with lifecycle hooks, automatic dependency resolution, DAG-based ordering. Sharing Test Fixtures Across Go Packages covers cross-package sharing through JSON state transfer and subprocess lifecycle management. This post assumes you have built your first fixture.

Sharing Test Fixtures Across Go Packages

Sun, 19 Jul 2026 00:00:00 +0000

go test compiles each package into a separate test binary and runs it as a separate OS process. That design buys you isolation, and it makes one thing structurally difficult: sharing a fixture across packages. A Postgres container that pkg/user, pkg/order, and pkg/billing all need. A Redis instance that three packages query. A schema migration that should run once for the entire test run, not once per package. Sharing any of these means crossing process boundaries.

Go Tests as Living Documentation: The Spec View

Sat, 18 Jul 2026 00:00:00 +0000

Documentation drifts. A README written six months ago describes code that no longer exists. An architecture doc from last quarter names services that have been renamed. Wiki pages go stale the moment they are published.

Tests don’t drift. If the code changes and the test doesn’t match, the build fails. This makes tests the most reliable form of documentation in any project — if you can read them. The problem is that most test output is designed for machines, not humans. go test -v produces a flat stream of PASS/FAIL lines with no hierarchy. You can see that everything passed, but you can’t see what the system does.

Snapshot Testing in Go

Fri, 17 Jul 2026 00:00:00 +0000

Some test assertions are about structure, not specific values. JSON API responses, rendered HTML, error messages, log output — things where the exact expected value is long, tedious to maintain by hand, and changes often enough to be annoying. Snapshot testing solves this by storing the expected output in a file and comparing against it on subsequent runs.

If you’ve used Jest, you know the pattern. In Go, it’s less common — but gotest has a built-in implementation that’s thread-safe, works inside parallel tests, and integrates with CI safety guards.

Testing Async Code in Go Without time.Sleep

Thu, 16 Jul 2026 00:00:00 +0000

Most Go code that tests async behavior uses time.Sleep. It’s slow, flaky, or both. The real problem is that sleeping conflates two separate concerns: how long to wait and how often to check. This post shows how to separate them with Eventually and Consistently, and why that separation makes async tests both faster and more reliable.

The sleep problem

Suppose you have a notification dispatcher that processes messages in a background goroutine. You send a notification and want to assert that it was delivered. The most common approach:

Go Test Watch Mode and Focused Tests: The Inner Loop

Wed, 15 Jul 2026 00:00:00 +0000

The “inner loop” is the cycle a developer repeats hundreds of times a day: change code, run tests, read results. The speed of this loop directly affects how you write code. A 30-second cycle means you batch changes and debug in your head. A 1-second cycle means you try things.

gotest has three features that compress the inner loop: watch mode for automatic re-runs, focus prefixes for narrowing scope, and spec output for readable results. Separately, each one removes a specific friction point. Together, they change how you develop.

Go Test Lifecycle: Setup, Teardown, and Execution Order

Tue, 14 Jul 2026 00:00:00 +0000

Every test framework has setup and teardown. The interesting question is not whether they exist, but what guarantees the lifecycle gives you. Can AfterAll run if BeforeAll panics? Does AfterEach still execute on t.Fatal? Where do fixture hooks fit relative to suite hooks? If you have ever guessed at these answers while debugging a leaked database connection, this post is for you.

Other posts in this series cover fixture patterns and getting started with suites. This post is different. It maps the full lifecycle from the inside out, so you build the correct mental model once and stop guessing.

BDD in Go: What Behavior-Driven Development Actually Means

Mon, 13 Jul 2026 00:00:00 +0000

BDD — Behavior-Driven Development — is one of the most misunderstood ideas in testing. Most developers encounter it as syntax: describe, context, it. They learn the keywords, use them in a few test files, and assume they are doing BDD. But BDD is not syntax. It is a communication practice. And Go’s type system makes it possible to do BDD without the ceremony that other languages require.

This is not a tutorial on When and It — that is covered in Readable Go Tests with BDD-Style Subtests. This post is about the idea behind BDD, why most implementations of it carry unnecessary weight, and how Go’s type system maps to BDD concepts in a way that is unique among programming languages.

Your First Go Test Suite in 10 Minutes: A gotest Tutorial

Sun, 12 Jul 2026 00:00:00 +0000

Plain go test carries you a long way — until you need setup that runs before every test, related cases grouped under a shared context, and output you can actually read. At that point most of us start hand-rolling lifecycle helpers and squinting at walls of --- PASS lines. In the next 10 minutes you’ll go from go install to a structured test suite with lifecycle hooks, BDD-style grouping, and spec output — all running on standard go test.

Why Your Go Tests Are Slow (and What to Do About It)

Sat, 11 Jul 2026 00:00:00 +0000

go test ./... takes 90 seconds. You’ve profiled the hot tests and they’re fast. The database setup is cached. The assertions are trivial. So where does the time go?

Usually the answer isn’t slow tests. It’s slow structure: the way tests are organized determines how much work runs sequentially, how much setup gets repeated, and how much parallelism the runtime can actually use. This post looks at the three structural patterns that make Go test suites slow, and what to do about each one. The payoff is real: the benchmark later in the post takes the same example suite from 6 seconds to 0.5 seconds through structural changes alone, without touching a single test.

Migrating from `testify/suite` to gotest

Fri, 10 Jul 2026 00:00:00 +0000

gotest migrate ./... rewrites most of a testify/suite codebase automatically: struct renames, lifecycle hooks, assertion calls, imports, and the suite.Run boilerplate. The catch is a handful of patterns it can’t convert safely and leaves for manual review. This guide shows what the tool converts, what it leaves for you, and how to migrate package by package without breaking the rest of the codebase.

testify/suite is the most widely used Go test suite framework, and for good reason. It gives you struct-based test grouping and lifecycle hooks on top of the standard library. Many teams have hundreds of suites built on it. This guide is for teams that have decided to try gotest alongside or in place of those suites.

Code Generation vs Reflection in Go Test Frameworks

Thu, 09 Jul 2026 00:00:00 +0000

Every Go test framework that supports suites needs to solve the same problem: how do you connect a struct full of test methods to the go test runner? The runner only knows about top-level func Test*(t *testing.T) functions. Your suite is a struct with methods. Something has to bridge the gap.

Most frameworks use reflection. gotest uses code generation. This post explains why, and what the code generation pipeline actually does.

Readable Go Tests with BDD-Style Subtests

Wed, 08 Jul 2026 00:00:00 +0000

When a test fails in CI, the first thing you read is its name. And for most Go projects, that name looks like this:

go test -v output

=== RUN TestCreateUser_WhenEmailInvalid_ReturnsError
--- FAIL: TestCreateUser_WhenEmailInvalid_ReturnsError (0.01s)

You can decode it. TestCreateUser is the subject, WhenEmailInvalid is the condition, ReturnsError is the expectation. But it takes a moment. And when you’re scanning twenty failures across five packages, those moments add up.

This post looks at why Go test output is hard to read at scale, how BDD-style structure helps, and what it takes to turn test runs into something that reads like a specification.

Test Fixtures in Go: Patterns That Scale

Tue, 07 Jul 2026 00:00:00 +0000

Most Go projects eventually need shared test infrastructure: a database connection, a message queue, a container that takes seconds to start. The stdlib doesn’t have a built-in answer for this. So every team invents its own fixture pattern, and most of those patterns quietly break the day you add t.Parallel() or a second package that needs the same Postgres.

This post looks at the common approaches, where each one breaks down, and what a fixture system needs to handle the cases that real projects run into.

Organizing Go Tests Beyond `func TestX`

Mon, 06 Jul 2026 00:00:00 +0000

A test file with 10 test functions is easy to hold in your head. At 50, you’re scrolling to find what you need. At 200, you’re grep-ing your own tests to figure out what’s covered and what isn’t.

Go’s testing package is deliberately simple. No annotations, no test classes, no dependency injection: just functions that start with Test and a *testing.T. This simplicity is one of Go’s genuine strengths. But it creates a gap that every growing project eventually falls into.

Why Go's testing Package Needs a Suite Layer

Sun, 05 Jul 2026 00:00:00 +0000

Go’s testing package is one of the best things about the language: no framework to install, no annotations to learn, just func Test* and go test. But past a few dozen test files, most projects hit the same wall. There is no way to group related tests, no per-test setup hook, and no way for two packages to share a database container.

That is not because the design is wrong, but because testing is deliberately minimal. It gives you a test runner and an assertion-free T type. Everything else is left to the developer: organizing tests into groups, managing setup and teardown, sharing expensive infrastructure, expressing what a test means rather than just what it does.