Auto-Maintenance & Recovery

At a glance

Layer	When it acts	What changes
Auto-recovery	During a run, the moment a step fails	Nothing in your repo. The test passes and is flagged Recovered.
Auto-healing	After a run, for failures recovery couldn’t fix	The test code, delivered as a pull request

Reference for AI: auto-maintenance at a glance

Interface	Setting or field	Values	Effect
Config	`runMode` in `checksum.config.ts`	`RunMode.Normal` (default) · `RunMode.Heal`	`Heal`: failing steps try recovery before being reported as failures
Config	`options.useChecksumSelectors`	`true` (default)	Smart Selector recovery
Config	`options.useChecksumAI.actions`	`true` (default)	AI retries failed interactions
Config	`options.useChecksumAI.assertions`	`false` (default)	Assertion failures are not auto-recovered
REST API	`recovered` on `GET /execution/status/run/{runId}` and `GET /test-runs/{id}/results`	number	Count of tests that failed a step and were recovered
Web app	Test Results → run → Recovered	—	Shows the recovery reason for each recovered test

Two layers: auto-recovery fixes steps during a run and changes nothing in the repo. Auto-healing fixes test code after a run and opens a PR.
Recovered = passing, flagged. API field: recovered.
Config lives in the tests repo’s checksum.config.ts. Checksum configures it during onboarding; change it through a normal PR.
Not recovered at runtime: major flow changes, redesigned pages, changed business logic, new authentication requirements. These go to auto-healing.

Developer guide

Configure recovery in checksum.config.ts and read recovery results from the API

Turn on and tune recovery

Recovery is controlled in your tests repository’s checksum.config.ts. Checksum configures this file during onboarding, and you can change it through a normal PR. Set runMode to RunMode.Heal so failing steps try to recover before they’re reported as failures (the default, RunMode.Normal, fails tests on assertion errors). The options control which kinds of recovery are allowed:

import { ChecksumConfig, RunMode } from "@checksum-ai/runtime";

const config: ChecksumConfig = {
  // ...
  runMode: RunMode.Heal,
  options: {
    useChecksumSelectors: true,
    useChecksumAI: { actions: true, assertions: false },
  },
};

Option	What it does
`useChecksumSelectors`	When a selector misses, falls back to other attributes to find the element (Smart Selector recovery). On by default.
`useChecksumAI.actions`	Lets the AI retry failed interactions such as clicks, fills, and navigation. On by default.
`useChecksumAI.assertions`	Off by default, so a changed expectation shows up as a real failure instead of being papered over.

See recovery in API results

Recovered tests show up in the recovered count on a run’s status and on its detailed results, so scripts can notice them:

curl https://api.checksum.ai/public-api/v1/execution/status/run/$RUN_ID \
  -H "Authorization: Bearer $CHECKSUM_API_KEY" | jq '{passed, failed, recovered, bug}'

A test that recovers on every run still passes, but the recovery is a hint that the test would benefit from healing. Full response details are in Run status and Results API.

Reference for AI: recovery settings and fields

checksum.config.ts

Setting	Values	Effect
`runMode`	`RunMode.Normal` (default) · `RunMode.Heal`	`Heal`: failing steps try recovery before being reported as failures. `Normal`: tests fail on assertion errors.
`options.useChecksumSelectors`	`true` (default)	Smart Selector recovery: falls back to alternative attributes when a selector misses
`options.useChecksumAI.actions`	`true` (default)	Lets the AI retry failed interactions (clicks, fills, navigation)
`options.useChecksumAI.assertions`	`false` (default)	When `false`, assertion failures are not auto-recovered

Import: import { ChecksumConfig, RunMode } from "@checksum-ai/runtime";

API fields

All requests send Authorization: Bearer $CHECKSUM_API_KEY.

Endpoint	Field	Meaning
`GET https://api.checksum.ai/public-api/v1/execution/status/run/{runId}`	`recovered`	Tests in the run that failed a step and then passed on recovery or retry
`GET https://api.checksum.ai/public-api/v1/test-runs/{id}/results`	`recovered`, `tests[].status`	Run-level recovered count, plus each test’s status

▦

In the Checksum web app

See which tests were recovered, and why

View recovery results

Open the run in Test Results. Each test shows one of these results:

Result	Meaning
Passed	The test passed without any recovery
Recovered	A step failed and was recovered automatically. Counts as passing. API field `recovered`.
Failed	The test failed and couldn’t be recovered

A recovered test with its recovery reason — A recovered test shows the recovery reason at the top of its details.

How it works

Why tests break, the two maintenance layers, and what recovery can fix

Auto-maintenance overview: auto-recovery during runs, auto-healing after runs

Why tests break

Cause	Example	Handled by
Selector drift	A button’s `data-testid` or text changed	Recovery, or healing if persistent
Timing issues	A page loads more slowly after a new feature ships	Recovery, or healing if persistent
Assertion mismatches	The expected text or value changed	Healing
Flow changes	A step was added to or removed from a user flow	Healing
Setup drift	Test data requirements changed	Healing

The two layers

Auto-recovery

The CLI’s AI fallback fixes a failing step in real time. If it works, the test passes and is flagged Recovered. Nothing changes in your repo.

Auto-healing

An agent session triages the remaining failures, fixes test code, and opens a PR. Real product bugs get flagged instead of hidden.

The maintenance loop

RunTests execute in CI

→

RecoverFailing steps recovered in real time where possible

→

HealRemaining failures triaged and fixed by an agent

→

ReviewYou review and merge the PR

→

GreenSuite is green; bugs tracked on the dashboard

Auto-recovery

How auto-recovery works

A step fails

For example, a button can’t be found.

The AI inspects the page

The CLI’s AI analyzes the current page state: what’s visible and what changed.

It attempts recovery

It finds the element by other means, waits for the right condition, or adapts to the new UI.

Success: the test continues

The step is recorded as recovered, and the test finishes as Recovered, which counts as passing.

Failure: escalate

The test is marked Failed and becomes a candidate for auto-healing.

All of this happens transparently during test execution. No manual intervention is needed.

What auto-recovery can fix

Issue	How it recovers
Changed selectors	Finds the element using other attributes (text, role, position)
Timing issues	Waits for the right conditions before continuing
Minor UI changes	Adapts to layout or text changes that don’t affect the flow

What auto-recovery can’t fix (auto-healing can)

Major flow changes (steps added or removed)
Completely redesigned pages
Changed business logic
New authentication requirements

These need code changes, so they go to Auto-Healing, which runs a full agent session.

Auto-Healing

Agent-driven fixes delivered as PRs.

Results & Reports

Recovered status and recovery reasons.

Test Repository & Config

Full checksum.config.ts reference.

Start Here

Managing Your Project

Test Generation

Test Execution

Maintenance & Monitoring

Integrations

Security & Admin

Auto-Maintenance & Recovery

At a glance

Turn on and tune recovery

See recovery in API results

checksum.config.ts

API fields

View recovery results

Why tests break

The two layers

Auto-recovery

Auto-healing

The maintenance loop

Auto-recovery

How auto-recovery works

What auto-recovery can fix

What auto-recovery can’t fix (auto-healing can)

Auto-Healing

Results & Reports

Test Repository & Config

​At a glance

​Turn on and tune recovery

​See recovery in API results

​checksum.config.ts

​API fields

​View recovery results

​Why tests break

​The two layers

Auto-recovery

Auto-healing

​The maintenance loop

​Auto-recovery

​How auto-recovery works

​What auto-recovery can fix

​What auto-recovery can’t fix (auto-healing can)

​Related

Auto-Healing

Results & Reports

Test Repository & Config

At a glance

Turn on and tune recovery

See recovery in API results

checksum.config.ts

API fields

View recovery results

Why tests break

The two layers

The maintenance loop

Auto-recovery

How auto-recovery works

What auto-recovery can fix

What auto-recovery can’t fix (auto-healing can)

Related