Skip to content

Commit c1d817e

Browse files
juancguerrerodevclaude
juancguerrerodev
and
claude
committed
docs: rewrite README with marketing copy, SEO optimization, and comparison table
World-class README matching code-sensei conventions: - Problem → Insight → Solution narrative structure - Shield badges (Claude Code Plugin, MIT, Testing, Open Source) - Competitive comparison table vs Percy/Chromatic/Applitools - Full installation, configuration, and CI setup docs - Pre-filter tier explanation with zero false-negative guarantee - Storybook and Supabase integration docs - Project structure with component descriptions - Contributing section and Dojo Coding attribution - SEO: visual regression testing, Playwright, pixelmatch, Claude Code, GitHub Actions, screenshot diff, open source, free Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent fc745d9 commit c1d817e

File tree

1 file changed

+216
-55
lines changed

1 file changed

+216
-55
lines changed

‎README.md‎

Lines changed: 216 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,59 +1,137 @@
1-
# DojoWatch
1+
# DojoWatch — AI-Native Visual Regression Testing
22

3-
AI-native visual regression testing engine. Captures screenshots with Playwright, pre-filters with pixelmatch, and uses LLM vision as the diff engine — Claude locally, Gemini in CI.
3+
[![Claude Code Plugin](https://img.shields.io/badge/Claude_Code-Plugin-blue?logo=anthropic&logoColor=white)](https://github.com/DojoCodingLabs/dojowatch)
4+
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
5+
[![Category: Testing](https://img.shields.io/badge/Category-Testing-purple)](https://github.com/topics/claude-code-plugin)
6+
[![Free & Open Source](https://img.shields.io/badge/Free-Open_Source-brightgreen)](https://github.com/DojoCodingLabs/dojowatch)
47

5-
**Zero incremental cost.** Uses models you already pay for (Claude Code subscription, Gemini free-tier tokens) and infrastructure already in place (GitHub Actions).
8+
### Open-source visual regression testing that uses AI to tell you *what* changed, *why*, and *how to fix it* — by [Dojo Coding](https://dojocoding.io)
69

7-
## How it works
10+
**DojoWatch** is a **Claude Code plugin** and **GitHub Actions CI tool** that catches visual regressions before they reach production. Unlike Percy, Chromatic, or Applitools — it costs nothing. It uses the AI models you already have.
11+
12+
---
13+
14+
## The Problem
15+
16+
Visual regressions reach production because:
17+
18+
- **No one tests visually.** Manual QA can't keep up with multiple deploys per day.
19+
- **Commercial tools are expensive.** Percy starts at $500/mo. Chromatic at $149/mo. Applitools at $1K+/mo. For an early-stage team, that's unjustifiable.
20+
- **Pixel-diff tools generate noise, not insight.** A red overlay of 10,000 changed pixels doesn't tell you *what broke* or *how to fix it*.
21+
22+
## The Insight
23+
24+
Claude Code is already multimodal. It can look at a screenshot *and* read your source code in the same context. It doesn't just see that pixels changed — it can trace the regression to the exact CSS property on the exact line.
25+
26+
No API keys. No per-screenshot pricing. No context-switching to a separate dashboard.
27+
28+
## The Solution
29+
30+
DojoWatch captures screenshots with Playwright, pre-filters with pixelmatch (to avoid wasting tokens on unchanged pages), and uses AI vision to classify every visual change:
31+
32+
- **REGRESSION** — an unintended visual change (bug). Severity: high / medium / low.
33+
- **INTENTIONAL** — a deliberate change (new feature, design update).
34+
- **NOISE** — insignificant rendering variance (sub-pixel anti-aliasing).
35+
36+
Locally, Claude Code *is* the AI engine — zero cost. In CI, Gemini handles batch analysis and posts PR comments.
37+
38+
---
39+
40+
## How It Works
841

942
```
1043
Source change → Playwright capture → pixelmatch pre-filter → AI analysis → Report
11-
│ │
12-
SKIP (identical) REGRESSION / INTENTIONAL / NOISE
44+
│ │
45+
SKIP (identical) REGRESSION / INTENTIONAL / NOISE
46+
0 tokens, ~1ms Claude reads images + source code
1347
```
1448

15-
- **Locally**: Claude Code is the AI engine. It reads screenshots + source code in the same context and traces regressions to the exact line of code.
16-
- **In CI**: Gemini 3.1 Pro batch-analyzes screenshot pairs and posts PR comments with regression summaries.
49+
**Locally (Claude Code plugin):**
50+
1. You run `/vr-check`
51+
2. Playwright captures your routes at configured viewports
52+
3. pixelmatch compares against baselines — identical screenshots are skipped instantly
53+
4. Claude reads the changed screenshots *and* the source files that render them
54+
5. You get natural-language analysis: what changed, why, severity, and a suggested fix
55+
6. You can ask follow-up questions: *"Why did the card shadow change?"* — Claude reads the CSS and answers
56+
57+
**In CI (GitHub Actions):**
58+
1. PR triggers the workflow
59+
2. Same capture + prefilter pipeline
60+
3. Gemini 3.1 Pro batch-analyzes screenshot pairs (20-30 per API call)
61+
4. A structured PR comment appears with a regression table, diff thumbnails, and fix suggestions
62+
5. High-severity regressions fail the check. Everything else is informational.
1763

18-
## Install
64+
---
1965

20-
### As a Claude Code plugin
66+
## Pre-Filter: Zero False Negatives, Zero Wasted Tokens
67+
68+
The tiered pre-filter ensures you never pay for analysis you don't need — and never miss a regression:
69+
70+
| Tier | Condition | Action | Token Cost |
71+
|------|-----------|--------|------------|
72+
| **SKIP** | SHA-256 identical OR 0 diff pixels | No AI call | 0 |
73+
| **FAST_CHECK** | 1-500 scattered pixels, no clusters | Low-depth analysis | ~600 |
74+
| **FULL_ANALYSIS** | 500+ pixels or spatially clustered | Full analysis | ~2,400 |
75+
76+
**The guarantee:** Only byte-identical screenshots are skipped. Every other screenshot — even a single changed pixel — is analyzed. The tiers control *depth*, not *whether analysis occurs*.
77+
78+
---
79+
80+
## Installation
81+
82+
### Claude Code Plugin (recommended)
2183

2284
```bash
23-
# From GitHub (recommended)
24-
claude plugin add --git https://github.com/DojoCodingLabs/dojowatch
85+
claude plugin marketplace add DojoCodingLabs/dojowatch
86+
claude plugin install dojowatch@dojowatch
87+
```
2588

26-
# Local development
27-
claude --plugin-dir /path/to/dojowatch
89+
That's it. Run `/vr-init` in any project to get started.
90+
91+
> **Requires:** [Claude Code](https://code.claude.com) with plugin support.
92+
> Scripts use [Playwright](https://playwright.dev) — install browsers with `npx playwright install chromium`.
93+
94+
### Updating
95+
96+
```bash
97+
claude plugin marketplace update DojoCodingLabs/dojowatch
98+
claude plugin update dojowatch@dojowatch
2899
```
29100

30-
### For CI
101+
Restart your Claude Code session after updating.
31102

32-
Clone or add as a git submodule. The CI scripts run standalone via `npx tsx`.
103+
### For CI Only
33104

34-
## Quick start
105+
Clone or add as a git submodule. CI scripts run standalone via `npx tsx`.
35106

36-
1. **Initialize** — run `/vr-init` in Claude Code. This detects your framework, discovers routes, and creates initial baselines.
107+
---
37108

38-
2. **Make changes** — edit your UI code as usual.
109+
## Quick Start
39110

40-
3. **Check for regressions** — run `/vr-check`. Claude captures fresh screenshots, compares them against baselines, and reports any visual differences with classification and severity.
111+
```
112+
1. /vr-init → Detect framework, discover routes, capture baselines
113+
2. Make UI changes → Edit CSS, components, layouts — whatever you're working on
114+
3. /vr-check → Capture → prefilter → Claude analyzes the diffs
115+
4. /vr-approve → Promote intentional changes to new baselines
116+
```
41117

42-
4. **Approve changes** — run `/vr-approve` to promote intentional changes to new baselines.
118+
---
43119

44-
## Slash commands
120+
## Commands
45121

46-
| Command | Description |
122+
| Command | What it does |
47123
|---------|-------------|
48-
| `/vr-init` | Initialize DojoWatch: generate config, discover routes, create baselines |
49-
| `/vr-check` | Full pipeline: capture → prefilter → AI analysis |
50-
| `/vr-check --fast` | Quick check: pixelmatch only, no AI analysis |
51-
| `/vr-check --scope branch` | Check only routes affected by branch changes |
52-
| `/vr-approve` | Promote current captures to baselines |
53-
| `/vr-report` | Generate a shareable markdown summary of the last check |
54-
| `/vr-watch` | Watch mode with live re-capture (coming soon) |
124+
| `/dojowatch:vr-init` | Initialize DojoWatch: detect framework, discover routes, create baselines |
125+
| `/dojowatch:vr-check` | Full pipeline: capture, prefilter, AI analysis with natural-language results |
126+
| `/dojowatch:vr-check --fast` | Quick check: pixelmatch only, no AI analysis (~2s) |
127+
| `/dojowatch:vr-check --scope branch` | Check only routes affected by current branch changes |
128+
| `/dojowatch:vr-approve` | Review and promote current captures to baselines |
129+
| `/dojowatch:vr-report` | Generate a shareable markdown summary of the last check |
130+
| `/dojowatch:vr-watch` | Watch mode: re-capture on file save (coming soon) |
55131

56-
## CI setup (GitHub Actions)
132+
---
133+
134+
## CI Setup (GitHub Actions)
57135

58136
Copy `templates/visual-regression.yml` to your project's `.github/workflows/`:
59137

@@ -75,15 +153,19 @@ jobs:
75153
- name: Start dev server
76154
run: npm run dev &
77155
- name: Wait for server
78-
run: npx wait-on http://localhost:3000
156+
run: npx wait-on http://localhost:3000 --timeout 60000
79157
- name: Run DojoWatch
80-
run: npx tsx path/to/dojowatch/scripts/ci.ts --pr ${{ github.event.pull_request.number }}
158+
run: npx tsx path/to/dojowatch/scripts/ci.ts --pr ${{ github.event.pull_request.number }} --upload
81159
env:
82160
GOOGLE_GENAI_API_KEY: ${{ secrets.GOOGLE_GENAI_API_KEY }}
83161
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
84162
continue-on-error: true
85163
```
86164
165+
The `--upload` flag pushes results to Supabase (optional). Without it, analysis runs locally and posts the PR comment.
166+
167+
---
168+
87169
## Configuration
88170

89171
DojoWatch is configured via `.dojowatch/config.json` at your project root:
@@ -98,48 +180,127 @@ DojoWatch is configured via `.dojowatch/config.json` at your project root:
98180
{ "name": "mobile", "width": 375, "height": 812 }
99181
],
100182
"routes": ["/", "/dashboard", "/settings"],
101-
"maskSelectors": ["[data-vr-mask]", ".live-timestamp"],
102-
"prefilter": {
103-
"threshold": 0.05,
104-
"clusterMinPixels": 500
105-
}
183+
"maskSelectors": ["[data-vr-mask]", ".live-timestamp"]
106184
}
107185
```
108186

109-
### Masking dynamic content
187+
### Masking Dynamic Content
110188

111-
Add `data-vr-mask` to elements that change between captures (timestamps, user avatars, live counters):
189+
Add `data-vr-mask` to elements that change between captures — timestamps, avatars, live counters:
112190

113191
```html
114192
<span data-vr-mask>March 27, 2026</span>
115193
```
116194

117-
## Architecture
195+
DojoWatch replaces masked elements with solid placeholders before capture, preventing false positives.
196+
197+
### Storybook Support
198+
199+
Point `storybookUrl` at your Storybook instance. DojoWatch crawls `stories.json`, captures every story in isolation, and provides component-level regression detection — equivalent to Chromatic's core offering.
200+
201+
### Supabase Integration (Optional)
202+
203+
Add `supabase` to your config to enable shared baselines and historical tracking:
204+
205+
```json
206+
{
207+
"supabase": {
208+
"url": "https://your-project.supabase.co",
209+
"anonKey": "your-anon-key",
210+
"serviceKeyEnv": "SUPABASE_SERVICE_KEY"
211+
}
212+
}
213+
```
214+
215+
This eliminates git bloat from baseline PNGs, enables shared baselines across your team, and stores run history with diff images accessible via signed URLs.
216+
217+
---
218+
219+
## What's Included
118220

119221
```
120222
dojowatch/
121-
├── commands/ # Claude Code slash commands
122-
├── agents/ # Regression analyzer agent
123-
├── skills/ # Visual regression skill + references
124-
├── scripts/ # Core TypeScript scripts (capture, prefilter, analyze)
125-
├── templates/ # Config example, GitHub Actions workflow
126-
└── tests/ # Vitest tests + fixtures
223+
├── .claude-plugin/
224+
│ ├── plugin.json # Plugin metadata
225+
│ └── marketplace.json # Marketplace catalog
226+
├── commands/ # 5 slash commands
227+
│ ├── vr-init.md # /dojowatch:vr-init
228+
│ ├── vr-check.md # /dojowatch:vr-check
229+
│ ├── vr-approve.md # /dojowatch:vr-approve
230+
│ ├── vr-report.md # /dojowatch:vr-report
231+
│ └── vr-watch.md # /dojowatch:vr-watch
232+
├── agents/
233+
│ └── regression-analyzer.md # Root-cause analysis agent
234+
├── skills/
235+
│ └── visual-regression/ # Auto-activating VR skill
236+
│ ├── SKILL.md
237+
│ └── references/
238+
│ ├── classification-schema.md
239+
│ └── analysis-prompt.md
240+
├── scripts/ # Core engine (TypeScript)
241+
│ ├── capture.ts # Playwright capture engine
242+
│ ├── stabilize.ts # Animation freeze, masking
243+
│ ├── prefilter.ts # pixelmatch tiered classification
244+
│ ├── baseline.ts # Baseline management
245+
│ ├── analyze-gemini.ts # Gemini batch analysis (CI)
246+
│ ├── comment.ts # PR comment generator
247+
│ ├── ci.ts # CI orchestrator
248+
│ ├── supabase.ts # Supabase data layer
249+
│ ├── config.ts # Config loader
250+
│ ├── route-map.ts # Source → route resolver
251+
│ └── types.ts # Shared TypeScript types
252+
├── migrations/
253+
│ └── 001_initial_schema.sql # Supabase schema
254+
├── templates/
255+
│ ├── config.example.json # Example configuration
256+
│ └── visual-regression.yml # GitHub Actions template
257+
└── tests/ # 44 tests (unit + integration)
127258
```
128259
129-
## Pre-filter tiers
260+
---
130261
131-
| Tier | Condition | Action | Cost |
132-
|------|-----------|--------|------|
133-
| SKIP | SHA-256 match OR 0 diff pixels | No analysis | 0 tokens |
134-
| FAST_CHECK | 1-500 scattered pixels | Low-depth analysis | ~600 tokens |
135-
| FULL_ANALYSIS | 500+ pixels or clustered | Full analysis | ~2400 tokens |
262+
## How DojoWatch Compares
136263
137-
**Zero false-negative guarantee**: Only byte-identical or zero-diff screenshots are skipped.
264+
| | DojoWatch | Percy | Chromatic | Applitools |
265+
|---|---|---|---|---|
266+
| **Cost** | $0 | $500-1K/mo | $149-399/mo | $1-2K/mo |
267+
| **AI analysis** | Claude + Gemini | Pixel diff only | Pixel diff only | AI (proprietary) |
268+
| **Natural language** | "Header padding reduced by 8px" | Red overlay | Red overlay | Some |
269+
| **Source code tracing** | Traces to exact CSS line | No | No | No |
270+
| **Local analysis** | Claude Code (free) | Cloud only | Cloud only | Cloud only |
271+
| **CI integration** | GitHub Actions | GitHub Actions | GitHub Actions | GitHub Actions |
272+
| **Storybook** | Full crawl | Full crawl | Full crawl | Full crawl |
273+
| **Open source** | MIT | No | No | No |
274+
275+
---
138276
139277
## Contributing
140278
279+
DojoWatch is open source and contributions are welcome:
280+
281+
- **Better classification prompts** — improve the AI analysis accuracy
282+
- **Framework detection** — add route discovery for more frameworks
283+
- **Performance** — optimize capture parallelization and prefilter speed
284+
- **New viewports** — add common device presets
285+
- **Bug fixes** — found an issue? Open a PR
286+
141287
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
142288
289+
---
290+
291+
## Built by Dojo Coding
292+
293+
[Dojo Coding](https://dojocoding.io) is a LATAM-first tech ecosystem building tools for developers. DojoWatch was built to serve our multi-SBU product portfolio — then open-sourced because every team deserves visual regression testing, not just those with enterprise budgets.
294+
295+
---
296+
143297
## License
144298
145-
MIT — see [LICENSE](LICENSE).
299+
MIT License — free to use, modify, and distribute.
300+
301+
---
302+
303+
<p align="center">
304+
<strong>Stop shipping visual regressions. Start shipping with confidence.</strong><br>
305+
<em>Free. Open source. By <a href="https://dojocoding.io">Dojo Coding</a>.</em>
306+
</p>

0 commit comments

Comments
 (0)