Skip to main content

Screen states, markScreenState, and ExploreChimp

What are screens and states?​

  • Screen — A distinct page or view in your application (for example Login, Dashboard, Checkout).
  • State — A meaningful configuration of that screen (for example empty form, error displayed, cart with items).

Stable screen–state names are how TestChimp attributes UX findings (from ExploreChimp, exploratory agents, and Atlas) to the right place in the product. They should match your project Atlas vocabulary where possible—use list-screen-states / upsert-screen-states (MCP or product) so names stay consistent.

Canonical: markScreenState Playwright fixture​

New SmartTests and agent-authored tests should use the markScreenState fixture only—not legacy line comments (see Legacy comment annotations below).

How it works​

  1. installTestChimp from @testchimp/playwright/runtime is applied to your merged test in tests/fixtures/index.js (often with mergeTests). That registers markScreenState on the same test instance specs import—never import test from @playwright/test in *.spec.* files if you rely on TestChimp runtime behaviour.

  2. In each UI test, declare the fixture on the callback: async ({ page, markScreenState }) => { ... }.

  3. After the UI has settled on a meaningful boundary, call:

    await markScreenState('Login', 'Empty form');
    • First argument — Screen name (Atlas-aligned).
    • Second argument — State name; optional — omit for a default state, for example await markScreenState('Dashboard').

  4. Order matters — Data for the interval since the previous markScreenState is attributed to that previous checkpoint; screenshot + DOM (+ related signals) attach to the current checkpoint.

  5. Do not over-mark: skip loading spinners and transient overlays; mark only durable states your team cares to regress against.

Example​

import { test, expect } from '../fixtures';

test('checkout happy path', async ({ page, markScreenState }) => {
  await page.goto('/cart');
  await markScreenState('Cart', 'With items');

  await page.getByRole('link', { name: 'Checkout' }).click();
  await expect(page.getByRole('heading', { name: 'Checkout' })).toBeVisible();
  await markScreenState('Checkout', 'Shipping step');
});

Why this matters for ExploreChimp​

ExploreChimp (optional /testchimp test Phase 5, /testchimp evolve, or /testchimp explore) sends checkpointed analytics—DOM, screenshots, console, optional network and metrics—along the same journeys as your SmartTests. Without markScreenState, there is little structure for the pipeline to attribute issues to. See /testchimp explore and the runtime plugin.

Naming: Prefer installTestChimp; installTrueCoverage is a deprecated alias (same implementation) in older repos.

Workflow with Atlas (agents and teams)​

When authoring or reviewing UI tests:

  1. list-screen-states — See existing vocabulary before inventing new names.
  2. upsert-screen-states — Add new screen–state pairs when the product introduces new surfaces.
  3. Add await markScreenState(...) immediately after the step that establishes each stable state.

During /testchimp test, this sequence aligns with Phase 4: Validate in the skill workflow.

Legacy comment annotations​

Older specs may use line comments after steps:

await page.goto('https://example.com/login');
// @screen: Login @state: Empty form

That format can still be parsed on legacy code, but do not add it to new tests—use the markScreenState fixture so Playwright, TrueCoverage, and ExploreChimp share one code path.

Product note: Some Web IDE flows (for example “Update Script Annotations”) may still talk in terms of comments; prefer migrating those outputs to markScreenState when you touch the file.

Best practices (summary)​

  1. Atlas first — Align names with list-screen-states / upsert-screen-states.
  2. Mark after stability — Wait for navigation, network idle, or assertions that prove the UI is ready.
  3. Granularity — Define states at the level you want bugs grouped (for example Cart with out-of-stock item vs a single Cart state) depending on product risk.
  4. ExploreChimp last — Turn on EXPLORECHIMP_ENABLED only when functional tests and Validate-quality markers are trustworthy, so analytics map to real product states.

For deeper authoring rules used by agents, see the TestChimp skill → references/write-smarttests.md.