@stablyai/playwright-base 2.0.16 → 2.1.0

package/dist/index.cjs

@@ -47,7 +47,7 @@ const isObject = (value) => {
 
 const SDK_METADATA_HEADERS = {
   "X-Client-Name": "stably-playwright-sdk-js",
-  "X-Client-Version": "2.0.16"
+  "X-Client-Version": "2.1.0"
 };
 
 const PROMPT_ASSERTION_PATH = "internal/v2/assert";
@@ -80,6 +80,7 @@ const parseErrorResponse = (value) => {
   return typeof error !== "string" ? void 0 : { error };
 };
 async function verifyPrompt({
+  model,
   pageMetadata,
   prompt,
   screenshot
@@ -91,6 +92,9 @@ async function verifyPrompt({
     ...pageMetadata?.title ? { pageTitle: pageMetadata.title } : {},
     ...pageMetadata?.url ? { pageUrl: pageMetadata.url } : {}
   };
+  if (model) {
+    metadata.model = model;
+  }
   form.append("metadata", JSON.stringify(metadata));
   const u8 = Uint8Array.from(screenshot);
   const blob = new Blob([u8], { type: "image/png" });
@@ -386,22 +390,41 @@ Reason: ${reason}`;
   return message;
 }
 const stablyPlaywrightMatchers = {
-  async toMatchScreenshotPrompt(received, condition, options) {
+  /**
+   * Asserts that the page or locator satisfies a natural language condition using AI vision.
+   *
+   * Takes a screenshot of the target and uses AI to verify whether the specified condition is met.
+   * The AI analyzes the visual content and provides reasoning for its determination.
+   *
+   * @param condition - A natural language description of what should be true about the page/locator
+   * @param options - Optional screenshot options (e.g., fullPage, timeout)
+   *
+   * @example
+   * ```typescript
+   * // Assert page content
+   * await expect(page).aiAssert('The login form is visible with email and password fields');
+   *
+   * // Assert locator content
+   * await expect(page.locator('.header')).aiAssert('The navigation menu contains a logout button');
+   * ```
+   */
+  async aiAssert(received, condition, options) {
     const target = isPage(received) ? received : isLocator(received) ? received : void 0;
     if (!target) {
       throw new Error(
-        "toMatchScreenshotPrompt only supports Playwright Page and Locator instances."
+        "aiAssert only supports Playwright Page and Locator instances."
       );
     }
     const targetType = isPage(target) ? "page" : "locator";
     const screenshot = await takeStableScreenshot(target, options);
     const verifyResult = await verifyPrompt({
+      model: options?.model,
       pageMetadata: isPage(target) ? { title: await target.title(), url: target.url() } : void 0,
       prompt: condition,
       screenshot
     });
     const testInfo = test.test.info();
-    const sanitizedName = condition.trim().toLowerCase().replace(/[^\w]+/g, "_").replace(/^_+|_+$/g, "").slice(0, MAX_ATTACHMENT_NAME_LENGTH) || "toMatchScreenshotPrompt";
+    const sanitizedName = condition.trim().toLowerCase().replace(/[^\w]+/g, "_").replace(/^_+|_+$/g, "").slice(0, MAX_ATTACHMENT_NAME_LENGTH) || "aiAssert";
     testInfo.attachments.push(
       {
         body: Buffer.from(
@@ -435,9 +458,20 @@ const stablyPlaywrightMatchers = {
         reason: verifyResult.reason,
         targetType
       }),
-      name: "toMatchScreenshotPrompt",
+      name: "aiAssert",
       pass: verifyResult.pass
     };
+  },
+  /**
+   * @deprecated Use `aiAssert` instead. This method will be removed in a future version.
+   */
+  async toMatchScreenshotPrompt(received, condition, options) {
+    return stablyPlaywrightMatchers.aiAssert.call(
+      this,
+      received,
+      condition,
+      options
+    );
   }
 };
 
@@ -858,7 +892,7 @@ const isExtractionResponse = (value) => {
   }
   return value.success === false && typeof value.error === "string";
 };
-const isErrorResponse = (value) => {
+const isErrorResponse$1 = (value) => {
   return isObject(value) && typeof value.error === "string";
 };
 class ExtractValidationError extends Error {
@@ -879,6 +913,7 @@ async function validateWithSchema(schema, value) {
   return result.data;
 }
 async function extract({
+  model,
   pageOrLocator,
   prompt,
   schema
@@ -899,6 +934,9 @@ async function extract({
     if (jsonSchema) {
       form.append("jsonSchema", JSON.stringify(jsonSchema));
     }
+    if (model) {
+      form.append("model", model);
+    }
     const pngBuffer = await pageOrLocator.screenshot({ type: "png" });
     const u8 = Uint8Array.from(pngBuffer);
     const blob = new Blob([u8], { type: "image/png" });
@@ -931,7 +969,7 @@ async function extract({
       });
       return schema ? await validateWithSchema(schema, value) : typeof value === "string" ? value : JSON.stringify(value);
     }
-    throw new Error(isErrorResponse(raw) ? raw.error : "Extract failed");
+    throw new Error(isErrorResponse$1(raw) ? raw.error : "Extract failed");
   });
 }
 
@@ -939,18 +977,97 @@ function createExtract(pageOrLocator) {
   const impl = (async (prompt, options) => {
     if (options?.schema) {
       return extract({
+        model: options.model,
         pageOrLocator,
         prompt,
         schema: options.schema
       });
     }
-    return extract({ pageOrLocator, prompt });
+    return extract({ model: options?.model, pageOrLocator, prompt });
   });
   return impl;
 }
 const createLocatorExtract = (locator) => createExtract(locator);
 const createPageExtract = (page) => createExtract(page);
 
+const GET_LOCATOR_PATH = "internal/v3/get-aria-refs";
+const EMPTY_LOCATOR_SELECTOR = "__stably_empty_locator__";
+function getEndpoint() {
+  const baseUrl = process.env.STABLY_API_URL || "https://api.stably.ai";
+  return new URL(GET_LOCATOR_PATH, baseUrl).toString();
+}
+const isAPIResponse = (value) => {
+  if (!isObject(value)) {
+    return false;
+  }
+  return Array.isArray(value.refs) && value.refs.every((ref) => typeof ref === "string") && typeof value.reason === "string";
+};
+const isErrorResponse = (value) => {
+  return isObject(value) && typeof value.error === "string";
+};
+async function getLocatorsByAI(page, prompt, options) {
+  return await test.test.step(`[GetLocatorByAI] ${prompt}`, async (stepInfo) => {
+    const apiKey = requireApiKey();
+    const pageWithSnapshot = page;
+    if (typeof pageWithSnapshot._snapshotForAI !== "function") {
+      throw new Error(
+        "getLocatorsByAI requires Playwright v1.54.1 or higher. Please upgrade your Playwright version."
+      );
+    }
+    const snapshotResult = await pageWithSnapshot._snapshotForAI();
+    const ariaSnapshot = typeof snapshotResult === "string" ? snapshotResult : snapshotResult.full;
+    const response = await (async () => {
+      try {
+        return await fetch(getEndpoint(), {
+          body: JSON.stringify({
+            ariaSnapshot,
+            prompt,
+            ...options?.model && { model: options.model }
+          }),
+          headers: {
+            ...SDK_METADATA_HEADERS,
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json"
+          },
+          method: "POST"
+        });
+      } catch (error) {
+        throw new Error(
+          `getLocatorsByAI failed to connect to Stably API: ${error instanceof Error ? error.message : "Unknown error"}`
+        );
+      }
+    })();
+    const raw = await response.json().catch(() => void 0);
+    if (!response.ok) {
+      const err = isErrorResponse(raw) ? raw.error : "Unknown error";
+      throw new Error(`getLocatorsByAI failed (${response.status}): ${err}`);
+    }
+    if (!isAPIResponse(raw)) {
+      throw new Error("getLocatorsByAI returned unexpected response shape");
+    }
+    await stepInfo.attach("[GetLocatorByAI] reason", {
+      body: raw.reason,
+      contentType: "text/plain"
+    });
+    const locator = raw.refs.length === 0 ? (
+      // Empty locator that matches nothing
+      page.locator(EMPTY_LOCATOR_SELECTOR)
+    ) : (
+      // Combine refs using .or()
+      raw.refs.map((ref) => page.locator(`aria-ref=${ref}`)).reduce((acc, loc) => acc.or(loc))
+    );
+    return {
+      count: raw.refs.length,
+      locator,
+      reason: raw.reason
+    };
+  });
+}
+
+const createPageGetLocatorByAI = (page) => {
+  return (prompt, options) => getLocatorsByAI(page, prompt, options);
+};
+
 const LOCATOR_PATCHED = Symbol.for("stably.playwright.locatorPatched");
 const PAGE_PATCHED = Symbol.for("stably.playwright.pagePatched");
 const CONTEXT_PATCHED = Symbol.for("stably.playwright.contextPatched");
@@ -982,6 +1099,7 @@ function augmentPage(page) {
     return augmentLocator(locator);
   });
   defineHiddenProperty(page, "extract", createPageExtract(page));
+  defineHiddenProperty(page, "getLocatorsByAI", createPageGetLocatorByAI(page));
   defineHiddenProperty(page, PAGE_PATCHED, true);
   return page;
 }