Skip to main content

Story Files (.checksum.md)

Story files describe the test scenario in a structured markdown format with YAML frontmatter. They serve as the source of truth for what the test does.

Example

Frontmatter Fields

Sections

  • Data Setup — How to prepare test data before the test runs (API calls, database seeds)
  • Data Cleanup — How to clean up after the test (delete created records)
  • Steps — The test steps with actions the user takes and verifications to check

Test Files (.checksum.spec.ts)

Test files are standard Playwright TypeScript tests. They’re generated from the story file and can be run with the Checksum CLI or directly with Playwright.

Checksum Fixtures

Tests use Checksum fixtures (init() from @checksum-ai/runtime) which provide automatic healing, smart selector recovery, report uploading, and a variable store for sharing data between steps. However, tests are pure Playwright under the hood — you can run them with vanilla Playwright by replacing the Checksum imports with standard Playwright imports.

Page Object Model

Generated tests can also use the Page Object Model pattern for better organization:

Example

Key Characteristics

  • Built on Playwright — Tests use Playwright under the hood via the @checksum-ai/runtime wrapper, which adds Checksum-specific features (auto-recovery, reporting, variable store).
  • Grounded selectors — Checksum grounds selectors in your actual app code (using data-testid, role attributes, text content) rather than guessing.
  • defineChecksumTest — Wraps each test with a name and Checksum test ID for tracking and reporting.
  • Variable store (vs) — A shared store for passing data between test steps (e.g., created record IDs for cleanup).
  • Web-first assertions — Uses Playwright’s built-in assertions (toBeVisible(), toHaveText()) that automatically retry.

Running Generated Tests

You can run generated tests locally or in CI:
See Checksum CLI for more details on running tests.