Imported from testchimphq/testchimp-skills (SKILL.md). Install upstream with npx skills add testchimphq/testchimp-skills. Copyright stays with the author.

TestChimp

TestChimp runs pre-defined QA workflows. references/ details how each workflow should be executed (battle-tested playbooks). Policies under plans/knowledge/policies/*.policy.md define custom project-specific instructions on top of those playbooks. Workflows can be triggered from a local coding agent (this skill) or via cloud agents on SDLC triggers. When a policy is missing, plans/knowledge/ai-test-instructions.md remains the fallback.

Routing — load the right reference first

ChimpHands on CI (P0 — do not skip): If you are ChimpHands running on GitHub Actions, read and follow references/chimphands.md before any file edits and references/chimphands-ci-runner.md before compile/container/test installs. Hard rules there: (1) create a testchimp-* agent branch from the base branch — never work on main/master or commit on the base branch; (2) commit and push at the end of every agent turn that left a dirty worktree (plan files included); (3) report-branch after the agent branch is on the remote; (4) scoped git fetch + disk hygiene on the runner. Interactive chat is still the default — GHA / CLOUD_AGENT does not mean --mode=non-interactive. Auth self-heal: testchimp chimphands refresh-git-auth — never ask the user for a GitHub token.

Plan → approve → execute → report (all workflows): Every catalog workflow follows Analyze/Plan → seek approval → Execute the approved plan → Report workflow execution. Persist each run’s plan under plans/knowledge/workflow_plans/<workflow-id>/<workflow_execution_id>.plan.md, then upsert-plans-support-file (blocking before Execute). Always write the plan file on disk in the mapped plans tree first, then upsert that same content — platform upsert alone is not enough (ChimpHands Files changed and git review need the local file). Explicit user approval is required unless the prompt sets --mode=non-interactive or the resolved policy explicitly permits non-interactive execution. Never treat a run as done without closing via report-agent-action ACTION_COMPLETED / ACTION_FAILED (or equivalent inline agentTraceability mutations plus the completion RAA) — plan upsert alone does not create a platform workflow execution. Full contract: Workflow execution plans and references/policies-and-traceability.md.

author-plans nuance: Gap / multi-artifact runs use the meta plan gate above. When the prompt already names an existing US-<n> / TS-<n>, skip the meta plan and write up that file directly — see references/author-plans.md#scoped-write-up-named-ordinal.

Prompt args — --mode: If the user/trigger prompt includes --mode=non-interactive (also accept --mode non-interactive / mode=non-interactive), treat approval as automatic: still write + upsert the plan first, set PlanApproved: yes and ApprovedBy: auto, do not wait for chat approval, Execute immediately, then open a PR with the changes. Details: references/policies-and-traceability.md#execution-mode--mode-prompt-arg.

Routine decisions: Before Plan/Execute, check references/agent-quick-answers.md. When a step matches (ULID mint, plan path, branch/PR, MCP vs CLI, runner env, git SHA for plans, workflow-id mapping), use the listed answer — do not re-derive the mechanics. ChimpHands branch/commit contract: references/chimphands.md. ChimpHands CI/auth issues: references/chimphands-faq.md.

Scoping (all workflows): If the prompt has Base branch: <name> (legacy: Working branch:; cloud/automation), treat it as the parent branch — check it out, then create a testchimp-* agent branch before editing. Then: explicit scope if given → else feature/PR branch = changes on the agent branch → else default branch = changes since last run of the same workflow (get-last-run-workflow-detail), or ask the user how far back to look (non-interactive: use last-run / recent commits without asking). For implement on the default branch, create a new testchimp-* feature branch before coding. Full rule: references/policies-and-traceability.md#scoping-overarching--all-workflows. On ChimpHands CI, the session branch rules in references/chimphands.md override “stay on default.”

TestChimp is a QA workflow orchestration layer for AI agents. It provides:

• Setup QA infra - sets up opinionated, enterprise-grade QA infra including CI setup, test-only seed / teardown / read endpoints, mocking strategy (Playwright page.route for HTTP/API; optional AIMock for LLM), TrueCoverage instrumentation, per-PR environment provisioning. Fixtures (barrels per scaffold — references/project-types-and-scaffolds.md) are introduced during /testchimp test as needed—see references/fixture-usage.md.

• Requirement traceability via Playwright annotation on tests (e.g. { type: 'scenario', description: '#TS-101' }) linking SmartTests to scenarios. One test may include multiple scenario annotations in the same annotation array when it covers several scenarios—see references/write-smarttests.md. Do not author deprecated // @Scenario: comments. Suite grouping uses Playwright tag (e.g. tag: '@smoke') from global.policy.md → tags: so the CLI can filter (npx playwright test --grep @smoke) — never { type: 'group' } annotations.

• Markdown test plans in a mapped plans/ folder (YAML frontmatter, stories/ / scenarios/ / knowledge/) — how to read and author them in references/author-plans.md.

• Intelligent Playwright steps (ai.act / ai.verify / ai.extract with ai-wright) on web for more stable execution-time intelligent behavior — not available for native mobile (Mobilewright) yet; see references/mobilewright-smarttests.md.

• Execution reporting via @testchimp/playwright (≥ 0.2.25 for TESTCHIMP_EXECUTION_SOURCE + [TestChimp] Batch invocation view: URL, ≥ 0.2.20 for smart-smoke selection/skip + Playwright scenario annotations on execution reports, and ≥ 0.2.0 for per-run device context: web/ios/android platform, device family, OS, resolution, orientation) so runs feed TestChimp for per-platform requirement coverage and scenario execution history (CLI/MCP: optional platform on coverage; scenarioId + dimension filters on execution history — references/cli.md).

• Fixtures + seed/read APIs - Fixture barrels (fixtures/, api/fixtures/, mobile/fixtures/, web/fixtures/) and shared/ seed helpers call seed, teardown, and read endpoints per references/seeding-endpoints.md. Layout: references/project-types-and-scaffolds.md. Patterns: references/fixture-usage.md.

• TrueCoverage - feedback loop for test coverage aligned with real user behaviour insights from production: @testchimp/rum-js on web; TestChimpRum (Swift / Kotlin) on iOS and Android, with @testchimp/playwright attaching test identity via installTestChimp (web: page; mobile: uiFixture: 'screen' + Mobilewright projects[].use.platform), and (on mobile) device-fixture automation URLs + in-app URL forwarding. See references/instrument-truecoverage.md. Default: opted-in unless plans/knowledge/ai-test-instructions.md explicitly records a TrueCoverage opt-out under ### TrueCoverage Plan.

• Performance testing (k6) — policy-backed init-perf, create-perf-tests, run-perf-tests, and upkeep-perf workflows under the SmartTests root, plus one-off import-perf-tests to bring existing Locust/k6/JMeter/etc. suites into k6/ (scenario links, tagging). Journeys link real scenario ordinals; composites require explicit membership approval. Load = N concurrent users completing the journey (ramping-vus from a low start + thinkTime(), not a tight request loop). Volume = few users against a large dataset — one k6 run per volume journey that holds 1 VU at 10% / 50% / 100% seeded cardinality and emits volume_size. Execute with k6/scripts/run.sh (paths relative to k6/; --impacted uses plans/smart-smoke/<branch>/related-perf-tests.json). k6/scripts/prepare.sh always fetches npm @testchimp/k6 latest — never pin K6_REPORTER_VERSION. Identify volume-sensitive scenarios during create-perf-tests planning and confirm with the user. REAL E2E interaction evidence is redacted; TrueCoverage supplies relative demand only—never TC-derived absolute VUs/RPS/duration/data size. External deps: identify SUT outbound systems, mock them in the perf harness, and respond with realistic latencies (never default to live calls or 0 ms stubs — false confidence). See references/perf-testing.md.

• ExploreChimp (UX analytics on UI journeys) — With EXPLORECHIMP_ENABLED and the markScreenState fixture, runs send DOM, screenshot, console, network, and metrics checkpoints to TestChimp so agents can surface UX issues (performance, layout, visual, usability, accessibility, and related signals) along the same pathways as SmartTests. Pure API-only automation is out of scope. For local / agent-driven runs (no CI branch env), set TESTCHIMP_BRANCH_NAME to the current git branch so the reporter sends branchName and the server can resolve branch_id on explorations and bugs. P0: honor the SmartTests config reporters (never CLI --reporter) and confirm each ExploreChimp batch reaches COMPLETED_EXPLORATION before closing the workflow — references/run-explorechimp.md. Workflow: references/run-explorechimp.md; command alias /testchimp explore. In /testchimp test, Phase 5: Smart smoke runs after Phase 4: Validate (impact analysis → plans/smart-smoke/<branch>/related-tests.json, then related-tests-only or budgeted smoke via TESTCHIMP_SMART_SMOKE_ENABLED — references/run-smart-smoke.md). Phase 6: ExploreChimp is default-on when the PR/plan scope includes new or materially changed UI SmartTests (real UI; markScreenState in use or planned once stable—especially new screen-states). The branch plan records yes or documented N/A (same user approval window as the rest of the plan); N/A is the exception (e.g. API-only change, no UI journey, user declined cost)—see references/run-qa.md. In /testchimp evolve, ExploreChimp stays plan-gated on TrueCoverage-prioritized UI slices (references/upkeep.md).

Preamble (run first)

Run this once at the start of any TestChimp flow. It will:

• Flag if your installed skill is outdated (git-based; canonical)
• Probe nearby MCP config for TESTCHIMP_API_KEY (without printing it) — does not prove the Playwright/Mobilewright child has the key; see Preamble checks #4

_TC_PRE=$(
  ~/.cursor/skills/testchimp/bin/testchimp-preamble-check 2>/dev/null \
  || ~/.claude/skills/testchimp/bin/testchimp-preamble-check 2>/dev/null \
  || .cursor/skills/testchimp/bin/testchimp-preamble-check 2>/dev/null \
  || .claude/skills/testchimp/bin/testchimp-preamble-check 2>/dev/null \
  || true
)
[ -n "$_TC_PRE" ] && echo "$_TC_PRE" || true

If the preamble script cannot be run (or prints nothing), the agent MUST manually validate Preamble checks items 1 (skill version) and 4 (TESTCHIMP_API_KEY / runner — full rules there).

Preamble checks (run first)

Before executing a TestChimp flow:

1. Skill update check — rely on the version in this file's frontmatter. Read the current version from the local SKILL.md, then fetch the remote SKILL.md from the published repo (https://github.com/testchimphq/testchimp-skills, see Updating this skill from Git below) and compare frontmatter versions. If the remote version is newer, tell the user an update is available and ask whether to update now (/testchimp skill upgrade / synonym /testchimp update). Major gate (advise, do not hard-stop): If remote ≥ 1.0.0 and local < 1.0.0, strongly advise upgrading now — skill 1.0.0 introduces policy-backed workflows (plans/knowledge/policies/). Do not refuse to continue if the user declines; proceed with a clear warning that policy/traceability tooling may be missing. If the user agrees, proceed with the update as noted below.

2. Decision memory check (project scope only) — locate plans/knowledge/policies/ (especially connect-to-test-env.policy.md, global.policy.md, and other *.policy.md) and, only if present, /plans/knowledge/ai-test-instructions.md. Prefer workflow policies when present. Environment strategy lives in connect-to-test-env.policy.md — if that policy is missing, recommend /testchimp project init or /testchimp create policy connect-to-test-env (do not tell the user to create ai-test-instructions.md for env connectivity). Treat existing ai-test-instructions.md as a legacy fallback for project decisions not yet migrated to policies (TrueCoverage choices, Mocking Plan, ## ExploreChimp, old Environment Provision Strategy). Also read plans/knowledge/policies/global.policy.md when present (suite coverage goals, prioritization signals, suite size constraints, and ## Test suite management → tags: for Playwright suite tags such as @smoke/@regression) — in addition to per-workflow *.policy.md files. When authoring or updating SmartTests (run-qa, create-tests, upkeep, nested authorship), apply those tags per each entry’s instructions (tag: '@smoke') — references/write-smarttests.md §6b and references/policies-and-traceability.md#global-policy--suite-tags-required-when-authoring-tests. Use Playwright annotations only for scenario linking ({ type: 'scenario', description: '#TS-…' }). Do not use annotation type group for smoke/regression — Playwright CLI cannot filter by annotations. Seed default: assets/policies/global.policy.md. TrueCoverage default: unless ai-test-instructions.md (when present) explicitly states that TrueCoverage is opted out (under ### TrueCoverage Plan or an equally clear project-level statement), treat TrueCoverage as opted in—plan instrumentation, RUM wiring, and plans/events/ work accordingly; do not skip TrueCoverage merely because the section is empty or says “deferred.” Do not infer workstation readiness from decision files: each developer still needs local MCP registration and a canonical key in MCP env — with #4 satisfied before any Playwright/Mobilewright run (see /testchimp init → Workstation gate in references/init-testchimp.md).

3. MCP-first access to TestChimp (BLOCKING) — without TestChimp API access, the agent cannot fetch coverage, execution history, environments, or create/update stories/scenarios.

   • Preference order (critical):
     1. Use MCP tools first (preferred): the MCP server process has the key in its env block.
     2. If MCP is unresponsive (agent bridge issues, tool timeouts), fallback to CLI only after #4 (same key in the shell that runs testchimp …).
   • Never print secrets: do not paste the key into chat, logs, or echoed commands.
   • Playwright / Mobilewright / CI: MCP env alone is not enough for the test runner — still apply #4 before spawning the runner.

4. TESTCHIMP_API_KEY + backend / ingress URLs (P0 — MCP, CLI, and runners) — Any process that runs Playwright or Mobilewright with @testchimp/playwright, or testchimp CLI against the project APIs, must have TESTCHIMP_API_KEY in that process’s environment. IDE-only or MCP-only config does not satisfy the child test runner or a CLI fallback shell. If you cannot verify the key is set on the process before spawn, halt — do not run tests “to see what happens.”

   • Resolve (never print secrets): Find a project MCP JSON that contains a TestChimp server entry (see Finding project MCP config). Prefer SmartTests root ( .testchimp-tests ) → walk up checking candidate paths at each directory; if none, search the git repo for mcp.json / .mcp.json files whose mcpServers include testchimp (or whose args include @testchimp/cli). Then read that entry’s env and export / inject all of:
     1. TESTCHIMP_API_KEY (required) — if the value is a placeholder like ${TESTCHIMP_API_KEY} / $TESTCHIMP_API_KEY, resolve from the current process environment or host secret store (never print)
     2. TESTCHIMP_BACKEND_URL when present in that env block (staging, enterprise, or self-hosted featureservice base URL — used by CLI / MCP / ai-wright)
     3. TESTCHIMP_INGRESS_URL when present in that env block (staging / enterprise ingress host — used by @testchimp/playwright CI ingest and RUM emit overrides). Parallel to TESTCHIMP_BACKEND_URL in mcp.json.
     4. TESTCHIMP_PROJECT_ID when present (TrueCoverage RUM projectId if not already in app config — references/instrument-truecoverage.md)
   • TESTCHIMP_EXECUTION_SOURCE (P0 — runner spawn, not from MCP env): Compute and export on every Playwright / Mobilewright process. Do not look for this key in MCP JSON. Skill never exports CI. Set CLOUD_AGENT only for a remote agent host: GITHUB_ACTIONS, CURSOR_AGENT_WORKER_ID (Cursor cloud worker), or Copilot platform (COPILOT_USE_PLATFORM / COPILOT_WORKSPACE). CURSOR_AGENT alone is the local Cursor IDE — use LOCAL_AGENT (same for Claude Code, Codex, OpenHands on the developer machine). True pipelines (testrunner / GHA workflows that are not this skill) set CI themselves. See references/policies-and-traceability.md#execution-source-local_agent--cloud_agent.
   • Host split: CLI/MCP → TESTCHIMP_BACKEND_URL (featureservice). Playwright reporter CI ingest → TESTCHIMP_INGRESS_URL when set; otherwise @testchimp/playwright rewrites SaaS featureservice*.testchimp.io → matching ingress*.testchimp.io, or defaults to https://ingress.testchimp.io.
   • TESTCHIMP_BACKEND_URL (enterprise / non-prod — BLOCKING when configured): If MCP env defines TESTCHIMP_BACKEND_URL, the agent MUST export it into every CLI / runner shell before the first testchimp … or Playwright spawn. Do not call the SaaS/prod default host when a project-specific backend is configured — keys are environment-scoped and a prod call with a staging/enterprise key returns 401. Only omit / leave unset when the MCP config has no TESTCHIMP_BACKEND_URL (then the CLI/MCP package default prod host is correct).
   • TESTCHIMP_INGRESS_URL (when configured): Export into every Playwright / Mobilewright runner shell alongside the API key. Prefer this over relying solely on featureservice→ingress rewrite.
   • Missing / blank / placeholder API key: STOP; during /testchimp init, create or merge the project MCP file from assets/sample-mcp.json (see Workstation gate), ask the user to paste API key + project ID (and backend/ingress URLs when not using SaaS prod), reload MCP, then re-export for the runner. For cloud / CI agents, inject TESTCHIMP_API_KEY from GitHub Actions secrets (or the host’s secret store) into the MCP env / job environment — see Setting up cloud agents.
   • On 401 / unauthorized (checklist — do in order):
     1. Re-read project MCP env and confirm TESTCHIMP_BACKEND_URL / TESTCHIMP_INGRESS_URL were exported into this shell when configured (wrong host is the most common agent failure mode).
     2. Confirm TESTCHIMP_API_KEY from the same MCP entry is exported (not blank/placeholder; never print it).
     3. Re-run the failing CLI/MCP call; if still 401, ask the user to verify the key for that backend (staging vs prod vs enterprise).
   • Symptoms (same fix): reporter disabled, 401, missing-key logs → re-apply #4 (key and backend/ingress URLs) on the runner/CLI env, then re-run.
   • Honor config reporters (P0): Never pass Playwright/Mobilewright CLI --reporter / -r — it replaces config reporters and drops @testchimp/playwright/reporter (execution ingest + ExploreChimp exploration_end). Full rule: references/run-explorechimp.md#honor-playwright-config-reporters-p0 and references/run-qa.md non-negotiables.
   • Never print the key. No key-rotation noise unless leaked or committed.
   • Not in .env-QA / .env-* (those are for BASE_URL, fixtures, etc.); canonical copy in MCP env per assets/sample-mcp.json (cloud/CI shape: assets/sample-mcp.cloud.json).

5. TestChimp CLI / MCP client compatibility check — read required_cli_version from this file's frontmatter (semver). Run npm view @testchimp/cli version and treat the result as registry latest. Find the project's MCP server config (see Finding project MCP config) and locate the server entry whose args include @testchimp/cli (often the server name testchimp), typically ["-y", "@testchimp/cli@latest", "mcp"].

   • If args use @testchimp/cli@latest or @testchimp/cli with no @ version suffix, treat the effective runtime version as registry latest (because npx -y will resolve @latest on each run).
   • If args use an explicit @testchimp/cli@x.y.z, parse x.y.z as the configured version.
   • Pass if the effective configured version is >= required_cli_version (semver). Pass if registry latest is >= required_cli_version when using @latest or an unpinned package name.
   • Corrective action when the pinned semver or registry latest is below required_cli_version: Update args to ["-y", "@testchimp/cli@latest", "mcp"] (see assets/sample-mcp.json), or pin to at least required_cli_version. Preserve env.TESTCHIMP_API_KEY. Tell the user to reload MCP / restart the IDE so the new command line applies.
   • If no project MCP config is present yet, during /testchimp init create or merge it from assets/sample-mcp.json (other flows: point the user to init or the Workstation gate).

6. Playwright / Mobilewright toolchain check — Web: TestChimp requires Playwright 1.59.0+. Before authoring SmartTests, running npx playwright test, or doing browser-driven exploration for /testchimp init smoke, ensure the repo has a compliant install (#4 before any such run):

   • Resolve the install root: from the SmartTests root (see Marker files), walk up until you find the package.json that declares @playwright/test (often a parent such as ui/ in a monorepo). That directory is where npm install / npm ci must succeed for Playwright to be runnable.
   • If node_modules is missing or npx playwright --version fails, run the repo’s install (npm install, npm ci, or documented workspace install) at that install root first. Do not treat missing node_modules as “optional”; without install, Playwright-based steps cannot be validated.
   • Verify the resolved @playwright/test version is >= 1.59.0, and that playwright (browser package) matches @playwright/test (same line as references/write-smarttests.md). Use e.g. npm ls @playwright/test --prefix <install-root> or npx playwright --version with cwd at the install root.
   • Corrective action if below minimum or version mismatch: bump @playwright/test and playwright together, reinstall, then npx playwright install for browsers if needed. If the environment cannot run install commands, tell the user to install dependencies and re-run; do not silently author tests that were never executed against a real runner.
   • Mobile / multi-platform (project_type=mobile|multi-platform in .testchimp-tests; legacy ios/android → mobile): ensure mobilewright and @mobilewright/test are installed and same version; run npx mobilewright doctor when setup is unclear (references/mobilewright-smarttests.md, references/project-types-and-scaffolds.md).

7. RUM client libraries (TrueCoverage) — latest vs installed (required when RUM is in scope) — Whenever TrueCoverage is in scope (see #2) or the task adds, upgrades, or validates RUM / session instrumentation, the agent MUST look up the latest published RUM library for the relevant platform and confirm the project has a correct, up-to-date install. Do not assume an existing dependency pin is current without checking the registry or upstream tags.

   • Latest sources (prefer network once per flow):
     • Web: npm view @testchimp/rum-js version → npm latest for @testchimp/rum-js.
     • iOS: Newest SemVer tag on https://github.com/testchimphq/testchimp-rum-ios (e.g. GitHub Tags / git ls-remote --tags on that repo). SwiftPM consumers use .package(url:…, from: "x.y.z") or an equivalent Xcode rule — compare to that tag.
     • Android: Newest SemVer tag on https://github.com/testchimphq/testchimp-rum-android; JitPack artifact com.github.testchimphq:testchimp-rum-android:<tag> — compare to build.gradle(.kts) / version catalog.
   • Verify in repo: Locate the real consumer manifest (package.json / lockfile for web; Package.swift or Xcode SPM for iOS; Gradle for Android). Confirm the declared version is present, resolved, and ≥ latest (semver). If the project intentionally stays below latest, add a one-line justification to the branch plan or plans/knowledge/ai-test-instructions.md FAQ; default is to bump to latest and reinstall.
   • Corrective action: Update the dependency, then npm install / npm ci (web), File → Packages → Resolve or CLI resolve (iOS), Gradle sync (Android). Re-validate init / initialize and automation URL wiring per references/instrument-truecoverage.md.
   • If npm/GitHub is unreachable, state that explicitly, use the lockfile or last-known tag as fallback, and tell the user to confirm against npm / tags when online.
   • Omit this check only when #2 records an explicit TrueCoverage opt-out and the task does not touch application RUM code.

8. @testchimp/playwright plugin — latest vs installed (required on create-tests / run-qa / upkeep) — playwright.config / Mobilewright config references the package by name (@testchimp/playwright/reporter); the installed version comes from the consumer package.json + lockfile. Publishing a new plugin on npm does not auto-upgrade client CI. On /testchimp create tests, /testchimp run QA / test, and /testchimp upkeep / evolve, agents MUST bring the install up to registry latest before authoring or running SmartTests (full procedure: references/create-tests.md → @testchimp/playwright upgrade).

   • Latest: npm view @testchimp/playwright version.
   • Install root: same as #6 — package.json that declares @playwright/test (and/or @testchimp/playwright).
   • Verify: npm ls @testchimp/playwright --prefix <install-root> (or lockfile resolved version) ≥ registry latest.
   • Corrective action when behind: at the install root, run npm install @testchimp/playwright@latest (preferred over bare npm update, which only moves within an existing semver range). Commit package.json + lockfile with the workflow’s other changes so CI npm ci picks up the bump.
   • Already current: mark the workflow checklist item done with the version; do not reinstall needlessly.
   • Nested create-tests under run-qa / upkeep: if the parent already completed this bump for the same workflow_execution_id, skip and note that.
   • If npm is unreachable, record that on the plan and continue on the lockfile version; tell the user to confirm when online.
   • Do not change reporter config paths solely for a version bump unless a release note requires it.

9. Headed authoring default (interactive) — when the agent is authoring or debugging SmartTests for /testchimp test, default to headed runs so the user can watch and optionally intervene:

   • Prefer npx playwright test --headed --debug during authoring/debug sessions.
   • Use headless runs once the test is stable (or when the user explicitly asks for headless/CI mode).

Finding project MCP config (TestChimp)

Locate a JSON file that registers the TestChimp MCP server. Do not assume a single path — hosts differ, and cloud agent repos often commit a generic mcp.json.

Example candidate paths (check in order from SmartTests root upward, then repo root):

1. <project dir>/.testchimp/mcp.json (TestChimp Studio / LOCAL_DESKTOP — prefer this when present; gitignored credentials)
2. <project dir>/.cursor/mcp.json
3. <project dir>/.mcp.json
4. <project dir>/mcp.json
5. <project dir>/.vscode/mcp.json (when present)
6. <project dir>/.github/mcp.json (when present)

At each ancestor directory from .testchimp-tests up to the git root, check for mcp.json. Accept the first file whose JSON has mcpServers.testchimp or any mcpServers entry whose args array includes a string containing @testchimp/cli.

If walk-up finds nothing: from the git root, search for files named mcp.json or .mcp.json (limit to a shallow find; skip node_modules, .git). Prefer a hit that contains TestChimp as above. Also accept .testchimp/mcp.json in that search.

Cloud / CI: The committed file may use ${TESTCHIMP_API_KEY} (or $TESTCHIMP_API_KEY) as the env value — see assets/sample-mcp.cloud.json. Treat that as “read from process env / host secrets,” not as a missing key—if the process env already has a non-placeholder TESTCHIMP_API_KEY, export that for runners. Hosts such as Cursor Cloud dashboard MCP, Copilot COPILOT_MCP_* secrets, Claude Code Action inline --mcp-config, and OpenHands MCP settings may inject the real key without rewriting the file.

TestChimp Studio (LOCAL_DESKTOP): When running in Studio or against a Studio-mapped folder, follow references/local-desktop-studio.md — shared worktree across threads, prefer Playwright CLI (not Playwright MCP by default), do not install GHA ChimpHands workflows for local runs.

How TestChimp works

1. Create a project in TestChimp and connect the Git repo. Map 2 folders in the repo to the project created in TestChimp platform tests (SmartTests) and plans (test plans). Those can be mapped after logging in to TestChimp -> Select Project -> Project Settings -> Integrations -> GitHub. Recommended: keep those folders in the same repo as the product code. Separation (plans/tests-only mapped repo + product elsewhere) is supported when you want it — see Split-repo / multi-root workspaces and references/split-repo-workspaces.md.
2. Run SmartTests with Playwright (web) or Mobilewright (native mobile — project_type in .testchimp-tests); install @testchimp/playwright as documented in references/write-smarttests.md. On web, dependencies typically include ai-wright for intelligent steps; mobile does not use ai-wright yet (references/mobilewright-smarttests.md).
3. Local and CI calls use the project’s TESTCHIMP_API_KEY — scope per project; placement and runner rules: Preamble checks #4.

Marker files

TestChimp adds marker files after mapping: .testchimp-tests at the SmartTests root (platform tests) and .testchimp-plans at the plans root (platform plans). On-disk folder names may differ (e.g. ui_tests, plans).

project_type: .testchimp-tests → web, mobile, or multi-platform (canonical layouts in references/project-types-and-scaffolds.md). Empty or omitted → web. Legacy ios/android → treat as mobile. Run platform for @testchimp/playwright comes from Mobilewright projects[].use.platform (ios/android); omit for web/API. Use installTestChimp(base, { uiFixture: 'screen' }) in mobile/fixtures/index.js; api/fixtures and web/fixtures use default page.

Finding them: Markers are dotfiles; workspace Glob may omit them, so an empty Glob search does not prove they are missing. From the repo (or workspace) root, use the terminal—e.g. find . -name '.testchimp-*', or ls -a in a candidate folder next to package.json or plans/.

Using SmartTests root: The directory that contains .testchimp-tests is the SmartTests root—use it for the API key walk-up (Preamble #4), Playwright install resolution (#6), and every npx playwright … run (Agent guardrails).

If markers are missing after mapping: Confirm sync PRs from the TestChimp platform were raised and merged for each mapped folder and the local workspace was updated (e.g. git pull)—see references/init-testchimp.md (Key Area 1 and Action item A).

Split-repo / multi-root workspaces

Recommended: put plans/ and tests/ in the same repo as the product. The split layout below is only for teams that want separation.

Optional layout: a TestChimp-mapped repo that is mostly plans/ + tests/, with product code in other workspace roots. Local agents should open a multi-root workspace (product folder(s) + mapped repo), read product roots for context, and write plans/tests only under the marked roots. Detect when the mapped git root looks plans/tests-only and sibling roots look like apps — inform the user once of the multi-root approach. Full rules: references/split-repo-workspaces.md.

Agent guardrails (must follow)

1. Scenario and story IDs — platform-provisioned only (BLOCKING).

   • Never invent / assume fake IDs: Do not guess or fabricate #TS-… / US-… ids, and do not write scenario annotation entries (or deprecated // @Scenario: #TS-… comments) before those entities exist in TestChimp.
   • Never write id-less plan markdown (critical failure mode): Do not Write / create new files under plans/stories/ or plans/scenarios/ (any mapped plans root) that omit id: US-<n> / id: TS-<n>, or that leave id: blank. Omitting the field is not a workaround for “don’t invent ids” — it produces broken artifacts that Git sync cannot import.
   • Required create → write → update sequence (every new story/scenario):
     1. MCP/CLI create-user-story / create-test-scenario (platform allocates ordinalId and returns stub content with id: already set).
     2. Write the returned content to the repo path (edit body only; keep id: / scenario story:).
     3. MCP/CLI update-user-story / update-test-scenario with the full markdown. Updates fail if id: (or scenario story:) is missing — use that error to fix before finishing.
   • Sequential creates only (BLOCKING): Never fan-out / parallelize create-user-story or create-test-scenario (MCP tool calls or CLI). Create one at a time, await each response, then the next. Parallel creates can race and return the same ordinalId (e.g. four scenarios all TS-2278).
   • Duplicate ordinal self-check: After any batch of creates in one Execute turn, verify all returned ordinalId values are unique. If any duplicate appears, treat it as a platform allocation failure — do not write story/scenario files, stop, and report-agent-action ACTION_FAILED with the duplicate ids.
   • Forbidden: Hand-authoring story/scenario .md files first and “adding ids later”; copying a sibling file’s frontmatter without a create call; using only story: US-… on a new scenario without a platform-issued id: TS-…; parallel create tool calls for stories/scenarios.
   • Correct behavior when coverage is missing: If the PR introduces behavior and there are no relevant stories/scenarios, plan their creation (via MCP/CLI) so the platform generates real IDs, then follow the sequence above.
   • Timing rule: Call create-user-story / create-test-scenario (and subsequent updates) only in Execute, after the user has explicitly approved the Plan. The Plan lists what will be created/updated but must not mutate the platform pre-approval.
   • After IDs exist: Add SmartTest scenario annotation entries using the actual platform ids (or ids already present in committed plan markdown). Full rules: references/author-plans.md and references/write-smarttests.md.
   • Self-check before finishing any plan-authoring turn: Every new/changed story/scenario file under the plans root must have a non-empty id: matching a platform ordinal from create/get in this session (or an id already on disk from a prior sync). If any file fails, stop and fix — do not commit or hand off.

2. Run Playwright only from the mapped SmartTests root (see Marker files). cd there, then run Playwright via npx (e.g. npx playwright test …). Do not run tests from the repo root unless that root is the mapped folder.

3. API keys, backend URL, ingress URL, and 401s. TESTCHIMP_API_KEY, (when configured) TESTCHIMP_BACKEND_URL, and (when configured) TESTCHIMP_INGRESS_URL: canonical mcp.json / MCP env plus runner/CLI export — full rules in Preamble checks #4 and Finding project MCP config. On 401, first verify the correct host was exported (TESTCHIMP_BACKEND_URL for CLI/MCP; TESTCHIMP_INGRESS_URL for reporter ingest), then the key. Obtain keys: TestChimp → Project Settings → Key management. Do not document PATs or alternate user-auth env pairs for agents.

4. Gitignore generated report folders. Playwright / Mobilewright (and reporters) can create generated artifacts (HTML reports, traces, screenshots, videos, raw results). These must not be committed. Ensure the repo’s .gitignore includes common Playwright output folders such as:

   • playwright-report/
   • mobilewright-report/
   • test-results/
   • blob-report/
   • any other repo-specific generated report/output directory configured by the test runner or CI

5. Persist infra learnings (required).

   • Test-env connectivity (startup / health / BASE_URL) belongs in plans/knowledge/policies/connect-to-test-env.policy.md (## Local Agent, ## CI / Cloud). Update that policy when bring-up steps change; bump version and upsert-policy. Do not create ai-test-instructions.md just to document env bring-up.
   • Legacy FAQ only when the file already exists: If plans/knowledge/ai-test-instructions.md is present, maintain ## Past learnings — authoring & validation (FAQ) (FAQ-style ### Q: / **A:** entries) for recurring pitfalls—see Binding: test-env contract in references/run-qa.md. If the file is absent, put durable env learnings into the connect-to-test-env policy instead.
   • ExploreChimp decisions (network URL regex when NETWORK is a source, default source list overrides, exploration scope habits, resolved blockers) belong under ## ExploreChimp in ai-test-instructions.md when that file already exists; otherwise record them in the relevant workflow policy / branch plan—see references/run-explorechimp.md.
   • Before improvising on env blockers: re-read connect-to-test-env.policy.md (and the legacy FAQ only if ai-test-instructions.md exists). If you resolve something not already documented, patch the policy (and append a FAQ Q/A only when the legacy file already exists).

6. SmartTests fixtures-first (correct barrel per scaffold). Read .testchimp-tests and references/project-types-and-scaffolds.md before authoring. Every *.spec.* imports { test, expect } from the matching barrel (fixtures/, api/fixtures/, mobile/fixtures/, web/fixtures/) — never from @playwright/test or @mobilewright/test directly. Each barrel’s index.js applies installTestChimp (≥ 0.1.8); mobile/fixtures uses { uiFixture: 'screen' }. Web UI: page + markScreenState. Mobile UI: screen / device — references/mobilewright-smarttests.md. Cross-platform seed helpers go in shared/, not specs. See references/fixture-usage.md. Atlas: testchimp list-screen-states / upsert-screen-states — references/cli.md, references/write-smarttests.md §7.

7. TrueCoverage RUM environment tag (web + native). RUM SDKs take environment in init / initialize; they do not read TESTCHIMP_ENV from the test runner process. Planning native (or web) TrueCoverage must include how the app maps environment (build config, plist, BuildConfig, bootstrap helper) so it aligns with list-rum-environments and execution scopes—or a deliberate mismatch documented with scope implications. Do not treat project id + API key + deep link / installTestChimp as complete without this. See references/instrument-truecoverage.md § RUM environment tag.

8. Platform scope on PR branches (mobile & multi-platform). When project_type is mobile or multi-platform, /testchimp test and /testchimp explore must resolve which of web, ios, and android are in scope for the branch. Deduce from PR diff and touched specs when evidence is strong; always inform the user of the chosen platform(s) and rationale. Ask which platform(s) to test when deduction is ambiguous—do not default to all platforms silently. Persist ## Platform scope (this run) on the branch plan and require user confirmation before Execute. Full rules: references/platform-scope.md.

9. Insufficient scenario context — infer first, then manual-session fallback. When authoring a SmartTest for a scenario that lacks detail (e.g. a one-line description), first try to recover Arrange/Act/Assert from the codebase / PR changes and existing harness. In a split-repo / multi-root workspace, search product workspace roots for application context (not only the mapped TestChimp repo) — references/split-repo-workspaces.md. Only if that still is not enough: do not invent the journey — suggest Chrome-extension manual session capture (scenario selected) and ask the user to paste Copy test generate prompt from the session view. Docs: manual session capture. Details: references/write-smarttests.md § Insufficient scenario context; after paste, references/author-test-from-manual-session.md.

MCP client and CLI (agents)

Install @testchimp/cli@latest (see references/init-testchimp.md) and register the MCP server using npx with @testchimp/cli@latest and the mcp subcommand in args.

CLI (shell / CI): Same package exposes the testchimp binary for calling the same HTTP APIs with flags or --json-input. See references/cli.md for env resolution, stdout/stderr, and when to prefer CLI vs MCP.

Reference config: assets/sample-mcp.json — shows command, args (-y + @testchimp/cli@latest + mcp), and env with TESTCHIMP_API_KEY and TESTCHIMP_PROJECT_ID placeholders. Cloud/CI template with ${TESTCHIMP_API_KEY} refs: assets/sample-mcp.cloud.json. /testchimp init must write this blob into the project-level MCP file (create or merge) when missing. Replace placeholders with values from TestChimp → Project Settings → Key management; do not commit real secrets. Discovery rules: Finding project MCP config.

Minimum versions: This skill declares required_cli_version in frontmatter. Agents must run Preamble checks #5 (CLI) and #6 (Playwright/Mobilewright toolchain). When TrueCoverage or application RUM code is in scope, also run #7 (latest @testchimp/rum-js / iOS tags / Android JitPack tag vs project install). On create-tests / run-qa / upkeep, also run #8 (latest @testchimp/playwright vs project install — autonomous lockfile bump).

MCP env: TESTCHIMP_API_KEY (required for MCP + runner/CLI export per #4); TESTCHIMP_BACKEND_URL (optional; required to export whenever set — staging/enterprise/self-hosted featureservice; omit only for default SaaS prod); TESTCHIMP_INGRESS_URL (optional; required to export whenever set — staging/enterprise ingress for Playwright reporter; omit for SaaS prod default ingress); TESTCHIMP_PROJECT_ID (optional for MCP calls; required for TrueCoverage RUM projectId when not elsewhere in app config — agents read it during instrumentation per references/instrument-truecoverage.md). 401 or missing-key symptoms → #4 (check backend/ingress URL first).

The MCP server exposes tools grouped by area:

• Org capabilities (CLI ≥ 0.1.29) — get-org-capabilities (organization capabilities[] + freeTrialActive; call before relying on TrueCoverage / API contract coverage insights so playbooks can soft-skip gated work — see references/cli.md § get-org-capabilities, references/instrument-truecoverage.md, references/upkeep.md, references/run-qa.md)
• Coverage & execution — get-requirement-coverage, get-execution-history (optional testId / --test-id, CLI ≥ 0.1.25), get-suite-execution-stats (full-suite duration / test-count rollup for bloat checks vs global.policy.md — see references/cli.md; use @testchimp/cli@latest until the tool is on a pinned CLI release), mark-plan-items-implementation-done, update-plan-items-lifecycle-status (CLI ≥ 0.1.22)
• API operations coverage (CLI ≥ 0.1.28) — list-api-operation-services, list-api-operations, get-api-operation-detail (OpenAPI ops + field/response-code coverage; see references/cli.md § API operations, references/api-testing.md)
• Performance testing (CLI ≥ 0.1.31) — soft-gate with get-org-capabilities → PERFORMANCE_TESTING; use list-api-operation-interactions for redacted REAL E2E request/response shapes (testId and/or operationId required; default REAL). History/baseline tools: list-perf-runs, get-perf-run, list-perf-baselines, promote-perf-baseline, compare-perf-to-baseline (prints JSON; CLI exits nonzero when comparison.regressed is true), list-related-perf-tests. Opt into perf coverage gaps with get-requirement-coverage --include-perf / recordTypes: ["PERF_TEST"]. See references/perf-testing.md; TestChimp/TrueCoverage signals never define absolute load.
• Workflows & policies (CLI ≥ 0.1.21; plans upsert ≥ 0.1.24; get plan ≥ 0.1.32) — report-agent-action, get-last-run-workflow-detail, get-policy, list-policies, upsert-policy, upsert-plans-support-file, get-plans-support-file, list-workflow-catalog (also list-workflow-executions / get-workflow-execution when available). Policies live under plans/knowledge/policies/*.policy.md (workflow policies and global.policy.md for suite goals / prioritization / size limits / suite tags). Workflow execution plans live under plans/knowledge/workflow_plans/<workflow-id>/. Optional env POLICY_FILE may point at the active policy path. Resolution: --policy → <workflow-id>.policy.md → any matching frontmatter workflow-id → ai-test-instructions.md fallback — references/policies-and-traceability.md. After authoring a policy locally, call upsert-policy. After writing a workflow plan file, call upsert-plans-support-file (blocking before Execute). When a prompt names a plan file, call get-plans-support-file first (platform copy wins; then fall back to the repo file).
• Screen-state atlas (SmartTests / traces / ExploreChimp) — list-screen-states, upsert-screen-states (same as testchimp list-screen-states / testchimp upsert-screen-states in references/cli.md)
• Semantic duplicate hygiene (/testchimp cleanup) — list-semantic-similar-tests, mark-semantic-tests-distinct (TestLocator-based; see references/cleanup.md)
• Verified-test review (/testchimp fix test failure only) — mark-tests-for-review (CLI ≥ 0.1.33; TestLocator + confidence 0–100; never from run-qa / create-tests; see references/fix-test-execution.md)
• Cross-entity semantic nearby (QA Brain) — list-semantic-nearby, mark-entity-distinct, unmark-entity-distinct (TestLocator / ordinal / event title; see references/cli.md)
• Execution debugging — fetch-execution-report, get-manual-session-details, get-batch-view-url (batch viewer deeplink from batchInvocationId)
• Agent evidence — after capturing screenshots during test/debug work, run upload-attachment --file <path> and include the returned viewUrl in chat (do not paste raw local paths). After test runs, include get-batch-view-url --batch-invocation-id <id> so the user can open the batch viewer.
• Issues — create-issue, get-issue-details, update-issue-status (see references/cli.md § Issues; create requires CLI ≥ 0.1.17). /testchimp implement (story, scenario, or plan file) uses create-issue with TASK_ISSUE, label TestChimp Implement, severity + category, and story/scenario linkTargets when those ids are known, then update-issue-status → FIXED as each task completes (implement-requirement.md).
• Release catalog & gating — get-release (thin catalog metadata: cut SHA, prior release, focus areas), get-release-details (gate-oriented: per-environment priority×status test stats, open-issue stats, scan summaries, in-scope scenario/issue records — for CI/agent release gating; requires CLI ≥ 0.1.18) (see references/cli.md § get-release / get-release-details)
• Planning (user stories & scenarios) — get-user-stories, get-test-scenarios, list-test-scenarios-for-scope, get-spec-lifecycle-details, create-user-story, create-test-scenario, update-user-story, update-test-scenario
• Requirement quality (DeFOSPAM — local agent) — get-requirement-quality-report, report-requirement-quality-findings (see references/run-requirement-quality-checks.md; CLI ≥ 0.1.19)
• Environments & EaaS — get-eaas-config, get-branch-specific-endpoint-config, provision-ephemeral-environment-and-wait, provision-ephemeral-environment, get-ephemeral-environment-status, destroy-ephemeral-environment
• Ephemeral deploy diagnostics (BunnyShell) — list-bunnyshell-environment-events, list-bunnyshell-workflow-jobs, get-bunnyshell-workflow-job-logs
• TrueCoverage analytics — list-rum-environments, get-truecoverage-events, get-truecoverage-event-details, get-truecoverage-child-event-tree, get-truecoverage-event-transition, get-truecoverage-event-time-series, get-truecoverage-session-metadata-keys, get-truecoverage-event-metadata-keys — set platform on each ExecutionScope in --json-input (see references/cli.md § TrueCoverage)

Use the repo, plans, policies, and those tools to decide what to test and how to run them.

Command routing

Truncated - read the full file at https://github.com/testchimphq/testchimp-skills/blob/5fa04cb3ca6ed0c5a4b257019b035642478d3d60/SKILL.md.