AGENTS.md

1# tests/ - Repository-Level Integration Tests
2 
3## OVERVIEW
4 
5Cross-package invariants and integration fixtures that do not belong to one package's co-located unit suite.
6 
7## STRUCTURE
8 
9```
10tests/
11├── omo-config-category-drift.test.ts  # Config/category contract stays synchronized
12├── omo-schema-freshness.test.ts       # Generated omo.schema.json matches source
13└── hashline/                          # Standalone headless Hashline exercise package
14    ├── package.json
15    ├── bun.lock
16    ├── headless.ts
17    ├── test-environment.ts   # Required env parser (HTTP/HTTPS URL, non-blank key)
18    └── test-*.ts
19```
20 
21## TEST SURFACES
22 
23| Surface | Command | Purpose |
24|---------|---------|---------|
25| Root invariants | `bun test tests/omo-config-category-drift.test.ts tests/omo-schema-freshness.test.ts` | Fast cross-package contract checks |
26| Full root suite | `bun test` | Includes these tests through root `bunfig.toml` |
27| Hashline fixture | Run from a disposable full-repository copy inside a filesystem-isolated VM/container | Exercises edit operations and multi-model behavior through adapter-internal imports; makes live network/model calls, and may write model-selected paths relative to cwd |
28 
29## CONVENTIONS
30 
31- Keep package-specific tests beside package source; use this directory only for real cross-package or standalone-fixture boundaries.
32- Treat `tests/hashline/` as its own Bun package. Preserve its lockfile and headless entry rather than importing it into the root test preload.
33- The Hashline fixture imports adapter-internal `../../packages/...` paths, performs live network/model calls, and may write model-selected paths relative to cwd. Run it only from a disposable full-repository copy inside a filesystem-isolated VM or container with no sensitive parent files and never from the primary checkout or an active worktree.
34- In that sandbox, set explicit short-lived, least-privilege test-only values for `HASHLINE_TEST_BASE_URL` and `HASHLINE_TEST_API_KEY`. `test-environment.ts` requires and validates them (HTTP/HTTPS URL, non-blank key); `headless.ts` throws without them and no longer falls back to hardcoded defaults. Use a non-production endpoint and never use production or personal credentials.
35- Keep generated files and raw stdout/stderr inside the disposable sandbox or local redacted evidence directory. Redact before sharing and never publish raw logs.
36- Freshness tests compare generated artifacts to source-derived output; regenerate the artifact instead of changing the expected value manually.
37- Pure prose changes do not get phrase-pin tests. Test machine-consumed schemas, registration, or runtime behavior.
38 
39## ANTI-PATTERNS
40 
41- Do not turn `tests/` into a second home for ordinary package unit tests.
42- Do not remove, skip, or isolate a failing cross-package invariant to make the root suite green.
43- The synthetic AGENTS.md benchmark fixture under `packages/omo-opencode/src/__tests__/perf/fixtures/` is governed by its own local guide; this guide only cross-references it and does not govern its contents.
44