> ## Documentation Index
> Fetch the complete documentation index at: https://checksum.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# How Test Generation Works

> Checksum takes you from "what should we test?" to merged Playwright tests. An AI agent proposes the user flows worth covering, writes and verifies the tests, and opens a pull request. You can drive each step from the REST API, your coding agent over MCP, a GitHub pull request, Slack, or the web app. This page shows how the pieces fit together and which path suits you.

## At a glance

| Step | Where you can do it | Learn more |
| - | - | - |
| Find what to test | Automatically, as part of generation from any trigger, or on its own in the web app | [Detect Test Flows](/docs/detect-tests) |
| Write the tests | REST API, a PR comment, your coding agent, Slack, the web app, or a recorded walkthrough in the Chrome extension | [Generate Tests](/docs/generate-tests) |
| Follow and steer the work | Web app, your coding agent, or the PR's progress comment | [Agent Sessions](/docs/agent-sessions) |

<div className="ai-ref">
  <Accordion title="Reference for AI: test generation capabilities by interface" icon="robot">
    #### What you can do from where

    ✓ = supported, — = not available from that interface.

    | Capability | REST API | MCP server | GitHub PR comment | Slack @checksum | Web app |
    | - | - | - | - | - | - |
    | Detect test flows | ✓ as part of generation | ✓ as part of generation | ✓ as part of generation | ✓ as part of generation | ✓ on its own or with generation |
    | Generate tests | ✓ from a PR: [`POST /public-api/v1/auto-generate`](/docs/generate-tests#reference-for-ai-generation-rest-api) | ✓ PR or described flow: [`checksum_test_generate`](/docs/generate-tests#ask-your-coding-agent-mcp) | ✓ [`/checksum generate`](/docs/generate-tests#ask-from-a-pull-request) | ✓ from a thread | ✓ from flows |
    | Choose Standard / Deep | — | — | — | — | ✓ |
    | Monitor progress | ✓ poll batch: [`GET /public-api/v1/auto-generate/batch/{batchId}`](/docs/generate-tests#check-on-progress) | ✓ `checksum_session_status` | ✓ sticky PR comment | ✓ session link | ✓ session view |
    | Steer a running session | — | ✓ `checksum_session_prompt` | — | — | ✓ |
    | Answer questions / approve plans | — | ✓ via prompt | — | — | ✓ |

    #### Entry points

    | Interface | Entry point | Full reference |
    | - | - | - |
    | REST API | `POST https://api.checksum.ai/public-api/v1/auto-generate`, then poll `GET https://api.checksum.ai/public-api/v1/auto-generate/batch/{batchId}` | [Generate Tests → REST API](/docs/generate-tests#start-generation-from-the-rest-api) |
    | MCP | `checksum_test_generate`, `checksum_session_status`, `checksum_session_prompt` on `https://api.checksum.ai/public-api/mcp` | [Coding Agents & MCP → MCP server](/docs/coding-agents#mcp-server-connect-and-use) |
    | GitHub | `/checksum generate [instructions]` PR comment, or auto-generate on PR open (enabled by Checksum) | [Generate Tests → GitHub PR comment](/docs/generate-tests#ask-from-a-pull-request) |
    | Slack | `@checksum` mention in a thread | [Generate Tests → Slack](/docs/generate-tests#mention-@checksum-in-slack) |
    | Chrome extension | Checksum Capture (Beta): record a walkthrough (DOM actions + optional voice narration), connected with the project API key from Settings. Output: one test ("Exactly what I recorded") or one test per flow ("Split into flows"), reviewed in the agent session, with a PR opened from there. | [Generate Tests → Chrome extension](/docs/generate-tests#record-a-walkthrough-with-the-chrome-extension) |

    * Detection is part of generation: a generation session started from the REST API, MCP, a PR comment, or Slack detects what to test and writes the tests in the same session. Running detection separately in the web app is optional.
    * Auth: REST calls send `Authorization: Bearer $CHECKSUM_API_KEY` ([API keys](/docs/authentication#your-api-key)). MCP clients sign in through the browser or use the same key ([MCP server](/docs/coding-agents#mcp-server-connect-and-use)).
    * PRs need all three: Checksum opens a PR only when it has the pull request number, repository, and head branch.
    * Output: a story file (`.checksum.md`) and a Playwright test (`.checksum.spec.ts`) per flow, delivered as a PR to the tests repository ([Story & Test Format](/docs/story-and-test-format)).
  </Accordion>
</div>

<div className="part dev"><span className="part-icon">{"</>"}</span><div><div className="part-title">Developer guide</div><div className="part-sub">Starting generation from your own tools</div></div></div>

## Start generation from your own tools

You don't need the web app to create tests. Developers usually start from one of these:

* **REST API:** have a release bot or CI step send a pull request to Checksum and wait for the tests. See [Generate Tests → REST API](/docs/generate-tests#start-generation-from-the-rest-api).
* **A pull request comment:** type `/checksum generate` on the PR, or ask Checksum to generate for every new PR automatically. See [Ask from a pull request](/docs/generate-tests#ask-from-a-pull-request).
* **Your coding agent:** with the MCP server connected, ask "Generate Checksum tests for this PR." See [Coding Agents & MCP](/docs/coding-agents).
* **Slack:** mention `@checksum` in the thread where the feature was discussed. See [Mention @checksum in Slack](/docs/generate-tests#mention-@checksum-in-slack).

<Note>
  **Detection happens as part of generation**

  When you start generation from any of these, the agent **detects** what to test and **generates** the tests in the same session. You don't need to run detection in the web app first.
</Note>

<div className="ai-ref">
  <Accordion title="Reference for AI: where the entry points are documented" icon="robot">
    The full entry-point table and capability matrix are in the "Reference for AI: test generation capabilities by interface" block under At a glance ([capability matrix](#what-you-can-do-from-where)). The generation REST API spec (fields, types, responses, errors) is in [Generate Tests → Reference for AI: generation REST API](/docs/generate-tests#start-generation-from-the-rest-api). MCP tool inputs are in [Generate Tests → Reference for AI: checksum\_test\_generate](/docs/generate-tests#ask-your-coding-agent-mcp).
  </Accordion>
</div>

<div className="part ui"><span className="part-icon">▦</span><div><div className="part-title">In the Checksum web app</div><div className="part-sub">Collections and test flows</div></div></div>

## Collections and test flows

Two objects organize the work in the web app:

| Object | What it is | Example |
| - | - | - |
| **Collection** | A group of related test flows, usually one feature area. Collections organize the suite, and you can run a whole collection at once (`POST /execution/collection/:id`). | "Checkout", "User Management", "Settings" |
| **Test flow** (user story) | One test scenario in a collection: a title, a description of the steps, and a start URL. Flows are what Checksum generates tests *from*. Each generated test gets a Checksum test ID for tracking. | "User can create an account", "Admin can export a report" |

A flow can come from detection, be written manually, be implied by a pull request, or be recorded. PR-based triggers (GitHub, REST API, MCP) generate from the PR diff without a saved flow. A walkthrough recorded with the [Chrome extension](/docs/generate-tests#record-a-walkthrough-with-the-chrome-extension) is used as context for the agent, which generates one test or, split into flows, a whole batch of tests from it.

<Frame caption="A test flow in a collection: title, steps, and start URL.">
  <img src="https://mintcdn.com/checksum/jreTwWrmFV2djRX_/images/test_card.png?fit=max&auto=format&n=jreTwWrmFV2djRX_&q=85&s=4cf18a4756883a1bdade3c138b985a42" alt="A detected test flow card showing title, description, and start URL" width="2320" height="1906" data-path="images/test_card.png" />
</Frame>

<div className="part bg"><span className="part-icon">i</span><div><div className="part-title">How it works</div><div className="part-sub">The lifecycle every test goes through</div></div></div>

## The generation lifecycle

Every test in your suite goes through the same stages, whichever tool you use to start them:

<div className="flow">
  <div className="node"><b>1 · Detect</b><span>Agent proposes the flows worth testing</span></div>
  <div className="arrow">→</div>
  <div className="node"><b>2 · Review flows</b><span>Edit, delete, or add flows</span></div>
  <div className="arrow">→</div>
  <div className="node"><b>3 · Generate</b><span>Story + Playwright test written</span></div>
  <div className="arrow">→</div>
  <div className="node"><b>4 · Verify</b><span>Agent runs the tests to prove they pass</span></div>
  <div className="arrow">→</div>
  <div className="node"><b>5 · PR</b><span>Delivered to your tests repo</span></div>
  <div className="arrow">→</div>
  <div className="node"><b>6 · Merge</b><span>You review and merge</span></div>
  <div className="arrow">→</div>
  <div className="node"><b>7 · Maintain</b><span>Auto-recovery + auto-healing</span></div>
</div>

<Steps>
  <Step title="Detect">
    [Detection](/docs/detect-tests) analyzes your application, including its source code, and proposes **test flows**: key user journeys, critical business flows, and edge cases. This step is optional. You can also write flows by hand, generate straight from a pull request, or record a walkthrough with the [Chrome extension](/docs/generate-tests#record-a-walkthrough-with-the-chrome-extension).
  </Step>

  <Step title="Review flows">
    Detected flows land in a **collection**. Check the titles, steps, and start URLs, remove what isn't relevant, and add any flows the agent missed. This is where you prioritize before any code is written.
  </Step>

  <Step title="Generate">
    [Generation](/docs/generate-tests) starts an [agent session](/docs/agent-sessions) that writes a story file (`.checksum.md`) and a Playwright test (`.checksum.spec.ts`) for each flow. In [Deep mode](/docs/generation-modes) it first interviews you and builds a plan.
  </Step>

  <Step title="Verify">
    The agent reviews its own work, validates it against the Checksum CLI ("Checksumify"), and **runs the tests** against your environment. Only passing tests are delivered.
  </Step>

  <Step title="Pull request">
    Checksum opens a PR on a new branch in your tests repository. The PR description explains the flow being covered.
  </Step>

  <Step title="Merge">
    You review the PR like any other change. Your repository is always the source of truth (see [Test Repository & Config](/docs/test-repository)).
  </Step>

  <Step title="Maintain">
    Once merged, tests run in CI or on demand ([Running Tests](/docs/running-tests)). [Auto-recovery](/docs/auto-maintenance) handles small UI drift at runtime, and [auto-healing](/docs/auto-healing) opens PRs to fix tests that break as your app evolves.
  </Step>
</Steps>

## Which path should I use?

<CardGroup cols={2}>
  <Card title="Web app" icon="table-columns">
    Run detection per collection, review and prioritize flows, then generate in batches. Use Deep mode the first time you cover a complex area. This is the best place to curate coverage by feature.
  </Card>

  <Card title="GitHub or MCP" icon="code-branch">
    Comment `/checksum generate` on your PR, or ask your coding agent: "Generate Checksum tests for this PR." The tests come back as a PR, and progress shows in a sticky comment.
  </Card>

  <Card title="REST API" icon="code">
    Call `POST /auto-generate` from a release bot or CI step, then poll the batch. You can pass a preview URL with `envOverrides`. Or ask Checksum to turn on **auto-generate on PR open**.
  </Card>

  <Card title="Slack" icon="slack">
    Mention `@checksum` in the thread where the feature was discussed. The whole thread becomes the agent's instructions.
  </Card>

  <Card title="Chrome extension" icon="chrome">
    Record yourself clicking through a flow with [Checksum Capture](/docs/generate-tests#record-a-walkthrough-with-the-chrome-extension), and narrate the edge cases, assertions, and variations you want. Split into flows, one recording can produce a batch of 10, 20, 30 or more tests.
  </Card>
</CardGroup>

## Before you generate

Generation needs a working project: an environment URL and test users, a connected tests repository, and your source code repository. **Checksum sets these up with you during onboarding** (see [Onboarding & Proof of Value](/docs/onboarding)). Once you're live, you can manage them yourself:

* [Environments & Test Users](/docs/environments): add staging or preview environments and role-based users
* [Git Integration](/docs/git-integration): connect or change the tests and code repositories
* [API Keys & Authentication](/docs/authentication#your-api-key): get the key for REST, CLI, and CI use

## In this section

<CardGroup cols={2}>
  <Card title="Detect Test Flows" icon="magnifying-glass" href="/docs/detect-tests">
    Let the agent propose what to test.
  </Card>

  <Card title="Generate Tests" icon="wand-magic-sparkles" href="/docs/generate-tests">
    Every trigger: app, API, GitHub, Slack, MCP, Chrome extension.
  </Card>

  <Card title="Deep vs Standard" icon="layer-group" href="/docs/generation-modes">
    Speed vs thoroughness, across every pipeline.
  </Card>

  <Card title="Story & Test Format" icon="file-code" href="/docs/story-and-test-format">
    What lands in your repo.
  </Card>

  <Card title="Agent Sessions" icon="robot" href="/docs/agent-sessions">
    Lifecycle, questions, approvals, steering.
  </Card>
</CardGroup>