AGENTS.md

1# OpenSpec Test Guidance
2 
3Applies to tests under `test/`.
4 
5## Running Tests
6 
7- Focused file: `pnpm exec vitest run test/path/to/file.test.ts`
8- Focused case: `pnpm exec vitest run test/path/to/file.test.ts -t "case name"`
9- Full suite: `pnpm test`
10- Run `pnpm run build` before focused CLI tests when implementation changes may leave `dist/` stale.
11 
12## Cross-Platform Paths
13 
14- Do not hard-code Unix path separators in CLI output expectations unless the implementation intentionally emits POSIX paths.
15- For filesystem paths, build expected values with `path.join(...)`, `path.relative(...)`, or `FileSystemUtils.joinPath(...)`.
16- For human-readable output, either assert a deliberately normalized display format or normalize both actual and expected strings before comparing, for example with `FileSystemUtils.toPosixPath()` to convert backslashes to forward slashes for cross-platform consistency.
17- When touching path behavior, add coverage that would fail on Windows path separators.
18 
19## Path Canonicalization
20 
21Path identity is a recurring CI failure mode: Windows short/long paths, symlink or
22junction aliases, and case-insensitive file systems can spell the same existing
23directory differently.
24 
25When asserting existing filesystem paths as identities, canonicalize both actual
26and expected paths first. Prefer `FileSystemUtils.canonicalizeExistingPath()` in
27project code and `fs.realpathSync.native()` in test-only expectations.
28 
29Add an alias-path regression when touching path identity logic. If preserving
30user-typed path spelling is intentional, assert it separately from identity comparisons.
31