front-end-testing

name: front-end-testing description: Behavior-driven UI testing patterns. Covers Vitest Browser Mode (preferred) and DOM Testing Library. Use when testing any front-end application, writing UI tests, querying DOM elements, or simulating user interactions. For React-specific patterns, see the react-testing skill.

Front-End Testing

For React-specific patterns (components, hooks, context), load the react-testing skill. For TDD workflow, load the tdd skill. For general testing patterns (factories, public API testing), load the testing skill.

Deep-dive resources are in the resources/ directory. Load them on demand:

Core Philosophy

Test behavior users see, not implementation details. This applies in every environment — Browser Mode, jsdom, anything.

Your UI has two users:

1. End-users: Interact through the DOM (clicks, typing, reading text)
2. Developers: You, refactoring implementation

Kent C. Dodds principle: "The more your tests resemble the way your software is used, the more confidence they can give you."

False negatives (tests break on refactor):

// ❌ WRONG - Coupled to state implementation; breaks when state → signals → stores
it('should update internal state', () => {
  const component = new CounterComponent();
  component.setState({ count: 5 });
  expect(component.state.count).toBe(5);
});

False positives (bugs pass tests):

// ❌ WRONG - Button exists but onClick is broken; test still passes
it('should render button', () => {
  render('<button data-testid="submit-btn">Submit</button>');
  expect(screen.getByTestId('submit-btn')).toBeInTheDocument();
});

✅ CORRECT - Drive the UI the way a user would, assert what the user sees: type into labelled fields, click the submit button, assert the submit handler received the form data. This survives refactors, tests the contract, and catches real bugs (broken onClick, validation errors).

Vitest Browser Mode (Preferred)

Always prefer Vitest Browser Mode over jsdom/happy-dom. Tests run in a real browser (via Playwright), giving production-accurate behavior for CSS, events, focus management, and accessibility.

Why Browser Mode Over jsdom

Setup

npm install -D vitest @vitest/browser-playwright
npx playwright install chromium  # Playwright provider needs browser binaries

// vitest.config.ts
import { defineConfig } from 'vitest/config'
import { playwright } from '@vitest/browser-playwright'

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      provider: playwright(),
      headless: true,
      instances: [{ browser: 'chromium' }],
    },
  },
})

Quick setup wizard: npx vitest init browser

Built-in Locators

Vitest Browser Mode has built-in locators that mirror Testing Library queries. No separate @testing-library/dom import needed.

import { page } from 'vitest/browser'

// These work exactly like Testing Library queries
page.getByRole('button', { name: /submit/i })
page.getByText(/welcome/i)
page.getByLabelText(/email/i)
page.getByPlaceholder(/search/i)
page.getByAltText(/logo/i)
page.getByTestId('my-element')  // Last resort only

Built-in Assertions with Retry

Use expect.element() for DOM assertions — it automatically retries until the assertion passes or times out, reducing flakiness:

// ✅ CORRECT - Auto-retrying assertion
await expect.element(page.getByText(/success/i)).toBeVisible()
await expect.element(page.getByRole('button')).toBeDisabled()

// Available matchers (no @testing-library/jest-dom needed):
await expect.element(el).toBeVisible()
await expect.element(el).toBeDisabled()
await expect.element(el).toHaveTextContent(/text/i)
await expect.element(el).toHaveValue('input value')
await expect.element(el).toHaveAttribute('aria-label', 'Close')
await expect.element(el).toBeChecked()

Built-in User Events (CDP-based)

import { userEvent } from 'vitest/browser'

// Real browser events via Chrome DevTools Protocol
await userEvent.click(page.getByRole('button', { name: /submit/i }))
await userEvent.fill(page.getByLabelText(/email/i), 'test@example.com')
await userEvent.keyboard('{Enter}')
await userEvent.selectOptions(page.getByLabelText(/country/i), 'USA')
await userEvent.clear(page.getByLabelText(/search/i))

Or use locator methods directly:

await page.getByRole('button', { name: /submit/i }).click()
await page.getByLabelText(/email/i).fill('test@example.com')

In jsdom codebases, use @testing-library/user-event instead — always prefer it over fireEvent (see resources/dom-testing-library-legacy.md). Create a fresh userEvent.setup() per test, never in beforeEach.

Multi-Project Setup (Node + Browser)

When you need both unit tests (Node) and UI tests (browser):

export default defineConfig({
  test: {
    projects: [
      {
        test: {
          include: ['tests/unit/**/*.test.ts'],
          name: 'unit',
          environment: 'node',
        },
      },
      {
        test: {
          include: ['tests/browser/**/*.test.ts'],
          name: 'browser',
          browser: {
            enabled: true,
            provider: playwright(),
            instances: [{ browser: 'chromium' }],
          },
        },
      },
    ],
  },
})

Browser Mode Gotchas

• vi.spyOn on imports: ES module namespaces are sealed in real browsers. vi.mock('./module', { spy: true }) works, but treat module mocking as temporary scaffolding — prefer parameter injection so the dependency is an explicit seam (load the finding-seams skill).
• alert()/confirm(): Thread-blocking dialogs halt browser execution. Mock them with vi.spyOn(window, 'alert').mockImplementation(() => {}).
• act(): Not needed for component interactions via locators — CDP events + expect.element() retry handle timing. renderHook state updates still need act (see react-testing).

Playwright / Browser Mode Test Idempotency

All Playwright-style tests MUST be idempotent. Every test must produce the same result regardless of execution order, how many times it runs, or what other tests ran before it.

Rules:

• Each test creates its own state from scratch — never depend on another test's side effects
• Clean up any persistent state (database rows, localStorage, cookies) created during the test
• Use unique identifiers (e.g., timestamp-based) to avoid collisions when tests run in parallel
• Never assume the DOM is in a particular state at the start of a test — render fresh
• If tests share a server or database, use isolation strategies (transactions, test-specific data)

// ❌ WRONG - Tests depend on shared state
it('creates a user', async () => {
  await page.getByRole('button', { name: /create/i }).click()
  // Creates user "Alice" in the database
})

it('lists users', async () => {
  // Assumes "Alice" exists from previous test!
  await expect.element(page.getByText('Alice')).toBeVisible()
})

// ✅ CORRECT - Each test is self-contained
it('creates and displays a user', async () => {
  const uniqueName = `User-${Date.now()}`
  await page.getByLabelText(/name/i).fill(uniqueName)
  await page.getByRole('button', { name: /create/i }).click()
  await expect.element(page.getByText(uniqueName)).toBeVisible()
})

Why this matters: Browser Mode can run tests in parallel across multiple browser instances. Non-idempotent tests will produce flaky failures that are nearly impossible to debug.

Query Selection Priority

Most critical skill: choosing the right query. Identical for Browser Mode locators and Testing Library queries.

Use queries in this order (accessibility-first):

1. getByRole - Highest priority. Queries by ARIA role + accessible name; mirrors screen reader experience; forces semantic HTML
2. getByLabelText - Form fields, via associated <label>
3. getByPlaceholder - Fallback for inputs when no label (placeholder shouldn't replace a label)
4. getByText - Non-interactive content users read
5. getByDisplayValue - Inputs with pre-filled values
6. getByAltText - Images
7. getByTitle - Rare, when other queries unavailable
8. getByTestId - Last resort only; not user-facing

Query Variants (Testing Library)

• getBy* - Element must exist (throws if not found). Use when asserting existence.
• queryBy* - Returns null if not found. Use when asserting non-existence.
• findBy* - Async, waits for element to appear. See resources/async-patterns.md.

(Browser Mode locators are lazy and retried by expect.element(), so the get/query/find split mostly disappears — use .not.toBeInTheDocument() via expect.element for absence.)

Common Mistakes

// ❌ WRONG - querySelector (DOM implementation detail)
const button = container.querySelector('.submit-button');
// ❌ WRONG - testId when a role is available (not how users find the button)
screen.getByTestId('submit-button');
// ❌ WRONG - role without accessible name (which button? pages have many)
screen.getByRole('button');
// ✅ CORRECT - role + accessible name (how screen readers find it)
screen.getByRole('button', { name: /submit/i });

// ❌ WRONG - getBy to assert non-existence (awkward throw-based check)
expect(() => screen.getByText(/error/i)).toThrow();
// ✅ CORRECT - queryBy returns null
expect(screen.queryByText(/error/i)).not.toBeInTheDocument();

// ❌ WRONG - exact string match (breaks on whitespace change)
screen.getByText('Welcome, John Doe');
// ✅ CORRECT - regex for flexibility
screen.getByText(/welcome.*john doe/i);

Accessibility-First Testing

Three benefits of accessible queries:

1. Tests mirror real usage - Query like screen readers do
2. Improves app accessibility - Tests force accessible markup
3. Refactor-friendly - Coupled to user experience, not implementation

If an accessible query fails, your app has an accessibility issue.

Always prefer semantic HTML over ARIA:

<!-- ❌ WRONG - Custom element + ARIA -->
<div role="button" onclick="handleClick()" tabindex="0">Submit</div>

<!-- ✅ CORRECT - Semantic HTML: built-in keyboard nav, focus, screen reader support -->
<button onclick="handleClick()">Submit</button>

Add ARIA only where semantic HTML is unavailable (e.g., role="dialog" on a custom modal), never redundantly on semantic elements.

Async Testing

In Browser Mode, await expect.element(...) handles most waiting automatically. In jsdom codebases, use findBy* for appearance, waitFor for complex conditions, and waitForElementToBeRemoved for disappearance.

Key rules: no side effects inside waitFor, one assertion per waitFor, never wrap findBy in waitFor.

For full patterns and anti-patterns, see resources/async-patterns.md.

API Mocking with MSW

Use MSW, not fetch/axios mocks — it intercepts at the network level, so the same handlers work in tests, Storybook, and dev.

Environment determines the API:

• Browser Mode: setupWorker from msw/browser (start the worker in a setup file; per-test overrides via worker.use())
• Node/jsdom: setupServer from msw/node (per-test overrides via server.use())

Using setupServer in Browser Mode silently does nothing — tests run in a real browser. See resources/msw.md for full setup of both.

Core Anti-Patterns

1. Testing implementation details — internal state, private methods, CSS classes as hooks. Test user-visible behavior.
2. querySelector/testId when an accessible query exists — see Query Selection Priority above.
3. beforeEach render with shared variables — use a factory function per test instead:

// ❌ WRONG - Shared state across tests
let button;
beforeEach(() => {
  render('<button>Submit</button>');
  button = screen.getByRole('button');
});

// ✅ CORRECT - Factory function per test
const renderButton = () => {
  render('<button>Submit</button>');
  return { button: screen.getByRole('button') };
};

For factory patterns, see the testing skill.

4. Fetch/axios mocking instead of MSW — see resources/msw.md.
5. waitFor misuse — see resources/async-patterns.md.
6. jsdom-specific anti-patterns (skipping screen, fireEvent, manual cleanup(), property assertions instead of jest-dom matchers, missing ESLint plugins) — see resources/dom-testing-library-legacy.md.

Summary Checklist

Before merging UI tests, verify:

• Preferred: Using Vitest Browser Mode with real browser (not jsdom/happy-dom)
• All Playwright/Browser Mode tests are idempotent (no shared state between tests)
• Using getByRole as first choice for queries (built-in or Testing Library)
• Using expect.element() for auto-retrying assertions (Browser Mode)
• Using userEvent for interactions (CDP-based in Browser Mode, or @testing-library/user-event)
• Testing behavior users see, not implementation details
• No manual cleanup() calls (automatic)
• No manual act() calls for component interactions (Browser Mode handles timing)
• MSW for API mocking — setupWorker in Browser Mode, setupServer in Node/jsdom
• Following TDD workflow (see tdd skill)
• Using test factories for data (see testing skill)
• For React-specific patterns (hooks, context, components), see react-testing skill