React Testing Patterns

/**
 * Component Test Template
 *
 * Copy this template as a starting point for component tests.
 * Adapt the imports, props, and assertions to your component.
 */
import { render, screen, waitFor } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { axe, toHaveNoViolations } from "jest-axe";
import { ExampleComponent } from "./ExampleComponent";

// Extend expect with accessibility matchers
expect.extend(toHaveNoViolations);

// Default props — reuse across tests, override per-test as needed
const defaultProps = {
  title: "Test Title",
  onAction: vi.fn(),
  items: [
    { id: 1, name: "Item 1" },
    { id: 2, name: "Item 2" },
  ],
};

describe("ExampleComponent", () => {
  // Reset mocks between tests
  beforeEach(() => {
    vi.clearAllMocks();
  });

  // ---------- Rendering ----------

  it("renders the title", () => {
    render(<ExampleComponent {...defaultProps} />);
    expect(screen.getByRole("heading", { name: "Test Title" })).toBeInTheDocument();
  });

  it("renders all items", () => {
    render(<ExampleComponent {...defaultProps} />);
    expect(screen.getAllByRole("listitem")).toHaveLength(2);
  });

  it("renders empty state when no items", () => {
    render(<ExampleComponent {...defaultProps} items={[]} />);
    expect(screen.getByText(/no items/i)).toBeInTheDocument();
  });

  // ---------- User Interaction ----------

  it("calls onAction when action button is clicked", async () => {
    const user = userEvent.setup();
    render(<ExampleComponent {...defaultProps} />);

    await user.click(screen.getByRole("button", { name: /action/i }));

    expect(defaultProps.onAction).toHaveBeenCalledTimes(1);
  });

  it("filters items when search is typed", async () => {
    const user = userEvent.setup();
    render(<ExampleComponent {...defaultProps} />);

    await user.type(screen.getByRole("searchbox"), "Item 1");

    expect(screen.getByText("Item 1")).toBeInTheDocument();
    expect(screen.queryByText("Item 2")).not.toBeInTheDocument();
  });

  // ---------- Async Behavior ----------

  it("shows loading state while fetching", () => {
    render(<ExampleComponent {...defaultProps} isLoading />);
    expect(screen.getByText(/loading/i)).toBeInTheDocument();
  });

  it("shows data after loading completes", async () => {
    render(<ExampleComponent {...defaultProps} />);

    // Use findBy for elements that appear asynchronously
    const heading = await screen.findByRole("heading", { name: "Test Title" });
    expect(heading).toBeInTheDocument();
  });

  // ---------- Accessibility ----------

  it("has no accessibility violations", async () => {
    const { container } = render(<ExampleComponent {...defaultProps} />);
    const results = await axe(container);
    expect(results).toHaveNoViolations();
  });

  it("has no accessibility violations in empty state", async () => {
    const { container } = render(<ExampleComponent {...defaultProps} items={[]} />);
    const results = await axe(container);
    expect(results).toHaveNoViolations();
  });
});

/**
 * Hook Test Template
 *
 * Patterns for testing custom React hooks with renderHook.
 */
import { renderHook, act, waitFor } from "@testing-library/react";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { useCounter } from "./useCounter";
import { useUsers } from "./useUsers";

// ---------- Simple Synchronous Hook ----------

describe("useCounter", () => {
  it("starts with initial value", () => {
    const { result } = renderHook(() => useCounter(10));
    expect(result.current.count).toBe(10);
  });

  it("increments the count", () => {
    const { result } = renderHook(() => useCounter(0));

    act(() => {
      result.current.increment();
    });

    expect(result.current.count).toBe(1);
  });

  it("decrements the count", () => {
    const { result } = renderHook(() => useCounter(5));

    act(() => {
      result.current.decrement();
    });

    expect(result.current.count).toBe(4);
  });

  it("resets to initial value", () => {
    const { result } = renderHook(() => useCounter(0));

    act(() => {
      result.current.increment();
      result.current.increment();
      result.current.reset();
    });

    expect(result.current.count).toBe(0);
  });
});

// ---------- Hook with Changing Props ----------

describe("useDebounce", () => {
  beforeEach(() => {
    vi.useFakeTimers();
  });

  afterEach(() => {
    vi.useRealTimers();
  });

  it("returns initial value immediately", () => {
    const { result } = renderHook(() => useDebounce("hello", 300));
    expect(result.current).toBe("hello");
  });

  it("updates value after delay", () => {
    const { result, rerender } = renderHook(
      ({ value }) => useDebounce(value, 300),
      { initialProps: { value: "hello" } },
    );

    // Change the value
    rerender({ value: "world" });

    // Not yet updated
    expect(result.current).toBe("hello");

    // Advance timers past the delay
    act(() => {
      vi.advanceTimersByTime(300);
    });

    // Now updated
    expect(result.current).toBe("world");
  });
});

// ---------- Async Hook with TanStack Query ----------

// Helper: create a fresh QueryClient wrapper for each test
function createTestWrapper() {
  const queryClient = new QueryClient({
    defaultOptions: {
      queries: {
        retry: false,
        gcTime: 0,
      },
    },
  });

  return function Wrapper({ children }: { children: React.ReactNode }) {
    return (
      <QueryClientProvider client={queryClient}>
        {children}
      </QueryClientProvider>
    );
  };
}

describe("useUsers (TanStack Query hook)", () => {
  it("starts in pending state", () => {
    const { result } = renderHook(() => useUsers(), {
      wrapper: createTestWrapper(),
    });

    expect(result.current.isPending).toBe(true);
    expect(result.current.data).toBeUndefined();
  });

  it("returns user data on success", async () => {
    const { result } = renderHook(() => useUsers(), {
      wrapper: createTestWrapper(),
    });

    await waitFor(() => {
      expect(result.current.isSuccess).toBe(true);
    });

    expect(result.current.data).toHaveLength(2);
    expect(result.current.data![0].displayName).toBe("Alice");
  });

  it("returns error on failure", async () => {
    // Override MSW handler for this test
    server.use(
      http.get("/api/users", () => {
        return HttpResponse.json(
          { detail: "Server error", code: "INTERNAL_ERROR" },
          { status: 500 },
        );
      }),
    );

    const { result } = renderHook(() => useUsers(), {
      wrapper: createTestWrapper(),
    });

    await waitFor(() => {
      expect(result.current.isError).toBe(true);
    });

    expect(result.current.error).toBeDefined();
  });
});

// ---------- Hook with Side Effects ----------

describe("useLocalStorage", () => {
  beforeEach(() => {
    localStorage.clear();
  });

  it("returns initial value when no stored value exists", () => {
    const { result } = renderHook(() =>
      useLocalStorage("theme", "light"),
    );
    expect(result.current[0]).toBe("light");
  });

  it("returns stored value when it exists", () => {
    localStorage.setItem("theme", JSON.stringify("dark"));

    const { result } = renderHook(() =>
      useLocalStorage("theme", "light"),
    );
    expect(result.current[0]).toBe("dark");
  });

  it("updates localStorage when value changes", () => {
    const { result } = renderHook(() =>
      useLocalStorage("theme", "light"),
    );

    act(() => {
      result.current[1]("dark");
    });

    expect(result.current[0]).toBe("dark");
    expect(JSON.parse(localStorage.getItem("theme")!)).toBe("dark");
  });
});

/**
 * MSW Handler Examples
 *
 * Mock Service Worker handler patterns for common API operations.
 * Import these in your test setup or override per-test.
 */
import { http, HttpResponse, delay } from "msw";

// ---------- CRUD Handlers ----------

// GET /api/users — List with pagination
const listUsers = http.get("/api/users", ({ request }) => {
  const url = new URL(request.url);
  const cursor = url.searchParams.get("cursor");
  const limit = Number(url.searchParams.get("limit") || "20");

  const allUsers = [
    { id: 1, displayName: "Alice", email: "alice@example.com", role: "admin" },
    { id: 2, displayName: "Bob", email: "bob@example.com", role: "member" },
    { id: 3, displayName: "Charlie", email: "charlie@example.com", role: "editor" },
  ];

  const startIndex = cursor ? allUsers.findIndex((u) => u.id > Number(cursor)) : 0;
  const items = allUsers.slice(startIndex, startIndex + limit);
  const hasMore = startIndex + limit < allUsers.length;

  return HttpResponse.json({
    items,
    next_cursor: hasMore ? String(items[items.length - 1].id) : null,
    has_more: hasMore,
  });
});

// GET /api/users/:id — Single user
const getUser = http.get("/api/users/:id", ({ params }) => {
  const userId = Number(params.id);
  const users: Record<number, object> = {
    1: { id: 1, displayName: "Alice", email: "alice@example.com", role: "admin" },
    2: { id: 2, displayName: "Bob", email: "bob@example.com", role: "member" },
  };

  const user = users[userId];
  if (!user) {
    return HttpResponse.json(
      { detail: `User ${userId} not found`, code: "NOT_FOUND" },
      { status: 404 },
    );
  }
  return HttpResponse.json(user);
});

// POST /api/users — Create user
const createUser = http.post("/api/users", async ({ request }) => {
  const body = (await request.json()) as Record<string, unknown>;
  return HttpResponse.json(
    {
      id: 99,
      ...body,
      created_at: new Date().toISOString(),
      updated_at: new Date().toISOString(),
    },
    { status: 201 },
  );
});

// PATCH /api/users/:id — Update user
const updateUser = http.patch("/api/users/:id", async ({ params, request }) => {
  const body = (await request.json()) as Record<string, unknown>;
  return HttpResponse.json({
    id: Number(params.id),
    displayName: "Alice",
    email: "alice@example.com",
    ...body,
    updated_at: new Date().toISOString(),
  });
});

// DELETE /api/users/:id — Delete user
const deleteUser = http.delete("/api/users/:id", () => {
  return new HttpResponse(null, { status: 204 });
});

// ---------- Error Handlers ----------

// Simulate server error
const serverError = http.get("/api/users", () => {
  return HttpResponse.json(
    { detail: "Internal server error", code: "INTERNAL_ERROR" },
    { status: 500 },
  );
});

// Simulate validation error
const validationError = http.post("/api/users", () => {
  return HttpResponse.json(
    {
      detail: "Validation failed",
      code: "VALIDATION_ERROR",
      field_errors: [
        { field: "email", message: "Invalid email format", code: "INVALID_FORMAT" },
      ],
    },
    { status: 422 },
  );
});

// Simulate network delay
const slowResponse = http.get("/api/users", async () => {
  await delay(3000); // 3 second delay
  return HttpResponse.json({ items: [], next_cursor: null, has_more: false });
});

// ---------- Auth Handlers ----------

const login = http.post("/api/auth/login", async ({ request }) => {
  const body = (await request.json()) as { email: string; password: string };
  if (body.email === "admin@test.com" && body.password === "password") {
    return HttpResponse.json({
      access_token: "mock-jwt-token",
      token_type: "bearer",
    });
  }
  return HttpResponse.json(
    { detail: "Invalid credentials", code: "UNAUTHORIZED" },
    { status: 401 },
  );
});

const getCurrentUser = http.get("/api/auth/me", ({ request }) => {
  const authHeader = request.headers.get("Authorization");
  if (!authHeader?.startsWith("Bearer ")) {
    return HttpResponse.json(
      { detail: "Not authenticated", code: "UNAUTHORIZED" },
      { status: 401 },
    );
  }
  return HttpResponse.json({
    id: 1,
    displayName: "Test Admin",
    email: "admin@test.com",
    role: "admin",
  });
});

// ---------- Export ----------

// Default handlers — use in setupServer
export const handlers = [
  listUsers,
  getUser,
  createUser,
  updateUser,
  deleteUser,
  login,
  getCurrentUser,
];

// Error handlers — use with server.use() for specific tests
export const errorHandlers = {
  serverError,
  validationError,
  slowResponse,
};