| name | agentplane-testkit-migration |
| description | Use when migrating Agentplane tests to @agentplane/testkit, replacing local test helpers, fixing testkit export/build failures, splitting large CLI/backend suites, or diagnosing missing testkit dist exports in package builds. |
Agentplane Testkit Migration
Use This Skill When
- A task mentions
@agentplane/testkit, run-cli.test-helpers, shared fixtures, Vitest wrappers, or test helper duplication.
- CI/build fails because
packages/agentplane/src/testing/* cannot import ../../../testkit/dist/*.
- A large test file is being split into scenario-focused suites.
- Tests use local helper clones that should move behind the canonical testkit surface.
Source Of Truth
Prefer exported testkit surfaces over deep imports or local helper copies. Before adding a helper, search for an existing one:
rg -n "tempRepo|mockTaskBackend|mockPrApi|mockConfig|describeWhen|runCliSilent|installRunCliIntegrationHarness" packages/testkit packages/agentplane/src
Migration Steps
- Identify the test family: CLI PR flow, task lifecycle, release/upgrade, runner, recipes, Redmine/backend, or scripts.
- Replace local setup with canonical testkit helpers:
- repository setup:
tempRepo, git helpers, config writers
- backend setup: mock task backend helpers
- GitHub PR setup: mock PR API helpers
- suite gating:
describeWhenEnvPresent, describeWhenNotHook, describeCritical
- Keep compatibility exports in
packages/agentplane/src/testing/index.ts only as a bridge. The canonical implementation belongs in packages/testkit.
- If
agentplane build imports from ../../../testkit/dist/*, ensure @agentplane/testkit is built before agentplane.
- Remove obsolete shims only after
rg proves no imports remain.
Build-Safe Export Checklist
When adding or moving a helper:
- Export it from the package-local module where it is implemented.
- Export it from the public testkit barrel.
- Export compatibility aliases only where existing agentplane tests still depend on them.
- Run both focused tests and package builds.
Common failure:
Module "../testing/index.js" has no exported member ...
Cannot find module "../../../testkit/dist/index.js"
Interpretation: the helper was migrated without a complete export chain, or build order skipped testkit.
Verification
Use focused checks first, then the smallest relevant package build:
bun run --filter=@agentplane/testkit build
bun run --filter=agentplane build
bunx vitest run <focused-test-files>
For known slow PR-flow suites, prefer the recorded single-worker route instead of broad retries.
Boundaries
- Do not introduce general testing style rules here.
- Do not add helper abstractions without at least two current consumers or an immediate build/export need.
- Do not hide fragile setup in testkit if the setup is task-specific and unlikely to recur.
