Debugging Tests
Diagnose failing, flaky, and hanging tests with logs, inspectors, and isolation.
What you'll learn
- Reading failure output to locate the broken assertion fast
- Using --inspect, console, and screen debug to see inside tests
- Tracking down flaky tests with repetition and seed control
- Isolating a failing test from the rest of the suite
Concept
Read the Failure First
The test runner's failure output tells you the file, the describe path, the failing assertion, and the expected vs actual values. Read this before reaching for a debugger. A good failure message — which is why naming matters — often pinpoints the bug in seconds. If the diff is unclear, add a more specific assertion or log the actual value to see its real shape.
See Inside the Test
When the failure is opaque, inspect the runtime. console.log inside a test prints to the terminal; screen.debug() (Testing Library) dumps the rendered DOM as HTML. For deep debugging, run Node with --inspect-brk and attach Chrome DevTools, or use VS Code's JavaScript debug terminal to set breakpoints inside test files. Vitest supports vitest --inspect-brk for the same workflow.
Flaky Tests
A flaky test passes sometimes and fails others — the worst kind of bug because it erodes trust in the whole suite. Find the source of non-determinism: shared state, time, random, network, test order. Run the single test in a loop (vitest test -t "name" --retry 50) to reproduce the flake. Fix it by isolating state, faking time, seeding random, or removing the network call. Never disable a flaky test without filing a ticket — it will rot.
Isolate and Bisect
When a test passes alone but fails in the suite, state is leaking between tests. Run the test with the ones before it to bisect the culprit. Add beforeEach resets, restore mocks, and clear shared singletons. If a test hangs, it is usually an unawaited promise or a missing vi.runAllTimers; add a timeout (it("...", () => {}, 1000)) to fail fast instead of waiting for the CI timeout.
In Practice
Develop a debugging routine: first read the failure message and the diff; if unclear, add a console.log of the actual value to see its real shape; if still stuck, isolate the test by running it alone and then with neighbors to find leaking state. For flaky tests, run the single test in a loop (vitest -t "name" --retry 50) to reproduce the failure, then trace the non-determinism to its source — usually a shared database row, an unmocked timer, or a network call. Fix the root cause rather than adding a retry. For hangs, set an explicit test timeout so the failure is fast and obvious. Keep a log of flaky tests you have fixed so patterns emerge — if the same cause recurs, it points to a structural issue in the test setup worth addressing once and for all.
Example
import { describe, it, expect, vi } from "vitest";
describe("debugging helpers", () => {
it("logs the actual value to inspect its shape", () => {
const result = buildReport();
console.log("actual:", JSON.stringify(result, null, 2));
expect(result.total).toBe(100);
});
it("retries a flaky test to reproduce the failure", () => {
// Run with: vitest -t "retries a flaky" --retry 20
const n = Math.random();
expect(n).toBeLessThan(0.5); // fails ~50% of the time
});
it("fails fast with a timeout instead of hanging", () => {
return new Promise(() => {}); // never resolves
}, 1000); // fails after 1s instead of hanging forever
});
console.log shows the real shape of the data, --retry reproduces flakiness, and an explicit timeout turns a hang into a fast, clear failure.
Try it
- Code Diff
Compare expected vs actual from a failing assertion.
- JSON Formatter
Pretty-print the logged objects you inspect while debugging.
Common mistakes
The mistake
Skipping or commenting out flaky tests
The fix
Reproduce and fix the flakiness, or quarantine with a tracked ticket. A skipped test is hidden rot that lets real bugs through.
The mistake
Debugging the whole suite at once
The fix
Isolate the failing test first (run it alone), then bisect by adding neighbors until it breaks. The leak is in the difference.
Look up unfamiliar terms
A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.
Build real projects
Apply what you learned by building guided projects with starter code and solutions.
Decode error messages
Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.