agentplane-testkit-migration

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

1. Identify the test family: CLI PR flow, task lifecycle, release/upgrade, runner, recipes, Redmine/backend, or scripts.
2. 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
3. Keep compatibility exports in packages/agentplane/src/testing/index.ts only as a bridge. The canonical implementation belongs in packages/testkit.
4. If agentplane build imports from ../../../testkit/dist/*, ensure @agentplane/testkit is built before agentplane.
5. Remove obsolete shims only after rg proves no imports remain.

Build-Safe Export Checklist

When adding or moving a helper:

1. Export it from the package-local module where it is implemented.
2. Export it from the public testkit barrel.
3. Export compatibility aliases only where existing agentplane tests still depend on them.
4. 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.