Lesson 15 · Senior testing practice

Flaky tests, determinism, and failure triage

How to reason about -count=3, shared state, ordering, timing, and why a test that passes once may still be lying to you.

Your win: explain why flakiness is a design signal, how to triage repeated-run failures, and what kinds of hidden coupling usually cause them.

In plain English Plain English: a flaky test is often a test that depends on something it forgot to admit — time, order, shared state, or leaked context.

Why this topic matters

A flaky test is rarely just an annoying test. That is the key shift. In a weak testing culture, people treat flakiness like weather: unfortunate, but normal. In a stronger testing culture, flakiness is evidence.

It is evidence that a test or the code under test is depending on something unstable, shared, or hidden. That is why the strongest earlier lessons in this course kept pushing independence, fresh setup, and parallel safety. They were already teaching the anti-flake mindset before naming it directly.

Why -count=3 exists

The course already taught you that this repo reruns suites three times to flush out non-determinism. The senior step is understanding what kinds of mistakes that rule is trying to expose.

A test that passes once may still be broken if it depends on leftover state, hidden ordering, timing luck, or reused mutable collaborators. Repetition is what stops “green by accident” from looking trustworthy.

The senior framing Flakiness is not just an annoyance. It is evidence that the test or the code under test is relying on something unstable or shared.

The usual failure families

If you need to triage a flaky test quickly, the search space is smaller than it first feels. Most flakes cluster into a few repeat families:

This is why rerun failures are so useful. They narrow the story from “anything could be wrong” to “some hidden dependency is escaping the unit boundary.”

Backend use case When a test only fails under repeated runs or in CI, this lesson helps you shorten the search from “anything could be wrong” to the small set of determinism failures the repo’s style rules are designed to prevent.
Common mistake Treating flakiness as a CI nuisance to rerun past instead of evidence that the suite is proving less than it claims.
Read this next

Revisit the workflow rule

Read the workflow and style rules again, this time as anti-flake design decisions rather than formatting rules.

→ .claude/rules/go-test-style.md
→ docs/testing/lessons/0012-running-coverage-workflow.html

Check yourself (from memory)

Q1. What is the best senior interpretation of a flaky test?

Flakes usually point to hidden coupling, unstable timing, or shared state.
Why does -count=3 matter in this repo?
recall, then click to reveal
Because it exposes tests that only pass once by accident and helps force suites toward deterministic, parallel-safe, repeatable behavior.
Want a quick triage checklist for “passes locally once, fails in CI or on rerun”? Ask me.

Sources. Workflow lesson; house rules.