E2E

E2E Tests

Execution Context

Write and run E2E coverage directly in the primary conversation. For a cost-controlled feature workflow, the user switches that conversation to the lower-cost implementation/test model before this phase.

Write E2E tests using TDD (Red-Green-Refactor). Always run the tests you create and watch them fail before implementing.

Related skills

• /tdd — Follow the Red-Green-Refactor cycle when writing tests.
• /pr-fixup — Use after the PR opens only for CI or reviewer findings.
• /playwright-cli — Interactive browser automation. Use to validate features against the dev server before writing tests, and to debug failing tests with --debug=cli.

References

Load references/fixture-state.md for capability-readiness, remembered workflow selection, cross-record correlation, restart persistence, and provider-backed PR feedback fixture rules. Load references/ui-state-and-cleanup.md for lifecycle, WebSocket, terminal, Dockview, and sidebar/context-menu rules.

Location

apps/web/e2e/

apps/web/e2e/
├── fixtures/
│   ├── backend.ts           # Worker-scoped backend + frontend process
│   ├── test-base.ts         # Extended fixture (apiClient, seedData, testPage)
│   └── office-fixture.ts    # Office fixtures (officeApi, officeSeed with workspace+agent)
├── helpers/
│   ├── api-client.ts        # HTTP client for seeding data (read for available methods)
│   └── office-api-client.ts # Office-specific API client (onboarding, issues, agents)
├── pages/                   # Page objects (read for available pages and methods)
└── tests/                   # Spec files (*.spec.ts), grouped by feature
    ├── task/                # Task creation, deletion, archiving, environment, subtasks
    ├── kanban/              # Kanban board, mobile kanban, preview panel
    ├── session/             # Session lifecycle, resume, recovery, multi-session, layout
    ├── workflow/            # Workflow steps, settings, automation, import/export
    ├── git/                 # Git changes panel, commits, diffs, symlinks
    ├── pr/                  # PR detection, watchers, changes panel
    ├── terminal/            # Terminal agent, keyboard, settings
    ├── chat/                # Quick chat, message queue, clarification, markdown, toolbar
    ├── settings/            # Config management, agent profiles, editor integration
    └── review/              # Code review diffs

Each worker gets an isolated backend, frontend, database, and mock agent — no Docker, no API keys needed.

Run commands

Always run headless (make test-e2e). Never use --headed, e2e:headed, or test-e2e-headed — headed mode requires a display and will fail in agent environments.

Fresh worktree bootstrap: Before the first pnpm or E2E command in a new worktree, install the workspace dependencies:

cd apps && pnpm install --frozen-lockfile

Do this once before changing into apps/web or running a filtered package command. Shared .git metadata does not include apps/node_modules.

Preferred: pnpm e2e:run (managed runner — builds, runs, tears down)

e2e/scripts/run-e2e.sh handles the build, the run, and cleanup in one command. Use it instead of stitching the steps together. It auto-selects docker vs host, runs a resource-bounded number of shards concurrently, enforces one Playwright worker per shard and strict WS accounting by default (matching CI), and never leaves root-owned artifacts behind.

cd apps/web
pnpm e2e:run                                   # auto: docker if daemon + CI image available, else host; builds first
pnpm e2e:run tests/task/my-test.spec.ts        # single file (extra args pass through to Playwright)
pnpm e2e:run tests/path/spec.ts -- --grep "exact test name"  # exact CI failure with a fresh build
pnpm e2e:run --shards 3                          # 3 shards concurrently on this machine (isolated)
pnpm e2e:run --no-build -- --grep "task creation"  # runner options before --; Playwright options after
pnpm e2e:run --no-build --project mobile-chrome tests/layout/mobile-spa-resilience.spec.ts
pnpm e2e:docker                                # force the docker CI image (full isolation from a host dev instance)
pnpm e2e:clean                                 # remove build/test artifacts, incl. root-owned ones from prior docker runs

Select the owning Playwright project. The default chromium project intentionally excludes routing, auth, mobile, and container suites; a matching path with the wrong project exits with No tests found. Pass the project before the spec path, for example:

pnpm e2e:run --project auth tests/auth/auth-lifecycle.spec.ts
pnpm e2e:run --project routing tests/office-routing-<name>.spec.ts
pnpm e2e:run --project containers tests/docker/<name>.spec.ts

Use mobile-chrome only for mobile-*.spec.ts files. Confirm Playwright discovers the intended test count before treating a focused command as evidence.

e2e:run accepts one --project; repeating it selects only the last value, so run desktop and mobile separately when both are required and confirm discovery for each.

Read resource-safety.md for full-run limits and compact output before managed E2E runs or full local suites.

The runner solves the sharp edges hand-rolling would hit: in docker it builds the CGO backend on the host and runs it in the runtime image (forward-compatible when the host glibc ≤ the image's — the usual case; it smoke-tests this and only falls back to the build image if the host is newer), builds the Vite web assets on the host, runs them through the Go-served SPA, and keeps Playwright output container-local. See apps/web/e2e/README.md → "the managed runner".

--no-build reuses Vite, backend, and packaged fixtures; prefer normal managed builds after source/base changes. If intentional, rebuild both with make -C apps/backend build and make -C apps/backend e2e-plugin-package; global setup requires the plugin tarball.

For raw Docker/SSH/container runs, make build-backend does not build the Linux mock-agent fixture. Prefer managed; otherwise run make build-backend build-backend-remote-helpers build-web. If KANDEV_MOCK_AGENT_LINUX_BINARY is missing, run make -C apps/backend build-mock-agent-linux before diagnosing code.

Raw commands (when you need fine control)

make test-e2e                                                      # all tests, headless (host)
cd apps && pnpm --filter @kandev/web e2e:raw -- tests/task/my-test.spec.ts  # single file
cd apps && pnpm --filter @kandev/web e2e:raw -- --grep "task creation" # workspace-filter syntax; from apps/web use `pnpm e2e:raw --project=mobile-chrome e2e/tests/<area>/<spec>.spec.ts` without a standalone `--`; run `--list` first if forwarding syntax is uncertain

For flake reproduction, load failure-triage.md.

CRITICAL: E2E tests run against the production Vite build served by the Go backend, not dev mode. After any frontend code change, you must rebuild before running tests (pnpm e2e:run does this for you):

make build-web   # ~30s, required after every frontend change

Without this, tests can exercise stale code: after backend changes run make -C apps/backend build before reproducing Playwright failures, and compare the binary timestamp/hash if a fixed test still fails. make test-e2e and pnpm e2e:run handle both builds.

Writing a test

1. Read helpers/api-client.ts and pages/ to discover available seed methods and page objects; use data-testid attributes for selectors — add them to components as needed
2. Import fixtures from ../../fixtures/test-base — provides testPage, apiClient, and seedData (pre-created workspace with default workflow). Pull backend from the fixture too when you need the backend URL — it's worker-scoped, dynamic, and process.env.KANDEV_API_BASE_URL is not set in the Playwright runner. Use backend.baseUrl.
3. Use page objects for common interactions; create new ones for new pages. For GitHub features, use apiClient.mockGitHub*() methods to seed mock data
4. Workspace-scoped mock events must carry the real workspace_id. mockGitHubAssociateTaskPR defaults an omitted ID to the active workspace; pass it explicitly for foreign-workspace cases, and keep production handlers fail-closed for missing or mismatched IDs. Direct-store bridges that inject Git status or inspect Changes must resolve environmentIdBySessionId[sessionId] and use environment-keyed state; sessions can share one environment.
5. For new status, hydration, or persistence assertions, inventory existing action/mutation scenarios and add coverage beside them, never replace them; preserve response/error, idempotency/duplicate-suppression, and desktop/mobile pointer/target checks, then run affected specs together.

Input-modality behavior

For a touch-specific interaction, use Playwright .tap() rather than .click() so the app receives a touch pointerType. Run focused mobile specs with pnpm e2e:run --project mobile-chrome e2e/tests/<area>/mobile-<name>.spec.ts. --project is a runner option and must precede --; the mobile project only matches mobile-*.spec.ts files, so another filename can produce no tests. After the interaction settles, assert the resulting state and exercise a later mouse or pen entry when the UI maintains hybrid-device pointer state.

For keyboard or accessibility regressions, start from the real visible opener and use real keyboard input (Tab, Enter/Space, and control typeahead when applicable). Do not focus an inner target programmatically to bypass focus management; assert that the target is reachable from the opener, especially for portaled Radix menus.

Visual alignment regressions

For a UI change whose contract is a rendered size or alignment relationship, assert that relationship from the intended elements' bounding boxes rather than only asserting visibility. Scope locators to the affected toolbar, dialog, or panel so unrelated controls cannot make the assertion pass.

const metrics = page.getByTestId("task-metrics");
const actions = page.getByTestId("task-actions");
const [metricsBox, actionsBox] = await Promise.all([
  metrics.boundingBox(),
  actions.boundingBox(),
]);

expect(metricsBox).not.toBeNull();
expect(actionsBox).not.toBeNull();
expect(metricsBox!.height).toBeCloseTo(actionsBox!.height, 1);

Run the assertion in the relevant desktop and mobile projects when responsive layout can change the result. Do not rely on fixed pixels when the product contract is equality or alignment. For control-size regressions, read the mobile-parity sizing contract. For computed colors, parse alpha/opacity semantically or assert a deliberate class/data contract; do not compare serialized getComputedStyle strings because browsers may return rgba(), oklab(), or color().

Animation-aware geometry: Before reading dialog or panel geometry, wait only for currently running Web Animations with finite effect.getComputedTiming().iterations; await animation.finished.catch(() => undefined) because Radix overlays can cancel animations during close or replacement. Never blanket-await infinite animations or use a fixed sleep; then read bounding boxes and assert the relationship.

For virtualized viewport-edge assertions, require the first visible row's top to cover the content top. Assert the last visible row's bottom only when the content overflows; allow legitimate trailing space and end padding in short trees. Check adjacent gaps and overlaps, and include blank-top, blank-bottom, and short-tree fixtures. Do not assert the opposite edge after filtering rows to viewport intersection, because that can reject valid virtualization states.

For narrow-width clipping or overlap regressions, visibility and containment are insufficient: assert a real hit target. Check document.elementFromPoint() at the control center resolves to the control (or its descendant), then prove the action remains clickable at the legal minimum width.

IDs and response shapes — common pitfalls

• apiClient.createTaskWithAgent(...) returns CreateTaskResponse, which is Task & { session_id?: string; agent_execution_id?: string }. Read created.session_id directly — don't call listTaskSessions(taskId) just to fetch the session that was auto-started by the same call.
• The URL /t/:id contains the TASK ID, not the session ID. Backend routes like /port-proxy/:sessionId/:port/*path expect the session ID. Don't extract IDs from window.location.pathname when you need a session ID — pull from the API response.
• page.request shares cookies/storage with the page context. Fine for the current no-auth local backend; if auth ever lands, this is where you'd plug it in.
• Go boot-payload data is available before React mounts. Routes that hydrate from window.__KANDEV_BOOT_PAYLOAD__ may not issue a browser-visible API request on first paint. Use apiClient to seed or re-query backend state, assert the user-visible outcome, and reserve page.waitForResponse("**/api/v1/...") for client-side fetches that the browser actually performs.
• Preview iframe tests: the seed repo has no dev_script configured, so the preview panel renders a placeholder ("Configure a dev script…") and the URL input never appears — tests that try to drive it hang on the locator timeout. To use the preview iframe in a test, set one first: await apiClient.updateRepository(seedData.repositoryId, { dev_script: "echo dev" }). Then click the Preview dockview tab (await session.clickTab("Preview")) — the toolbar will mount and the URL input becomes targetable.

Example:

import { test, expect } from "../../fixtures/test-base";
import { KanbanPage } from "../../pages/kanban-page";

test.describe("my feature", () => {
  test("does something", async ({ testPage, seedData, apiClient }) => {
    const task = await apiClient.createTask(seedData.workspaceId, "Test Task", "Description");
    const kanban = new KanbanPage(testPage);
    await kanban.goto(seedData.workspaceId);
    await expect(kanban.taskCardByTitle("Test Task")).toBeVisible();
  });
});

Dev-first workflow

For interactive development and PR captures, load dev-workflow.md. Production-build verification remains required after development.

Test organization

Tests are grouped by feature area in subdirectories under tests/. When creating a new test:

• Place it in the matching feature directory. A test for PR detection goes in pr/, a test for session resume goes in session/, etc.
• Merge related tests into the same file. Tests covering the same feature (e.g., git commit body and pre-hooks) belong in one file with separate test.describe blocks. Don't create a new file for each narrow scenario.
• Import paths from subdirectories use ../../ (e.g., from "../../fixtures/test-base").
• Standalone root files are allowed for truly cross-cutting tests that don't fit any group.
• Extract shared helpers. Extract helpers into a sibling *-helpers.ts file whenever they are used by multiple spec files, even when small; keep only scenario-specific setup in specs. Reusable page polling, seeding, and Dockview cleanup belong in the helper module.
• Keep pure unit tests out of apps/web/e2e/tests/. Playwright discovery imports files in that tree, so a Vitest file can fail discovery before any browser test runs. Put pure Vitest tests beside the component or helper, and after adding an E2E-adjacent helper test run: cd apps/web && pnpm exec playwright test --config e2e/playwright.config.ts --project=chromium --project=mobile-chrome --project=containers --list --reporter=json. Require zero discovery errors before treating the E2E suite as runnable.