@stablyai/playwright-base 2.0.16 → 2.1.1

package/dist/index.d.cts

@@ -3,8 +3,8 @@ import { BrowserContext, Page, Locator, MatcherReturnType, Browser, BrowserType
 import * as z4 from 'zod/v4/core';
 
 type AnthropicModel = "anthropic/claude-sonnet-4-5-20250929";
-type GeminiModel = "google/gemini-2.5-computer-use-preview-10-2025";
-type Model = AnthropicModel | GeminiModel | (string & {});
+type GeminiModel$1 = "google/gemini-2.5-computer-use-preview-10-2025";
+type Model = AnthropicModel | GeminiModel$1 | (string & {});
 
 /**
  * Options for configuring agent behavior during execution.
@@ -82,16 +82,64 @@ declare class Agent {
     act(prompt: string, options: AgentActOptions): Promise<void>;
 }
 
+type OpenAIModel = "openai/o4-mini";
+type GeminiModel = "google/gemini-3-pro-preview" | "google/gemini-3-flash-preview";
+/**
+ * AI model to use for Stably API calls.
+ *
+ * Predefined models:
+ * - `"openai/o4-mini"` - OpenAI's efficient reasoning model
+ * - `"google/gemini-3-pro-preview"` - Google's most capable model
+ * - `"google/gemini-3-flash-preview"` - Google's fast, efficient model
+ *
+ * Custom models can also be specified as strings.
+ */
+type AIModel = OpenAIModel | GeminiModel | (string & {});
+
 type ExtractSchema = {
     safeParseAsync(data: unknown, params?: z4.ParseContext<z4.$ZodIssue>): Promise<z4.util.SafeParseResult<z4.output<any>>>;
 } & z4.$ZodType;
 type SchemaOutput<T extends ExtractSchema> = z4.output<T>;
 
+type GetLocatorsByAIResult = {
+    locator: Locator;
+    count: number;
+    reason: string;
+};
+type GetLocatorsByAIOptions = {
+    /**
+     * AI model to use for element location.
+     */
+    model?: AIModel;
+};
+
 type MatcherContext = {
     isNot: boolean;
     message?: () => string;
 };
 declare const stablyPlaywrightMatchers: {
+    /**
+     * 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');
+     * ```
+     */
+    readonly aiAssert: (this: MatcherContext, received: Page | Locator, condition: string, options?: ScreenshotPromptOptions) => Promise<MatcherReturnType>;
+    /**
+     * @deprecated Use `aiAssert` instead. This method will be removed in a future version.
+     */
     readonly toMatchScreenshotPrompt: (this: MatcherContext, received: Page | Locator, condition: string, options?: ScreenshotPromptOptions) => Promise<MatcherReturnType>;
 };
 
@@ -104,9 +152,24 @@ declare function augmentBrowserType<TBrowser extends Browser>(browserType: Brows
 declare function setApiKey(apiKey: string): void;
 declare function requireApiKey(): string;
 
-type ScreenshotPromptOptions = _playwright_test.PageAssertionsToHaveScreenshotOptions;
+type ScreenshotPromptOptions = _playwright_test.PageAssertionsToHaveScreenshotOptions & {
+    /**
+     * AI model to use for screenshot prompt assertion.
+     */
+    model?: AIModel;
+};
 
 type Expect<T = Page> = {
+    /**
+     * Asserts that the target satisfies a natural language condition using AI vision.
+     *
+     * @param condition - A natural language description of what should be true
+     * @param options - Optional screenshot options
+     */
+    aiAssert(condition: string, options?: ScreenshotPromptOptions): Promise<void>;
+    /**
+     * @deprecated Use `aiAssert` instead. This method will be removed in a future version.
+     */
     toMatchScreenshotPrompt(condition: string, options?: ScreenshotPromptOptions): Promise<void>;
 };
 declare module "@playwright/test" {
@@ -131,11 +194,27 @@ declare module "@playwright/test" {
          * @param prompt - A natural language description of what information to extract
          * @param options - Configuration object containing the Zod schema for validation
          * @param options.schema - Zod schema to validate and type the extracted data
+         * @param options.model - AI model to use for extraction
          * @returns Typed data matching the provided schema
          */
         extract<T extends ExtractSchema>(prompt: string, options: {
             schema: T;
+            model?: AIModel;
         }): Promise<SchemaOutput<T>>;
+        /**
+         * Extracts information from this locator using Stably AI.
+         *
+         * Takes a screenshot of the locator and uses AI to extract information based on the
+         * provided prompt.
+         *
+         * @param prompt - A natural language description of what information to extract
+         * @param options - Configuration object with optional model selection
+         * @param options.model - AI model to use for extraction
+         * @returns A string containing the extracted information
+         */
+        extract(prompt: string, options: {
+            model?: AIModel;
+        }): Promise<string>;
     }
     interface Page {
         /**
@@ -158,11 +237,64 @@ declare module "@playwright/test" {
          * @param prompt - A natural language description of what information to extract
          * @param options - Configuration object containing the Zod schema for validation
          * @param options.schema - Zod schema to validate and type the extracted data
+         * @param options.model - AI model to use for extraction
          * @returns Typed data matching the provided schema
          */
         extract<T extends ExtractSchema>(prompt: string, options: {
             schema: T;
+            model?: AIModel;
         }): Promise<SchemaOutput<T>>;
+        /**
+         * Extracts information from this page using Stably AI.
+         *
+         * Takes a screenshot of the page and uses AI to extract information based on the
+         * provided prompt.
+         *
+         * @param prompt - A natural language description of what information to extract
+         * @param options - Configuration object with optional model selection
+         * @param options.model - AI model to use for extraction
+         * @returns A string containing the extracted information
+         */
+        extract(prompt: string, options: {
+            model?: AIModel;
+        }): Promise<string>;
+        /**
+         * Gets Locators from a page using AI based on the page's accessibility tree.
+         *
+         * Analyzes the page's aria snapshot and uses AI to identify elements matching
+         * the provided natural language prompt. Returns Playwright Locators that can
+         * be used for interactions and assertions.
+         *
+         * Requires Playwright v1.54.1 or higher.
+         *
+         * @param prompt - Natural language description of the elements to find.
+         *   Should describe elements by their accessible properties (labels, roles, text)
+         *   rather than visual attributes (colors, positioning).
+         * @param options - Optional configuration including model selection
+         *
+         * @returns Object containing:
+         *   - `locator`: Playwright Locator for the found elements (empty if none found)
+         *   - `count`: Number of elements found (0 if none)
+         *   - `reason`: AI's explanation of what it found and why
+         *
+         * @example
+         * // Find a single element
+         * const { locator: loginBtn } = await page.getLocatorsByAI("the login button");
+         * await loginBtn.click();
+         *
+         * @example
+         * // Find multiple elements
+         * const { locator: cards, count } = await page.getLocatorsByAI("all product cards in the grid");
+         * console.log(`Found ${count} product cards`);
+         * await expect(cards).toHaveCount(count);
+         *
+         * @example
+         * // With model selection
+         * const { locator } = await page.getLocatorsByAI("the submit button", {
+         *   model: "google/gemini-3-flash-preview"
+         * });
+         */
+        getLocatorsByAI(prompt: string, options?: GetLocatorsByAIOptions): Promise<GetLocatorsByAIResult>;
     }
     interface BrowserContext {
         /**
@@ -223,5 +355,5 @@ declare module "@playwright/test" {
 }
 
 export { Agent, augmentBrowser, augmentBrowserContext, augmentBrowserType, augmentLocator, augmentPage, requireApiKey, setApiKey, stablyPlaywrightMatchers };
-export type { Expect, ExtractSchema, SchemaOutput, ScreenshotPromptOptions };
+export type { AIModel, Expect, ExtractSchema, GetLocatorsByAIOptions, GetLocatorsByAIResult, SchemaOutput, ScreenshotPromptOptions };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","sources":["../src/playwright-augment/methods/agent/models.ts","../src/playwright-augment/methods/agent.ts","../src/ai/extract.ts","../src/expect.ts","../src/playwright-augment/augment.ts","../src/runtime.ts","../src/index.ts"],"mappings":";;;;AAAA,KAAK,cAAc;AACnB,KAAK,WAAW;AACV,KAAM,KAAK,GAAG,cAAc,GAAG,WAAW;;ACchD;;;AAGA,KAAK,eAAe;;;;UAIZ,IAAI;;;;;;;;;;;YAWF,KAAK;;AAQf;;;;;;;;;;;;;;AAcA,cAAa,KAAK;6BACqB,cAAc;gCAAd,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iCAsChB,eAAe,GAAG,OAAO;;;ACnFxD,KAAM,aAAa;2CAGZ,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,SAAS,IAEpC,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC,MAAM;IAC1C,EAAE,CAAC,QAAQ;AAET,KAAM,YAAY,WAAW,aAAa,IAAI,EAAE,CAAC,MAAM;;ACT7D,KAAK,cAAc;;;;AA+BnB,cAAa,wBAAwB;6CAE3B,cAAc,YACV,IAAI,GAAG,OAAO,+BAEd,uBAAuB,KAChC,OAAO,CAAC,iBAAiB;;;AChB9B,iBAAgB,cAAc,WAAW,OAAO;AAchD,iBAAgB,WAAW,WAAW,IAAI;AAiB1C,iBAAgB,qBAAqB,WAAW,cAAc;AA8B9D,iBAAgB,cAAc,WAAW,OAAO;AAuChD,iBAAgB,kBAAkB,kBAAkB,OAAO,eAC5C,WAAW,aACvB,WAAW;;ACpId,iBAAgB,SAAS;AAQzB,iBAAgB,aAAa;;ACQvB,KAAM,uBAAuB,GAEjC,gBAAyB,CAAE,qCAAqC;;AAY5D,KAAM,MAAM,KAAKA,IAAY;yDAGrB,uBAAuB,GAChC,OAAO;;AAGZ;;;;;;;;;;;;iCAa6B,OAAO;;;;;;;;;;;;0BAYd,aAAa;;YAG5B,OAAO,CAAC,YAAY;;;;;;;;;;;;;iCAeE,OAAO;;;;;;;;;;;;0BAYd,aAAa;;YAG5B,OAAO,CAAC,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBA+BXC,KAAkD;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBA+BlDA,KAAkD","names":["InternalPage","__playwright_augment_methods_agent.Agent"]}
+{"version":3,"file":"index.d.cts","sources":["../src/playwright-augment/methods/agent/models.ts","../src/playwright-augment/methods/agent.ts","../src/ai/models.ts","../src/ai/extract.ts","../src/ai/get-locators-by-ai.ts","../src/expect.ts","../src/playwright-augment/augment.ts","../src/runtime.ts","../src/index.ts"],"mappings":";;;;AAAA,KAAK,cAAc;AACnB,KAAKA,aAAW;AACV,KAAM,KAAK,GAAG,cAAc,GAAGA,aAAW;;ACchD;;;AAGA,KAAK,eAAe;;;;UAIZ,IAAI;;;;;;;;;;;YAWF,KAAK;;AAQf;;;;;;;;;;;;;;AAcA,cAAa,KAAK;6BACqB,cAAc;gCAAd,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iCAsChB,eAAe,GAAG,OAAO;;;AC9F9D,KAAK,WAAW;AAGhB,KAAK,WAAW;AAIhB;;;;;;;;;;AAUM,KAAM,OAAO,GAAG,WAAW,GAAG,WAAW;;ACLzC,KAAM,aAAa;2CAGZ,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,SAAS,IAEpC,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC,MAAM;IAC1C,EAAE,CAAC,QAAQ;AAET,KAAM,YAAY,WAAW,aAAa,IAAI,EAAE,CAAC,MAAM;;ACFvD,KAAM,qBAAqB;aACtB,OAAO;;;;AAKZ,KAAM,sBAAsB;;;;YAIxB,OAAO;;;AClBjB,KAAK,cAAc;;;;AA+BnB,cAAa,wBAAwB;;;;;;;;;;;;;;;;;;;8BAoB3B,cAAc,YACV,IAAI,GAAG,OAAO,+BAEd,uBAAuB,KAChC,OAAO,CAAC,iBAAiB;;;;6CA+EpB,cAAc,YACV,IAAI,GAAG,OAAO,+BAEd,uBAAuB,KAChC,OAAO,CAAC,iBAAiB;;;ACpH9B,iBAAgB,cAAc,WAAW,OAAO;AAchD,iBAAgB,WAAW,WAAW,IAAI;AAkB1C,iBAAgB,qBAAqB,WAAW,cAAc;AA8B9D,iBAAgB,cAAc,WAAW,OAAO;AAuChD,iBAAgB,kBAAkB,kBAAkB,OAAO,eAC5C,WAAW,aACvB,WAAW;;ACtId,iBAAgB,SAAS;AAQzB,iBAAgB,aAAa;;ACkBvB,KAAM,uBAAuB,GAEjC,gBAAyB,CAAE,qCAAqC;;;;YAItD,OAAO;;;AAab,KAAM,MAAM,KAAKC,IAAY;;;;;;;0CAOK,uBAAuB,GAAG,OAAO;;;;yDAO3D,uBAAuB,GAChC,OAAO;;AAGZ;;;;;;;;;;;;iCAa6B,OAAO;;;;;;;;;;;;;0BAad,aAAa;;oBAEC,OAAO;YACpC,OAAO,CAAC,YAAY;;;;;;;;;;;;;oBAYoB,OAAO;YAAK,OAAO;;;;;;;;;;;;;iCAerC,OAAO;;;;;;;;;;;;;0BAad,aAAa;;oBAEC,OAAO;YACpC,OAAO,CAAC,YAAY;;;;;;;;;;;;;oBAYoB,OAAO;YAAK,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kDAwClD,sBAAsB,GAC/B,OAAO,CAAC,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBA+BpBC,KAAkD;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBA+BlDA,KAAkD","names":["GeminiModel","InternalPage","__playwright_augment_methods_agent.Agent"]}

package/dist/index.d.mts

@@ -3,8 +3,8 @@ import { BrowserContext, Page, Locator, MatcherReturnType, Browser, BrowserType
 import * as z4 from 'zod/v4/core';
 
 type AnthropicModel = "anthropic/claude-sonnet-4-5-20250929";
-type GeminiModel = "google/gemini-2.5-computer-use-preview-10-2025";
-type Model = AnthropicModel | GeminiModel | (string & {});
+type GeminiModel$1 = "google/gemini-2.5-computer-use-preview-10-2025";
+type Model = AnthropicModel | GeminiModel$1 | (string & {});
 
 /**
  * Options for configuring agent behavior during execution.
@@ -82,16 +82,64 @@ declare class Agent {
     act(prompt: string, options: AgentActOptions): Promise<void>;
 }
 
+type OpenAIModel = "openai/o4-mini";
+type GeminiModel = "google/gemini-3-pro-preview" | "google/gemini-3-flash-preview";
+/**
+ * AI model to use for Stably API calls.
+ *
+ * Predefined models:
+ * - `"openai/o4-mini"` - OpenAI's efficient reasoning model
+ * - `"google/gemini-3-pro-preview"` - Google's most capable model
+ * - `"google/gemini-3-flash-preview"` - Google's fast, efficient model
+ *
+ * Custom models can also be specified as strings.
+ */
+type AIModel = OpenAIModel | GeminiModel | (string & {});
+
 type ExtractSchema = {
     safeParseAsync(data: unknown, params?: z4.ParseContext<z4.$ZodIssue>): Promise<z4.util.SafeParseResult<z4.output<any>>>;
 } & z4.$ZodType;
 type SchemaOutput<T extends ExtractSchema> = z4.output<T>;
 
+type GetLocatorsByAIResult = {
+    locator: Locator;
+    count: number;
+    reason: string;
+};
+type GetLocatorsByAIOptions = {
+    /**
+     * AI model to use for element location.
+     */
+    model?: AIModel;
+};
+
 type MatcherContext = {
     isNot: boolean;
     message?: () => string;
 };
 declare const stablyPlaywrightMatchers: {
+    /**
+     * 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');
+     * ```
+     */
+    readonly aiAssert: (this: MatcherContext, received: Page | Locator, condition: string, options?: ScreenshotPromptOptions) => Promise<MatcherReturnType>;
+    /**
+     * @deprecated Use `aiAssert` instead. This method will be removed in a future version.
+     */
     readonly toMatchScreenshotPrompt: (this: MatcherContext, received: Page | Locator, condition: string, options?: ScreenshotPromptOptions) => Promise<MatcherReturnType>;
 };
 
@@ -104,9 +152,24 @@ declare function augmentBrowserType<TBrowser extends Browser>(browserType: Brows
 declare function setApiKey(apiKey: string): void;
 declare function requireApiKey(): string;
 
-type ScreenshotPromptOptions = _playwright_test.PageAssertionsToHaveScreenshotOptions;
+type ScreenshotPromptOptions = _playwright_test.PageAssertionsToHaveScreenshotOptions & {
+    /**
+     * AI model to use for screenshot prompt assertion.
+     */
+    model?: AIModel;
+};
 
 type Expect<T = Page> = {
+    /**
+     * Asserts that the target satisfies a natural language condition using AI vision.
+     *
+     * @param condition - A natural language description of what should be true
+     * @param options - Optional screenshot options
+     */
+    aiAssert(condition: string, options?: ScreenshotPromptOptions): Promise<void>;
+    /**
+     * @deprecated Use `aiAssert` instead. This method will be removed in a future version.
+     */
     toMatchScreenshotPrompt(condition: string, options?: ScreenshotPromptOptions): Promise<void>;
 };
 declare module "@playwright/test" {
@@ -131,11 +194,27 @@ declare module "@playwright/test" {
          * @param prompt - A natural language description of what information to extract
          * @param options - Configuration object containing the Zod schema for validation
          * @param options.schema - Zod schema to validate and type the extracted data
+         * @param options.model - AI model to use for extraction
          * @returns Typed data matching the provided schema
          */
         extract<T extends ExtractSchema>(prompt: string, options: {
             schema: T;
+            model?: AIModel;
         }): Promise<SchemaOutput<T>>;
+        /**
+         * Extracts information from this locator using Stably AI.
+         *
+         * Takes a screenshot of the locator and uses AI to extract information based on the
+         * provided prompt.
+         *
+         * @param prompt - A natural language description of what information to extract
+         * @param options - Configuration object with optional model selection
+         * @param options.model - AI model to use for extraction
+         * @returns A string containing the extracted information
+         */
+        extract(prompt: string, options: {
+            model?: AIModel;
+        }): Promise<string>;
     }
     interface Page {
         /**
@@ -158,11 +237,64 @@ declare module "@playwright/test" {
          * @param prompt - A natural language description of what information to extract
          * @param options - Configuration object containing the Zod schema for validation
          * @param options.schema - Zod schema to validate and type the extracted data
+         * @param options.model - AI model to use for extraction
          * @returns Typed data matching the provided schema
          */
         extract<T extends ExtractSchema>(prompt: string, options: {
             schema: T;
+            model?: AIModel;
         }): Promise<SchemaOutput<T>>;
+        /**
+         * Extracts information from this page using Stably AI.
+         *
+         * Takes a screenshot of the page and uses AI to extract information based on the
+         * provided prompt.
+         *
+         * @param prompt - A natural language description of what information to extract
+         * @param options - Configuration object with optional model selection
+         * @param options.model - AI model to use for extraction
+         * @returns A string containing the extracted information
+         */
+        extract(prompt: string, options: {
+            model?: AIModel;
+        }): Promise<string>;
+        /**
+         * Gets Locators from a page using AI based on the page's accessibility tree.
+         *
+         * Analyzes the page's aria snapshot and uses AI to identify elements matching
+         * the provided natural language prompt. Returns Playwright Locators that can
+         * be used for interactions and assertions.
+         *
+         * Requires Playwright v1.54.1 or higher.
+         *
+         * @param prompt - Natural language description of the elements to find.
+         *   Should describe elements by their accessible properties (labels, roles, text)
+         *   rather than visual attributes (colors, positioning).
+         * @param options - Optional configuration including model selection
+         *
+         * @returns Object containing:
+         *   - `locator`: Playwright Locator for the found elements (empty if none found)
+         *   - `count`: Number of elements found (0 if none)
+         *   - `reason`: AI's explanation of what it found and why
+         *
+         * @example
+         * // Find a single element
+         * const { locator: loginBtn } = await page.getLocatorsByAI("the login button");
+         * await loginBtn.click();
+         *
+         * @example
+         * // Find multiple elements
+         * const { locator: cards, count } = await page.getLocatorsByAI("all product cards in the grid");
+         * console.log(`Found ${count} product cards`);
+         * await expect(cards).toHaveCount(count);
+         *
+         * @example
+         * // With model selection
+         * const { locator } = await page.getLocatorsByAI("the submit button", {
+         *   model: "google/gemini-3-flash-preview"
+         * });
+         */
+        getLocatorsByAI(prompt: string, options?: GetLocatorsByAIOptions): Promise<GetLocatorsByAIResult>;
     }
     interface BrowserContext {
         /**
@@ -223,5 +355,5 @@ declare module "@playwright/test" {
 }
 
 export { Agent, augmentBrowser, augmentBrowserContext, augmentBrowserType, augmentLocator, augmentPage, requireApiKey, setApiKey, stablyPlaywrightMatchers };
-export type { Expect, ExtractSchema, SchemaOutput, ScreenshotPromptOptions };
+export type { AIModel, Expect, ExtractSchema, GetLocatorsByAIOptions, GetLocatorsByAIResult, SchemaOutput, ScreenshotPromptOptions };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","sources":["../src/playwright-augment/methods/agent/models.ts","../src/playwright-augment/methods/agent.ts","../src/ai/extract.ts","../src/expect.ts","../src/playwright-augment/augment.ts","../src/runtime.ts","../src/index.ts"],"mappings":";;;;AAAA,KAAK,cAAc;AACnB,KAAK,WAAW;AACV,KAAM,KAAK,GAAG,cAAc,GAAG,WAAW;;ACchD;;;AAGA,KAAK,eAAe;;;;UAIZ,IAAI;;;;;;;;;;;YAWF,KAAK;;AAQf;;;;;;;;;;;;;;AAcA,cAAa,KAAK;6BACqB,cAAc;gCAAd,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iCAsChB,eAAe,GAAG,OAAO;;;ACnFxD,KAAM,aAAa;2CAGZ,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,SAAS,IAEpC,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC,MAAM;IAC1C,EAAE,CAAC,QAAQ;AAET,KAAM,YAAY,WAAW,aAAa,IAAI,EAAE,CAAC,MAAM;;ACT7D,KAAK,cAAc;;;;AA+BnB,cAAa,wBAAwB;6CAE3B,cAAc,YACV,IAAI,GAAG,OAAO,+BAEd,uBAAuB,KAChC,OAAO,CAAC,iBAAiB;;;AChB9B,iBAAgB,cAAc,WAAW,OAAO;AAchD,iBAAgB,WAAW,WAAW,IAAI;AAiB1C,iBAAgB,qBAAqB,WAAW,cAAc;AA8B9D,iBAAgB,cAAc,WAAW,OAAO;AAuChD,iBAAgB,kBAAkB,kBAAkB,OAAO,eAC5C,WAAW,aACvB,WAAW;;ACpId,iBAAgB,SAAS;AAQzB,iBAAgB,aAAa;;ACQvB,KAAM,uBAAuB,GAEjC,gBAAyB,CAAE,qCAAqC;;AAY5D,KAAM,MAAM,KAAKA,IAAY;yDAGrB,uBAAuB,GAChC,OAAO;;AAGZ;;;;;;;;;;;;iCAa6B,OAAO;;;;;;;;;;;;0BAYd,aAAa;;YAG5B,OAAO,CAAC,YAAY;;;;;;;;;;;;;iCAeE,OAAO;;;;;;;;;;;;0BAYd,aAAa;;YAG5B,OAAO,CAAC,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBA+BXC,KAAkD;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBA+BlDA,KAAkD","names":["InternalPage","__playwright_augment_methods_agent.Agent"]}
+{"version":3,"file":"index.d.mts","sources":["../src/playwright-augment/methods/agent/models.ts","../src/playwright-augment/methods/agent.ts","../src/ai/models.ts","../src/ai/extract.ts","../src/ai/get-locators-by-ai.ts","../src/expect.ts","../src/playwright-augment/augment.ts","../src/runtime.ts","../src/index.ts"],"mappings":";;;;AAAA,KAAK,cAAc;AACnB,KAAKA,aAAW;AACV,KAAM,KAAK,GAAG,cAAc,GAAGA,aAAW;;ACchD;;;AAGA,KAAK,eAAe;;;;UAIZ,IAAI;;;;;;;;;;;YAWF,KAAK;;AAQf;;;;;;;;;;;;;;AAcA,cAAa,KAAK;6BACqB,cAAc;gCAAd,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iCAsChB,eAAe,GAAG,OAAO;;;AC9F9D,KAAK,WAAW;AAGhB,KAAK,WAAW;AAIhB;;;;;;;;;;AAUM,KAAM,OAAO,GAAG,WAAW,GAAG,WAAW;;ACLzC,KAAM,aAAa;2CAGZ,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,SAAS,IAEpC,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC,MAAM;IAC1C,EAAE,CAAC,QAAQ;AAET,KAAM,YAAY,WAAW,aAAa,IAAI,EAAE,CAAC,MAAM;;ACFvD,KAAM,qBAAqB;aACtB,OAAO;;;;AAKZ,KAAM,sBAAsB;;;;YAIxB,OAAO;;;AClBjB,KAAK,cAAc;;;;AA+BnB,cAAa,wBAAwB;;;;;;;;;;;;;;;;;;;8BAoB3B,cAAc,YACV,IAAI,GAAG,OAAO,+BAEd,uBAAuB,KAChC,OAAO,CAAC,iBAAiB;;;;6CA+EpB,cAAc,YACV,IAAI,GAAG,OAAO,+BAEd,uBAAuB,KAChC,OAAO,CAAC,iBAAiB;;;ACpH9B,iBAAgB,cAAc,WAAW,OAAO;AAchD,iBAAgB,WAAW,WAAW,IAAI;AAkB1C,iBAAgB,qBAAqB,WAAW,cAAc;AA8B9D,iBAAgB,cAAc,WAAW,OAAO;AAuChD,iBAAgB,kBAAkB,kBAAkB,OAAO,eAC5C,WAAW,aACvB,WAAW;;ACtId,iBAAgB,SAAS;AAQzB,iBAAgB,aAAa;;ACkBvB,KAAM,uBAAuB,GAEjC,gBAAyB,CAAE,qCAAqC;;;;YAItD,OAAO;;;AAab,KAAM,MAAM,KAAKC,IAAY;;;;;;;0CAOK,uBAAuB,GAAG,OAAO;;;;yDAO3D,uBAAuB,GAChC,OAAO;;AAGZ;;;;;;;;;;;;iCAa6B,OAAO;;;;;;;;;;;;;0BAad,aAAa;;oBAEC,OAAO;YACpC,OAAO,CAAC,YAAY;;;;;;;;;;;;;oBAYoB,OAAO;YAAK,OAAO;;;;;;;;;;;;;iCAerC,OAAO;;;;;;;;;;;;;0BAad,aAAa;;oBAEC,OAAO;YACpC,OAAO,CAAC,YAAY;;;;;;;;;;;;;oBAYoB,OAAO;YAAK,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kDAwClD,sBAAsB,GAC/B,OAAO,CAAC,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBA+BpBC,KAAkD;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBA+BlDA,KAAkD","names":["GeminiModel","InternalPage","__playwright_augment_methods_agent.Agent"]}

package/dist/index.d.ts

@@ -3,8 +3,8 @@ import { BrowserContext, Page, Locator, MatcherReturnType, Browser, BrowserType
 import * as z4 from 'zod/v4/core';
 
 type AnthropicModel = "anthropic/claude-sonnet-4-5-20250929";
-type GeminiModel = "google/gemini-2.5-computer-use-preview-10-2025";
-type Model = AnthropicModel | GeminiModel | (string & {});
+type GeminiModel$1 = "google/gemini-2.5-computer-use-preview-10-2025";
+type Model = AnthropicModel | GeminiModel$1 | (string & {});
 
 /**
  * Options for configuring agent behavior during execution.
@@ -82,16 +82,64 @@ declare class Agent {
     act(prompt: string, options: AgentActOptions): Promise<void>;
 }
 
+type OpenAIModel = "openai/o4-mini";
+type GeminiModel = "google/gemini-3-pro-preview" | "google/gemini-3-flash-preview";
+/**
+ * AI model to use for Stably API calls.
+ *
+ * Predefined models:
+ * - `"openai/o4-mini"` - OpenAI's efficient reasoning model
+ * - `"google/gemini-3-pro-preview"` - Google's most capable model
+ * - `"google/gemini-3-flash-preview"` - Google's fast, efficient model
+ *
+ * Custom models can also be specified as strings.
+ */
+type AIModel = OpenAIModel | GeminiModel | (string & {});
+
 type ExtractSchema = {
     safeParseAsync(data: unknown, params?: z4.ParseContext<z4.$ZodIssue>): Promise<z4.util.SafeParseResult<z4.output<any>>>;
 } & z4.$ZodType;
 type SchemaOutput<T extends ExtractSchema> = z4.output<T>;
 
+type GetLocatorsByAIResult = {
+    locator: Locator;
+    count: number;
+    reason: string;
+};
+type GetLocatorsByAIOptions = {
+    /**
+     * AI model to use for element location.
+     */
+    model?: AIModel;
+};
+
 type MatcherContext = {
     isNot: boolean;
     message?: () => string;
 };
 declare const stablyPlaywrightMatchers: {
+    /**
+     * 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');
+     * ```
+     */
+    readonly aiAssert: (this: MatcherContext, received: Page | Locator, condition: string, options?: ScreenshotPromptOptions) => Promise<MatcherReturnType>;
+    /**
+     * @deprecated Use `aiAssert` instead. This method will be removed in a future version.
+     */
     readonly toMatchScreenshotPrompt: (this: MatcherContext, received: Page | Locator, condition: string, options?: ScreenshotPromptOptions) => Promise<MatcherReturnType>;
 };
 
@@ -104,9 +152,24 @@ declare function augmentBrowserType<TBrowser extends Browser>(browserType: Brows
 declare function setApiKey(apiKey: string): void;
 declare function requireApiKey(): string;
 
-type ScreenshotPromptOptions = _playwright_test.PageAssertionsToHaveScreenshotOptions;
+type ScreenshotPromptOptions = _playwright_test.PageAssertionsToHaveScreenshotOptions & {
+    /**
+     * AI model to use for screenshot prompt assertion.
+     */
+    model?: AIModel;
+};
 
 type Expect<T = Page> = {
+    /**
+     * Asserts that the target satisfies a natural language condition using AI vision.
+     *
+     * @param condition - A natural language description of what should be true
+     * @param options - Optional screenshot options
+     */
+    aiAssert(condition: string, options?: ScreenshotPromptOptions): Promise<void>;
+    /**
+     * @deprecated Use `aiAssert` instead. This method will be removed in a future version.
+     */
     toMatchScreenshotPrompt(condition: string, options?: ScreenshotPromptOptions): Promise<void>;
 };
 declare module "@playwright/test" {
@@ -131,11 +194,27 @@ declare module "@playwright/test" {
          * @param prompt - A natural language description of what information to extract
          * @param options - Configuration object containing the Zod schema for validation
          * @param options.schema - Zod schema to validate and type the extracted data
+         * @param options.model - AI model to use for extraction
          * @returns Typed data matching the provided schema
          */
         extract<T extends ExtractSchema>(prompt: string, options: {
             schema: T;
+            model?: AIModel;
         }): Promise<SchemaOutput<T>>;
+        /**
+         * Extracts information from this locator using Stably AI.
+         *
+         * Takes a screenshot of the locator and uses AI to extract information based on the
+         * provided prompt.
+         *
+         * @param prompt - A natural language description of what information to extract
+         * @param options - Configuration object with optional model selection
+         * @param options.model - AI model to use for extraction
+         * @returns A string containing the extracted information
+         */
+        extract(prompt: string, options: {
+            model?: AIModel;
+        }): Promise<string>;
     }
     interface Page {
         /**
@@ -158,11 +237,64 @@ declare module "@playwright/test" {
          * @param prompt - A natural language description of what information to extract
          * @param options - Configuration object containing the Zod schema for validation
          * @param options.schema - Zod schema to validate and type the extracted data
+         * @param options.model - AI model to use for extraction
          * @returns Typed data matching the provided schema
          */
         extract<T extends ExtractSchema>(prompt: string, options: {
             schema: T;
+            model?: AIModel;
         }): Promise<SchemaOutput<T>>;
+        /**
+         * Extracts information from this page using Stably AI.
+         *
+         * Takes a screenshot of the page and uses AI to extract information based on the
+         * provided prompt.
+         *
+         * @param prompt - A natural language description of what information to extract
+         * @param options - Configuration object with optional model selection
+         * @param options.model - AI model to use for extraction
+         * @returns A string containing the extracted information
+         */
+        extract(prompt: string, options: {
+            model?: AIModel;
+        }): Promise<string>;
+        /**
+         * Gets Locators from a page using AI based on the page's accessibility tree.
+         *
+         * Analyzes the page's aria snapshot and uses AI to identify elements matching
+         * the provided natural language prompt. Returns Playwright Locators that can
+         * be used for interactions and assertions.
+         *
+         * Requires Playwright v1.54.1 or higher.
+         *
+         * @param prompt - Natural language description of the elements to find.
+         *   Should describe elements by their accessible properties (labels, roles, text)
+         *   rather than visual attributes (colors, positioning).
+         * @param options - Optional configuration including model selection
+         *
+         * @returns Object containing:
+         *   - `locator`: Playwright Locator for the found elements (empty if none found)
+         *   - `count`: Number of elements found (0 if none)
+         *   - `reason`: AI's explanation of what it found and why
+         *
+         * @example
+         * // Find a single element
+         * const { locator: loginBtn } = await page.getLocatorsByAI("the login button");
+         * await loginBtn.click();
+         *
+         * @example
+         * // Find multiple elements
+         * const { locator: cards, count } = await page.getLocatorsByAI("all product cards in the grid");
+         * console.log(`Found ${count} product cards`);
+         * await expect(cards).toHaveCount(count);
+         *
+         * @example
+         * // With model selection
+         * const { locator } = await page.getLocatorsByAI("the submit button", {
+         *   model: "google/gemini-3-flash-preview"
+         * });
+         */
+        getLocatorsByAI(prompt: string, options?: GetLocatorsByAIOptions): Promise<GetLocatorsByAIResult>;
     }
     interface BrowserContext {
         /**
@@ -223,5 +355,5 @@ declare module "@playwright/test" {
 }
 
 export { Agent, augmentBrowser, augmentBrowserContext, augmentBrowserType, augmentLocator, augmentPage, requireApiKey, setApiKey, stablyPlaywrightMatchers };
-export type { Expect, ExtractSchema, SchemaOutput, ScreenshotPromptOptions };
+export type { AIModel, Expect, ExtractSchema, GetLocatorsByAIOptions, GetLocatorsByAIResult, SchemaOutput, ScreenshotPromptOptions };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sources":["../src/playwright-augment/methods/agent/models.ts","../src/playwright-augment/methods/agent.ts","../src/ai/extract.ts","../src/expect.ts","../src/playwright-augment/augment.ts","../src/runtime.ts","../src/index.ts"],"mappings":";;;;AAAA,KAAK,cAAc;AACnB,KAAK,WAAW;AACV,KAAM,KAAK,GAAG,cAAc,GAAG,WAAW;;ACchD;;;AAGA,KAAK,eAAe;;;;UAIZ,IAAI;;;;;;;;;;;YAWF,KAAK;;AAQf;;;;;;;;;;;;;;AAcA,cAAa,KAAK;6BACqB,cAAc;gCAAd,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iCAsChB,eAAe,GAAG,OAAO;;;ACnFxD,KAAM,aAAa;2CAGZ,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,SAAS,IAEpC,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC,MAAM;IAC1C,EAAE,CAAC,QAAQ;AAET,KAAM,YAAY,WAAW,aAAa,IAAI,EAAE,CAAC,MAAM;;ACT7D,KAAK,cAAc;;;;AA+BnB,cAAa,wBAAwB;6CAE3B,cAAc,YACV,IAAI,GAAG,OAAO,+BAEd,uBAAuB,KAChC,OAAO,CAAC,iBAAiB;;;AChB9B,iBAAgB,cAAc,WAAW,OAAO;AAchD,iBAAgB,WAAW,WAAW,IAAI;AAiB1C,iBAAgB,qBAAqB,WAAW,cAAc;AA8B9D,iBAAgB,cAAc,WAAW,OAAO;AAuChD,iBAAgB,kBAAkB,kBAAkB,OAAO,eAC5C,WAAW,aACvB,WAAW;;ACpId,iBAAgB,SAAS;AAQzB,iBAAgB,aAAa;;ACQvB,KAAM,uBAAuB,GAEjC,gBAAyB,CAAE,qCAAqC;;AAY5D,KAAM,MAAM,KAAKA,IAAY;yDAGrB,uBAAuB,GAChC,OAAO;;AAGZ;;;;;;;;;;;;iCAa6B,OAAO;;;;;;;;;;;;0BAYd,aAAa;;YAG5B,OAAO,CAAC,YAAY;;;;;;;;;;;;;iCAeE,OAAO;;;;;;;;;;;;0BAYd,aAAa;;YAG5B,OAAO,CAAC,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBA+BXC,KAAkD;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBA+BlDA,KAAkD","names":["InternalPage","__playwright_augment_methods_agent.Agent"]}
+{"version":3,"file":"index.d.ts","sources":["../src/playwright-augment/methods/agent/models.ts","../src/playwright-augment/methods/agent.ts","../src/ai/models.ts","../src/ai/extract.ts","../src/ai/get-locators-by-ai.ts","../src/expect.ts","../src/playwright-augment/augment.ts","../src/runtime.ts","../src/index.ts"],"mappings":";;;;AAAA,KAAK,cAAc;AACnB,KAAKA,aAAW;AACV,KAAM,KAAK,GAAG,cAAc,GAAGA,aAAW;;ACchD;;;AAGA,KAAK,eAAe;;;;UAIZ,IAAI;;;;;;;;;;;YAWF,KAAK;;AAQf;;;;;;;;;;;;;;AAcA,cAAa,KAAK;6BACqB,cAAc;gCAAd,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iCAsChB,eAAe,GAAG,OAAO;;;AC9F9D,KAAK,WAAW;AAGhB,KAAK,WAAW;AAIhB;;;;;;;;;;AAUM,KAAM,OAAO,GAAG,WAAW,GAAG,WAAW;;ACLzC,KAAM,aAAa;2CAGZ,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,SAAS,IAEpC,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC,MAAM;IAC1C,EAAE,CAAC,QAAQ;AAET,KAAM,YAAY,WAAW,aAAa,IAAI,EAAE,CAAC,MAAM;;ACFvD,KAAM,qBAAqB;aACtB,OAAO;;;;AAKZ,KAAM,sBAAsB;;;;YAIxB,OAAO;;;AClBjB,KAAK,cAAc;;;;AA+BnB,cAAa,wBAAwB;;;;;;;;;;;;;;;;;;;8BAoB3B,cAAc,YACV,IAAI,GAAG,OAAO,+BAEd,uBAAuB,KAChC,OAAO,CAAC,iBAAiB;;;;6CA+EpB,cAAc,YACV,IAAI,GAAG,OAAO,+BAEd,uBAAuB,KAChC,OAAO,CAAC,iBAAiB;;;ACpH9B,iBAAgB,cAAc,WAAW,OAAO;AAchD,iBAAgB,WAAW,WAAW,IAAI;AAkB1C,iBAAgB,qBAAqB,WAAW,cAAc;AA8B9D,iBAAgB,cAAc,WAAW,OAAO;AAuChD,iBAAgB,kBAAkB,kBAAkB,OAAO,eAC5C,WAAW,aACvB,WAAW;;ACtId,iBAAgB,SAAS;AAQzB,iBAAgB,aAAa;;ACkBvB,KAAM,uBAAuB,GAEjC,gBAAyB,CAAE,qCAAqC;;;;YAItD,OAAO;;;AAab,KAAM,MAAM,KAAKC,IAAY;;;;;;;0CAOK,uBAAuB,GAAG,OAAO;;;;yDAO3D,uBAAuB,GAChC,OAAO;;AAGZ;;;;;;;;;;;;iCAa6B,OAAO;;;;;;;;;;;;;0BAad,aAAa;;oBAEC,OAAO;YACpC,OAAO,CAAC,YAAY;;;;;;;;;;;;;oBAYoB,OAAO;YAAK,OAAO;;;;;;;;;;;;;iCAerC,OAAO;;;;;;;;;;;;;0BAad,aAAa;;oBAEC,OAAO;YACpC,OAAO,CAAC,YAAY;;;;;;;;;;;;;oBAYoB,OAAO;YAAK,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kDAwClD,sBAAsB,GAC/B,OAAO,CAAC,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBA+BpBC,KAAkD;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBA+BlDA,KAAkD","names":["GeminiModel","InternalPage","__playwright_augment_methods_agent.Agent"]}