@testnexus/locatai 1.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Divyarajsinh Dodia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -0,0 +1,173 @@
+import { Locator, Page } from 'playwright-core';
+import { z } from 'zod';
+
+/**
+ * Type definitions and Zod schemas for LocatAI
+ */
+
+type LocatorOrEmpty = Locator | string;
+declare const LocatAIPlan: z.ZodObject<{
+    candidates: z.ZodArray<z.ZodObject<{
+        strategy: z.ZodObject<{
+            type: z.ZodEnum<{
+                testid: "testid";
+                role: "role";
+                label: "label";
+                placeholder: "placeholder";
+                text: "text";
+                altText: "altText";
+                title: "title";
+                css: "css";
+            }>;
+            value: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            selector: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            role: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            exact: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        }, z.core.$strip>;
+        confidence: z.ZodNumber;
+        why: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type LocatAIPlanT = z.infer<typeof LocatAIPlan>;
+interface LocatAIErrorContext {
+    action: string;
+    contextName: string;
+    url: string;
+    candidatesAnalyzed: number;
+    strategiesTried: Array<{
+        type: string;
+        reason: string;
+    }>;
+    aiResponse?: string;
+    originalError?: string;
+}
+declare class LocatAIError extends Error {
+    readonly context: LocatAIErrorContext;
+    constructor(message: string, context: LocatAIErrorContext);
+    static formatMessage(message: string, ctx: LocatAIErrorContext): string;
+}
+interface ClickOptions {
+    /** Force click even if element is not visible (for hover-dependent buttons) */
+    force?: boolean;
+}
+/**
+ * A locator that automatically falls back to AI healing if the original selector fails.
+ * Provides a subset of Playwright Locator methods with self-healing capabilities.
+ */
+interface LocatAILocator {
+    /** Click the element, with AI fallback if selector fails */
+    click(options?: ClickOptions): Promise<void>;
+    /** Fill the element with text, with AI fallback if selector fails */
+    fill(value: string): Promise<void>;
+    /** Double-click the element, with AI fallback if selector fails */
+    dblclick(): Promise<void>;
+    /** Check the checkbox/radio, with AI fallback if selector fails */
+    check(): Promise<void>;
+    /** Hover over the element, with AI fallback if selector fails */
+    hover(): Promise<void>;
+    /** Focus the element, with AI fallback if selector fails */
+    focus(): Promise<void>;
+    /** Uncheck a checkbox/radio, with AI fallback if selector fails */
+    uncheck(): Promise<void>;
+    /** Select an option in a dropdown, with AI fallback if selector fails */
+    selectOption(value: string): Promise<void>;
+}
+interface LocatAIMethods {
+    click(target: LocatorOrEmpty, contextName: string, options?: ClickOptions): Promise<void>;
+    fill(target: LocatorOrEmpty, contextName: string, value: string): Promise<void>;
+    selectOption(target: LocatorOrEmpty, contextName: string, value: string): Promise<void>;
+    dblclick(target: LocatorOrEmpty, contextName: string): Promise<void>;
+    check(target: LocatorOrEmpty, contextName: string): Promise<void>;
+    uncheck(target: LocatorOrEmpty, contextName: string): Promise<void>;
+    hover(target: LocatorOrEmpty, contextName: string): Promise<void>;
+    focus(target: LocatorOrEmpty, contextName: string): Promise<void>;
+    setTestName(name: string): void;
+    /**
+     * Create a self-healing locator with a semantic description fallback.
+     * @param selector CSS selector or Playwright locator string
+     * @param contextName Semantic description for AI fallback
+     * @returns A LocatAILocator that can be used like a regular locator
+     * @example
+     * await page.locatai.locator('.new-todo', 'Input field for new todos').fill('Buy milk');
+     */
+    locator(selector: string, contextName: string): LocatAILocator;
+}
+interface LocatAIPage extends Page {
+    locatai: LocatAIMethods;
+}
+interface LocatAIOptions {
+    enabled?: boolean;
+    provider?: "openai" | "gpt" | "anthropic" | "claude" | "google" | "gemini" | "local" | "ollama";
+    model?: string;
+    cacheFile?: string;
+    reportFile?: string;
+    maxAiTries?: number;
+    maxCandidates?: number;
+    timeout?: number;
+    testName?: string;
+    apiKey?: string;
+}
+
+/**
+ * LocatAI - AI-powered self-healing locators for Playwright
+ */
+
+/**
+ * Enhance a Playwright Page with self-healing capabilities.
+ *
+ * @example
+ * ```typescript
+ * import { withLocatAI } from '@testnexus/locatai';
+ *
+ * const locataiPage = withLocatAI(page);
+ * await locataiPage.locatai.click(page.getByRole('button'), 'Submit button');
+ * await locataiPage.locatai.fill('', 'Email input', 'test@example.com');
+ * ```
+ */
+declare function withLocatAI(page: Page, opts?: LocatAIOptions): LocatAIPage;
+/**
+ * Create a Playwright test fixture with LocatAI capabilities.
+ *
+ * @example
+ * ```typescript
+ * import { test as base } from '@playwright/test';
+ * import { createLocatAIFixture, LocatAIPage } from '@testnexus/locatai';
+ *
+ * export const test = base.extend<{ page: LocatAIPage }>(createLocatAIFixture());
+ * ```
+ */
+declare function createLocatAIFixture(opts?: LocatAIOptions): {
+    page: ({ page }: {
+        page: Page;
+    }, use: (page: LocatAIPage) => Promise<void>) => Promise<void>;
+};
+
+/**
+ * AI Provider abstraction for LocatAI
+ * Supports multiple AI backends: OpenAI, Anthropic, Google, Local (Ollama)
+ */
+
+type ProviderName = "openai" | "gpt" | "anthropic" | "claude" | "google" | "gemini" | "local" | "ollama";
+interface GenerateLocatAIPlanInput {
+    systemPrompt: string;
+    userContent: string;
+    jsonSchema: object;
+}
+interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+}
+interface LocatAIPlanResult {
+    plan: LocatAIPlanT | null;
+    tokenUsage: TokenUsage | null;
+}
+interface AIProvider {
+    readonly name: ProviderName;
+    generateLocatAIPlan(input: GenerateLocatAIPlanInput): Promise<LocatAIPlanResult>;
+}
+declare const DEFAULT_MODELS: Record<ProviderName, string>;
+
+export { type AIProvider, type ClickOptions, DEFAULT_MODELS, LocatAIError, type LocatAIErrorContext, type LocatAILocator, type LocatAIMethods, type LocatAIOptions, type LocatAIPage, type ProviderName, createLocatAIFixture, withLocatAI };

package/dist/index.d.ts

@@ -0,0 +1,173 @@
+import { Locator, Page } from 'playwright-core';
+import { z } from 'zod';
+
+/**
+ * Type definitions and Zod schemas for LocatAI
+ */
+
+type LocatorOrEmpty = Locator | string;
+declare const LocatAIPlan: z.ZodObject<{
+    candidates: z.ZodArray<z.ZodObject<{
+        strategy: z.ZodObject<{
+            type: z.ZodEnum<{
+                testid: "testid";
+                role: "role";
+                label: "label";
+                placeholder: "placeholder";
+                text: "text";
+                altText: "altText";
+                title: "title";
+                css: "css";
+            }>;
+            value: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            selector: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            role: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            exact: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        }, z.core.$strip>;
+        confidence: z.ZodNumber;
+        why: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type LocatAIPlanT = z.infer<typeof LocatAIPlan>;
+interface LocatAIErrorContext {
+    action: string;
+    contextName: string;
+    url: string;
+    candidatesAnalyzed: number;
+    strategiesTried: Array<{
+        type: string;
+        reason: string;
+    }>;
+    aiResponse?: string;
+    originalError?: string;
+}
+declare class LocatAIError extends Error {
+    readonly context: LocatAIErrorContext;
+    constructor(message: string, context: LocatAIErrorContext);
+    static formatMessage(message: string, ctx: LocatAIErrorContext): string;
+}
+interface ClickOptions {
+    /** Force click even if element is not visible (for hover-dependent buttons) */
+    force?: boolean;
+}
+/**
+ * A locator that automatically falls back to AI healing if the original selector fails.
+ * Provides a subset of Playwright Locator methods with self-healing capabilities.
+ */
+interface LocatAILocator {
+    /** Click the element, with AI fallback if selector fails */
+    click(options?: ClickOptions): Promise<void>;
+    /** Fill the element with text, with AI fallback if selector fails */
+    fill(value: string): Promise<void>;
+    /** Double-click the element, with AI fallback if selector fails */
+    dblclick(): Promise<void>;
+    /** Check the checkbox/radio, with AI fallback if selector fails */
+    check(): Promise<void>;
+    /** Hover over the element, with AI fallback if selector fails */
+    hover(): Promise<void>;
+    /** Focus the element, with AI fallback if selector fails */
+    focus(): Promise<void>;
+    /** Uncheck a checkbox/radio, with AI fallback if selector fails */
+    uncheck(): Promise<void>;
+    /** Select an option in a dropdown, with AI fallback if selector fails */
+    selectOption(value: string): Promise<void>;
+}
+interface LocatAIMethods {
+    click(target: LocatorOrEmpty, contextName: string, options?: ClickOptions): Promise<void>;
+    fill(target: LocatorOrEmpty, contextName: string, value: string): Promise<void>;
+    selectOption(target: LocatorOrEmpty, contextName: string, value: string): Promise<void>;
+    dblclick(target: LocatorOrEmpty, contextName: string): Promise<void>;
+    check(target: LocatorOrEmpty, contextName: string): Promise<void>;
+    uncheck(target: LocatorOrEmpty, contextName: string): Promise<void>;
+    hover(target: LocatorOrEmpty, contextName: string): Promise<void>;
+    focus(target: LocatorOrEmpty, contextName: string): Promise<void>;
+    setTestName(name: string): void;
+    /**
+     * Create a self-healing locator with a semantic description fallback.
+     * @param selector CSS selector or Playwright locator string
+     * @param contextName Semantic description for AI fallback
+     * @returns A LocatAILocator that can be used like a regular locator
+     * @example
+     * await page.locatai.locator('.new-todo', 'Input field for new todos').fill('Buy milk');
+     */
+    locator(selector: string, contextName: string): LocatAILocator;
+}
+interface LocatAIPage extends Page {
+    locatai: LocatAIMethods;
+}
+interface LocatAIOptions {
+    enabled?: boolean;
+    provider?: "openai" | "gpt" | "anthropic" | "claude" | "google" | "gemini" | "local" | "ollama";
+    model?: string;
+    cacheFile?: string;
+    reportFile?: string;
+    maxAiTries?: number;
+    maxCandidates?: number;
+    timeout?: number;
+    testName?: string;
+    apiKey?: string;
+}
+
+/**
+ * LocatAI - AI-powered self-healing locators for Playwright
+ */
+
+/**
+ * Enhance a Playwright Page with self-healing capabilities.
+ *
+ * @example
+ * ```typescript
+ * import { withLocatAI } from '@testnexus/locatai';
+ *
+ * const locataiPage = withLocatAI(page);
+ * await locataiPage.locatai.click(page.getByRole('button'), 'Submit button');
+ * await locataiPage.locatai.fill('', 'Email input', 'test@example.com');
+ * ```
+ */
+declare function withLocatAI(page: Page, opts?: LocatAIOptions): LocatAIPage;
+/**
+ * Create a Playwright test fixture with LocatAI capabilities.
+ *
+ * @example
+ * ```typescript
+ * import { test as base } from '@playwright/test';
+ * import { createLocatAIFixture, LocatAIPage } from '@testnexus/locatai';
+ *
+ * export const test = base.extend<{ page: LocatAIPage }>(createLocatAIFixture());
+ * ```
+ */
+declare function createLocatAIFixture(opts?: LocatAIOptions): {
+    page: ({ page }: {
+        page: Page;
+    }, use: (page: LocatAIPage) => Promise<void>) => Promise<void>;
+};
+
+/**
+ * AI Provider abstraction for LocatAI
+ * Supports multiple AI backends: OpenAI, Anthropic, Google, Local (Ollama)
+ */
+
+type ProviderName = "openai" | "gpt" | "anthropic" | "claude" | "google" | "gemini" | "local" | "ollama";
+interface GenerateLocatAIPlanInput {
+    systemPrompt: string;
+    userContent: string;
+    jsonSchema: object;
+}
+interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+}
+interface LocatAIPlanResult {
+    plan: LocatAIPlanT | null;
+    tokenUsage: TokenUsage | null;
+}
+interface AIProvider {
+    readonly name: ProviderName;
+    generateLocatAIPlan(input: GenerateLocatAIPlanInput): Promise<LocatAIPlanResult>;
+}
+declare const DEFAULT_MODELS: Record<ProviderName, string>;
+
+export { type AIProvider, type ClickOptions, DEFAULT_MODELS, LocatAIError, type LocatAIErrorContext, type LocatAILocator, type LocatAIMethods, type LocatAIOptions, type LocatAIPage, type ProviderName, createLocatAIFixture, withLocatAI };