@bughunters/vision 1.0.0 → 1.0.2

package/README.md

@@ -42,17 +42,19 @@ BUGHUNTERS_VISION_TOKEN=bhv_your_token_here
 
 ```typescript
 import { defineConfig, devices } from '@playwright/test';
-import type { VisionFixtureOptions } from '@bughunters/vision';
 
-export default defineConfig<VisionFixtureOptions>({
+export default defineConfig({
   testDir: './tests',
   reporter: [
     ['list'],
     ['@bughunters/vision/reporter', { snapshotsDir: './bhv-snapshots', reportDir: './bhv-report' }],
   ],
   use: {
-    bvMode: 'ai',  // 'ai' | 'strict' | 'off'
-  },
+    // BugHunters Vision options — can also be set via env variables
+    bvMode:           'ai',              // 'ai' | 'strict' | 'off'
+    bvSnapshotsDir:   './bhv-snapshots',
+    bvUpdateBaseline: false,
+  } as Record<string, unknown>,
   projects: [
     { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
   ],
@@ -62,19 +64,26 @@ export default defineConfig<VisionFixtureOptions>({
 ### 4. Write a visual test
 
 ```typescript
-import { test } from '@bughunters/vision';
+import { test } from '@playwright/test';
+import { vision } from '@bughunters/vision';
 
-test('homepage looks correct', async ({ page, visionCheck }) => {
+test('homepage looks correct', async ({ page }) => {
   await page.goto('https://example.com');
   await page.waitForLoadState('networkidle');
-  await visionCheck('homepage');
+  await vision.check(page, 'homepage');
 });
 ```
 
-You can pass an optional AI hint as the second argument:
+You can pass an optional AI hint as the third argument:
 
 ```typescript
-await visionCheck('dashboard', 'Ignore the live timestamp in the top-right corner.');
+await vision.check(page, 'dashboard', 'Ignore the live timestamp in the top-right corner.');
+```
+
+`vision.check()` accepts a `Page` or a `Locator` — useful for scoped element checks:
+
+```typescript
+await vision.check(page.locator('#sidebar'), 'sidebar');
 ```
 
 ### 5. Run your tests
@@ -104,16 +113,18 @@ The report includes side-by-side Baseline / Current / Diff views with full-scree
 
 ## Configuration reference
 
-All options can be set in `playwright.config.ts` under `use:`, or overridden via environment variables.
+Options can be set in `playwright.config.ts` under `use:` **or** via environment variables. The `use:` block takes precedence; env vars are the fallback.
 
 | Option in `use:` | Environment variable | Default | Description |
 |---|---|---|---|
 | `bvMode` | `BHV_MODE` | `'ai'` | Comparison mode: `ai` · `strict` · `off` |
 | `bvSnapshotsDir` | `BHV_SNAPSHOTS_DIR` | `'./bhv-snapshots'` | Where to store PNG snapshots |
-| `bvUpdateBaseline` | `BHV_UPDATE_BASELINE` | `false` | Force-overwrite all baselines on this run |
+| `bvUpdateBaseline` | `BHV_UPDATE_BASELINE` | `false` | Set to `true` to force-overwrite all baselines |
 | `bvApiUrl` | `BUGHUNTERS_VISION_API_URL` | *(production)* | Override API endpoint (e.g. for self-hosted) |
 | `bvToken` | `BUGHUNTERS_VISION_TOKEN` | — | Your API token — always use env var, never commit |
 
+> **Note:** Because `vision` is a standalone object (not a Playwright fixture), the `use:` options are not TypeScript-typed. Add `as Record<string, unknown>` to the `use` block to suppress TS errors.
+
 ### Comparison modes
 
 | Mode | Behaviour |

package/dist/check.d.ts

@@ -1,15 +1,8 @@
-import type { Page, TestInfo } from '@playwright/test';
-import type { VisionMode } from './types';
+import type { Page, Locator } from '@playwright/test';
 export interface RunVisionCheckOptions {
-    page: Page;
+    target: Page | Locator;
     name: string;
     prompt?: string;
-    apiUrl: string;
-    mode: VisionMode;
-    snapshotsDir: string;
-    updateBaseline: boolean;
-    token?: string;
-    testInfo?: TestInfo;
 }
 export declare function getLastRemainingBalance(): string | null;
 export declare function runVisionCheck(opts: RunVisionCheckOptions): Promise<void>;

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,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAGvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,UAAU,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,OAAO,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAKD,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,IAAI,CAEvD;AA+GD,wBAAsB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4I/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;AA+GD,wBAAsB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmJ/E"}

package/dist/check.js

@@ -40,6 +40,7 @@ const path = __importStar(require("path"));
 const test_1 = require("@playwright/test");
 const pixel_match_1 = require("./pixel-match");
 const results_1 = require("./results");
+const PRODUCTION_API_URL = 'https://bugvision-backend.vercel.app';
 // Module-level balance tracker — updated after each AI call, read by reporter.onEnd()
 let _lastRemainingBalance = null;
 function getLastRemainingBalance() {
@@ -137,7 +138,19 @@ async function pushToPlaywright(testInfo, status, reason, resolvedDir, baselineF
     }
 }
 async function runVisionCheck(opts) {
-    const { page, name, prompt = 'Check for any visual regressions.', apiUrl, mode, snapshotsDir, updateBaseline, token, testInfo, } = opts;
+    const { target, name, prompt = 'Check for any visual regressions.' } = opts;
+    // Read config from testInfo.project.use (if available) or fall back to env vars
+    let testInfo;
+    try {
+        testInfo = test_1.test.info();
+    }
+    catch { /* called outside test context */ }
+    const projectUse = (testInfo?.project?.use ?? {});
+    const apiUrl = projectUse['bvApiUrl'] ?? process.env.BUGHUNTERS_VISION_API_URL ?? process.env.BHV_API_URL ?? PRODUCTION_API_URL;
+    const mode = (projectUse['bvMode'] ?? process.env.BHV_MODE ?? 'ai');
+    const snapshotsDir = projectUse['bvSnapshotsDir'] ?? process.env.BHV_SNAPSHOTS_DIR ?? './bhv-snapshots';
+    const updateBaseline = projectUse['bvUpdateBaseline'] ?? (process.env.BHV_UPDATE_BASELINE === 'true');
+    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`);
@@ -146,7 +159,7 @@ async function runVisionCheck(opts) {
     const resolvedDir = path.resolve(process.cwd(), snapshotsDir);
     fs.mkdirSync(resolvedDir, { recursive: true });
     const baselineFile = path.join(resolvedDir, `${name}.baseline.png`);
-    const currentBuffer = await page.screenshot({ fullPage: false, type: 'png' });
+    const currentBuffer = await target.screenshot();
     if (!fs.existsSync(baselineFile) || updateBaseline) {
         // First run — save as baseline
         fs.writeFileSync(baselineFile, currentBuffer);

package/dist/index.d.ts

@@ -1,6 +1,9 @@
-export { test, expect } from './fixture';
-export type { VisionFixtureOptions } from './fixture';
+import type { Page, Locator } from '@playwright/test';
 export type { VisionMode, TestResult, Meta } from './types';
 export { BugHuntersVisionReporter } from './reporter';
 export type { BugHuntersVisionReporterOptions } from './reporter';
+export { getLastRemainingBalance } from './check';
+export declare const vision: {
+    check(target: Page | Locator, name: string, prompt?: string): Promise<void>;
+};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACzC,YAAY,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACtD,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AACtD,YAAY,EAAE,+BAA+B,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAGtD,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AACtD,YAAY,EAAE,+BAA+B,EAAE,MAAM,YAAY,CAAC;AAClE,OAAO,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAElD,eAAO,MAAM,MAAM;kBACG,IAAI,GAAG,OAAO,QAAQ,MAAM,WAAW,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGlF,CAAC"}

package/dist/index.js

@@ -1,8 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BugHuntersVisionReporter = exports.expect = exports.test = void 0;
-var fixture_1 = require("./fixture");
-Object.defineProperty(exports, "test", { enumerable: true, get: function () { return fixture_1.test; } });
-Object.defineProperty(exports, "expect", { enumerable: true, get: function () { return fixture_1.expect; } });
+exports.vision = exports.getLastRemainingBalance = exports.BugHuntersVisionReporter = void 0;
+const check_1 = require("./check");
 var reporter_1 = require("./reporter");
 Object.defineProperty(exports, "BugHuntersVisionReporter", { enumerable: true, get: function () { return reporter_1.BugHuntersVisionReporter; } });
+var check_2 = require("./check");
+Object.defineProperty(exports, "getLastRemainingBalance", { enumerable: true, get: function () { return check_2.getLastRemainingBalance; } });
+exports.vision = {
+    async check(target, name, prompt) {
+        return (0, check_1.runVisionCheck)({ target, name, prompt });
+    },
+};

package/package.json

@@ -1,16 +1,20 @@
 {
   "name": "@bughunters/vision",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "InfoSec-friendly AI Visual Testing plugin for Playwright.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "require": "./dist/index.js",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js",
       "types": "./dist/index.d.ts"
     },
     "./reporter": {
       "require": "./dist/reporter.js",
+      "import": "./dist/reporter.js",
+      "default": "./dist/reporter.js",
       "types": "./dist/reporter.d.ts"
     }
   },

package/dist/fixture.d.ts

@@ -1,21 +0,0 @@
-import { expect } from '@playwright/test';
-import type { VisionMode } from './types';
-export interface VisionFixtureOptions {
-    /** BugHunters Vision API URL (default: https://bugvision-backend.vercel.app) */
-    bvApiUrl: string;
-    /** Comparison mode: ai | strict | off (default: ai) */
-    bvMode: VisionMode;
-    /** Where to store baseline + current screenshots (default: ./bhv-snapshots) */
-    bvSnapshotsDir: string;
-    /** Force-overwrite all baselines on this run (default: false) */
-    bvUpdateBaseline: boolean;
-    /** BugHunters Vision API token (env: BUGHUNTERS_VISION_TOKEN) */
-    bvToken: string;
-}
-type VisionFixtures = {
-    /** Run a visual snapshot check for the current page state */
-    visionCheck: (name: string, prompt?: string) => Promise<void>;
-};
-export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & VisionFixtures & VisionFixtureOptions, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
-export { expect };
-//# sourceMappingURL=fixture.d.ts.map

package/dist/fixture.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"fixture.d.ts","sourceRoot":"","sources":["../src/fixture.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAExD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAK1C,MAAM,WAAW,oBAAoB;IACnC,gFAAgF;IAChF,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,MAAM,EAAE,UAAU,CAAC;IACnB,+EAA+E;IAC/E,cAAc,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,gBAAgB,EAAE,OAAO,CAAC;IAC1B,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,KAAK,cAAc,GAAG;IACpB,6DAA6D;IAC7D,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/D,CAAC;AAEF,eAAO,MAAM,IAAI,qRAoBf,CAAC;AAEH,OAAO,EAAE,MAAM,EAAE,CAAC"}

package/dist/fixture.js

@@ -1,25 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.expect = exports.test = void 0;
-const test_1 = require("@playwright/test");
-Object.defineProperty(exports, "expect", { enumerable: true, get: function () { return test_1.expect; } });
-const check_1 = require("./check");
-const PRODUCTION_API_URL = 'https://bugvision-backend.vercel.app';
-exports.test = test_1.test.extend({
-    bvApiUrl: [process.env.BUGHUNTERS_VISION_API_URL ?? process.env.BHV_API_URL ?? PRODUCTION_API_URL, { option: true }],
-    bvMode: [(process.env.BHV_MODE ?? 'ai'), { option: true }],
-    bvSnapshotsDir: [process.env.BHV_SNAPSHOTS_DIR ?? './bhv-snapshots', { option: true }],
-    bvUpdateBaseline: [process.env.BHV_UPDATE_BASELINE === 'true', { option: true }],
-    bvToken: [process.env.BUGHUNTERS_VISION_TOKEN ?? '', { option: true }],
-    visionCheck: async ({ page, bvApiUrl, bvMode, bvSnapshotsDir, bvUpdateBaseline, bvToken }, use, testInfo) => {
-        await use((name, prompt) => (0, check_1.runVisionCheck)({
-            page, name, prompt,
-            apiUrl: bvApiUrl,
-            mode: bvMode,
-            snapshotsDir: bvSnapshotsDir,
-            updateBaseline: bvUpdateBaseline,
-            token: bvToken || undefined,
-            testInfo,
-        }));
-    },
-});