AGENTS.md

1# Koenig Lexical Test Guide
2 
3## Test Commands
4 
5### Unit Tests
6```bash
7pnpm test:unit          # Run unit tests once
8pnpm test:unit:watch    # Run unit tests in watch mode
9```
10 
11### Acceptance Tests (Playwright)
12```bash
13pnpm test:acceptance           # Run Playwright tests (headless, list reporter)
14pnpm test:acceptance:quiet     # Minimal output, failures only
15pnpm test:acceptance:headed    # Run with browser UI visible
16pnpm test:acceptance:report    # Run with HTML report
17pnpm test:slowmo               # Slow motion + UI
18```
19 
20### All Tests
21```bash
22pnpm test               # Run unit + acceptance tests, then lint
23```
24 
25## AI-Friendly Testing
26 
27The test runner has been configured to work well with AI agents:
28 
29- **Default behavior**: Headless mode with list reporter (no browser UI, no web pages)
30- **Quiet mode**: Use `pnpm test:acceptance:quiet` for minimal output (only shows failures)
31- **Clean exit**: Tests complete without hanging processes or opening browsers
32- **Clear output**: List reporter provides clear pass/fail information
33 
34## Human-Friendly Testing
35 
36For debugging and development:
37 
38- Use `pnpm test:acceptance:headed` to see the browser UI
39- Use `pnpm test:acceptance:report` to generate an HTML report
40- Use `pnpm test:slowmo` for slow-motion debugging
41 
42## Environment Variables
43 
44- `PLAYWRIGHT_HEADED=true` - Show browser UI
45- `PLAYWRIGHT_HTML_REPORT=true` - Generate HTML report
46- `PLAYWRIGHT_SLOWMO=100` - Slow motion delay (ms)
47 
48## Test Structure
49 
50- `test/unit/` - Unit tests (Vitest)
51- `test/e2e/` - Package-level acceptance tests (Playwright,
52  `test:acceptance` target); Ghost's end-to-end suite lives in the repository's
53  top-level `e2e/` directory
54- `test/utils/` - Shared test utilities
55 
56## Development Workflow
57 
581. Run unit tests during development: `pnpm test:unit:watch`
592. Run acceptance tests before committing: `pnpm test:acceptance`
603. Use headed mode for debugging: `pnpm test:acceptance:headed`
61