Testing

Testing

This project uses multiple testing tools depending on the type of test needed.

Testing Stack

• Vitest: Unit and integration tests
• React Testing Library (RTL): Component testing
• Playwright: E2E tests

Unit & Integration Tests (Vitest + RTL)

Setup

Tests are configured in vitest.config.ts and setup in src/tests/setup.tsx.

Import testing utilities from setup: You can import commonly used testing utilities directly from @tests/setup:

// Instead of importing from multiple places:
import { render, screen } from "@testing-library/react";
import { describe, it, expect, vi } from "vitest";
import userEvent from "@testing-library/user-event";

// You can import from setup (if exported):
import { render, screen, userEvent, describe, it, expect, vi } from "@tests/setup";

The setup file exports:

• render, screen, waitFor, within from @testing-library/react
• userEvent from @testing-library/user-event
• vi, expect, describe, it, beforeEach, afterEach, beforeAll, afterAll from vitest

Component Tests

Test components in src/ui/custom/[Component]/[Component].test.tsx:

// src/ui/custom/Button/Button.test.tsx
// Import from setup for convenience
import { render, screen, userEvent, describe, it, expect, vi } from "@tests/setup";
import Button from "./Button";

describe("Button", () => {
  it("renders children", () => {
    render(<Button>Click me</Button>);
    expect(screen.getByText("Click me")).toBeInTheDocument();
  });

  it("calls onClick when clicked", async () => {
    const handleClick = vi.fn();
    const user = userEvent.setup();
    
    render(<Button
    
    await user.click(screen.getByText("Click"));
    expect(handleClick).toHaveBeenCalledTimes(1);
  });
});

Hook Tests

Test custom hooks:

// src/hooks/useCounter/useCounter.test.tsx
import { renderHook, act } from "@testing-library/react";
import { describe, it, expect } from "vitest";
import { useCounter } from "./useCounter";

describe("useCounter", () => {
  it("initializes with 0", () => {
    const { result } = renderHook(() => useCounter());
    expect(result.current.count).toBe(0);
  });

  it("increments count", () => {
    const { result } = renderHook(() => useCounter());
    
    act(() => {
      result.current.increment();
    });
    
    expect(result.current.count).toBe(1);
  });
});

API Route Tests

Test API routes:

// src/pages/api/users/route.test.ts
import { describe, it, expect } from "vitest";
import { createMocks } from "node-mocks-http";
import handler from "./route";

describe("/api/users", () => {
  it("returns users on GET", async () => {
    const { req, res } = createMocks({
      method: "GET",
    });

    await handler(req, res);

    expect(res._getStatusCode()).toBe(200);
    const data = JSON.parse(res._getData());
    expect(data).toHaveProperty("data");
  });
});

Test Utilities

Recommended: Import testing utilities from @tests/setup for convenience:

// All-in-one import from setup
import { 
  render, 
  screen, 
  waitFor, 
  within,
  userEvent,
  describe, 
  it, 
  expect, 
  vi,
  beforeEach,
  afterEach 
} from "@tests/setup";

The setup file (src/tests/setup.tsx) exports:

• RTL utilities: render, screen, waitFor, within from @testing-library/react
• User events: userEvent from @testing-library/user-event
• Vitest utilities: vi, expect, describe, it, beforeEach, afterEach, beforeAll, afterAll
• Mocks: Sonner toast, ResizeObserver, IntersectionObserver are pre-configured

You can also import directly from the source packages if you prefer:

import { render, screen } from "@testing-library/react";
import { describe, it, expect } from "vitest";

E2E Tests (Playwright)

Setup e2e

E2E tests go in e2e/ directory.

Writing E2E Tests

// e2e/homepage.spec.ts
import { test, expect } from "@playwright/test";

test("homepage loads correctly", async ({ page }) => {
  await page.goto("/");
  
  await expect(page).toHaveTitle(/Next.js/);
  await expect(page.locator("h1")).toBeVisible();
});

test("navigation works", async ({ page }) => {
  await page.goto("/");
  await page.click("text=About");
  
  await expect(page).toHaveURL("/about");
});

Running E2E Tests

# Run E2E tests
npx playwright test

# Run in UI mode
npx playwright test --ui

# Run specific test
npx playwright test e2e/homepage.spec.ts

Test Organization

File Structure

src/
├── ui/
│   └── custom/
│       └── Component/
│           ├── Component.tsx
│           └── Component.test.tsx
├── hooks/
│   └── useHook/
│       ├── useHook.ts
│       └── useHook.test.tsx
└── pages/
    └── api/
        └── route.ts
        └── route.test.ts

e2e/
└── feature.spec.ts

Naming Conventions

• Test files: [name].test.tsx or [name].test.ts
• E2E tests: [feature].spec.ts
• Test descriptions: Use describe blocks for grouping, it or test for individual tests

Best Practices

1. Test Behavior, Not Implementation

// ❌ Bad - tests implementation
it("sets state to true", () => {
  // ...
});

// ✅ Good - tests behavior
it("shows error message when validation fails", () => {
  // ...
});

2. Use Accessible Queries

// ❌ Bad
screen.getByClassName("button");

// ✅ Good
screen.getByRole("button", { name: "Submit" });
screen.getByLabelText("Email");
screen.getByText("Welcome");

3. Test User Interactions

import userEvent from "@testing-library/user-event";

it("submits form on button click", async () => {
  const user = userEvent.setup();
  render(<Form />);
  
  await user.type(screen.getByLabelText("Email"), "test@example.com");
  await user.click(screen.getByRole("button", { name: "Submit" }));
  
  expect(screen.getByText("Success")).toBeInTheDocument();
});

4. Mock External Dependencies

// Mock API calls
vi.mock("@/lib/api/client", () => ({
  fetchUsers: vi.fn(() => Promise.resolve([{ id: 1, name: "Test" }])),
}));

// Mock next/router
vi.mock("next/router", () => ({
  useRouter: () => ({
    push: vi.fn(),
    query: {},
  }),
}));

5. Clean Up

import { cleanup, render } from "@testing-library/react";
import { afterEach } from "vitest";

afterEach(() => {
  cleanup();
});

Running Tests

# Run all tests
bun test

# Run tests in watch mode
bun test --watch

# Run tests with coverage
bun test:coverage

# Run E2E tests
npx playwright test

Important Notes

• Use Vitest for unit/integration tests
• Use React Testing Library for component tests
• Use Playwright for E2E tests
• Test user behavior, not implementation details
• Use accessible queries (getByRole, getByLabelText, etc.)
• Mock external dependencies (API calls, router, etc.)
• Keep tests simple and focused - one assertion per test when possible

Converted and distributed by TomeVault — claim your Tome and manage your conversions.