Skip to main content

Crate coatcheck

Crate coatcheck 

Source
Expand description

§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

Modules§

config
Project configuration loaded from Coatcheck.toml.
contract
Versioned wire contracts shared by a Coatcheck host and runner.
runner
Deterministic Playwright generation from a version-1 host manifest.

Structs§

ArgType
Describes one editable or documented story argument.
Catalog
An allocation-free collection of registered stories.
Scene
A reusable pairing of viewport and surface.
Story
A named production-component state in a Coatcheck catalog.
Surface
A named canvas background or surface.
Viewport
A named canvas size in CSS pixels.

Enums§

CatalogError
Structural errors in a story catalog.
ControlKind
The editor used to change a story argument.
StoryKind
The intent of a story, modeled after useful Storybook story families.

Constants§

DEFAULT_SCENES
Useful default viewport and surface pairings.
DEFAULT_SURFACES
Neutral surface contracts that applications can map to their own tokens.
DEFAULT_VIEWPORTS
Mobile-first viewports adapted from the first Coatcheck reference application.

Functions§

validate
Checks the structural guarantees every Coatcheck catalog relies on.