Skip to main content

Published Updated

Quick Start Guide

In brief: Connect Git, install the TestChimp skill and MCP, run /testchimp init (each teammate) and /testchimp project-init (once per project)—then /testchimp run QA after each PR, and /testchimp create release when you ship.

This guide is the hands-on path for the model in What is TestChimp?. After setup, you do not invent ad-hoc agent prompts for every QA task—you run pre-defined workflows: battle-tested playbooks in the skill, customized by project policies in your repo.

Day-to-day shape:

CadenceWorkflowSynonyms
When a PR / change is readyRun QA/testchimp run QA, /testchimp test
When creating a releaseCreate Release/testchimp create release
Suite maintenance (gaps, cleanup)Upkeep/testchimp upkeep, /testchimp evolve

Composites chain modular subflows under one approved plan and one scope. You can also invoke atomic workflows on their own when you only need one job. Full catalog, policies, and scoping rules: Workflows.

Before you begin​

  • A TestChimp account and project (see Onboarding if you need team/project setup).
  • Node.js and a supported test toolchain where the agent runs tests: Playwright for web and Mobilewright for native mobile (the skill documents minimum versions). Mobile-specific CI guidance: Mobile testing.
  • A TESTCHIMP_API_KEY for the project (from Project settings in TestChimp), set both in MCP config and in the shell when running Playwright—see /testchimp init.

Step 1: Map your repository in TestChimp (Git)​

  1. In TestChimp → your project → Project settings → Integrations → Git, select the Git repository for this product.
  2. Map two folders in that repo:
    • Tests — SmartTests root: where your UI suite runs (for example npx playwright test on web or npx mobilewright test on native mobile) and .testchimp-tests lives after sync.
    • Plans — Markdown test plans root: stories, scenarios, knowledge; .testchimp-plans lives here after sync.
  3. Complete the product sync so marker files and any scaffold land in Git, then pull the branch locally.

Why two folders: Plans carry intent (what to verify); tests carry automation (how you verify it). Agents, MCP, and workflow policies use both. Details: Code Repository — Overview.

Step 2: Install the TestChimp skill​

Install the TestChimp skill on your agent host (Claude Code, Cursor, or any environment that loads skills—follow that host’s skill directory layout). Keep a git clone so you can pull updates or run /testchimp skill upgrade.

Restart the IDE or agent host if the skill does not load immediately.

Step 3: Register MCP (@testchimp/cli)​

Workflows call TestChimp through MCP tools (coverage, planning, environments, TrueCoverage, policies, …). Register @testchimp/cli in your project MCP config (for example .cursor/mcp.json) with TESTCHIMP_API_KEY in the server env. Use the skill’s sample config as a template; pin or use @latest per your team policy—see /testchimp init — Dependencies and reporter.

Step 4: Run /testchimp init (every teammate)​

In the agent chat, run /testchimp init. It is a per-user step: every teammate runs it once, in their own agent, to make sure their local workspace is configured to talk to TestChimp properly (skill, MCP and API key working, and workstation connectivity confirmed).

A teammate who joins later only needs Steps 2 to 4. The project itself is already set up.

Full narrative: Init.

Step 5: Run /testchimp project-init (once per project)​

In the agent chat, run /testchimp project-init once per project, not per person. It makes sure the project is ready for the workflows that follow:

  • Test environment connect strategy — how your agent reaches an environment to author and run E2E tests (staging, previews, or an ephemeral full stack).
  • Existing plans and tests imported — so the project starts from what you already have.

Step 6: Run QA on each PR​

When implementation on a PR (or change set) is ready, run the Run QA composite:

/testchimp run QA
/testchimp test
/testchimp run QA for checkout

The agent follows the run-qa playbook and your run-qa.policy.md: typically author or update plans for the scope, connect the test environment, create or repair SmartTests and fixtures, run smart smoke, optionally ExploreChimp on new UI journeys, and advance TrueCoverage—under one approved plan and one workflow_execution_id. If you are not on a PR, pass an explicit focus area (story, folder, or scenario scope).

Details and default subflows: Run QA. Broader model (composites vs atomic workflows, policies, scoping): Workflows.

Step 7: Create a release when you ship​

When it is time to cut a release, run the Create Release composite:

/testchimp create release
/testchimp create release 1.4.0 MINOR

The agent locks release label/type and create-release.policy.md (first run: accept or customize defaults), creates the catalog release and a named test run, ensures suite coverage for the cut (CI find/link or local), runs nested ExploreChimp / perf / security actions per policy, then summarises GATE posture.

Details: Create Release.

For portfolio suite maintenance (coverage gaps, cleanup, instrumentation)—not the ship loop—use Upkeep (/testchimp upkeep / /testchimp evolve).

After you are running​

NextWhen
Atomic workflowsNeed one job only—e.g. Create tests, ExploreChimp, Fix coverage gaps, Connect to test env—see the Workflows catalog.
PoliciesTune smoke vs full composites, skip ExploreChimp, pin env rules—/testchimp create policy and Workflows — Policies.
CIKeep @testchimp/playwright so runs report to TestChimp and attach test identity for TrueCoverage (web and native when RUM is wired)—see Runtime plugin and Instrumenting your app. Native mobile: prefer mobile_use_api_key with cloud devices (Mobile Use)—see Mobile testing.
Web appAuthor or refine plans, review coverage and bugs, configure integrations, watch Workflows execution history.

See also​

  • What is TestChimp? — Positioning and “why not just Claude”.
  • TestChimp Studio — Desktop IDE for software delivery; download.
  • Workflows — Composites, atomic workflows, policies, and traceability.
  • Run QA / Create Release — Recommended composites (PR loop and ship).
  • Upkeep — Suite maintenance under Functional Testing.
  • SmartTests — Playwright on web + optional ai.* steps (web today).
  • Mobile testing — Native iOS / Android with Mobilewright.
  • Chrome extension — Optional manual session capture (scenario-linked or open-ended, with notes and bugs), then Copy test generate prompt for agent-authored SmartTests; recommended day-to-day path for test and infra work is still skill + workflows.

FAQ

What do I need before starting?

A Git repository, a TestChimp project, and an agent host (Claude Code, Cursor, etc.) with the TestChimp skill and MCP wired via @testchimp/cli.

Which folders should I map in TestChimp?

Map one folder for markdown test plans (e.g. plans/) and one for SmartTests (e.g. tests/) so agents and CI share the same source of truth.

What are the day-to-day workflows after setup?

Run /testchimp run QA (or /testchimp test) after each PR. When creating a release, run /testchimp create release. Use /testchimp upkeep for suite maintenance.

How long does initial setup take?

Most teams complete Git mapping and /testchimp init in under a day; first PR-scoped tests often land within the same sprint.