@bughunters/vision 1.0.3 → 1.0.5

package/README.md

@@ -86,6 +86,25 @@ await vision.check(page, 'dashboard', 'Ignore the live timestamp in the top-righ
 await vision.check(page.locator('#sidebar'), 'sidebar');
 ```
 
+### Multi-step visual checks
+
+Call `vision.check()` multiple times within one test — each step gets its own baseline file, its own row in the HTML report, and its own annotation in the native Playwright report.
+
+```typescript
+test('checkout flow looks correct', async ({ page }) => {
+  await page.goto('https://shop.example.com/cart');
+  await vision.check(page, 'cart-page', 'Cart summary should be visible.');
+
+  await page.click('#checkout-btn');
+  await vision.check(page, 'shipping-form', 'Shipping form should be shown.');
+
+  await page.click('#next-btn');
+  await vision.check(page, 'payment-page', 'Payment options should be visible.');
+});
+```
+
+Each step produces isolated files (`<test-title>--<step-name>.baseline.png`) so steps from different tests never collide, even if you reuse step names like `"header"` across multiple tests.
+
 ### 5. Run your tests
 
 ```bash
@@ -111,6 +130,39 @@ The report includes side-by-side Baseline / Current / Diff views with full-scree
 
 ---
 
+## Terminal output
+
+BugHunters Vision keeps terminal output compact and linear — one line per step, no duplicates:
+
+```
+📸 [BugHunters Vision] Baseline created: cart-page
+✅ [BugHunters Vision] FAST PIXEL MATCH: shipping-form
+🔍 [BugHunters Vision] AI evaluating: payment-page (12 pixel(s) differ)…
+🤖 [BugHunters Vision] AI PASS: payment-page
+⚠️  [BugHunters Vision] AI error: header — Claude AI is temporarily overloaded.
+⏭  [BugHunters Vision] off: footer
+```
+
+When a check fails, a single clear error is thrown (no repeated messages):
+
+```
+Error: [BugHunters Vision] Visual regression detected in step "payment-page": Button label changed from "Pay now" to "Subscribe".
+```
+
+---
+
+## IDE & VS Code integration
+
+BugHunters Vision is fully compatible with the **VS Code Playwright extension** and **Playwright UI mode**.
+
+- Tests appear normally in the VS Code Test Explorer sidebar
+- `npx playwright test --list` works as expected
+- `npx playwright test --ui` works as expected
+
+This works because `vision` is a standalone object — not a custom fixture — so the native `import { test } from '@playwright/test'` is preserved.
+
+---
+
 ## Configuration reference
 
 Options can be set in `playwright.config.ts` under `use:` **or** via environment variables. The `use:` block takes precedence; env vars are the fallback.
@@ -144,10 +196,9 @@ BHV_MODE=off    npx playwright test
 
 After every run a report is generated at `bhv-report/index.html`. No upload, no cloud — everything is local.
 
-- **Summary bar** — total / passed / failed / baseline counts
+- **Summary bar** — total / passed / failed / baseline / error counts
 - **Baseline / Current / Diff** tab view per test — click any image for fullscreen zoom
 - **AI verdict** with human-readable explanation for every evaluated test
-- **Low Confidence FAIL** — amber tag when the AI detects a likely intentional change (A/B test, loading state) that a human should review
 - **Method badge** — `AI` · `PIXEL` · `NEW` — shows how each test was evaluated
 - **Light / Dark / System** theme toggle, persisted in `localStorage`
 

package/dist/check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../src/check.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAY,MAAM,kBAAkB,CAAC;AAOhE,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAKD,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,IAAI,CAEvD;AA+GD,wBAAsB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmJ/E"}
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../src/check.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAY,MAAM,kBAAkB,CAAC;AAOhE,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAKD,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,IAAI,CAEvD;AAoHD,wBAAsB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyJ/E"}

package/dist/check.js

@@ -122,19 +122,22 @@ function humanReadableApiError(raw) {
     }
     return raw;
 }
-async function pushToPlaywright(testInfo, status, reason, resolvedDir, baselineFile, currentFile) {
+function sanitize(s) {
+    return s.replace(/[^a-z0-9]/gi, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
+}
+async function pushToPlaywright(testInfo, stepName, status, reason, resolvedDir, baselineFile, currentFile) {
     if (!testInfo)
         return;
-    testInfo.annotations.push({ type: 'BugHunters Vision', description: `${status}: ${reason}` });
+    testInfo.annotations.push({ type: `BugHunters Vision - ${stepName}`, description: `${status}: ${reason}` });
     if (baselineFile) {
         const p = path.join(resolvedDir, baselineFile);
         if (fs.existsSync(p))
-            await testInfo.attach('bhv-baseline', { path: p, contentType: 'image/png' });
+            await testInfo.attach(`bhv-baseline [${stepName}]`, { path: p, contentType: 'image/png' });
     }
     if (currentFile) {
         const p = path.join(resolvedDir, currentFile);
         if (fs.existsSync(p))
-            await testInfo.attach('bhv-current', { path: p, contentType: 'image/png' });
+            await testInfo.attach(`bhv-current [${stepName}]`, { path: p, contentType: 'image/png' });
     }
 }
 async function runVisionCheck(opts) {
@@ -153,116 +156,122 @@ async function runVisionCheck(opts) {
     const token = projectUse['bvToken'] ?? process.env.BUGHUNTERS_VISION_TOKEN ?? undefined;
     // Mode: off → skip all visual testing immediately
     if (mode === 'off') {
-        console.log(`\n⏭  [BugHunters Vision] "${name}" — skipped (BHV_MODE=off)\n`);
+        console.log(`⏭  [BugHunters Vision] off: ${name}`);
         return;
     }
     const resolvedDir = path.resolve(process.cwd(), snapshotsDir);
     fs.mkdirSync(resolvedDir, { recursive: true });
-    const baselineFile = path.join(resolvedDir, `${name}.baseline.png`);
+    // Build unique, collision-free filenames scoped to both the test title and the step name.
+    // Format: <safe-test-title>--<safe-step-name>.baseline.png
+    const safeTitle = testInfo?.title ? sanitize(testInfo.title) : 'unknown';
+    const safeName = sanitize(name);
+    const filePrefix = `${safeTitle}--${safeName}`;
+    // Human-readable label used in the HTML report: "Test title › step name"
+    const testName = testInfo?.title ? `${testInfo.title} › ${name}` : name;
+    const baselinePath = path.join(resolvedDir, `${filePrefix}.baseline.png`);
     const currentBuffer = await target.screenshot();
-    if (!fs.existsSync(baselineFile) || updateBaseline) {
+    if (!fs.existsSync(baselinePath) || updateBaseline) {
         // First run — save as baseline
-        fs.writeFileSync(baselineFile, currentBuffer);
-        console.log(`\n📸 [BugHunters Vision] Baseline saved: ${baselineFile}`);
-        console.log('   ✅ Test PASSED (baseline created — no previous reference exists)\n');
+        fs.writeFileSync(baselinePath, currentBuffer);
+        console.log(`📸 [BugHunters Vision] Baseline created: ${name}`);
         (0, results_1.appendResult)(resolvedDir, {
-            testName: name,
+            testName,
             status: 'BASELINE_CREATED',
             reason: 'First run detected — screenshot saved as the new baseline.',
             method: null,
-            baselineFile: `${name}.baseline.png`,
+            baselineFile: `${filePrefix}.baseline.png`,
             currentFile: null,
             timestamp: new Date().toISOString(),
         });
-        await pushToPlaywright(testInfo, 'BASELINE_CREATED', 'First run — screenshot saved as the new baseline.', resolvedDir, `${name}.baseline.png`, null);
+        await pushToPlaywright(testInfo, name, 'BASELINE_CREATED', 'First run — screenshot saved as the new baseline.', resolvedDir, `${filePrefix}.baseline.png`, null);
         return;
     }
     // Baseline exists — run Fast Pixel Match first to save AI credits
-    const baselineBuffer = fs.readFileSync(baselineFile);
+    const baselineBuffer = fs.readFileSync(baselinePath);
     const diffPixels = (0, pixel_match_1.fastPixelMatch)(baselineBuffer, currentBuffer);
-    const currentFileName = `${name}.current.png`;
+    const currentFileName = `${filePrefix}.current.png`;
     fs.writeFileSync(path.join(resolvedDir, currentFileName), currentBuffer);
     if (diffPixels === 0) {
         // ✅ Pixel-perfect match — skip AI call entirely
-        console.log(`\n⚡ [BugHunters Vision] "${name}" — pixel-perfect match. Skipping AI call.`);
-        console.log('   ✅ Test PASSED (Fast Pixel Match)\n');
+        console.log(`✅ [BugHunters Vision] FAST PIXEL MATCH: ${name}`);
         (0, results_1.appendResult)(resolvedDir, {
-            testName: name,
+            testName,
             status: 'PASS',
             reason: 'Identical (Fast Pixel Match) — pixel-perfect match, no AI evaluation needed.',
             method: 'FAST_PIXEL_MATCH',
-            baselineFile: `${name}.baseline.png`,
+            baselineFile: `${filePrefix}.baseline.png`,
             currentFile: currentFileName,
             timestamp: new Date().toISOString(),
         });
-        await pushToPlaywright(testInfo, 'PASS', 'Pixel-perfect match — no AI evaluation needed.', resolvedDir, `${name}.baseline.png`, currentFileName);
+        await pushToPlaywright(testInfo, name, 'PASS', 'Pixel-perfect match — no AI evaluation needed.', resolvedDir, `${filePrefix}.baseline.png`, currentFileName);
         return;
     }
     // Pixels differ — behaviour depends on mode
     const diffLabel = diffPixels === -1 ? 'dimension mismatch' : `${diffPixels} pixel(s) differ`;
     if (mode === 'strict') {
         // strict: fail immediately without calling AI
-        console.log(`\n❌ [BugHunters Vision] "${name}" — ${diffLabel}. FAILED (strict mode — no AI call).\n`);
         (0, results_1.appendResult)(resolvedDir, {
-            testName: name,
+            testName,
             status: 'FAIL',
             reason: `Pixel mismatch detected (${diffLabel}). Strict mode — AI evaluation disabled.`,
             method: 'FAST_PIXEL_MATCH',
-            baselineFile: `${name}.baseline.png`,
+            baselineFile: `${filePrefix}.baseline.png`,
             currentFile: currentFileName,
             timestamp: new Date().toISOString(),
         });
-        await pushToPlaywright(testInfo, 'FAIL', `Pixel mismatch detected (${diffLabel}). Strict mode.`, resolvedDir, `${name}.baseline.png`, currentFileName);
-        (0, test_1.expect)(false, `[BugHunters Vision strict] Pixel mismatch: ${diffLabel}`).toBe(true);
+        await pushToPlaywright(testInfo, name, 'FAIL', `Pixel mismatch detected (${diffLabel}). Strict mode.`, resolvedDir, `${filePrefix}.baseline.png`, currentFileName);
+        (0, test_1.expect)(false, `[BugHunters Vision] Visual regression detected in step "${name}": ${diffLabel} (strict mode)`).toBe(true);
         return;
     }
     // ai mode — escalate to AI for intelligent evaluation
-    console.log(`\n🔍 [BugHunters Vision] "${name}" — ${diffLabel}. Sending to AI…`);
+    console.log(`🔍 [BugHunters Vision] AI evaluating: ${name} (${diffLabel})…`);
     let result;
     try {
         result = await callVisionApi(baselineBuffer.toString('base64'), currentBuffer.toString('base64'), prompt, apiUrl, token);
     }
     catch (err) {
         const reason = humanReadableApiError(err instanceof Error ? err.message : String(err));
-        console.log(`\n❌ [BugHunters Vision] ${reason}\n`);
         (0, results_1.appendResult)(resolvedDir, {
-            testName: name,
+            testName,
             status: 'FAIL',
             reason,
             method: 'AI',
-            baselineFile: `${name}.baseline.png`,
+            baselineFile: `${filePrefix}.baseline.png`,
             currentFile: currentFileName,
             timestamp: new Date().toISOString(),
         });
-        await pushToPlaywright(testInfo, 'FAIL', reason, resolvedDir, `${name}.baseline.png`, currentFileName);
-        throw err;
+        await pushToPlaywright(testInfo, name, 'FAIL', reason, resolvedDir, `${filePrefix}.baseline.png`, currentFileName);
+        throw new Error(`[BugHunters Vision] Visual regression detected in step "${name}": ${reason}`);
     }
     // ERROR: AI temporarily unavailable — record but do NOT fail the Playwright test
     if (result.status === 'ERROR') {
-        console.log(`\n⚠️  [BugHunters Vision] "${name}" — AI unavailable: ${result.reason}\n`);
+        console.log(`⚠️  [BugHunters Vision] AI error: ${name} — ${result.reason}`);
         (0, results_1.appendResult)(resolvedDir, {
-            testName: name,
+            testName,
             status: 'ERROR',
             reason: result.reason,
             method: 'AI',
-            baselineFile: `${name}.baseline.png`,
+            baselineFile: `${filePrefix}.baseline.png`,
             currentFile: currentFileName,
             timestamp: new Date().toISOString(),
         });
-        await pushToPlaywright(testInfo, 'ERROR', result.reason, resolvedDir, `${name}.baseline.png`, currentFileName);
+        await pushToPlaywright(testInfo, name, 'ERROR', result.reason, resolvedDir, `${filePrefix}.baseline.png`, currentFileName);
         return; // test stays green
     }
-    const icon = result.status === 'PASS' ? '✅' : '❌';
-    console.log(`${icon} [BugHunters Vision] ${result.status}: ${result.reason}\n`);
     (0, results_1.appendResult)(resolvedDir, {
-        testName: name,
+        testName,
         status: result.status,
         reason: result.reason,
         method: 'AI',
-        baselineFile: `${name}.baseline.png`,
+        baselineFile: `${filePrefix}.baseline.png`,
         currentFile: currentFileName,
         timestamp: new Date().toISOString(),
     });
-    await pushToPlaywright(testInfo, result.status, result.reason, resolvedDir, `${name}.baseline.png`, currentFileName);
-    (0, test_1.expect)(result.status, `Visual regression detected: ${result.reason}`).toBe('PASS');
+    await pushToPlaywright(testInfo, name, result.status, result.reason, resolvedDir, `${filePrefix}.baseline.png`, currentFileName);
+    if (result.status === 'PASS') {
+        console.log(`🤖 [BugHunters Vision] AI PASS: ${name}`);
+    }
+    else {
+        throw new Error(`[BugHunters Vision] Visual regression detected in step "${name}": ${result.reason}`);
+    }
 }

package/dist/reporter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reporter.d.ts","sourceRoot":"","sources":["../src/reporter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAI1D,MAAM,WAAW,+BAA+B;IAC9C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA87BD,cAAM,wBAAyB,YAAW,QAAQ;IAChD,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,SAAS,CAAS;gBAEd,OAAO,CAAC,EAAE,+BAA+B;IAKrD,aAAa,IAAI,OAAO;IAIxB,OAAO,IAAI,IAAI;IAKf,KAAK,IAAI,IAAI;CA8Cd;AAED,eAAe,wBAAwB,CAAC;AACxC,OAAO,EAAE,wBAAwB,EAAE,CAAC"}
+{"version":3,"file":"reporter.d.ts","sourceRoot":"","sources":["../src/reporter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAI1D,MAAM,WAAW,+BAA+B;IAC9C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA4hCD,cAAM,wBAAyB,YAAW,QAAQ;IAChD,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,SAAS,CAAS;gBAEd,OAAO,CAAC,EAAE,+BAA+B;IAKrD,aAAa,IAAI,OAAO;IAIxB,OAAO,IAAI,IAAI;IAKf,KAAK,IAAI,IAAI;CAkDd;AAED,eAAe,wBAAwB,CAAC;AACxC,OAAO,EAAE,wBAAwB,EAAE,CAAC"}

package/dist/reporter.js

@@ -37,6 +37,36 @@ exports.BugHuntersVisionReporter = void 0;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const check_1 = require("./check");
+// ─── Group flat step results by Playwright test title ─────────────────────────
+function groupResults(results) {
+    const order = [];
+    const map = new Map();
+    for (const r of results) {
+        const sep = r.testName.indexOf(' › ');
+        const title = sep >= 0 ? r.testName.slice(0, sep) : r.testName;
+        if (!map.has(title)) {
+            map.set(title, []);
+            order.push(title);
+        }
+        map.get(title).push(r);
+    }
+    return order.map(testTitle => {
+        const steps = map.get(testTitle);
+        const hasFail = steps.some(s => s.status === 'FAIL');
+        const hasError = steps.some(s => s.status === 'ERROR');
+        const allBase = steps.every(s => s.status === 'BASELINE_CREATED');
+        const status = hasFail ? 'FAIL' : hasError ? 'ERROR' : allBase ? 'BASELINE_CREATED' : 'PASS';
+        return {
+            testTitle,
+            status,
+            passedSteps: steps.filter(s => s.status === 'PASS').length,
+            failedSteps: steps.filter(s => s.status === 'FAIL').length,
+            erroredSteps: steps.filter(s => s.status === 'ERROR').length,
+            baselineSteps: steps.filter(s => s.status === 'BASELINE_CREATED').length,
+            steps,
+        };
+    });
+}
 // ─── CSS ─────────────────────────────────────────────────────────────────────
 function getCss() {
     return `
@@ -192,27 +222,36 @@ body {
 
 /* ── Test list ── */
 .test-list { display: flex; flex-direction: column; gap: 6px; padding-bottom: 48px; }
-.test-item { background: var(--surface); border: 1px solid var(--border); border-radius: var(--radius); overflow: hidden; box-shadow: var(--shadow-sm); }
-.test-item.s-fail { border-left: 3px solid var(--fail); }
-.test-item.s-base { border-left: 3px solid var(--base); }
-.test-item.s-warn { border-left: 3px solid var(--pixel); }
 
-.test-row {
+/* ── Test group — one Playwright test ── */
+.test-group {
+  background: var(--surface); border: 1px solid var(--border);
+  border-radius: var(--radius); overflow: hidden; box-shadow: var(--shadow-sm);
+}
+.test-group.s-fail { border-left: 3px solid var(--fail); }
+.test-group.s-base { border-left: 3px solid var(--base); }
+.test-group.s-warn { border-left: 3px solid var(--pixel); }
+
+/* ── Group header row (clickable, expands step list) ── */
+.group-row {
   display: flex; align-items: center; gap: 11px;
   padding: 12px 14px; cursor: pointer;
   transition: background .1s; user-select: none;
 }
-.test-row:hover { background: var(--surface-2); }
+.group-row:hover { background: var(--surface-2); }
 
+/* ── Status dot ── */
 .s-dot {
   width: 8px; height: 8px; border-radius: 50%; flex-shrink: 0;
   margin-top: 1px;
 }
+.s-dot-sm { width: 6px; height: 6px; margin-top: 0; }
 .s-pass .s-dot { background: var(--pass); }
 .s-fail .s-dot { background: var(--fail); }
 .s-base .s-dot { background: var(--base); }
 .s-warn .s-dot { background: var(--pixel); }
 
+/* ── Group text ── */
 .test-meta { flex: 1; min-width: 0; }
 .test-name {
   font-family: ui-monospace, 'SFMono-Regular', 'Fira Code', monospace;
@@ -224,6 +263,7 @@ body {
   white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
 }
 
+/* ── Badges ── */
 .badges { display: flex; gap: 5px; align-items: center; flex-shrink: 0; }
 .badge {
   font-size: 10px; font-weight: 600; padding: 2px 7px; border-radius: 4px;
@@ -240,9 +280,35 @@ body {
 .chev { font-size: 16px; color: var(--text-3); flex-shrink: 0; line-height: 1; transition: transform .2s; display: inline-block; }
 .chev.open { transform: rotate(90deg); }
 
-/* ── Detail panel ── */
-.test-detail { border-top: 1px solid var(--border); padding: 18px 14px 18px 33px; display: none; }
+/* ── Step list (expands when group is open) ── */
+.group-steps { display: none; }
+
+/* ── Individual step ── */
+.step-item { border-top: 1px solid var(--border); }
+
+/* ── Step header row (clickable, expands detail) ── */
+.step-row {
+  display: flex; align-items: center; gap: 9px;
+  padding: 9px 14px 9px 34px; cursor: pointer;
+  transition: background .1s; user-select: none;
+}
+.step-row:hover { background: var(--surface-2); }
 
+/* ── Step text ── */
+.step-meta { flex: 1; min-width: 0; }
+.step-name {
+  font-family: ui-monospace, 'SFMono-Regular', 'Fira Code', monospace;
+  font-size: 12px; font-weight: 500; color: var(--text-2);
+  white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+}
+
+/* ── Step detail (verdict + images) ── */
+.step-detail {
+  display: none; border-top: 1px solid var(--border);
+  padding: 16px 14px 16px 34px;
+}
+
+/* ── Verdict box ── */
 .verdict {
   background: var(--accent-soft); border-left: 3px solid var(--accent);
   border-radius: 0 6px 6px 0; padding: 12px 14px; margin-bottom: 18px;
@@ -267,9 +333,7 @@ body {
 .view-tab.diff-tab.on { color: var(--fail); }
 
 /* ── Image views ── */
-.img-section { }
 .img-lbl { font-size: 10px; text-transform: uppercase; letter-spacing: 1.2px; color: var(--text-3); font-weight: 500; margin-bottom: 12px; }
-.img-view { }
 .view-img {
   width: 100%; display: block; border-radius: 6px; border: 1px solid var(--border);
   max-height: 360px; object-fit: contain; object-position: top center;
@@ -380,8 +444,8 @@ function getJs() {
 (function () {
   'use strict';
 
-  var RESULTS = JSON.parse(document.getElementById('bv-r').textContent);
-  var META    = JSON.parse(document.getElementById('bv-m').textContent);
+  var GROUPS = JSON.parse(document.getElementById('bv-g').textContent);
+  var META   = JSON.parse(document.getElementById('bv-m').textContent);
 
   /* ── State ── */
   var state = {
@@ -423,23 +487,19 @@ function getJs() {
 
   /* ── Pixel diff engine (100% client-side, zero server calls) ── */
 
-  /* Weighted squared RGB distance — perceptually accurate, fast (no sqrt needed) */
   function colorDist(r1, g1, b1, r2, g2, b2) {
     var rd = r1 - r2, gd = g1 - g2, bd = b1 - b2;
     return rd * rd * 0.299 + gd * gd * 0.587 + bd * bd * 0.114;
   }
 
-  /* Render diff image: changed pixels = neon red, unchanged = desaturated baseline */
   function renderDiff(d1, d2, w, h) {
     var n   = w * h * 4;
     var out = new Uint8ClampedArray(n);
-    var thr = 900; /* squared perceptual threshold */
+    var thr = 900;
     for (var i = 0; i < n; i += 4) {
       if (colorDist(d1[i], d1[i+1], d1[i+2], d2[i], d2[i+1], d2[i+2]) > thr) {
-        /* neon red highlight */
         out[i] = 220; out[i+1] = 38; out[i+2] = 38; out[i+3] = 255;
       } else {
-        /* desaturated baseline — guides the eye to red pixels */
         var lum = (d1[i] * 77 + d1[i+1] * 150 + d1[i+2] * 29) >> 8;
         out[i] = lum; out[i+1] = lum; out[i+2] = lum; out[i+3] = 210;
       }
@@ -447,7 +507,6 @@ function getJs() {
     return new ImageData(out, w, h);
   }
 
-  /* Load image and extract raw pixel data via canvas */
   function loadImgPixels(url, cb) {
     var img = new Image();
     img.crossOrigin = 'anonymous';
@@ -469,7 +528,6 @@ function getJs() {
   var diffCache = {};
 
   function genDiff(idx, baseUrl, curUrl, container) {
-    /* Return cached result if already computed */
     if (diffCache[idx]) {
       var cached = diffCache[idx];
       var clone  = document.createElement('canvas');
@@ -525,7 +583,6 @@ function getJs() {
 
   function lbReset() { lb.scale = 1; lb.tx = 0; lb.ty = 0; lbApply(); }
 
-  /* Zoom towards a viewport-center-relative point (mx, my) */
   function lbZoom(factor, mx, my) {
     var ns  = Math.max(lb.minScale, Math.min(lb.maxScale, lb.scale * factor));
     var r   = ns / lb.scale;
@@ -535,7 +592,6 @@ function getJs() {
     lbApply();
   }
 
-  /* Auto-fit: scale image to fill viewport on first open */
   function lbAutoFit(w, h) {
     var vw = lb.inner.clientWidth  - 48;
     var vh = lb.inner.clientHeight - 48;
@@ -556,7 +612,6 @@ function getJs() {
       el.onload = function () { lbAutoFit(el.naturalWidth, el.naturalHeight); };
       el.src = payload;
     } else {
-      /* diff canvas */
       var src = diffCache[payload];
       if (!src) return;
       el = document.createElement('canvas');
@@ -603,28 +658,19 @@ function getJs() {
     lb.wrap    = ov.querySelector('.lb-img-wrap');
     lb.zoomLbl = ov.querySelector('.lb-zoom-label');
 
-    /* close button */
     ov.querySelector('.lb-close').addEventListener('click', lbClose);
-
-    /* click on backdrop (not on image) */
     lb.inner.addEventListener('click', function (e) {
       if (e.target === lb.inner) lbClose();
     });
-
-    /* double-click: reset zoom */
     lb.inner.addEventListener('dblclick', function (e) {
       e.preventDefault();
       lbReset();
     });
-
-    /* scroll-to-zoom */
     lb.inner.addEventListener('wheel', function (e) {
       e.preventDefault();
       var p = lbCenterPos(e);
       lbZoom(e.deltaY < 0 ? 1.12 : 1 / 1.12, p.x, p.y);
     }, { passive: false });
-
-    /* mouse drag: pan */
     lb.inner.addEventListener('mousedown', function (e) {
       if (e.button !== 0) return;
       lb.dragging = true;
@@ -644,8 +690,6 @@ function getJs() {
       lb.dragging = false;
       lb.wrap.classList.remove('dragging');
     });
-
-    /* touch: pan + pinch-to-zoom */
     lb.inner.addEventListener('touchstart', function (e) {
       if (e.touches.length === 2) {
         var dx = e.touches[0].clientX - e.touches[1].clientX;
@@ -674,8 +718,6 @@ function getJs() {
       }
     }, { passive: false });
     lb.inner.addEventListener('touchend', function () { lb.dragging = false; }, { passive: true });
-
-    /* keyboard shortcuts */
     document.addEventListener('keydown', function (e) {
       if (!lb.overlay.classList.contains('open')) return;
       if (e.key === 'Escape') lbClose();
@@ -684,6 +726,7 @@ function getJs() {
   }
 
   /* ── HTML builders ── */
+
   function statusInfo(r) {
     if (r.status === 'PASS')  return { cls:'s-pass', badge:'m-pass', label:'PASS' };
     if (r.status === 'FAIL')  return { cls:'s-fail', badge:'m-fail', label:'FAIL' };
@@ -749,40 +792,75 @@ function getJs() {
       + tabs + basePanel + curPanel + diffPanel;
   }
 
-  function buildDetail(r) {
-    var imgWrap    = r.status === 'PASS' ? 'img-section pass-imgs' : 'img-section';
+  /* Build a single visual-check step row + expandable detail */
+  function buildStep(r) {
+    var s         = statusInfo(r);
+    var method    = methodLabel(r);
+    var methodCls = methodBadgeCls(r);
+
+    /* Extract step name: "Test title › step name" → "step name" */
+    var raw    = r.testName || '';
+    var sepIdx = raw.indexOf(' \u203a ');
+    var stepName = sepIdx >= 0 ? raw.slice(sepIdx + 3) : raw;
+
     var verdictLbl = r.method === 'FAST_PIXEL_MATCH'
       ? '\u26A1 Fast Pixel Match'
       : '\uD83E\uDD16 AI Verdict';
-    return '<div class="test-detail" id="d' + r.index + '">'
-      + '<div class="verdict">'
-        + '<div class="verdict-lbl">' + verdictLbl + '</div>'
-        + '<p class="verdict-txt">\u201C' + esc(r.reason) + '\u201D</p>'
+    var imgWrap = r.status === 'PASS' ? 'img-section pass-imgs' : 'img-section';
+
+    return '<div class="step-item ' + s.cls + '">'
+      + '<div class="step-row" data-s="' + r.index + '">'
+        + '<div class="s-dot s-dot-sm"></div>'
+        + '<div class="step-meta">'
+          + '<div class="step-name">' + esc(stepName) + '</div>'
+        + '</div>'
+        + '<div class="badges">'
+          + '<span class="badge ' + methodCls + '">' + method + '</span>'
+          + '<span class="badge ' + s.badge   + '">' + s.label  + '</span>'
+        + '</div>'
+        + '<span class="chev" id="sc' + r.index + '">\u203a</span>'
+      + '</div>'
+      + '<div class="step-detail" id="sd' + r.index + '">'
+        + '<div class="verdict">'
+          + '<div class="verdict-lbl">' + verdictLbl + '</div>'
+          + '<p class="verdict-txt">\u201C' + esc(r.reason) + '\u201D</p>'
+        + '</div>'
+        + '<div class="' + imgWrap + '">' + buildImages(r) + '</div>'
       + '</div>'
-      + '<div class="' + imgWrap + '">' + buildImages(r) + '</div>'
-      + '</div>';
+    + '</div>';
   }
 
-  function buildItem(r) {
-    var s         = statusInfo(r);
-    var method    = methodLabel(r);
-    var methodCls = methodBadgeCls(r);
-    var snip      = trunc(r.reason, 88);
-    return '<div class="test-item ' + s.cls + '">'
-      + '<div class="test-row" data-t="' + r.index + '">'
+  /* Build a test group row (Playwright test + its visual-check steps) */
+  function buildGroup(g, gIdx) {
+    var s = statusInfo(g);
+    var n = g.steps.length;
+
+    /* Snip: "5 visual checks · 2 failed" or "3 visual checks · all passed" */
+    var parts = [];
+    if (g.failedSteps   > 0) parts.push(g.failedSteps + ' failed');
+    if (g.erroredSteps  > 0) parts.push(g.erroredSteps + (g.erroredSteps !== 1 ? ' errors' : ' error'));
+    if (g.baselineSteps > 0 && g.failedSteps === 0 && g.erroredSteps === 0)
+      parts.push('baselines created');
+    var checkWord = n === 1 ? 'visual check' : 'visual checks';
+    var snip = n + ' ' + checkWord
+      + (parts.length > 0 ? ' \u00b7 ' + parts.join(' \u00b7 ') : ' \u00b7 all passed');
+
+    var stepsHtml = g.steps.map(buildStep).join('');
+
+    return '<div class="test-group ' + s.cls + '" data-gst="' + g.status + '">'
+      + '<div class="group-row" data-g="' + gIdx + '">'
         + '<div class="s-dot"></div>'
         + '<div class="test-meta">'
-          + '<div class="test-name">' + esc(r.testName) + '</div>'
-          + '<div class="test-snip">'  + esc(snip)       + '</div>'
+          + '<div class="test-name">' + esc(g.testTitle) + '</div>'
+          + '<div class="test-snip">' + esc(snip)        + '</div>'
         + '</div>'
         + '<div class="badges">'
-          + '<span class="badge ' + methodCls + '">' + method   + '</span>'
-          + '<span class="badge ' + s.badge   + '">' + s.label  + '</span>'
+          + '<span class="badge ' + s.badge + '">' + s.label + '</span>'
         + '</div>'
-        + '<span class="chev" id="c' + r.index + '">\u203A</span>'
+        + '<span class="chev" id="gc' + gIdx + '">\u203a</span>'
       + '</div>'
-      + buildDetail(r)
-      + '</div>';
+      + '<div class="group-steps" id="gs' + gIdx + '">' + stepsHtml + '</div>'
+    + '</div>';
   }
 
   function buildThemeBtns() {
@@ -812,7 +890,7 @@ function getJs() {
     var warnFilter = hasErrors
       ? '<button class="f-btn" data-f="warn">Errors (' + META.errored + ')</button>'
       : '';
-    var items     = RESULTS.map(buildItem).join('');
+    var items = GROUPS.map(function (g, i) { return buildGroup(g, i); }).join('');
 
     return '<header class="hdr">'
         + '<div class="wrap"><div class="hdr-inner">'
@@ -826,7 +904,7 @@ function getJs() {
       + '</header>'
       + '<div class="wrap">'
         + '<div class="summary">'
-          + '<div class="stat"><div class="stat-lbl">Total</div><div class="stat-val">'   + META.total   + '</div></div>'
+          + '<div class="stat"><div class="stat-lbl">Tests</div><div class="stat-val">'   + META.total   + '</div></div>'
           + '<div class="stat s-pass"><div class="stat-lbl">Passed</div><div class="stat-val">' + META.passed + '</div></div>'
           + '<div class="stat' + failCls + '"><div class="stat-lbl">Failed</div><div class="stat-val">' + META.failed + '</div></div>'
           + warnStat
@@ -853,35 +931,45 @@ function getJs() {
   function bind() {
     var tlist = document.getElementById('tlist');
 
-    /* accordion expand/collapse — only fires from .test-row[data-t] */
+    /* Level 1: test group accordion — expand/collapse step list */
+    tlist.addEventListener('click', function (e) {
+      var row = e.target.closest('[data-g]');
+      if (!row) return;
+      var idx   = row.getAttribute('data-g');
+      var steps = document.getElementById('gs' + idx);
+      var chev  = document.getElementById('gc' + idx);
+      if (!steps) return;
+      var open = steps.style.display !== 'none';
+      steps.style.display = open ? 'none' : 'block';
+      if (chev) chev.classList.toggle('open', !open);
+    });
+
+    /* Level 2: step accordion — expand/collapse verdict + images */
     tlist.addEventListener('click', function (e) {
-      var row = e.target.closest('[data-t]');
+      var row = e.target.closest('[data-s]');
       if (!row) return;
-      var idx     = row.getAttribute('data-t');
-      var detail  = document.getElementById('d' + idx);
-      var chevron = document.getElementById('c' + idx);
+      var idx    = row.getAttribute('data-s');
+      var detail = document.getElementById('sd' + idx);
+      var chev   = document.getElementById('sc' + idx);
       if (!detail) return;
       var open = detail.style.display !== 'none';
       detail.style.display = open ? 'none' : 'block';
-      if (chevron) chevron.classList.toggle('open', !open);
+      if (chev) chev.classList.toggle('open', !open);
     });
 
-    /* view-tab switching: Baseline / Current / Diff */
+    /* View-tab switching: Baseline / Current / Diff */
     tlist.addEventListener('click', function (e) {
       var tab = e.target.closest('[data-tab]');
       if (!tab) return;
       var tidx    = tab.getAttribute('data-tidx');
       var tabName = tab.getAttribute('data-tab');
-      /* update active tab */
       tab.closest('.view-tabs').querySelectorAll('.view-tab').forEach(function (t) {
         t.classList.toggle('on', t === tab);
       });
-      /* show correct panel, hide others */
       ['base', 'cur', 'diff'].forEach(function (key) {
         var panel = document.getElementById('v' + key + '-' + tidx);
         if (panel) panel.style.display = key === tabName ? '' : 'none';
       });
-      /* lazy diff generation — only on first click */
       if (tabName === 'diff') {
         var dp = document.getElementById('vdiff-' + tidx);
         if (dp && dp.getAttribute('data-ready') === '0') {
@@ -891,7 +979,7 @@ function getJs() {
       }
     });
 
-    /* image / diff-canvas click → open lightbox */
+    /* Image / diff-canvas click → open lightbox */
     tlist.addEventListener('click', function (e) {
       var el = e.target.closest('[data-lb]');
       if (!el) return;
@@ -900,7 +988,7 @@ function getJs() {
       if (type === 'diff') lbOpen('diff', el.getAttribute('data-lb-idx'));
     });
 
-    /* theme */
+    /* Theme */
     document.getElementById('t-toggle').addEventListener('click', function (e) {
       var btn = e.target.closest('[data-th]');
       if (!btn) return;
@@ -912,7 +1000,7 @@ function getJs() {
       });
     });
 
-    /* screenshots on pass toggle */
+    /* Screenshots on pass toggle */
     document.getElementById('img-btn').addEventListener('click', function () {
       state.showPassImg = !state.showPassImg;
       localStorage.setItem('bv-pass-img', String(state.showPassImg));
@@ -920,18 +1008,20 @@ function getJs() {
       this.classList.toggle('on', state.showPassImg);
     });
 
-    /* filter */
+    /* Filter — operates at test-group level */
     document.querySelectorAll('[data-f]').forEach(function (btn) {
       btn.addEventListener('click', function () {
         var f = btn.getAttribute('data-f');
         document.querySelectorAll('[data-f]').forEach(function (b) {
           b.classList.toggle('on', b.getAttribute('data-f') === f);
         });
-        document.querySelectorAll('.test-item').forEach(function (el) {
+        document.querySelectorAll('.test-group').forEach(function (el) {
+          var gst  = el.getAttribute('data-gst');
           var show = f === 'all'
-            || (f === 'pass' && el.classList.contains('s-pass'))
-            || (f === 'fail' && el.classList.contains('s-fail'))
-            || (f === 'warn' && el.classList.contains('s-warn'));
+            || (f === 'pass' && gst === 'PASS')
+            || (f === 'fail' && gst === 'FAIL')
+            || (f === 'warn' && gst === 'ERROR')
+            || (f === 'base' && gst === 'BASELINE_CREATED');
           el.style.display = show ? '' : 'none';
         });
       });
@@ -952,8 +1042,8 @@ function getJs() {
 `.trim();
 }
 // ─── HTML Assembly ───────────────────────────────────────────────────────────
-function generateHTML(results, meta) {
-    const resultsJson = JSON.stringify(results);
+function generateHTML(groups, meta) {
+    const groupsJson = JSON.stringify(groups);
     const metaJson = JSON.stringify(meta);
     const svgPass = encodeURIComponent('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="6" fill="#1a2e22"/><path d="M7 16.5L13 22L25 10" stroke="#73c991" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/></svg>');
     const svgFail = encodeURIComponent('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="6" fill="#2a1515"/><path d="M10 10L22 22M22 10L10 22" stroke="#f14c4c" stroke-width="3" stroke-linecap="round"/></svg>');
@@ -977,7 +1067,7 @@ function generateHTML(results, meta) {
 </head>
 <body>
   <div id="root"></div>
-  <script type="application/json" id="bv-r">${resultsJson}</script>
+  <script type="application/json" id="bv-g">${groupsJson}</script>
   <script type="application/json" id="bv-m">${metaJson}</script>
   <script>${getJs()}</script>
 </body>
@@ -1010,13 +1100,14 @@ class BugHuntersVisionReporter {
             return;
         }
         const results = JSON.parse(raw);
-        const passed = results.filter(r => r.status === 'PASS').length;
-        const failed = results.filter(r => r.status === 'FAIL').length;
-        const baselines = results.filter(r => r.status === 'BASELINE_CREATED').length;
-        const errored = results.filter(r => r.status === 'ERROR').length;
+        const groups = groupResults(results);
+        const passed = groups.filter(g => g.status === 'PASS').length;
+        const failed = groups.filter(g => g.status === 'FAIL').length;
+        const baselines = groups.filter(g => g.status === 'BASELINE_CREATED').length;
+        const errored = groups.filter(g => g.status === 'ERROR').length;
         const meta = {
             generatedAt: new Date().toISOString(),
-            total: results.length,
+            total: groups.length,
             passed,
             failed,
             baselines,
@@ -1024,11 +1115,13 @@ class BugHuntersVisionReporter {
         };
         const reportPath = path.join(this.reportDir, 'index.html');
         fs.mkdirSync(this.reportDir, { recursive: true });
-        fs.writeFileSync(reportPath, generateHTML(results, meta), 'utf-8');
+        fs.writeFileSync(reportPath, generateHTML(groups, meta), 'utf-8');
+        const testWord = groups.length === 1 ? 'test' : 'tests';
+        const stepWord = results.length === 1 ? 'check' : 'checks';
         console.log('\n\uD83D\uDC1E BugHunters Vision Report generated:');
         console.log('   \uD83D\uDCC4 ' + reportPath);
         const erroredStr = errored > 0 ? '  \u26A0\uFE0F ' + errored + ' errored' : '';
-        console.log('   \u2705 ' + passed + ' passed  \u274C ' + failed + ' failed' + erroredStr + '  (' + results.length + ' total)');
+        console.log('   \u2705 ' + passed + ' passed  \u274C ' + failed + ' failed' + erroredStr + '  (' + groups.length + ' ' + testWord + ' \u00B7 ' + results.length + ' ' + stepWord + ' total)');
         // Show remaining API balance if an AI call was made this run
         const balance = (0, check_1.getLastRemainingBalance)();
         if (balance !== null) {

package/dist/types.d.ts

@@ -9,6 +9,15 @@ export interface TestResult {
     currentFile: string | null;
     timestamp: string;
 }
+export interface TestGroup {
+    testTitle: string;
+    status: 'PASS' | 'FAIL' | 'BASELINE_CREATED' | 'ERROR';
+    passedSteps: number;
+    failedSteps: number;
+    erroredSteps: number;
+    baselineSteps: number;
+    steps: TestResult[];
+}
 export interface Meta {
     generatedAt: string;
     total: number;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEjD,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,kBAAkB,GAAG,OAAO,CAAC;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,IAAI,GAAG,kBAAkB,GAAG,IAAI,CAAC;IACzC,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,IAAI;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEjD,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,kBAAkB,GAAG,OAAO,CAAC;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,IAAI,GAAG,kBAAkB,GAAG,IAAI,CAAC;IACzC,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB;AAGD,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,kBAAkB,GAAG,OAAO,CAAC;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,IAAI;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bughunters/vision",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "InfoSec-friendly AI Visual Testing plugin for Playwright.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",