# Coatcheck
Coatcheck is a component workbench contract and semantic browser-test runner
for [Topcoat](https://github.com/tokio-rs/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:
```sh
cargo install coatcheck --locked
```
From a local checkout:
```sh
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:
```sh
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
```toml
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
```sh
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](docs/runner.md).
## Host API
Versioned JSON and frame types are additive to the 0.1 static catalog:
```rust
use coatcheck::{
Catalog,
contract::{FrameContractV1, ManifestV1},
};
fn manifest(catalog: Catalog) -> ManifestV1 {
ManifestV1::from_catalog(catalog, FrameContractV1::default())
}
```
The default host endpoints are:
```text
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](docs/contracts.md).
## Static catalog API
The allocation-free 0.1 API remains available:
```rust
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/`](.github/) — automation documentation.
- [`.github/workflows/`](.github/workflows/) — CI and locked-install smoke
checks.
- [`docs/`](docs/) — host and runner coordination contracts.
- [`src/`](src/) — library contracts, config, generation, and CLI.
- [`templates/`](templates/) — files embedded in the installable binary.
- [`tests/`](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