testing-library

When to Use

• Testing UI components with @testing-library/react, @testing-library/vue, or @testing-library/dom.
• Choosing the right query method for elements.
• Simulating user interactions (typing, clicking, selecting).
• Testing async behavior (data fetching, loading states, debounced input).
• Writing tests that enforce and verify accessibility.

Critical Patterns

• Test User Behavior, Not Implementation: Your tests should resemble how users interact with your app. Query by role, label, and text — not by class, test ID, or component internals.
• Query Priority: Follow this order strictly — it maps to accessibility:
  1. getByRole — accessible roles (button, textbox, heading)
  2. getByLabelText — form fields with labels
  3. getByPlaceholderText — when no label exists
  4. getByText — visible text content
  5. getByDisplayValue — current input values
  6. getByAltText — images
  7. getByTitle — title attribute
  8. getByTestId — LAST RESORT only
• userEvent Over fireEvent: Always use @testing-library/user-event for interactions. It simulates real browser behavior (focus, keydown, keyup, input) while fireEvent dispatches a single synthetic event.
• No Implementation Details: NEVER assert on component state, props, or internal methods. NEVER query by class name or component structure.
• Async by Default: Use findBy queries (which return Promises) or wrap assertions in waitFor for any UI that updates asynchronously.

Code Examples

Query Priority in Practice

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

it("renders the signup form with accessible elements", () => {
  render(<SignupForm />);

  // BEST — getByRole with accessible name
  screen.getByRole("heading", { name: /create account/i });
  screen.getByRole("textbox", { name: /email/i });
  screen.getByRole("button", { name: /sign up/i });

  // GOOD — getByLabelText for form fields
  screen.getByLabelText(/password/i);

  // ACCEPTABLE — getByText for static content
  screen.getByText(/already have an account/i);

  // LAST RESORT — only when element has no accessible role or text
  screen.getByTestId("captcha-widget");
});