js-testing

JS Testing Skill — Vitest + React Testing Library for Next.js

Critical Rules

1. Vitest is the test runner. Do not use Jest. All configuration, mocking, and assertions use the Vitest API (vi.fn(), vi.mock(), vi.spyOn(), etc.).
2. React Testing Library (RTL) for component tests. Query elements the way a user would find them — by role, label, text, or placeholder. Never reach for getByTestId unless no semantic query is possible.
3. Test user behavior, not implementation. Assert what the user sees and can interact with. Do not assert on component state, refs, internal variables, or hook return values directly (except when using renderHook).
4. Never test React internals. Do not mock useState, useEffect, useRef, or any React built-in. If you need to control what a hook returns, extract the logic into a custom hook and test it with renderHook.
5. Use MSW for API mocking. Mock at the network layer with Mock Service Worker, not by stubbing fetch or axios directly. This gives realistic request/response cycles and catches serialization issues.
6. Prefer userEvent over fireEvent. userEvent simulates real browser behavior (focus, blur, keystrokes). fireEvent dispatches synthetic DOM events and should only be used for events userEvent does not support.
7. Every test file must be self-contained. Shared setup belongs in vitest.setup.ts or a dedicated test utility file, not scattered across tests via implicit globals.

---

Component Testing

Basic Render Test

// components/greeting.tsx
export function Greeting({ name }: { name: string }) {
  return <h1>Hello, {name}!</h1>;
}

// components/greeting.test.tsx
import { render, screen } from "@testing-library/react";
import { describe, it, expect } from "vitest";
import { Greeting } from "./greeting";

describe("Greeting", () => {
  it("renders the user name", () => {
    render(<Greeting name="Kelley" />);

    expect(
      screen.getByRole("heading", { name: /hello, kelley/i })
    ).toBeInTheDocument();
  });
});