Frontend Testing Rules

Style ("small test" practice — stable boundary, data over mocks, focused assertions, concise makeMe): the unit-testing skill — follow that first.

These commands cover behavioral testing only. Before accepting frontend proof, also pass the typecheck required by the frontend skill's "Frontend proof" rule.

Test Commands

From the repo root:

CURSOR_DEV=true nix develop -c pnpm frontend:test

All frontend unit-test commands use headless Chromium and never automatically open a browser window. Do not enable a visible browser unless the user explicitly asks.

The legacy UI command also runs headlessly:

CURSOR_DEV=true nix develop -c pnpm frontend:test:ui

Run tests in headless watch mode (the Vitest UI remains available at its printed URL without opening a browser):

CURSOR_DEV=true nix develop -c pnpm frontend:test:watch

Run a single test file from the repo root:

CURSOR_DEV=true nix develop -c pnpm frontend:test tests/path/to/TestFile.spec.ts

Or only the frontend package:

CURSOR_DEV=true nix develop -c pnpm -C frontend test tests/path/to/TestFile.spec.ts

Run a specific test case:

CURSOR_DEV=true nix develop -c pnpm -C frontend test -t "test name pattern"

The test file path is relative to frontend/. Do not use pnpm ... test -- tests/...; the -- is forwarded to Vitest and file filtering is skipped.

In most situations, run all unit tests instead of a selected file only. Use a single test file when actively debugging or iterating on a specific component.

For dough-test-optimization, frontend:test remains the ordinary local feedback measurement because it runs Chromium browser mode. When per-test JSON durations are needed for investigation, use CURSOR_DEV=true nix develop -c pnpm -C frontend exec vitest run --reporter=json. That plain Vitest run is profiling evidence only; verify retained changes with the normal browser-mode command and do not compare its wall time directly with frontend:test.

Component Behavior

• Drive the mounted component / page ("small test" style per unit-testing skill); cover lower layers with realistic makeMe props/state, not by testing internal helpers in isolation.
• Test through user interactions; assert observable DOM outcomes.
• Use data-testid for test selectors.
• Use Vitest browser mode and prefer real browser rendering over mocking sibling components or internal modules; stop using jsdom.

Allowed Mocks

vi.mock is limited to these modules; everything else in-process runs for real:

• @/managedApi/AiReplyEventSource: the streaming backend API (same boundary as mockSdkService).
• @/models/audio/audioRecorder, @/models/audio/recorderWorklet, @/models/wakeLocker: microphone, audio worklet, and screen wake lock, which headless Chromium lacks.
• file-saver: starts a browser download.
• pdfjs-dist (gesture-zoom support file only): the PDF engine and worker, whose page geometry the spec must control.

Real in-process code, observed through shared helpers:

• Popups: the real usePopups stack, emptied before each test; answer and inspect with @tests/helpers/popupStackTestSupport.
• Router: productionRouterAt(location) and countHistoryEntriesAdded(router) from @tests/helpers; assert the router's current named location.
• Toasts: showToastsOnPage() from @tests/helpers/toastTestSupport; assert the toast on the page.

Routing assertions

Navigation assertions use named locations (or helpers that return them). Rendered-href assertions use noteShowHref. Path strings belong only in routes.spec.ts (matching / redirects) and inbound URL classifiers. Test routers that resolve named screen locations use production routes or dummyRouteRecordsFromMetadata (the routeMetadata table with dummy components; no page imports). A spec's router over production routes comes from productionRouterAt(location) (from @tests/helpers) or plain withRouter(); every test starts at the root location, reset in shared test setup. Catch-all / or /:pathMatch(.*)* routers and useRoute stubs with path: "/" are not a second screen dialect (ADR 0005).

Avoid Role Queries

• Do not use getByRole, findByRole, queryByRole, getAllByRole, and similar queries; they are slow due to expensive visibility checks.
• Testing Library recommends role queries for accessibility, but this project prioritizes test performance.
• Use faster alternatives: getByText, getByLabelText, getByTitle, or querySelector / querySelectorAll.

Mock SDK Services

The backend HTTP API is an external dependency from the frontend’s perspective (unit-testing skill mocking exception).

• Use mockSdkService from @tests/helpers for type-safe mocking: pass the generated controller class and the method name (same static methods as @generated/donut-backend-api/sdk.gen).
• It automatically wraps responses in the standard format { data, error, request, response }.
• It returns a spy that can be reconfigured in tests.
• Use wrapSdkResponse when updating mock return values.
• Use mockSdkServiceWithImplementation only for custom async logic based on options.
• Build response payloads with makeMe; do not mock in-process collaborators to “reach” coverage.

import { NoteController } from "@generated/donut-backend-api/sdk.gen"
import { mockSdkService } from "@tests/helpers"

beforeEach(() => {
  mockSdkService(NoteController, "getRecentNotes", [])
  mockSdkService(NoteController, "showNote", makeMe.aNoteRealm.please())
})

import { NoteController } from "@generated/donut-backend-api/sdk.gen"
import { mockSdkService, wrapSdkResponse } from "@tests/helpers"

const spy = mockSdkService(NoteController, "showNote", makeMe.aNoteRealm.please())
spy.mockResolvedValue(wrapSdkResponse(differentNote))

import { TextContentController } from "@generated/donut-backend-api/sdk.gen"
import { mockSdkServiceWithImplementation } from "@tests/helpers"

mockSdkServiceWithImplementation(TextContentController, "updateNoteContent", async (options) => {
  return await someAsyncOperation(options)
})

Component Props

• Use helper.component(ComponentName).withStorageProps if the component requires a storageAccessor prop.
• Use withProps instead of withStorageProps if the component does not require storageAccessor.
• Test prop changes and their effects.

const wrapper = helper
  .component(Component)
  .withStorageProps({ value: initialValue })
  .mount()

await wrapper.setProps({ value: newValue })

Data Builders

• Use makeMe for API-shaped test data; implementation lives in packages/donut-test-fixtures.
• Import donut-test-fixtures/makeMe only. Do not import the bare package name or deep paths into src/.
• Concise setup, defaults, and extending builders: unit-testing skill.

const note = makeMe.aNoteRealm.title("Dummy Title").content("Description").please()
const answered = makeMe.anAnsweredQuestion
  .accidentalMatch("alias", [note.note.noteTopology])
  .please()

Browser Mode Mounting

• Use render() from @testing-library/vue for most tests.
• render() encourages user-perspective tests and returns fast queries such as getByText, getByLabelText, and data-testid.
• Use mount() from @vue/test-utils only when you need direct access to Vue internals, emitted events, slots, or provide/inject edge cases.
• Query the DOM, not Vue components.

Prefer:

page.getByText(/submit/i)
screen.getByText("Loading...")

Avoid:

wrapper.findComponent(MyButton)
wrapper.find("[data-testid='my-component']")

Layout and Pointer Tests

• Prove that text is visible with geometry: scrollWidth <= clientWidth, and range or element rectangles inside their row. Checking textContent alone misses clipped text.
• Browser specs use production CSS. Set the container width, or call page.viewport for breakpoint (sm:) behavior; the default viewport is 414px wide.
• Name a spec *.touch.spec.ts when it needs a real coarse pointer. The chromium-touch browser instance in vitest.config.ts runs those files with touch emulation, so (pointer: coarse) matches. Do not substitute a matchMedia stub.

Deterministic Tests

• Tests must always execute the same way.
• Use assertions instead of if-conditions so failures are clear.
• Use sequential async operations instead of loops where possible.

Avoid:

if (vm.searchResults) {
  const selected = vm.searchResults.find((result) => result.id === wikidataId)
  if (selected) {
    // do something
  }
}

Prefer:

expect(vm.searchResults).toBeDefined()
expect(vm.searchResults.length).toBeGreaterThan(0)
const selected = vm.searchResults.find((result) => result.id === wikidataId)
expect(selected).toBeDefined()