@stablyai/playwright-base 0.1.0 → 0.1.2

package/dist/playwright-type-predicates.js

@@ -3,14 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isPage = isPage;
 exports.isLocator = isLocator;
 function isPage(candidate) {
-    return (typeof candidate === 'object' &&
+    return (typeof candidate === "object" &&
         candidate !== null &&
-        typeof candidate.screenshot === 'function' &&
-        typeof candidate.goto === 'function');
+        typeof candidate.screenshot === "function" &&
+        typeof candidate.goto === "function");
 }
 function isLocator(candidate) {
-    return (typeof candidate === 'object' &&
+    return (typeof candidate === "object" &&
         candidate !== null &&
-        typeof candidate.screenshot === 'function' &&
-        typeof candidate.nth === 'function');
+        typeof candidate.screenshot === "function" &&
+        typeof candidate.nth === "function");
 }

package/dist/runtime.js

@@ -13,7 +13,7 @@ function getApiKey() {
 function requireApiKey() {
     const apiKey = getApiKey();
     if (!apiKey) {
-        throw new Error('Missing Stably API key. Call setApiKey(apiKey) or set the STABLY_API_KEY environment variable.');
+        throw new Error("Missing Stably API key. Call setApiKey(apiKey) or set the STABLY_API_KEY environment variable.");
     }
     return apiKey;
 }

package/dist/screenshot.d.ts

@@ -0,0 +1,3 @@
+import type { Locator, Page } from "@stablyai/internal-playwright-test";
+import type { ScreenshotPromptOptions } from "./index";
+export declare function takeStableScreenshot(target: Page | Locator, options?: ScreenshotPromptOptions): Promise<Buffer>;

package/dist/screenshot.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.takeStableScreenshot = takeStableScreenshot;
+const playwright_type_predicates_1 = require("./playwright-type-predicates");
+const image_compare_1 = require("./image-compare");
+async function takeStableScreenshot(target, options) {
+    const page = (0, playwright_type_predicates_1.isPage)(target) ? target : target.page();
+    // Use a small budget for stabilization within the overall assertion timeout.
+    // We allocate up to 25% of the total timeout (bounded between 300ms and 2000ms).
+    const totalTimeout = options?.timeout ?? 5000;
+    // Budget is 25% of the total timeout
+    const stabilizationBudgetMs = Math.floor(totalTimeout * 0.25);
+    const stabilityBudgetMs = Math.min(2000, Math.max(300, stabilizationBudgetMs));
+    const deadline = Date.now() + stabilityBudgetMs;
+    let actual;
+    let previous;
+    const pollIntervals = [0, 100, 250, 500];
+    let isFirstIteration = true;
+    while (true) {
+        if (Date.now() >= deadline)
+            break;
+        const delay = pollIntervals.length ? pollIntervals.shift() : 1000;
+        if (delay) {
+            await page.waitForTimeout(delay);
+        }
+        previous = actual;
+        actual = await target.screenshot(options);
+        if (!isFirstIteration &&
+            actual &&
+            previous &&
+            (0, image_compare_1.imagesAreSimilar)({
+                image1: previous,
+                image2: actual,
+                threshold: options?.threshold ?? 0.02,
+            })) {
+            return actual;
+        }
+        isFirstIteration = false;
+    }
+    return actual ?? (await target.screenshot(options));
+}

package/package.json

@@ -1,20 +1,29 @@
 {
   "name": "@stablyai/playwright-base",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Shared augmentation runtime for Stably Playwright wrappers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
   "engines": {
     "node": ">=18"
   },
-  "dependencies": {},
+  "dependencies": {
+    "@stablyai/internal-playwright-test": "^0.1.1",
+    "jpeg-js": "^0.4.4",
+    "pixelmatch": "^5.3.0",
+    "pngjs": "^7.0.0"
+  },
   "peerDependencies": {
-    "@playwright/test": "^1.44.0",
-    "playwright": "^1.44.0",
-    "zod": "^4.0.0"
+    "zod": "^3.25.0 || ^4.0.0"
   },
   "devDependencies": {
-    "zod": "^4.0.0"
+    "@types/jpeg-js": "^0.3.7",
+    "@types/pngjs": "^6.0.5",
+    "@types/pixelmatch": "^5.2.6",
+    "zod": "^3.25.0 || ^4.0.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json"

package/src/ai/extract.ts

@@ -1,97 +0,0 @@
-import type { Locator, Page } from 'playwright';
-import * as z4 from 'zod/v4/core';
-import { z } from 'zod';
-import { requireApiKey } from '../runtime';
-
-export type ExtractSchema = z4.$ZodType;
-
-export type SchemaOutput<T extends ExtractSchema> = z4.output<T>;
-
-type ExtractIssue = z4.$ZodIssue;
-
-const EXTRACT_ENDPOINT = 'https://api.stably.ai/internal/v1/extract';
-
-const zSuccess = z.object({ value: z.unknown() });
-const zError = z.object({ error: z.string() });
-
-class ExtractValidationError extends Error {
-  constructor(
-    message: string,
-    readonly issues: ReadonlyArray<ExtractIssue>,
-  ) {
-    super(message);
-    this.name = 'ExtractValidationError';
-  }
-}
-
-async function validateWithSchema<T extends ExtractSchema>(
-  schema: T,
-  value: unknown,
-): Promise<SchemaOutput<T>> {
-  const result = await z4.safeParseAsync(schema, value);
-  if (!result.success) {
-    throw new ExtractValidationError('Validation failed', result.error.issues);
-  }
-
-  return result.data;
-}
-
-type ExtractSubject = Page | Locator;
-
-type BaseExtractArgs = {
-  prompt: string;
-  pageOrLocator: ExtractSubject;
-};
-
-type ExtractArgsWithSchema<T extends ExtractSchema> = BaseExtractArgs & {
-  schema: T;
-};
-
-export async function extract(args: BaseExtractArgs): Promise<string>;
-export async function extract<T extends ExtractSchema>(
-  args: ExtractArgsWithSchema<T>,
-): Promise<SchemaOutput<T>>;
-export async function extract<T extends ExtractSchema>({
-  prompt,
-  pageOrLocator,
-  schema,
-}: BaseExtractArgs & { schema?: T }): Promise<string | SchemaOutput<T>> {
-  const jsonSchema = schema ? z4.toJSONSchema(schema) : undefined;
-
-  const apiKey = requireApiKey();
-
-  const form = new FormData();
-  form.append('prompt', prompt);
-  if (jsonSchema) {
-    form.append('jsonSchema', JSON.stringify(jsonSchema));
-  }
-
-  const pngBuffer = await pageOrLocator.screenshot({ type: 'png' }); // Buffer
-  const u8 = Uint8Array.from(pngBuffer); // strips Buffer type → plain Uint8Array
-  const blob = new Blob([u8], { type: 'image/png' });
-  form.append('image', blob, 'screenshot.png');
-
-  const response = await fetch(EXTRACT_ENDPOINT, {
-    method: 'POST',
-    headers: {
-      Authorization: `Bearer ${apiKey}`,
-    },
-    body: form,
-  });
-
-  const parsed = await response.json().catch(() => undefined as unknown);
-
-  if (response.ok) {
-    const { value } = zSuccess.parse(parsed);
-    return (
-      schema ? await validateWithSchema(schema, value)
-      : typeof value === 'string' ? value
-      : JSON.stringify(value)
-    );
-  }
-
-  const err = zError.safeParse(parsed);
-  throw new Error(
-    `Extract failed (${response.status})${err.success ? `: ${err.data.error}` : ''}`,
-  );
-}

package/src/ai/verify-prompt.ts

@@ -1,57 +0,0 @@
-const PROMPT_ASSERTION_ENDPOINT = 'https://api.stably.ai/internal/v1/assert';
-
-import { z } from 'zod';
-import { requireApiKey } from '../runtime';
-
-const zSuccess = z.object({
-  success: z.boolean(),
-  reason: z.string().optional(),
-});
-
-const zError = z.object({
-  error: z.string(),
-});
-
-export async function verifyPrompt({
-  prompt,
-  screenshot,
-}: {
-  prompt: string;
-  screenshot: Uint8Array;
-}): Promise<{
-  pass: boolean;
-  reason?: string;
-}> {
-  const apiKey = requireApiKey();
-
-  const form = new FormData();
-  form.append('prompt', prompt);
-  const u8 = Uint8Array.from(screenshot);
-  const blob = new Blob([u8], { type: 'image/png' });
-  form.append('image', blob, 'screenshot.png');
-
-  const response = await fetch(PROMPT_ASSERTION_ENDPOINT, {
-    method: 'POST',
-    headers: {
-      Authorization: `Bearer ${apiKey}`,
-    },
-    body: form,
-  });
-
-  const parsed = await response.json().catch(() => undefined as unknown);
-
-  if (response.ok) {
-    const { success, reason } = zSuccess.parse(parsed);
-    return {
-      pass: success,
-      reason,
-    };
-  }
-
-  const err = zError.safeParse(parsed);
-  throw new Error(
-    `Verify prompt failed (${response.status})${
-      err.success ? `: ${err.data.error}` : ''
-    }`,
-  );
-}

package/src/expect.ts

@@ -1,134 +0,0 @@
-import type { Locator, Page } from 'playwright';
-import type { ScreenshotPromptOptions } from './index';
-
-import { isLocator, isPage } from './playwright-type-predicates';
-
-import { verifyPrompt } from './ai/verify-prompt';
-
-type VerifyTargetType = 'page' | 'locator';
-
-type MatcherContext = {
-  isNot: boolean;
-  message?: () => string;
-};
-
-function createFailureMessage({
-  targetType,
-  condition,
-  didPass,
-  isNot,
-  reason,
-}: {
-  targetType: VerifyTargetType;
-  condition: string;
-  didPass: boolean;
-  isNot: boolean;
-  reason?: string;
-}): string {
-  const expectation = isNot ? 'not to satisfy' : 'to satisfy';
-  const result = didPass ? 'it did' : 'it did not';
-
-  let message = `Expected ${targetType} ${expectation} ${JSON.stringify(condition)}, but ${result}.`;
-  if (reason) {
-    message += `\n\nReason: ${reason}`;
-  }
-
-  return message;
-}
-
-function areScreenshotsEqual(a: Uint8Array, b: Uint8Array): boolean {
-  if (a.byteLength !== b.byteLength) {
-    return false;
-  }
-
-  for (let index = 0; index < a.byteLength; index += 1) {
-    if (a[index] !== b[index]) {
-      return false;
-    }
-  }
-
-  return true;
-}
-
-async function takeStableScreenshot(
-  target: Page | Locator,
-  options?: ScreenshotPromptOptions,
-): Promise<Uint8Array> {
-  const page = isPage(target) ? target : target.page();
-
-  // Use a small budget for stabilization within the overall assertion timeout.
-  // We allocate up to 25% of the total timeout (bounded between 300ms and 2000ms).
-  const totalTimeout =
-    (options as { timeout?: number } | undefined)?.timeout ?? 5000;
-  // Budget is 25% of the total timeout
-  const stabilizationBudgetMs = Math.floor(totalTimeout * 0.25);
-  const stabilityBudgetMs = Math.min(
-    2000,
-    Math.max(300, stabilizationBudgetMs),
-  );
-  const deadline = Date.now() + stabilityBudgetMs;
-
-  let actual: Uint8Array | undefined;
-  let previous: Uint8Array | undefined;
-  const pollIntervals = [0, 100, 250, 500];
-  let isFirstIteration = true;
-
-  while (true) {
-    if (Date.now() >= deadline) break;
-    const delay = pollIntervals.length ? pollIntervals.shift()! : 1000;
-    if (delay) {
-      await page.waitForTimeout(delay);
-    }
-    previous = actual;
-    const rawScreenshot = await target.screenshot(options);
-    actual = Uint8Array.from(rawScreenshot);
-    if (
-      !isFirstIteration &&
-      actual &&
-      previous &&
-      areScreenshotsEqual(actual, previous)
-    ) {
-      return actual;
-    }
-    isFirstIteration = false;
-  }
-  return actual ?? Uint8Array.from(await target.screenshot(options));
-}
-
-export const stablyPlaywrightMatchers = {
-  async toMatchScreenshotPrompt(
-    this: MatcherContext,
-    received: Page | Locator,
-    condition: string,
-    options?: ScreenshotPromptOptions,
-  ) {
-    const target =
-      isPage(received) ? received
-      : isLocator(received) ? received
-      : undefined;
-    if (!target) {
-      // Should never happen
-      throw new Error(
-        'toMatchScreenshotPrompt only supports Playwright Page and Locator instances.',
-      );
-    }
-    const targetType: VerifyTargetType = isPage(target) ? 'page' : 'locator';
-
-    // Wait for two consecutive identical screenshots before sending to AI
-    const screenshot = await takeStableScreenshot(target, options);
-
-    const verifyResult = await verifyPrompt({ prompt: condition, screenshot });
-
-    return {
-      pass: verifyResult.pass,
-      message: () =>
-        createFailureMessage({
-          targetType,
-          condition,
-          didPass: verifyResult.pass,
-          reason: verifyResult.reason,
-          isNot: this.isNot,
-        }),
-    };
-  },
-} as const;

package/src/index.ts

@@ -1,69 +0,0 @@
-import type { Page } from 'playwright';
-import type { LocatorDescribeOptions } from './playwright-augment/augment';
-import type { ExtractSchema, SchemaOutput } from './ai/extract';
-
-import {
-  augmentBrowser,
-  augmentBrowserContext,
-  augmentBrowserType,
-  augmentLocator,
-  augmentPage,
-} from './playwright-augment/augment';
-import { stablyPlaywrightMatchers } from './expect';
-import { requireApiKey } from './runtime';
-
-export { setApiKey } from './runtime';
-
-export type { LocatorDescribeOptions } from './playwright-augment/augment';
-export type { ExtractSchema, SchemaOutput } from './ai/extract';
-export type ScreenshotPromptOptions =
-  import('@playwright/test').PageAssertionsToHaveScreenshotOptions;
-export {
-  augmentBrowser,
-  augmentBrowserContext,
-  augmentBrowserType,
-  augmentLocator,
-  augmentPage,
-  stablyPlaywrightMatchers,
-  requireApiKey,
-};
-
-export interface Expect<T = Page> {
-  toMatchScreenshotPrompt(
-    condition: string,
-    options?: ScreenshotPromptOptions,
-  ): Promise<void>;
-}
-
-declare module 'playwright' {
-  interface Locator {
-    extract(prompt: string): Promise<string>;
-    extract<T extends ExtractSchema>(
-      prompt: string,
-      options: { schema: T },
-    ): Promise<SchemaOutput<T>>;
-    describe(description: string, options?: LocatorDescribeOptions): Locator;
-  }
-
-  interface Page {
-    extract(prompt: string): Promise<string>;
-    extract<T extends ExtractSchema>(
-      prompt: string,
-      options: { schema: T },
-    ): Promise<SchemaOutput<T>>;
-  }
-
-  interface BrowserContext {
-    agent(
-      prompt: string,
-      options: { page: Page; maxCycles?: number },
-    ): Promise<{ success: boolean }>;
-  }
-
-  interface Browser {
-    agent(
-      prompt: string,
-      options: { page: Page; maxCycles?: number },
-    ): Promise<{ success: boolean }>;
-  }
-}

package/src/playwright-augment/augment.ts

@@ -1,207 +0,0 @@
-import type {
-  Browser,
-  BrowserContext,
-  BrowserType,
-  Locator,
-  Page,
-} from 'playwright';
-
-import { createLocatorExtract, createPageExtract } from './methods/extract';
-import { createAgentStub } from './methods/agent';
-
-export interface LocatorDescribeOptions {
-  autoHeal?: boolean;
-}
-
-const LOCATOR_PATCHED = Symbol.for('stably.playwright.locatorPatched');
-const LOCATOR_DESCRIBE_WRAPPED = Symbol.for(
-  'stably.playwright.locatorDescribeWrapped',
-);
-const PAGE_PATCHED = Symbol.for('stably.playwright.pagePatched');
-const CONTEXT_PATCHED = Symbol.for('stably.playwright.contextPatched');
-const BROWSER_PATCHED = Symbol.for('stably.playwright.browserPatched');
-const BROWSER_TYPE_PATCHED = Symbol.for('stably.playwright.browserTypePatched');
-
-function defineHiddenProperty<T, K extends PropertyKey>(
-  target: T,
-  key: K,
-  value: unknown,
-): void {
-  Object.defineProperty(target as unknown as object, key, {
-    value,
-    enumerable: false,
-    configurable: true,
-    writable: true,
-  });
-}
-
-export function augmentLocator<T extends Locator>(locator: T): T {
-  if (
-    (locator as unknown as { [LOCATOR_PATCHED]?: boolean })[LOCATOR_PATCHED]
-  ) {
-    return locator;
-  }
-
-  defineHiddenProperty(locator, 'extract', createLocatorExtract(locator));
-
-  const markerTarget = locator as unknown as Record<PropertyKey, unknown>;
-
-  if (
-    typeof locator.describe === 'function' &&
-    !markerTarget[LOCATOR_DESCRIBE_WRAPPED]
-  ) {
-    const originalDescribe = locator.describe.bind(locator);
-    locator.describe = ((
-      description: string,
-      options?: LocatorDescribeOptions,
-    ) => {
-      void options;
-      const result = originalDescribe(description);
-      return result ? augmentLocator(result as Locator) : result;
-    }) as Locator['describe'];
-
-    defineHiddenProperty(locator, LOCATOR_DESCRIBE_WRAPPED, true);
-  }
-
-  defineHiddenProperty(locator, LOCATOR_PATCHED, true);
-
-  return locator;
-}
-
-export function augmentPage<T extends Page>(page: T): T {
-  if ((page as unknown as { [PAGE_PATCHED]?: boolean })[PAGE_PATCHED]) {
-    return page;
-  }
-
-  const originalLocator = page.locator.bind(page);
-  page.locator = ((...args: Parameters<Page['locator']>) => {
-    const locator = originalLocator(...args);
-    return augmentLocator(locator);
-  }) as Page['locator'];
-
-  defineHiddenProperty(page, 'extract', createPageExtract(page));
-  defineHiddenProperty(page, PAGE_PATCHED, true);
-
-  return page;
-}
-
-export function augmentBrowserContext<T extends BrowserContext>(context: T): T {
-  if (
-    (context as unknown as { [CONTEXT_PATCHED]?: boolean })[CONTEXT_PATCHED]
-  ) {
-    return context;
-  }
-
-  const originalNewPage = context.newPage.bind(context);
-  context.newPage = (async (...args: Parameters<BrowserContext['newPage']>) => {
-    const page = await originalNewPage(...args);
-    return augmentPage(page);
-  }) as BrowserContext['newPage'];
-
-  const originalPages = context.pages?.bind(context);
-  if (originalPages) {
-    context.pages = (() =>
-      originalPages().map((page) =>
-        augmentPage(page),
-      )) as BrowserContext['pages'];
-  }
-
-  if (!(context as unknown as { agent?: unknown }).agent) {
-    defineHiddenProperty(context, 'agent', createAgentStub());
-  }
-
-  defineHiddenProperty(context, CONTEXT_PATCHED, true);
-
-  return context;
-}
-
-export function augmentBrowser<T extends Browser>(browser: T): T {
-  if (
-    (browser as unknown as { [BROWSER_PATCHED]?: boolean })[BROWSER_PATCHED]
-  ) {
-    return browser;
-  }
-
-  const originalNewContext = browser.newContext.bind(browser);
-  browser.newContext = (async (...args: Parameters<Browser['newContext']>) => {
-    const context = await originalNewContext(...args);
-    return augmentBrowserContext(context);
-  }) as Browser['newContext'];
-
-  const originalNewPage = browser.newPage.bind(browser);
-  browser.newPage = (async (...args: Parameters<Browser['newPage']>) => {
-    const page = await originalNewPage(...args);
-    return augmentPage(page);
-  }) as Browser['newPage'];
-
-  const originalContexts = browser.contexts.bind(browser);
-  browser.contexts = (() =>
-    originalContexts().map((context) =>
-      augmentBrowserContext(context),
-    )) as Browser['contexts'];
-
-  if (!(browser as unknown as { agent?: unknown }).agent) {
-    defineHiddenProperty(browser, 'agent', createAgentStub());
-  }
-
-  defineHiddenProperty(browser, BROWSER_PATCHED, true);
-
-  return browser;
-}
-
-export function augmentBrowserType<TBrowser extends Browser>(
-  browserType: BrowserType<TBrowser>,
-): BrowserType<TBrowser> {
-  if (
-    (browserType as unknown as { [BROWSER_TYPE_PATCHED]?: boolean })[
-      BROWSER_TYPE_PATCHED
-    ]
-  ) {
-    return browserType;
-  }
-
-  const originalLaunch = browserType.launch.bind(browserType);
-  browserType.launch = (async (
-    ...args: Parameters<BrowserType<TBrowser>['launch']>
-  ) => {
-    const browser = await originalLaunch(...args);
-    return augmentBrowser(browser);
-  }) as BrowserType<TBrowser>['launch'];
-
-  const originalConnect = browserType.connect?.bind(browserType);
-  if (originalConnect) {
-    browserType.connect = (async (
-      ...args: Parameters<NonNullable<BrowserType<TBrowser>['connect']>>
-    ) => {
-      const browser = await originalConnect(...args);
-      return augmentBrowser(browser);
-    }) as NonNullable<BrowserType<TBrowser>['connect']>;
-  }
-
-  const originalConnectOverCDP = browserType.connectOverCDP?.bind(browserType);
-  if (originalConnectOverCDP) {
-    browserType.connectOverCDP = (async (
-      ...args: Parameters<NonNullable<BrowserType<TBrowser>['connectOverCDP']>>
-    ) => {
-      const browser = await originalConnectOverCDP(...args);
-      return augmentBrowser(browser);
-    }) as NonNullable<BrowserType<TBrowser>['connectOverCDP']>;
-  }
-
-  const originalLaunchPersistentContext =
-    browserType.launchPersistentContext?.bind(browserType);
-  if (originalLaunchPersistentContext) {
-    browserType.launchPersistentContext = (async (
-      ...args: Parameters<
-        NonNullable<BrowserType<TBrowser>['launchPersistentContext']>
-      >
-    ) => {
-      const context = await originalLaunchPersistentContext(...args);
-      return augmentBrowserContext(context);
-    }) as NonNullable<BrowserType<TBrowser>['launchPersistentContext']>;
-  }
-
-  defineHiddenProperty(browserType, BROWSER_TYPE_PATCHED, true);
-
-  return browserType;
-}

package/src/playwright-augment/methods/agent.ts

@@ -1,19 +0,0 @@
-import type { Page } from 'playwright';
-import { requireApiKey } from '../../runtime';
-
-type AgentOptions = {
-  page: Page;
-  maxCycles?: number;
-};
-
-export function createAgentStub(): (
-  prompt: string,
-  options: AgentOptions,
-) => Promise<{ success: boolean }> {
-  return async (prompt: string, options: AgentOptions) => {
-    requireApiKey();
-    void prompt;
-    void options;
-    return { success: true };
-  };
-}