React Testing Library Fundamentals

import { render, screen, waitFor } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
 
// 1. Render the component
render(<LoginForm onSubmit={handleSubmit} />);
 
// 2. Query elements (by priority)
screen.getByRole("textbox", { name: /email/i });       // Best: accessible role
screen.getByLabelText(/password/i);                     // Good: label association
screen.getByText(/submit/i);                            // OK: visible text
screen.getByTestId("login-form");                       // Last resort: test ID
 
// 3. Interact with userEvent (not fireEvent)
const user = userEvent.setup();
await user.type(screen.getByRole("textbox", { name: /email/i }), "alice@example.com");
await user.click(screen.getByRole("button", { name: /submit/i }));
 
// 4. Assert outcomes
expect(screen.getByText(/welcome/i)).toBeInTheDocument();
 
// 5. Async queries
const message = await screen.findByText(/success/i); // waits up to 1s
await waitFor(() => expect(handleSubmit).toHaveBeenCalled());

// src/components/login-form.tsx
"use client";
 
import { useState } from "react";
 
interface LoginFormProps {
  onSubmit: (data: { email: string; password: string }) => Promise<void>;
}
 
export function LoginForm({ onSubmit }: LoginFormProps) {
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");
  const [error, setError] = useState("");
  const [loading, setLoading] = useState(false);
 
  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault();
    setError("");
    setLoading(true);
    try {
      await onSubmit({ email, password });
    } catch (err) {
      setError(err instanceof Error ? err.message : "Login failed");
    } finally {
      setLoading(false);
    }
  }
 
  return (
    <form onSubmit={handleSubmit} aria-label="Login">
      <div>
        <label htmlFor="email">Email</label>
        <input
          id="email"
          type="email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          required
        />
      </div>
      <div>
        <label htmlFor="password">Password</label>
        <input
          id="password"
          type="password"
          value={password}
          onChange={(e) => setPassword(e.target.value)}
          required
        />
      </div>
      {error && <p role="alert">{error}</p>}
      <button type="submit" disabled={loading}>
        {loading ? "Logging in..." : "Log in"}
      </button>
    </form>
  );
}

// src/components/login-form.test.tsx
import { render, screen, waitFor } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { vi, describe, it, expect } from "vitest";
import { LoginForm } from "./login-form";
 
describe("LoginForm", () => {
  const user = userEvent.setup();
 
  it("submits email and password", async () => {
    const handleSubmit = vi.fn().mockResolvedValue(undefined);
    render(<LoginForm onSubmit={handleSubmit} />);
 
    await user.type(screen.getByLabelText(/email/i), "alice@example.com");
    await user.type(screen.getByLabelText(/password/i), "password123");
    await user.click(screen.getByRole("button", { name: /log in/i }));
 
    await waitFor(() => {
      expect(handleSubmit).toHaveBeenCalledWith({
        email: "alice@example.com",
        password: "password123",
      });
    });
  });
 
  it("shows error on failed submission", async () => {
    const handleSubmit = vi.fn().mockRejectedValue(new Error("Invalid credentials"));
    render(<LoginForm onSubmit={handleSubmit} />);
 
    await user.type(screen.getByLabelText(/email/i), "alice@example.com");
    await user.type(screen.getByLabelText(/password/i), "wrong");
    await user.click(screen.getByRole("button", { name: /log in/i }));
 
    expect(await screen.findByRole("alert")).toHaveTextContent("Invalid credentials");
  });
 
  it("disables button while loading", async () => {
    const handleSubmit = vi.fn(() => new Promise(() => {})); // never resolves
    render(<LoginForm onSubmit={handleSubmit} />);
 
    await user.type(screen.getByLabelText(/email/i), "alice@example.com");
    await user.type(screen.getByLabelText(/password/i), "password123");
    await user.click(screen.getByRole("button", { name: /log in/i }));
 
    expect(screen.getByRole("button")).toBeDisabled();
    expect(screen.getByRole("button")).toHaveTextContent("Logging in...");
  });
});

// The render result is typed -- you can access container and other utilities
const { container, rerender, unmount } = render(<MyComponent />);
 
// Custom render with wrapper for providers
function renderWithProviders(ui: React.ReactElement) {
  return render(ui, {
    wrapper: ({ children }) => (
      <ThemeProvider>{children}</ThemeProvider>
    ),
  });
}