Skip to content

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.

View glossary

Build real projects

Apply what you learned by building guided projects with starter code and solutions.

View projects

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors