Tests

arka-deck uses two test pipelines: Vitest for unit and lightweight integration tests, Playwright for end-to-end UI tests.

Vitest — unit + integration

Run all tests

npm test

Watch mode

npm run test:watch

Target a file

npm test -- core/use-cases/projects/build-for-projects.test.ts

Target a pattern

npm test -- --grep "purge"

Coverage

npm test -- --coverage

v8 coverage produced in coverage/. The blocking threshold in CI is set in vitest.config.ts.

Placement convention

Tests live next to the tested code:

core/use-cases/projects/
├── build-for-projects.ts
├── build-for-projects.test.ts        ← unit tests
└── build-for-projects.integration.test.ts  ← integration tests (optional)

adapters/inbound/web/server/src/__tests__/
└── projects-routes.test.ts            ← server tests

For HTTP routes, tests live in adapters/inbound/web/server/src/__tests__/.

Fakes and test doubles

core/_fakes/ contains reusable outbound port implementations for tests:

InMemoryFilesystem
InMemoryEventBus (= prod and test impl, no separate fake)
InMemoryChatSessionStore
FakeClock ({ now: () => new Date('2026-01-01T00:00:00Z') })
FakeIdGenerator ({ next: () => 'test-id-N' })
etc.

Import from tests:

import { InMemoryFilesystem } from '../../../core/_fakes/in-memory-filesystem.js';

Playwright — E2E

Install Playwright

npm run e2e:install

(Downloads Chromium and its deps.)

Run E2E

npm run e2e

The test launches the arka-deck server, opens the UI in headless Chromium, and plays scenarios defined in e2e/.

Available E2E tests

File	Scenario
`e2e/smoke.spec.ts`	Server launch + UI load + health check
others	To add per critical flows

Anti-patterns to avoid

Global `fs` mocking

❌ Don’t mock fs or node:fs directly. Use InMemoryFilesystem injected in deps.

Order-dependent test

❌ Vitest can parallelize. Tests must be isolated (no shared state between tests).

Real-clock-dependent test

❌ Use FakeClock or vi.useFakeTimers().

Artificial coverage

❌ Don’t write empty tests just to cover a line. Prefer removing dead code.