Skip to content

Test Organization

Structure test files, naming, and folders so the suite stays navigable as it grows.

What you'll learn

  • Co-locating tests with source vs central test folders
  • Naming conventions for test files and describe blocks
  • Grouping with describe and tagging for selective runs
  • Scaling a test suite without losing navigability

Concept

Where Tests Live

Two conventions dominate. Co-location places foo.test.ts next to foo.ts, making it easy to find a module's tests and keep them in sync. Centralized puts all tests under a test/ or __tests__/ folder, keeping source folders clean. Co-location wins for unit tests (tight coupling to the file), while a central test/ folder works well for integration and E2E tests that span modules. Many projects use both.

Naming Conventions

Name test files after the unit they test: cart.test.ts for cart.ts. Name describe blocks after the unit and its public surface: describe("Cart", () => { describe("add", ...) }). Name it blocks for the behavior and expected outcome: it("adds the item when the cart is empty", ...). When a test fails, the full path Cart > add > adds the item when the cart is empty should read like a sentence describing the broken behavior.

Grouping and Tagging

Use nested describe blocks to group related tests and share setup via beforeEach. For selective runs, tag tests with a comment or a custom matcher and filter by name: vitest -t "auth" runs only tests matching "auth". Some frameworks support custom annotations for @slow or @integration so CI can run a fast subset on every push and the full suite nightly.

Scaling

As the suite grows, enforce conventions with a linter (eslint-plugin-testing-library) and a naming check in CI. Keep test files small — if a file exceeds a few hundred lines, split by describe block. Periodically prune redundant tests and consolidate overlapping ones. A well-organized suite is a map of your application's behavior; a disorganized suite is a pile no one trusts.

In Practice

Pick a convention and enforce it from day one — retrofitting organization onto a thousand tests is painful. Co-locate unit tests with their source (foo.ts → foo.test.ts) so tests are easy to find and delete together, and keep integration and E2E tests in a central test/ folder with names that describe the feature (auth-flow.e2e.test.ts). Use nested describe blocks to mirror the public API, and write it names as behavior sentences. Add a CI check that fails if a source file has no corresponding test file, so coverage stays organic. Run a periodic "test hygiene" session: delete tests that assert nothing, merge duplicates, and fix or remove flaky ones. A tidy suite is a trustworthy suite.

Example

              // src/cart/cart.test.ts — co-located unit tests
import { describe, it, expect, beforeEach } from "vitest";
import { Cart } from "./cart";

describe("Cart", () => {
  let cart: Cart;
  beforeEach(() => (cart = new Cart()));

  describe("add", () => {
    it("adds an item to an empty cart", () => {
      cart.add({ id: 1, price: 10 });
      expect(cart.size()).toBe(1);
    });
    it("increases the total by the item price", () => {
      cart.add({ id: 1, price: 10 });
      expect(cart.total()).toBe(10);
    });
  });

  describe("remove", () => {
    it("removes an existing item", () => {
      cart.add({ id: 1, price: 10 });
      cart.remove(1);
      expect(cart.size()).toBe(0);
    });
  });
});
            

Tests co-located with the source. Nested describes mirror the public methods, and each it describes a behavior. The failure path reads as a sentence.

Try it

  • Code Diff

    Review test structure changes during refactors.

  • JSON Formatter

    Read the structured test report to navigate failures.

Common mistakes

The mistake

One giant test file for the whole module

The fix

Split by describe block or by feature. Files over a few hundred lines are hard to navigate and slow to run in watch mode.

The mistake

Vague test names like 'works' or 'test1'

The fix

Name tests for the behavior and outcome. The full describe > it path should read as a sentence that explains the broken behavior when it fails.

Practice Test Organization

5 exercises

Practice Test Organization

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