frontend-testing

Frontend Testing Guidelines

Applies to all client apps: apps/frontend, apps/admin, apps/mobile, and apps/extension.

The shared philosophy (no vi.mock except unavailable third parties, reusable mock helpers, Arrange/Act/Assert, no vitest imports) lives in the testing-philosophy rule. Below are the client-app specifics.

Core Philosophy

Components render with real hooks, real SDK, real state management. The only boundary is the network — HyperFetch setMock intercepts HTTP requests so components behave exactly like production, just with controlled responses.

New third-party mocks go in the app's src/testing/helpers/ as reusable helpers.

Network mocks

HyperFetch setMock on request objects. This is NOT mocking — it's the framework's built-in test mode that replaces the network layer while keeping everything else real.

import { sdk } from "@/api/sdk";

sdk.users.me.$get.setMock({
  data: { user: { id: "1", email: "[email protected]" } },
});
sdk.auth.login.$post.setMock({ data: { sealedSession: "token" } });
sdk.auth.login.$post.setMock({
  data: null,
  error: { message: "Invalid credentials" },
  status: 401,
});

Clean up in afterEach:

afterEach(() => {
  sdk.users.me.$get.setMock(undefined);
});

What is NEVER acceptable

• vi.mock("@hyper-fetch/react") — NO
• vi.mock("@/api/sdk") — NO
• vi.mock("@/hooks/use-auth") — NO
• vi.mock("@tanstack/react-router") — NO (use a test router provider)
• vi.mock on ANY internal module — NO

Setup

• Global (src/testing/setup/setup.ts): @testing-library/jest-dom/vitest, cleanup() after each test.
• Config: configs/vite.base.config.ts — jsdom, globals enabled.
• Env vars: VITE_API_BASE_URL, VITE_APP_TYPE=web, VITE_ENVIRONMENT=test.

Critical Rules

1. NEVER vi.mock anything unless physically impossible without it. setMock handles API data.
2. Use @testing-library/react — render, screen, fireEvent, waitFor (on mobile, @testing-library/react-native).
3. No snapshot tests.
4. Clean up setMock in afterEach so tests stay independent.