coatcheck 0.2.1

Contracts and a Playwright accessibility runner for Topcoat component workbenches.
Documentation

Coatcheck

Coatcheck is a component workbench contract and semantic browser-test runner for Topcoat.

The library models stories, typed props, controls, scenes, manifests, and isolated frames. The installable coatcheck binary turns a host manifest into explicit Playwright and Axe tests. It produces screenshots for review, but it does not store or compare pixel baselines.

Install

After the 0.2 release is available from crates.io:

cargo install coatcheck --locked

From a local checkout:

cargo install --path . --locked

The crate package includes Cargo.lock and every runtime scaffold template, so the locked install does not depend on repository-only files.

Start a project

From the project that hosts the Topcoat workbench:

coatcheck init --package-manager bun

init writes:

  • Coatcheck.toml;
  • a private package.json when the project does not already have one;
  • coatcheck/example.spec.ts;
  • a .coatcheck/ ignore entry;
  • exact project-local @playwright/test and @axe-core/playwright development dependencies;
  • Playwright Chromium.

It does not replace an existing JavaScript package manifest. Use --skip-install when scaffolding offline.

Configure the host

version = 1
name = "Cold Front"

[host]
command = ["topcoat", "dev"]
url = "http://127.0.0.1:3000"
health = "/health"
manifest = "/__coatcheck/manifest.json"
startup_timeout_seconds = 30

[test]
story_globs = ["coatcheck/**/*.spec.ts"]
artifacts = ".coatcheck/artifacts"
timeout_ms = 30000
axe_impacts = ["serious", "critical"]

host.command is an argument array and is executed directly, without a shell. The generated configuration uses topcoat dev so asset bundles and live reload behave exactly as they do during application development. This keeps quoting deterministic and makes the process boundary explicit.

Commands

coatcheck doctor
coatcheck doctor --fix
coatcheck dev
coatcheck test
coatcheck test --no-host
coatcheck test --headed
coatcheck test --headed --story route-option --slow-mo 150
  • doctor validates configuration, Bun, project-local Playwright and Axe, Chromium, and reports whether the host is reachable.
  • doctor --fix installs or repairs the JavaScript dependencies and Chromium.
  • dev runs host.command in the foreground.
  • test starts the host, waits for health, fetches the manifest, generates explicit tests under .coatcheck/generated, runs generated and custom specs, and stops the host.
  • test --no-host uses an already-running host.

The generated semantic gate checks navigation, frame root/readiness/error markers, uncaught page and console errors, and the configured Axe impacts. Each case writes a PNG, DOM, Axe JSON, and console JSON. Playwright also writes HTML, JSON, and failure traces. See the runner contract.

Host API

Versioned JSON and frame types are additive to the 0.1 static catalog:

use coatcheck::{
    Catalog,
    contract::{FrameContractV1, ManifestV1},
};

fn manifest(catalog: Catalog) -> ManifestV1 {
    ManifestV1::from_catalog(catalog, FrameContractV1::default())
}

The default host endpoints are:

GET /__coatcheck/manifest.json
GET /__coatcheck/frame?story=<story-id>&scene=<scene-id>

The manifest owns the actual frame path, query names, and DOM selectors. Detailed producer/consumer requirements are in the host contract.

Static catalog API

The allocation-free 0.1 API remains available:

use coatcheck::{ArgType, Catalog, ControlKind, Story, StoryKind};

const LABEL: ArgType = ArgType {
    name: "label",
    type_name: "String",
    control: ControlKind::Text,
    default_value: "Continue",
    description: "Visible action copy.",
    options: &[],
};

const STORIES: &[Story] = &[Story {
    id: "action-link",
    title: "Action link",
    tier: "Atoms",
    kind: StoryKind::Playground,
    description: "A navigational action.",
    source: "src/atoms.rs",
    args: &[LABEL],
}];

const CATALOG: Catalog = Catalog::new("Example", STORIES);

assert!(CATALOG.validate().is_ok());

Repository navigation

Every tracked, human-maintained folder is linked here:

  • .github/ — automation documentation.
  • .github/workflows/ — CI and locked-install smoke checks.
  • docs/ — host and runner coordination contracts.
  • src/ — library contracts, config, generation, and CLI.
  • templates/ — files embedded in the installable binary.
  • tests/ — process-level CLI integration tests.

Status

Coatcheck is experimental and tracks Topcoat’s early-stage development. Manifest and frame versions are explicit so future schemas can be added without changing the 0.1 static story model.

License

MIT