frontend-testing

Frontend Testing

Test what the user experiences, not implementation details. Query the DOM the way a user (or assistive tech) does.

Close the loop yourself (do not hand back to the user)

Writing tests/code is not the finish line — a clean run is. Drive the verify-and-fix loop autonomously; never ask the user to run the app, paste errors back, or confirm a fix worked.

1. Run pnpm typecheck, pnpm lint, pnpm build, pnpm test (and pnpm build-storybook when present) for the target app.
2. Read the full output, fix every error and meaningful warning, then re-run from the failed step.
3. Repeat until all steps pass. Only stop to ask the user when genuinely blocked (missing secret, ambiguous product decision) — not for routine type/lint/test/build failures.
4. Report completion only with fresh passing output as evidence.

When to use

• Adding tests for React components, hooks, or Next.js routes.
• Writing end-to-end flows with Playwright.
• Fixing flaky or implementation-coupled frontend tests.

Levels

1. Unit — pure functions, hooks, utilities. Fast, no DOM where possible.
2. Component — render a component with Testing Library; assert on visible output and behavior.
3. End-to-end — Playwright drives a real browser through whole user flows.

Prefer the lowest level that proves the behavior; reserve E2E for critical paths.

Component tests (Vitest + Testing Library)

• Query by role/label/text, not test IDs or class names: getByRole('button', { name: /save/i }). Use data-testid only as a last resort.
• Drive interactions with @testing-library/user-event, not raw fireEvent.
• Assert on what the user sees (text, roles, ARIA state), never on component internals or props.
• Use findBy* / waitFor for async UI instead of fixed timeouts.
• Mock network at the boundary (e.g. MSW), not by stubbing your own components.

test('submits the form', async () => {
  const user = userEvent.setup()
  render(<LoginForm onSubmit={onSubmit} />)
  await user.type(screen.getByLabelText(/email/i), '[email protected]')
  await user.click(screen.getByRole('button', { name: /sign in/i }))
  expect(onSubmit).toHaveBeenCalledWith({ email: '[email protected]' })
})