Skip to main content

​
Commands

​
init

npx checksumai init
Initializes Checksum in your project. This creates the checksum/ folder containing:
  • checksum.config.ts — project configuration (base URL, browser settings, etc.)
  • playwright.config.ts — Playwright configuration pre-wired for Checksum
  • tsconfig.json — TypeScript configuration for the test directory
  • Login helper — a reusable authentication setup
  • Example test — a starter test file to verify everything works
Prerequisites: Install the runtime package first: 
npm install @checksum-ai/runtime

​
test

npx checksumai test
Runs your Checksum tests locally using Playwright. Flags
FlagDescription
-g "pattern"Run only tests whose name matches the given pattern
--cksm-auto-healAfter the run finishes, automatically heal any failing tests. When the run has failures, Checksum analyzes them and (by default) opens a PR with the fixes
--cksm-auto-heal-create-pr[=false]Whether healing opens a pull request with the fixes. Defaults to true when --cksm-auto-heal is set; pass =false to dispatch healing without creating a PR
--cksm-auto-heal-repo-name=<owner>/<repo>Repository that hosts the source PR for healing progress comments (usually app-code). Auto-detected from the CI environment when omitted
--cksm-auto-heal-branch=<branch>Branch in the tests repository that the healed PR targets. Auto-detected from the CI environment when omitted
--cksm-auto-heal-pr-number=<number>Existing pull request to post healing progress on. Auto-detected for pull-request CI events when omitted
In GitHub Actions and GitLab CI, the repository, branch, and pull-request number are detected automatically from the CI environment — --cksm-auto-heal on its own is usually all you need.
Examples 
# Run all tests
npx checksumai test

# Run tests matching "login"
npx checksumai test -g "login"

# Run tests and auto-heal failures in CI (repo/branch/PR auto-detected)
npx checksumai test --cksm-auto-heal

# Heal failures but don't open a PR
npx checksumai test --cksm-auto-heal --cksm-auto-heal-create-pr=false

​
Affected tests only (--cksm-affected)

Run only the Checksum tests impacted by files changed since a git base ref. The CLI:
  1. Computes changed files between your current checkout and the base ref
  2. Asks Checksum which tests are affected by those files
  3. Runs Playwright with an internal --grep over those test IDs
# Compare against origin/main (default branch resolved automatically when omitted in local dev)
npx checksumai test --cksm-affected=origin/main

# Shorthand — enabled without an explicit ref (uses CI base branch when available)
npx checksumai test --cksm-affected
Flags
FlagDescription
--cksm-affected[=<ref>]Enable affected-test selection. Optional git ref (branch, tag, or SHA). In GitHub Actions / GitLab CI, defaults to the PR/MR target branch when no ref is passed
--cksm-affected-dry-runPrint the resolved changed files and affected test IDs, then exit without running Playwright. Can be used without --cksm-affected
CI examples 
# GitHub Actions — base ref auto-detected from GITHUB_BASE_REF
npx checksumai test --cksm-affected

# GitLab merge request — base ref auto-detected from CI_MERGE_REQUEST_TARGET_BRANCH_NAME
npx checksumai test --cksm-affected
Constraints
  • Cannot be combined with -g / --grep (affected mode sets grep internally)
  • Cannot be combined with --cksm-rerun-failed
  • Shallow clones without enough history may fail — fetch depth must include the merge base with your target ref
Use --cksm-affected-dry-run in CI to log which tests would run before enabling the flag on pull-request workflows.

​
Re-run non-passing tests (--cksm-rerun-failed)

Re-run only the test files that did not pass in a previous Checksum run (failed or recovered), without executing the full suite. 
# Re-run non-passing tests from the latest completed non-manual run
npx checksumai test --cksm-rerun-failed

# Re-run non-passing tests from a specific test run (UUID)
npx checksumai test --cksm-rerun-failed=<test-run-id>
FlagDescription
--cksm-rerun-failedUse the latest completed non-manual run from the API (GET /public-api/v1/test-runs/latest)
--cksm-rerun-failed=<id>Use the given test run UUID
Checksum fetches per-test results from the API, resolves failing file paths, and passes them to Playwright. If every test in the run passed, the command exits successfully with nothing to run. Constraints
  • Cannot be combined with --cksm-affected or -g / --grep
Example 
# After a CI run failed, retry only the failing specs locally
npx checksumai test --cksm-rerun-failed

​
dotenv

npx checksumai dotenv --download --api-key=<KEY>
Downloads environment variables from Checksum cloud and saves them to a local .env file. This is useful for syncing secrets and configuration that your tests depend on without committing them to source control. Flags
FlagDescription
--downloadDownload the environment variables
--api-key=<KEY>Your Checksum API key

​
tsconfig

npx checksumai tsconfig
Adds or updates the tsconfig.json file inside the checksum/ directory. Run this if you need to reset or refresh the TypeScript configuration after an upgrade.

​
eslint

npx checksumai eslint
Adds an ESLint configuration to the checksum/ directory. When run, it will optionally install the required devDependencies:
  • eslint
  • typescript
  • typescript-eslint

​
show-report

npx checksumai show-report
Opens the HTML test report from your most recent local test run in your default browser.

​
postinstall

npx checksumai postinstall
Runs post-installation setup. This is typically called automatically after npm install and does not need to be run manually in most cases.

​
Configuration

The checksum.config.ts file in your checksum/ directory controls project-level settings such as the base URL, browser options, authentication flows, and more. For the full configuration reference, see Repo & CLI Setup.