> ## 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.

# Key Concepts & Glossary

> The vocabulary used across the web app, the CLI, and the REST API: what each object is, how the objects relate, and which ID to pass where.

<div className="part dev"><span className="part-icon">{"</>"}</span><div><div className="part-title">Developer reference</div><div className="part-sub">IDs, outcomes, and verdict values used by the API, CLI, and MCP</div></div></div>

## IDs you'll meet

Most integration mistakes come from passing the wrong ID. This table covers each one.

| ID | Example | Where it comes from | What consumes it |
| - | - | - | - |
| **Checksum test ID**<br />`checksumTestId` / `testId` | `OFJlm` | Story frontmatter, `defineChecksumTest(title, id)`, results payloads, `POST /affected-tests` | `POST /execution/tests` (`testIds`), attachments and verdict endpoints, dashboard "Copy all affected test IDs" |
| **Run ID**<br />`runId` = `testRunId` = `id` | `9f2c7a4e-8b31-…` (UUID) | Every execution endpoint's response, `GET /test-runs/latest`, v2 status (`testRunId`) | `GET /execution/status/run/:runId`, `/test-runs/:id/*`, `POST /auto-heal` (`testRunId`), `--cksm-rerun-failed=<id>` |
| **Job name**<br />`name` / `jobName` | `job-name-12345` | Execution responses for *non-sharded* runs (`null` when sharded) | Legacy `GET /execution/status/:jobName` only. **Not** accepted by `POST /auto-heal`. |
| **Batch ID**<br />`batchId` | `batch-xyz-789` | `POST /auto-generate`, `POST /auto-heal`, MCP generate/heal tools | `GET /auto-generate/batch/:batchId`, `GET /auto-heal/batch/:batchId` |
| **Session ID**<br />`sessionId` | `sess-xyz` | Generate/heal responses, batch `sessions[]` | Session links in the web app, MCP `checksum_session_status` / `checksum_session_prompt` |
| **Collection ID** | (from the web app) | Test Generation → collection | `POST /execution/collection/:id`, GitHub Action `collection-id` |
| **Bug ID** | `BUG-42` | Health Dashboard bug entities | Bug page links such as `https://app.checksum.ai/#/health-dashboard/bug/BUG-42` |
| **Project ID** | `project-abc-123` | `GET /me` | Confirms which project an API key belongs to. MCP calls it `applicationId` when you have several projects. |

<Warning>
  **Healing needs the run UUID**

  To heal a run that already finished, pass `testRunId` set to the run's UUID: the `runId` returned when you started it, or the `id` from `GET /test-runs/latest`. The job `name` won't work.
</Warning>

## Outcomes and verdicts (API values)

The enum values your code will read from run, result, and report payloads.

### Test outcomes

These terms are used consistently across the web app, CLI, API, and notifications:

| Outcome | Meaning | Where you'll see it |
| - | - | - |
| **Passed** | Passed with no recovery needed | Reports, `passed` in the API |
| **Failed** | Failed and couldn't be recovered during the run | Reports, `failed` |
| **Recovered** | A step failed, but the CLI's [auto-recovery](/docs/auto-maintenance#auto-recovery) fixed it on the fly. Counts as passing, and is flagged so you can review it. | Reports ("Recovered" plus the recovery reason), `recovered` |
| **Healed** | After the run, a [healing agent](/docs/auto-healing) changed the test code, and the fix arrived as a PR | Healing PRs, the `healed` run status, Test Run Completed notifications |
| **Bug** | Triage decided the application is broken, not the test. The test is tagged `@bug` and tracked in a bug entity. | Health Dashboard, `bug` |
| **Skipped** | The test didn't execute | Notifications (`skipped`), report stats |

### Run verdict

For CI gating, the API computes one `verdict` per run: `pass`, `fail`, or `pending`. Gate on `verdict` once `isTerminal` is `true`, not on `status` or on the raw counts. An empty test selection (`executedCount: 0`) is a `fail`, and a sharded run only gets a verdict after its shards merge. See [Run status](/docs/running-tests#check-whether-a-run-passed).

### Report verdicts

Separately, people and automation can submit a per-test verdict on a run report: `bug`, `recovered`, `healing`, or `triage`, each with an annotation. See [Submit verdicts](/docs/results-and-reports#record-a-verdict-from-your-own-tooling).

<div className="part bg"><span className="part-icon">i</span><div><div className="part-title">Glossary</div><div className="part-sub">The objects you work with in Checksum</div></div></div>

## How the pieces fit

<div className="flow">
  <div className="node"><b>Project</b><span>API key, environments, Git</span></div>
  <div className="arrow">→</div>
  <div className="node"><b>Collection</b><span>Feature area</span></div>
  <div className="arrow">→</div>
  <div className="node"><b>Test flow</b><span>One user journey</span></div>
  <div className="arrow">→</div>
  <div className="node"><b>Story + test</b><span><code>.checksum.md</code> + <code>.spec.ts</code></span></div>
  <div className="arrow">→</div>
  <div className="node"><b>Test run</b><span>Results, artifacts, verdict</span></div>
</div>

**Agent sessions** are the work units that detect flows, generate tests, and heal them. **Bug entities** group the failures that sessions classify as real application bugs.

## Project and configuration

### Project

Everything in Checksum belongs to a project, which usually means one application under test. A project has exactly one [API key](/docs/authentication#your-api-key), one or more environments, a connected tests repository, and a connected code repository. Checksum creates your project during [onboarding](/docs/onboarding).

### Environment & test users

An **environment** is a deployment of your app to test against (e.g. UAT, staging), with an environment URL and an optional login URL. Each environment has one or more **test users**, the credentials the agent and test runs use to log in, often one per role (admin, viewer). See [Environments & Test Users](/docs/environments).

### Tests repository & code repository

The **tests repository** is where your Playwright tests live. Checksum writes to it only by opening pull requests. The **code repository** is your application source, which Checksum only reads, to improve detection and generation. They can be the same repo. See [Test Repository & Config](/docs/test-repository).

### Repo mirror

Checksum keeps a synchronized view of your repositories through webhooks (pushes, PR events, app installation changes). It reads your existing tests so it doesn't generate duplicates, and it writes back only through PRs. **Your repository is always the source of truth.** Configuration works differently: settings in the web app don't sync to your repository. Your tests read from a `.env` file that Checksum maintains and you download with `npx checksumai dotenv --download` (see [Environments](/docs/environments#work-with-environment-variables)). [More on the repo mirror →](/docs/test-repository#the-repo-mirror)

## Tests

### Collection

A group of related test flows, such as "Checkout", "User Management", or "Settings". Collections organize the suite by feature area. You can run a whole collection by ID from the API (`POST /execution/collection/:id`) and filter dashboards and bug lists by collection.

### Test flow (user story)

One test scenario inside a collection, describing a user journey like "User can create an account" or "Admin can export a report". A flow has a title, a description of its steps, and a start URL. Flows come from [detection](/docs/detect-tests) or are created manually, and they are what Checksum generates tests *for*. You can also skip writing flows and record a walkthrough with the [Chrome extension](/docs/generate-tests#record-a-walkthrough-with-the-chrome-extension), which the agent uses as context to generate one test or a batch of tests, one per flow.

### Story file & test file

Each generated test is two files: a **story** (`.checksum.md`, a human-readable spec with frontmatter, data setup and cleanup, and steps) and a **test** (`.checksum.spec.ts`, Playwright code using Checksum fixtures). See [Story & Test Format](/docs/story-and-test-format).

### Tags

Labels on tests (e.g. `smoke`, `checkout`) that appear in results and can filter dashboards, bug lists, and notification reports. A grep such as `@smoke` is a common way to select a subset for a run.

## Agents

### Agent session

A running instance of the AI agent doing one piece of work: detecting flows, generating a test, or healing failures. Sessions move through a lifecycle (Initializing → Cloning → Running → Completed/Failed) and can pause for your input or approval. See [Agent Sessions](/docs/agent-sessions).

### Standard vs Deep mode

Every pipeline (detection, generation, and healing) runs in **Standard** mode (fast and fully autonomous; the default) or **Deep** mode (interview and plan first, then a knowledge-base update and more thorough review). See [Deep vs Standard Modes](/docs/generation-modes).

### Batch

API-triggered generation and healing return a `batchId`. A batch groups one or more sessions started by the same request. For example, one heal request can fan out into a session per failing test. Poll the batch until `allTerminal` is `true`.

## Runs and outcomes

### Test run

One execution of some or all tests, via the CLI, CI, the GitHub Action, or the REST API. A run records per-test outcomes, branch and commit, and artifacts (videos, screenshots, HAR files, Playwright traces), and appears under **Test Results**. A run can be **sharded** across parallel machines and merged into one result (see [Sharding](/docs/sharding)).

### Bug entity

A trackable bug (e.g. `BUG-42`) that groups every failing test caused by the same problem, so you triage, comment on, and resolve it once. Statuses: **Needs Triage**, **Confirmed**, **Fixed**, **Not Bug**, **Snoozed**. See [Feature Health Dashboard](/docs/health-dashboard).

### Test health

A rolled-up status based on recent run history, not just the latest run: **Passing** or **Failing**, with per-test recent-run history to show intermittent failures. Result payloads also carry a `healthStatus` such as `healthy` or `flaky`.

## Related

<CardGroup cols={2}>
  <Card title="API Keys & Authentication" icon="key" href="/docs/authentication">
    Base URL, versions, and the typical API flow.
  </Card>

  <Card title="How Test Generation Works" icon="wand-magic-sparkles" href="/docs/test-generation">
    From flows to PRs.
  </Card>

  <Card title="Results, Reports & Traces" icon="chart-line" href="/docs/results-and-reports">
    Where outcomes show up.
  </Card>
</CardGroup>