tuffgal

Tuffgal

JSON-driven visual regression testing for web apps.

Status: Pre-1.0. Published on npm as tuffgal@0.1.0-alpha.{n} with provenance. Linklater is the pilot consumer.

Public API is unstable until v1.0.0.

The idea

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.

What ships in v1

• 9 step primitives composed into actions: click, input, intercept, navigate, read, scroll, type, wait, waitFor
• An implicit screenshot at the end of every action
• Named breakpoint modes (mobile, tablet, laptop, desktop) keyed to Tailwind widths. Pick which to run per project or per story. Each mode gets its own baseline and a per-mode group in the HTML report
• DAG scheduler with needs/produces labels 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
• V8 coverage (optional via monocart-coverage-reports)
• Per-run DB reset + per-breakpoint fixture hooks (consumer-supplied via config), plus a ${breakpoint} interpolation token for per-mode test data
• Process supervisor for dev-server hot-reload rot (it happens)

What's explicitly out of scope (v1)

• 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

Quick start

npm install -D tuffgal@alpha
npx tuffgal init  # scaffolds tuffgal.config.ts
npx tuffgal run   # runs all stories

For CI on GitHub Actions, use the companion nschneble/tuffgal-action composite action.

Documentation

• App contract
• Authoring guide
• Changelog
• CI integration
• CLI reference
• Config reference
• Migrating from Cypress
• Migrating from Playwright
• Product requirements
• Reporting data (results.json)
• Supervisor

License

MIT. See LICENSE.

Roadmap

Acknowledgements

The Tuffgal logo is an illustration by Art Attack on Unsplash.