From 5496c0d5b72984ddc8adc2392fc007ace9039dbe Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Thu, 14 May 2026 11:11:15 +0800 Subject: [PATCH] docs(testing): clarify pnpm proof routing --- .agents/skills/openclaw-testing/SKILL.md | 22 +++++++++++++++++++--- AGENTS.md | 9 ++++++--- CHANGELOG.md | 1 + docs/ci.md | 6 +++++- docs/reference/test.md | 1 + 5 files changed, 32 insertions(+), 7 deletions(-) diff --git a/.agents/skills/openclaw-testing/SKILL.md b/.agents/skills/openclaw-testing/SKILL.md index c120884c2e0c..3c28fb4b794a 100644 --- a/.agents/skills/openclaw-testing/SKILL.md +++ b/.agents/skills/openclaw-testing/SKILL.md @@ -19,9 +19,11 @@ or validating a change without wasting hours. Prove the touched surface first. Do not reflexively run the whole suite. 1. Inspect the diff and classify the touched surface: - - source: `pnpm changed:lanes --json`, then `pnpm check:changed` - - tests only: `pnpm test:changed` - - one failing file: `pnpm test -- --reporter=verbose` + - normal source checkout, source change: `pnpm changed:lanes --json`, then `pnpm check:changed` + - normal source checkout, tests only: `pnpm test:changed` + - normal source checkout, one failing file: `pnpm test -- --reporter=verbose` + - Codex worktree or linked/sparse checkout, one/few explicit files: `node scripts/run-vitest.mjs ` + - Codex worktree or linked/sparse checkout, changed gates or anything broad: `node scripts/crabbox-wrapper.mjs run --provider blacksmith-testbox ... --shell -- "pnpm check:changed"` - workflow-only: `git diff --check`, workflow syntax/lint (`actionlint` when available) - docs-only: `pnpm docs:list`, docs formatter/lint only if docs tooling changed or requested 2. Reproduce narrowly before fixing. @@ -36,6 +38,12 @@ Prove the touched surface first. Do not reflexively run the whole suite. - Prefer GitHub Actions for release/Docker proof when the workflow already has the prepared image and secrets. - Use `scripts/committer "" ` when committing; stage only your files. - If deps are missing, run `pnpm install`, retry once, then report the first actionable error. +- In a Codex worktree or linked/sparse checkout, do not run direct local + `pnpm test*`, `pnpm check*`, `pnpm crabbox:run`, or `scripts/committer` until + you have verified pnpm will not reconcile or reinstall dependencies. Use + `node scripts/run-vitest.mjs` for tiny local proof, `node + scripts/crabbox-wrapper.mjs` for Testbox, and `git commit --no-verify` only + after the relevant remote or node-wrapper proof is already clean. - For Blacksmith Testbox proof, use Crabbox first. `pnpm crabbox:run -- --provider blacksmith-testbox --timing-json -- ` warms, claims, syncs, runs, reports, and cleans up one-shot boxes. Reuse only an id/slug created in this @@ -55,6 +63,14 @@ OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test Use targeted file paths whenever possible. Avoid raw `vitest`; use the repo `pnpm test` wrapper so project routing, workers, and setup stay correct. +When the checkout is a Codex worktree, prefer the direct node harness instead: + +```bash +node scripts/run-vitest.mjs +``` + +That keeps the test scoped without giving pnpm a chance to run dependency +status checks or install reconciliation in a linked worktree. ## Command Semantics diff --git a/AGENTS.md b/AGENTS.md index 34d17dd4734a..50d3499d1909 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -47,8 +47,10 @@ Skills own workflows; root owns hard policy and routing. - Package manager/runtime: repo defaults only. No swaps without approval. - Install: `pnpm install` (keep Bun lock/patches aligned if touched). - CLI: `pnpm openclaw ...` or `pnpm dev`; build: `pnpm build`. -- Tests: `pnpm test [vitest args...]`, `pnpm test:changed`, `pnpm test:serial`, `pnpm test:coverage`; never raw `vitest`. -- Checks: `pnpm check:changed`; lanes: `pnpm changed:lanes --json`; staged: `pnpm check:changed --staged`; full: `pnpm check`. +- Tests in a normal source checkout: `pnpm test [vitest args...]`, `pnpm test:changed`, `pnpm test:serial`, `pnpm test:coverage`; never raw `vitest`. +- Tests in a Codex worktree or linked/sparse checkout: avoid direct local `pnpm test*`; use `node scripts/run-vitest.mjs ` for tiny explicit-file proof, or Crabbox/Testbox for anything broader. +- Checks in a normal source checkout: `pnpm check:changed`; lanes: `pnpm changed:lanes --json`; staged: `pnpm check:changed --staged`; full: `pnpm check`. +- Checks in a Codex worktree or linked/sparse checkout: avoid direct local `pnpm check*`; use `node scripts/crabbox-wrapper.mjs run ... --shell -- "pnpm check:changed"` so pnpm runs inside Testbox, not locally. - Extension tests: `pnpm test:extensions`, `pnpm test extensions`, `pnpm test extensions/`. - Typecheck: `tsgo` lanes only (`pnpm tsgo*`, `pnpm check:test-types`); never add `tsc --noEmit`, `typecheck`, `check:types`. - Formatting: `oxfmt`, not Prettier. Use repo wrappers (`pnpm format:*`, `pnpm lint:*`, `scripts/run-oxlint.mjs`). @@ -57,7 +59,8 @@ Skills own workflows; root owns hard policy and routing. ## Validation - Use `$openclaw-testing` for test/CI choice and `$crabbox` for remote/full/E2E proof. -- Small/narrow tests, lints, format checks, and type probes are fine locally. +- Small/narrow tests, lints, format checks, and type probes are fine locally only in a healthy normal checkout. +- In Codex worktrees, direct local `pnpm test*`, `pnpm check*`, `pnpm crabbox:run`, and `scripts/committer` can trigger pnpm dependency reconciliation or install prompts. Prefer `node` wrappers locally and Crabbox/Testbox for pnpm-gated proof. - Full suites, broad changed gates, Docker/package/E2E/live/cross-OS proof, or anything that bogs down the Mac: Crabbox/Testbox. - One/few files local. If a local command fans out, stop and move broad proof to Crabbox/Testbox. - Before handoff/push: prove touched surface. Before landing to `main`: issue proof plus appropriate full/broad proof unless scope is clearly narrow. diff --git a/CHANGELOG.md b/CHANGELOG.md index 1e09d86766f2..d9d73a67496d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,7 @@ Docs: https://docs.openclaw.ai ### Fixes - Control UI/chat: reconcile terminal and reconnect run cleanup with cached session activity, stale compaction/fallback indicators, and a compact composer run-status chip so completed or interrupted turns do not leave Stop active. Fixes #76874 and #64220; refs #71630. Thanks @BunsDev. +- Maintainer tooling: clarify which pnpm test/check commands are safe locally versus inside Codex worktrees, routing linked-worktree gates through node wrappers and Crabbox/Testbox. - iOS/chat: resize PhotosPicker image attachments to capped JPEGs before staging and sending, stripping source metadata and keeping oversized camera photos under the chat upload budget. Fixes #68524. Thanks @BunsDev. - Codex harness: classify native app-server token-refresh logout and relogin failures as authentication refresh errors, so users get re-authentication guidance instead of a raw runtime failure. - Codex startup: treat selectable configured OpenAI agent models as Codex runtime requirements during plugin auto-enable, startup planning, and doctor install repair, so Anthropic-primary configs can still switch to OpenAI/Codex cleanly. diff --git a/docs/ci.md b/docs/ci.md index 996d125f7e82..5274d757600d 100644 --- a/docs/ci.md +++ b/docs/ci.md @@ -517,7 +517,11 @@ Before a first run, check the wrapper from the repo root: pnpm crabbox:run -- --help | sed -n '1,120p' ``` -The repo wrapper refuses a stale Crabbox binary that does not advertise `blacksmith-testbox`. Pass the provider explicitly even though `.crabbox.yaml` has owned-cloud defaults. +The repo wrapper refuses a stale Crabbox binary that does not advertise `blacksmith-testbox`. Pass the provider explicitly even though `.crabbox.yaml` has owned-cloud defaults. In Codex worktrees or linked/sparse checkouts, avoid the local `pnpm crabbox:run` script because pnpm may reconcile dependencies before Crabbox starts; invoke the node wrapper directly instead: + +```bash +node scripts/crabbox-wrapper.mjs run --provider blacksmith-testbox --timing-json --shell -- "pnpm test " +``` Changed gate: diff --git a/docs/reference/test.md b/docs/reference/test.md index 08f37ec5b542..017e2d959acc 100644 --- a/docs/reference/test.md +++ b/docs/reference/test.md @@ -15,6 +15,7 @@ title: "Tests" - `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`: explicit broad changed test run. Use it when a test harness/config/package edit should fall back to Vitest's broader changed-test behavior. - `pnpm changed:lanes`: shows the architectural lanes triggered by the diff against `origin/main`. - `pnpm check:changed`: runs the smart changed check gate for the diff against `origin/main`. It runs typecheck, lint, and guard commands for the affected architectural lanes, but does not run Vitest tests. Use `pnpm test:changed` or explicit `pnpm test ` for test proof. +- Codex worktrees and linked/sparse checkouts: avoid direct local `pnpm test*`, `pnpm check*`, and `pnpm crabbox:run` unless you have verified pnpm will not reconcile dependencies. For tiny explicit-file proof use `node scripts/run-vitest.mjs `; for changed gates or broad proof use `node scripts/crabbox-wrapper.mjs run --provider blacksmith-testbox ... --shell -- "pnpm check:changed"` so pnpm runs inside Testbox. - `OPENCLAW_HEAVY_CHECK_LOCK_SCOPE=worktree `: keeps heavy-check serialization inside the current worktree instead of the Git common dir for commands such as `pnpm check:changed` and targeted `pnpm test ...`. Use it only on high-capacity local hosts when you intentionally run independent checks across linked worktrees. - `pnpm test`: routes explicit file/directory targets through scoped Vitest lanes. Untargeted runs use fixed shard groups and expand to leaf configs for local parallel execution; the extension group always expands to the per-extension shard configs instead of one giant root-project process. - Test wrapper runs end with a short `[test] passed|failed|skipped ... in ...` summary. Vitest's own duration line stays the per-shard detail.