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 --lockedFrom a local checkout:
cargo install --path . --lockedThe 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 buninit writes:
Coatcheck.toml;- a private
package.jsonwhen the project does not already have one; coatcheck/example.spec.ts;- a
.coatcheck/ignore entry; - exact project-local
@playwright/testand@axe-core/playwrightdevelopment 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 150doctorvalidates configuration, Bun, project-local Playwright and Axe, Chromium, and reports whether the host is reachable.doctor --fixinstalls or repairs the JavaScript dependencies and Chromium.devrunshost.commandin the foreground.teststarts 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-hostuses 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§
- Catalog
Error - Structural errors in a story catalog.
- Control
Kind - The editor used to change a story argument.
- Story
Kind - 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.