@bughunters/vision 1.0.3 → 1.0.4

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,18 @@ The report includes side-by-side Baseline / Current / Diff views with full-scree
 
 ---
 
+## 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 +175,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,CA4J/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) {
@@ -158,44 +161,51 @@ async function runVisionCheck(opts) {
     }
     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}`);
+        fs.writeFileSync(baselinePath, currentBuffer);
+        console.log(`\n📸 [BugHunters Vision] Baseline saved: ${baselinePath}`);
         console.log('   ✅ Test PASSED (baseline created — no previous reference exists)\n');
         (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');
         (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
@@ -204,15 +214,15 @@ async function runVisionCheck(opts) {
         // 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);
+        await pushToPlaywright(testInfo, name, 'FAIL', `Pixel mismatch detected (${diffLabel}). Strict mode.`, resolvedDir, `${filePrefix}.baseline.png`, currentFileName);
         (0, test_1.expect)(false, `[BugHunters Vision strict] Pixel mismatch: ${diffLabel}`).toBe(true);
         return;
     }
@@ -226,43 +236,43 @@ async function runVisionCheck(opts) {
         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);
+        await pushToPlaywright(testInfo, name, 'FAIL', reason, resolvedDir, `${filePrefix}.baseline.png`, currentFileName);
         throw err;
     }
     // 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`);
         (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);
+    await pushToPlaywright(testInfo, name, result.status, result.reason, resolvedDir, `${filePrefix}.baseline.png`, currentFileName);
     (0, test_1.expect)(result.status, `Visual regression detected: ${result.reason}`).toBe('PASS');
 }

package/package.json

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