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
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.