JSON-driven visual regression testing for web apps.
Status: Pre-1.0. Published on npm as tuffgal@0.1.0-alpha.3 with
provenance. Linklater is the
pilot consumer.
Public API is unstable until v1.0.0.
Tuffgal sits between component tests (which are fast but mocked) and end-to-end tests (which are real but verbose). You write actions (atomic user steps) and stories (chains of actions) as pure JSON. The harness runs them in a real browser, captures a screenshot after each story, and pixel-diffs against a baseline you commit alongside your code.
When a screenshot changes, a human reviews the diff and decides what to do.
- 9 step primitives as action verbs:
click,input,intercept,navigate,read,scroll,type,wait,waitFor - An implicit screenshot at the end of every action
- DAG scheduler with
needs/produceslabels and parallel workers - SSIM-gated visual diff + pixelmatch overlay + a11y-tree snapshots
- Trace zip on failure (Playwright trace viewer)
- Clock freeze (
page.clock.install) - Storage-state persistence across stories
- Static HTML reporter + optional SARIF for GitHub code scanning
- V8 coverage (optional via
monocart-coverage-reports) - Per-story DB reset + fixture hooks (consumer-supplied via config)
- Process supervisor for dev-server hot-reload rot (it happens)
- AI fuzzy locator matching (deferred to v1.1, BYOLLM)
- Hosted SaaS / cloud runs
- Native mobile (Playwright cannot drive it)
- WebDriver / Puppeteer substrate
- Supporting browsers other than Chromium
npm install -D tuffgal@alpha
npx tuffgal init # scaffolds tuffgal.config.ts
npx tuffgal run # runs all storiesFor CI on GitHub Actions, use the companion
nschneble/tuffgal-action
composite action.
- App contract
- Authoring guide
- CI integration
- Config reference
- Migrating from Cypress
- Migrating from Playwright
- Product requirements
- Supervisor
MIT. See LICENSE.
| Milestone | Status |
|---|---|
| Repo bootstrap | ✅ |
| Core extraction | ✅ |
| Bridges | ✅ |
| Linklater migration | ✅ |
| GitHub Action | ✅ |
v0.1.0-alpha npm publish |
✅ |
v1.0.0 public launch |
⏳ |
v1.1.0 AI fuzzy matching |
Deferred |
The Tuffgal logo is an illustration by Art Attack on Unsplash.