Unit Testing

A unit test verifies one piece of behaviour in isolation. Done well, a test suite gives you the confidence to refactor, the documentation of intent, and the safety net that catches regressions before they reach users. Done poorly, it becomes a brittle maintenance burden that slows the team down without adding value.

What to Test — and What Not To

Test behaviour, not implementation. A test that checks which internal function was called breaks every time you refactor, even when nothing visible changed.

Worth testing:

• Pure functions — given these inputs, produce this output
• Business logic isolated from framework code
• Edge cases that are hard to exercise manually (empty arrays, null values, boundary numbers)
• Error paths (what happens when an API call throws?)

Not worth testing:

• Third-party library internals
• Trivial getters/setters with zero logic
• Framework wiring (that React renders a <div> when you write <div>)
• Exact pixel positions or CSS values

Vitest / Jest Structure

Both Vitest and Jest share the same API. Vitest is preferred for modern projects because it shares your Vite config and is significantly faster.

// math.test.ts
import { describe, it, expect } from "vitest";
import { add, divide } from "./math";

describe("add", () => {
  it("returns the sum of two numbers", () => {
    expect(add(2, 3)).toBe(5);
  });

  it("handles negative numbers", () => {
    expect(add(-1, 1)).toBe(0);
  });
});

describe("divide", () => {
  it("throws when dividing by zero", () => {
    expect(() => divide(10, 0)).toThrow("Division by zero");
  });
});

Use describe to group related cases. Each it (or test) should express one assertion idea. Prefer descriptive strings that read like sentences.

Mocking

vi.fn() creates a spy function you can assert against:

import { vi } from "vitest";

const onSubmit = vi.fn();
onSubmit("data");
expect(onSubmit).toHaveBeenCalledOnce();
expect(onSubmit).toHaveBeenCalledWith("data");

vi.mock() replaces an entire module. The factory runs before imports, so it must not reference outer variables:

vi.mock("../api/users", () => ({
  fetchUser: vi.fn().mockResolvedValue({ id: 1, name: "Alice" }),
}));

Use vi.spyOn when you want to wrap a real implementation and assert on calls without replacing it:

const spy = vi.spyOn(console, "warn").mockImplementation(() => {});
// ... code that should warn ...
expect(spy).toHaveBeenCalledWith(expect.stringContaining("deprecated"));
spy.mockRestore();

Testing Components with Testing Library

Testing Library queries the DOM the way a user would — by role, label, or text — rather than by CSS selectors or component internals:

import { render, screen, fireEvent } from "@testing-library/react";
import { Counter } from "./Counter";

it("increments the count when the button is clicked", () => {
  render(<Counter />);
  const button = screen.getByRole("button", { name: /increment/i });
  fireEvent.click(button);
  expect(screen.getByText("Count: 1")).toBeInTheDocument();
});

Prefer getByRole over getByTestId. If you cannot find an element by role or label, that is often a signal that the component is not accessible.

Coverage

Coverage tells you which lines were executed during tests, not whether those lines are correctly tested. A file can be 100% covered and still have bugs if assertions are weak.

Run coverage with vitest run --coverage. Look at branch coverage — an uncovered branch means an if/else path that was never exercised.

Set a coverage threshold to prevent regression, but do not chase 100% — focus it on business-critical modules:

// vitest.config.ts
coverage: {
  thresholds: { statements: 80, branches: 75 }
}

Further Learning

Search these terms to go deeper:

• “testing-library docs queries” — the canonical guide to choosing the right query
• “Vitest mocking guide” — covers vi.fn, vi.mock, vi.spyOn, and timers in depth
• “Kent C. Dodds testing trophy” — the alternative to the test pyramid; argues for more integration tests
• “testing implementation details” — Kent C. Dodds article on why querying internal state leads to fragile tests
• “Vitest coverage v8 vs istanbul” — choosing the right coverage provider and understanding its output

Unit Testing

A unit test is a little piece of code that checks another piece of code does what it should. Instead of clicking through your app by hand to make sure nothing broke, you write tests once and run them anytime. They’re your safety net when you change things later.

Test what matters (not everything)

The golden rule: test what the code does, not how it’s built inside. A good test still passes when you clean up the internals.

Worth testing:

• Functions that take input and return output (easy to check).
• Important logic and edge cases (empty list? missing value?).
• What happens when something fails.

Skip:

• Other people’s libraries (already tested).
• Trivial stuff with no real logic.

What a test looks like

Tests read almost like sentences: describe a thing, then it should do something, and you expect a result:

import { describe, it, expect } from 'vitest'
import { add } from './math'

describe('add', () => {
  it('adds two numbers', () => {
    expect(add(2, 3)).toBe(5)
  })
})

expect(...).toBe(...) is the actual check: “I expect this to equal that.”

Testing a component

For UI, Testing Library lets you interact with a component the way a real user would — find the button by its label, click it, check what shows up:

import { render, screen, fireEvent } from '@testing-library/react'
import { Counter } from './Counter'

it('counts up when clicked', () => {
  render(<Counter />)
  fireEvent.click(screen.getByRole('button', { name: /increment/i }))
  expect(screen.getByText('Count: 1')).toBeInTheDocument()
})

Finding elements by their visible role/label (not hidden CSS classes) also nudges you toward more accessible UI.

About “coverage”

Coverage tells you what percentage of your code the tests ran — but 100% coverage doesn’t mean bug-free (you could run a line without really checking it). Use it to spot untested areas, but don’t obsess over hitting a magic number.

In one sentence

Unit tests check behavior (not internals) so you can change code fearlessly — write them as describe/it/expect, use Testing Library to click through UI like a user, and treat coverage as a hint, not a goal.

Want to go deeper?

Switch to Expert mode above for mocking with vi.fn/vi.mock, userEvent vs fireEvent, and reading branch-coverage reports.