Skip to content

Commit ec84c10

Browse files
committed
enhance(test): stabilize the unit suite and gate commits [anomalyco#245]
Test layering - isolate integration dirs with trailing slashes and drop the stale snapshot dir - move live-I/O tests out of the unit layer via the *-integration.test.ts convention - include the runner's own script tests in the unit layer Assertions and fixtures - derive version and protocol assertions from their single sources - pin fixture git commands to their temp repo and clear locator vars per test process Commit gate - run the opencode unit layer from .husky/pre-commit for staged .ts/.tsx Specs - sync the EN and zh test specs with the new layering, scopes and baseline
1 parent c9480ab commit ec84c10

22 files changed

Lines changed: 648 additions & 143 deletions

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,3 +32,4 @@ logs/
3232
tsconfig.tsbuildinfo
3333
CLAUDE.md
3434
release/legacy-inventory.dry-run.json
35+
.bun-cache

‎.husky/pre-commit‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,4 +10,24 @@ if [ -n "$staged_ts" ]; then
1010
if [ -n "$non_test" ]; then
1111
bun typecheck
1212
fi
13-
fi
13+
14+
# Git exports repository-locator variables (GIT_DIR, GIT_INDEX_FILE, ...) to
15+
# hooks. Tests build throwaway repositories in temp directories, so a leaked
16+
# GIT_DIR redirects them at this checkout: false failures, and fixture
17+
# `git init` / `git config` writes landing in the real repository config.
18+
# Clear them so the unit layer sees the same environment as a direct run.
19+
unset GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE GIT_COMMON_DIR GIT_OBJECT_DIRECTORY GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_PREFIX
20+
unset GIT_AUTHOR_NAME GIT_AUTHOR_EMAIL GIT_AUTHOR_DATE GIT_COMMITTER_NAME GIT_COMMITTER_EMAIL GIT_COMMITTER_DATE
21+
22+
# Any staged TypeScript (source or test) must pass the opencode unit layer.
23+
# Only the opencode package runs here: the root test:unit fans out through
24+
# run-tests-root.ts to app/desktop/cordis, far beyond the commit budget.
25+
if ! bun run --cwd packages/opencode test:unit; then
26+
echo ""
27+
echo "✖ pre-commit blocked: the opencode unit layer failed."
28+
echo " The commit was rejected; no bad revision enters history."
29+
echo " Reproduce with: bun run --cwd packages/opencode test:unit"
30+
echo ""
31+
exit 1
32+
fi
33+
fi

‎AGENTS.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,10 @@ Wopal capabilities enter the engine through two module groups in `packages/openc
5151
|---|---|
5252
| Lint | `bun run lint` |
5353
| Full-repo typecheck | `bun run typecheck` |
54-
| opencode package tests | `bun test --timeout 30000 --force-exit` (from `packages/opencode`) |
54+
| opencode package tests (unit) | `bun run test:unit` (from `packages/opencode`) |
55+
| opencode package tests (integration) | `bun run test:integration` (from `packages/opencode`) |
56+
| opencode package tests (e2e) | `bun run test:e2e` (from `packages/opencode`) |
57+
| opencode package tests (full regression) | `bun run test:all` (from `packages/opencode`) |
5558
| opencode build | `bun run build` (from `packages/opencode`) |
5659
| ellamaka-brand package tests | `bun test` (from `packages/ellamaka-brand`) |
5760
| Build ellamaka-branded CLI | `bun packages/ellamaka-release/src/cli/build.ts --web-ui ellamaka-app` |
@@ -65,6 +68,8 @@ Wopal capabilities enter the engine through two module groups in `packages/openc
6568

6669
Tests cannot run from repo root. Run `./scripts/dev.sh help` and `./scripts/build.sh help` for full parameter documentation.
6770

71+
opencode tests run through the layered entries above (`test:unit` for the daily loop, `test:integration` when a change touches an integration directory or a `*-integration.test.ts` file, `test:e2e` for `*-e2e.test.ts` files, `test:all` for full regression). Commits are gated: when the staged change contains `.ts`/`.tsx` files, `.husky/pre-commit` runs the opencode package unit layer (`bun run --cwd packages/opencode test:unit`) and rejects the commit on failure, adding roughly twenty seconds to the commit. Documentation-only commits skip the gate.
72+
6873
## Implementation Rules
6974

7075
### WopalSpace Customization Constraints

‎AGENTS.zh-CN.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,10 @@ Wopal 能力经 `packages/opencode/src/` 下的两个模块组进入引擎:`wo
5151
|---|---|
5252
| Lint | `bun run lint` |
5353
| 全仓类型检查 | `bun run typecheck` |
54-
| opencode 包测试 | `bun test --timeout 30000 --force-exit`(from `packages/opencode`) |
54+
| opencode 包测试(unit) | `bun run test:unit`(from `packages/opencode`) |
55+
| opencode 包测试(integration) | `bun run test:integration`(from `packages/opencode`) |
56+
| opencode 包测试(e2e) | `bun run test:e2e`(from `packages/opencode`) |
57+
| opencode 包测试(全量回归) | `bun run test:all`(from `packages/opencode`) |
5558
| opencode 构建 | `bun run build`(from `packages/opencode`) |
5659
| ellamaka-brand 包测试 | `bun test`(from `packages/ellamaka-brand`) |
5760
| 构建 ellamaka 品牌 CLI | `bun packages/ellamaka-release/src/cli/build.ts --web-ui ellamaka-app` |
@@ -65,6 +68,8 @@ Wopal 能力经 `packages/opencode/src/` 下的两个模块组进入引擎:`wo
6568

6669
测试不能从 repo root 运行。`./scripts/dev.sh help` 和 `./scripts/build.sh help` 查看完整参数说明。
6770

71+
opencode 测试走上表的分层入口(`test:unit` 用于日常循环,改动涉及集成目录或 `*-integration.test.ts` 文件时跑 `test:integration`,`*-e2e.test.ts` 文件跑 `test:e2e`,`test:all` 用于全量回归)。提交设有门禁:当暂存变更包含 `.ts`/`.tsx` 文件时,`.husky/pre-commit` 会运行 opencode 包的单元层(`bun run --cwd packages/opencode test:unit`),失败即拒绝提交,给提交增加约二十秒。纯文档提交跳过门禁。
72+
6873
## Implementation Rules
6974

7075
### WopalSpace 定制约束

‎packages/opencode/AGENTS.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -40,10 +40,10 @@ This is ellamaka's main engine package. It carries the OpenCode inherited runtim
4040
|---|---|---|
4141
| Dev | `bun run dev` | Local package dev entry |
4242
| Typecheck | `bun typecheck` | After TypeScript changes; never run `tsc` directly |
43-
| Test (default subset) | `bun run test:unit` | After behavior changes (fast unit subset, ~60s) |
43+
| Test (default subset) | `bun run test:unit` | After behavior changes (fast unit subset, ~25s) |
4444
| Test (heavy integration) | `bun run test:integration` | After behavior changes in integration-dir code (dir list in Testing below; `INTEGRATION_DIRS` is the source of truth) |
4545
| Test (e2e) | `bun run test:e2e` | After changes to real provider-chain / browser e2e tests |
46-
| Test (full regression) | `bun run test:all` | Full regression (equivalent to `bun test --timeout 30000 --force-exit`) |
46+
| Test (full regression) | `bun run test:all` | Full regression (equivalent to `bun test --timeout 30000 --force-exit --max-concurrency=4`) |
4747
| Build | `bun run build` | After runtime, CLI, or package build changes |
4848
| Database migration | `bun run db generate --name <slug>` | After schema changes |
4949

@@ -82,11 +82,11 @@ All commands run from `packages/opencode`.
8282

8383
## Testing
8484

85-
- Test subsets are expanded by `script/run-tests.ts` on a layer basis. `package.json` exposes four entries: `test:unit` (default dev subset — scans all `test/` subdirectories plus top-level `*.test.ts`, excluding the integration dirs and any `*-e2e.test.ts`), `test:integration` (only the integration directories: server/session/cli/snapshot/project/tool/control-plane/plugin/file/pty/skill/reference/share/mcp/lsp/publish-smoke), `test:e2e` (only `*-e2e.test.ts` files, recursively), and `test:all` (full regression). Use `test:unit` for daily development; when touching integration-dir code, run at least `test:integration`; run `test:all` before commit/merge.
85+
- Test subsets are expanded by `script/run-tests.ts` on a layer basis. `package.json` exposes four entries: `test:unit` (default dev subset — scans all `test/` subdirectories, top-level `*.test.ts`, and the runner's own `script/*.test.ts`, excluding the integration dirs and any file named `*-e2e.test.ts` or `*-integration.test.ts`), `test:integration` (the integration directories plus every `*-integration.test.ts` under `test/` and `script/`: server/session/cli/project/tool/control-plane/plugin/file/pty/skill/reference/share/mcp/lsp/publish-smoke), `test:e2e` (only `*-e2e.test.ts` files under `test/` and `script/`, recursively), and `test:all` (full regression). The unit layer is the fast daily loop: it currently covers roughly 94 files / 1434 tests in the low twenties of seconds. Use `test:unit` for daily development; when touching integration-dir code or a `*-integration.test.ts` file, run at least `test:integration`; run `test:all` before commit/merge.
8686
- e2e files follow the `*-e2e.test.ts` naming convention and are isolated from `test:unit`/`test:integration` via `pathIgnorePatterns` (CLI value overrides bunfig, not merged). They run only under `test:e2e`. Do not move e2e files out of their domain directories.
8787
- New test directories are auto-included in `test:unit` (scan-based). If a directory is integration (real I/O), add its name to the `INTEGRATION_DIRS` constant in `script/run-tests.ts` and keep this file's integration-dir list in sync.
88-
- **The unit layer must stay fast and deterministic.** A unit test must not fork subprocesses (`Process.run`/`spawn`), watch the filesystem, run git, hit the network, or rely on real clocks/`it.live`. Tests that need live OS behavior belong in an integration directory — put the file in the matching `INTEGRATION_DIRS` directory (or add the directory to that constant) so it runs under `test:integration`, not on every unit pass. The one exception: a test that merely needs a temp directory (`tmpdir`/`it.instance`) is still a unit test.
89-
- Cross-package orchestration: from repo root, `bun run test:unit|test:integration|test:e2e` runs the matching layer across all packages via `script/run-tests.ts` (root). Use `--package <name>` to target a single package (e.g. `bun run test:unit --package opencode`).
88+
- **The unit layer must stay fast and deterministic.** A unit test must not fork subprocesses (`Process.run`/`spawn`), watch the filesystem, run git against a real repository, hit the network, or rely on real clocks/`it.live`. Tests that need live OS behavior belong in the integration layer — put the file in the matching `INTEGRATION_DIRS` directory (or add the directory to that constant), or, when moving the file is not practical, name it `*-integration.test.ts`: the unit layer excludes that suffix and `test:integration` includes it explicitly, so it runs on demand rather than on every unit pass. The one exception: a test that merely needs a temp directory (`tmpdir`/`it.instance`) is still a unit test — including the fixture's own throwaway repo (`tmpdir({ git: true })`), whose git commands are pinned to the temp directory.
89+
- Cross-package orchestration: from repo root, `bun run test:unit|test:integration|test:e2e` runs the matching layer across all packages via the root entry `packages/opencode/script/run-tests-root.ts`. Use `--package <name>` to target a single package (e.g. `bun run test:unit --package opencode`).
9090
- Use the built-in tooling for test speedup work: `bun run bench:test` (full-suite benchmark) and `bun run profile:test` (locate slowest test files; narrow with `TEST_PROFILE_GLOB`/`TEST_PROFILE_LIMIT`). A speedup counts only if the target file's median across 3 repeated runs improves — a single full-suite run is noisy and can inflate a file's cost severalfold from mixed-scope contention, so never conclude from it alone.
9191
- Code changes follow TDD: write a failing test first, then implement to make it pass.
9292
- Run tests from `packages/opencode`; never from repo root.

‎packages/opencode/AGENTS.zh-CN.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -42,10 +42,10 @@ description: Main inherited OpenCode engine package for CLI, runtime, config, se
4242
|---|---|---|
4343
| Dev | `bun run dev` | 本地运行 package dev entry |
4444
| Typecheck | `bun typecheck` | 修改 TypeScript 后;不要直接运行 `tsc` |
45-
| Test(默认子集) | `bun run test:unit` | 修改 package behavior 后(只跑快速单元测试,约 60s) |
45+
| Test(默认子集) | `bun run test:unit` | 修改 package behavior 后(只跑快速单元测试,约 25s) |
4646
| Test(重目录集成) | `bun run test:integration` | 修改集成目录相关行为后(目录清单见下方 Testing 一节,以 `INTEGRATION_DIRS` 为准) |
4747
| Test(e2e) | `bun run test:e2e` | 修改真实 provider 链路 / 浏览器 e2e 测试后 |
48-
| Test(全量回归) | `bun run test:all` | 完整回归(等价 `bun test --timeout 30000 --force-exit`) |
48+
| Test(全量回归) | `bun run test:all` | 完整回归(等价 `bun test --timeout 30000 --force-exit --max-concurrency=4`) |
4949
| Build | `bun run build` | 修改 runtime、CLI、package build 或发布相关代码后 |
5050
| Database migration | `bun run db generate --name <slug>` | schema 变化需要生成 migration 时 |
5151

@@ -84,10 +84,11 @@ description: Main inherited OpenCode engine package for CLI, runtime, config, se
8484

8585
## Testing
8686

87-
- 测试子集由 `script/run-tests.ts` 按层展开,`package.json` 提供四个入口:`test:unit`(默认开发子集,扫 `test/` 全部子目录 + 顶层 `*.test.ts`,剔除集成目录与 `*-e2e.test.ts`)、`test:integration`(只跑集成目录:server/session/cli/snapshot/project/tool/control-plane/plugin/file/pty/skill/reference/share/mcp/lsp/publish-smoke)、`test:e2e`(只跑 `*-e2e.test.ts` 文件,递归)、`test:all`(全量回归)。日常开发默认用 `test:unit`;改到集成目录相关代码时至少跑 `test:integration`;提交/合并前跑 `test:all` 回归。
87+
- 测试子集由 `script/run-tests.ts` 按层展开,`package.json` 提供四个入口:`test:unit`(默认开发子集——扫描 `test/` 全部子目录、顶层 `*.test.ts` 以及 runner 自身的 `script/*.test.ts`,剔除集成目录以及任何名为 `*-e2e.test.ts` 或 `*-integration.test.ts` 的文件)、`test:integration`(集成目录加上 `test/` 与 `script/` 下所有 `*-integration.test.ts`:server/session/cli/project/tool/control-plane/plugin/file/pty/skill/reference/share/mcp/lsp/publish-smoke)、`test:e2e`(只跑 `test/` 与 `script/` 下的 `*-e2e.test.ts` 文件,递归)、`test:all`(全量回归)。单元层是快速日常循环:目前覆盖约 94 files / 1434 tests,耗时二十几秒。日常开发用 `test:unit`;改到集成目录相关代码或 `*-integration.test.ts` 文件时,至少跑 `test:integration`;提交/合并前跑 `test:all`。
8888
- e2e 文件遵循 `*-e2e.test.ts` 命名约定,通过 `pathIgnorePatterns` 从 `test:unit`/`test:integration` 隔离(CLI 值覆盖 bunfig,不合并),只在 `test:e2e` 下运行。不要将 e2e 文件移出所属 domain 目录。
8989
- 新增测试目录默认自动纳入 `test:unit`(扫描式);若某目录属于集成(真实 I/O),把目录名加入 `script/run-tests.ts` 的 `INTEGRATION_DIRS` 常量,并在本文件集成目录清单同步。
90-
- 跨包编排:从 repo root 运行 `bun run test:unit|test:integration|test:e2e` 会通过根目录 `script/run-tests.ts` 在所有 package 上跑对应层;用 `--package <name>` 指定单个 package(如 `bun run test:unit --package opencode`)。
90+
- **单元层必须保持快速且确定。** 单元测试不得 fork 子进程(`Process.run`/`spawn`)、监听文件系统、对真实仓库运行 git、访问网络,或依赖真实时钟/`it.live`。需要真实 OS 行为的测试属于集成层——把文件放进匹配的 `INTEGRATION_DIRS` 目录(或把该目录加入该常量),或者在移动文件不现实时,命名为 `*-integration.test.ts`:单元层排除该后缀,`test:integration` 显式纳入它,因此它按需运行而不必每次都跑。唯一例外:只需要临时目录的测试(`tmpdir`/`it.instance`)仍属单元测试——包括夹具自己的临时仓库(`tmpdir({ git: true })`),其 git 命令固定在该临时目录内。
91+
- 跨包编排:从 repo root 运行 `bun run test:unit|test:integration|test:e2e` 会通过根入口 `packages/opencode/script/run-tests-root.ts` 在所有 package 上跑对应层;用 `--package <name>` 指定单个 package(如 `bun run test:unit --package opencode`)。
9192
- 测试提速用现成工具:`bun run bench:test`(全量基准)与 `bun run profile:test`(定位最慢测试文件,`TEST_PROFILE_GLOB`/`TEST_PROFILE_LIMIT` 收窄范围)。判定提速成立以目标文件 3 次重跑的中位数为准——单次全量运行噪声大,混跑时单文件耗时可被放大数倍,不得据此下结论。
9293
- 代码类变更遵循 TDD:先写能失败的测试,再实现代码使其通过。
9394
- 测试从 `packages/opencode` 运行;不要从 repo root 运行测试。

0 commit comments

Comments
 (0)