@irsprs/mobwright 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,546 @@
+import * as _playwright_test from '@playwright/test';
+import { Browser } from 'webdriverio';
+
+/**
+ * Supported mobile platforms.
+ */
+declare enum Platform {
+    ANDROID = "android",
+    IOS = "ios"
+}
+/**
+ * Where the device comes from.
+ * v0.1: emulator (Android) | simulator (iOS)
+ * v0.2+: real-device, browserstack, lambdatest, etc.
+ */
+type DeviceProvider = 'emulator' | 'simulator';
+/**
+ * Device configuration for a project.
+ */
+interface DeviceConfig {
+    provider: DeviceProvider;
+    /** Emulator AVD name (Android) or simulator device name (iOS) */
+    name: string;
+}
+/**
+ * Configuration for a single project (platform + device combo).
+ */
+interface ProjectConfig {
+    name: string;
+    use: {
+        platform: Platform;
+        device: DeviceConfig;
+        buildPath: string;
+        /** Android only: explicit launcher activity */
+        appActivity?: string;
+        /** Android only: explicit app package */
+        appPackage?: string;
+        /** iOS only: bundle id (launches installed app without needing buildPath) */
+        bundleId?: string;
+        /** iOS only: platform version (e.g. "17.4") */
+        platformVersion?: string;
+        /** iOS only: simulator UDID (faster than deviceName matching) */
+        udid?: string;
+        actionTimeout?: number;
+    };
+}
+/**
+ * AI provider name. v0.1 supports these three.
+ */
+type AIProviderName = 'anthropic' | 'openai' | 'deepseek';
+/**
+ * AI configuration.
+ */
+interface AIConfig {
+    provider: AIProviderName;
+    model: string;
+    apiKey: string;
+    /** Optional override of the base URL. */
+    baseURL?: string;
+    /** Optional timeout in ms. */
+    timeout?: number;
+}
+/**
+ * Top-level mobwright configuration.
+ */
+interface MobwrightConfig {
+    projects: ProjectConfig[];
+    ai?: AIConfig;
+    /** Default timeout for all locator actions in ms */
+    actionTimeout?: number;
+}
+
+interface LocatorOptions {
+    /** Max time in ms to wait for the element to be actionable. Default 5000. */
+    timeout?: number;
+}
+/**
+ * A lazy reference to a UI element.
+ *
+ * Locators don't query the device when created — only when an action runs.
+ * Every action auto-waits up to `timeout` (default 5s) for the element to
+ * be present + visible + enabled before failing.
+ *
+ * @example
+ *   await device.locator('~loginButton').tap();
+ *   const text = await device.locator('~welcome').getText();
+ */
+declare class Locator {
+    readonly selector: string;
+    private readonly browser;
+    private readonly platform;
+    private readonly defaultTimeout;
+    constructor(browser: Browser, platform: Platform, selector: string, options?: LocatorOptions);
+    /**
+     * Wait for the element to be present in the tree AND displayed.
+     * Returns the wdio element handle once ready.
+     */
+    private waitForElement;
+    /**
+     * Tap (click) the element. Auto-waits until visible + enabled.
+     */
+    tap(): Promise<void>;
+    /**
+     * Type text into the element. Auto-waits until visible.
+     * Clears existing content first.
+     */
+    fill(text: string): Promise<void>;
+    /**
+     * Get the visible text of the element.
+     */
+    getText(): Promise<string>;
+    /**
+     * Check if the element is currently visible (no waiting).
+     * Returns false if not present.
+     */
+    isVisible(): Promise<boolean>;
+    /**
+     * Wait for the element to become visible.
+     * Useful for explicit waits without performing an action.
+     */
+    waitFor(options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Press and hold the element for `duration` ms (long-press).
+     * Default duration: 1000 ms.
+     */
+    tapAndHold(options?: {
+        duration?: number;
+    }): Promise<void>;
+    /** Swipe left within the element bounds. */
+    swipeLeft(options?: {
+        duration?: number;
+        distance?: number;
+    }): Promise<void>;
+    /** Swipe right within the element bounds. */
+    swipeRight(options?: {
+        duration?: number;
+        distance?: number;
+    }): Promise<void>;
+    /** Swipe up within the element bounds. */
+    swipeUp(options?: {
+        duration?: number;
+        distance?: number;
+    }): Promise<void>;
+    /** Swipe down within the element bounds. */
+    swipeDown(options?: {
+        duration?: number;
+        distance?: number;
+    }): Promise<void>;
+    /**
+     * Scroll up inside a scrollable container.
+     * Slower and longer than swipeUp — use on lists/pages.
+     */
+    scrollUp(options?: {
+        duration?: number;
+        distance?: number;
+    }): Promise<void>;
+    /**
+     * Scroll down inside a scrollable container.
+     * Slower and longer than swipeDown — use on lists/pages.
+     */
+    scrollDown(options?: {
+        duration?: number;
+        distance?: number;
+    }): Promise<void>;
+    /**
+     * Check if the element is currently enabled (not greyed out / disabled).
+     * Returns false if not present or not enabled.
+     * Does NOT auto-wait — for retry behavior, use expect(locator).toBeEnabled().
+     */
+    isEnabled(): Promise<boolean>;
+    private _swipe;
+    private _scroll;
+    private _performSwipeAction;
+}
+
+/**
+ * What every AI provider must understand for locator resolution.
+ */
+interface ResolveLocatorInput {
+    /** Natural-language description of the target element. */
+    description: string;
+    /** Serialized accessibility tree (XML for Appium). */
+    accessibilityTree: string;
+    /** Optional screenshot, for providers that support vision. */
+    screenshot?: Buffer;
+    /** Target platform — affects selector strategy choices. */
+    platform: Platform;
+}
+/**
+ * What the provider returns.
+ */
+interface ResolveLocatorResult {
+    /** A selector string mobwright can parse: ~foo, #foo, //xpath, or plain text. */
+    selector: string;
+    /** Which strategy the selector uses. Helps with validation/logging. */
+    strategy: SelectorStrategy;
+    /** 0..1 — how confident the provider is. <0.5 should be treated as a miss. */
+    confidence: number;
+    /** Free-text explanation, for debugging. */
+    rationale?: string;
+}
+type SelectorStrategy = 'accessibility-id' | 'id' | 'xpath' | 'text';
+/**
+ * Provider configuration. Each provider may interpret these differently.
+ */
+interface ProviderConfig {
+    apiKey: string;
+    model: string;
+    /** Override the API base URL. Used for DeepSeek (OpenAI-compatible endpoint). */
+    baseURL?: string;
+    /** Request timeout in ms. */
+    timeout?: number;
+}
+
+/**
+ * Common interface for all AI providers.
+ *
+ * v0.1 only needs resolveLocator. Future versions will add:
+ *   - analyzeFailure() for AI failure reports
+ *   - suggestHeal() for self-healing locators
+ */
+interface AIProvider {
+    /** Provider name for logging, e.g. 'anthropic', 'openai', 'deepseek'. */
+    readonly name: string;
+    /** Resolve a natural-language description to a concrete selector. */
+    resolveLocator(input: ResolveLocatorInput): Promise<ResolveLocatorResult>;
+}
+
+interface AILocatorOptions extends LocatorOptions {
+    /**
+     * Minimum confidence the AI must return for us to trust the resolution.
+     * Below this, we throw with a clear error rather than silently using a bad selector.
+     * Default: 0.5.
+     */
+    minConfidence?: number;
+    /**
+     * Max characters of the accessibility tree to send to the AI.
+     * Default: 12,000 (~3000 tokens).
+     */
+    treeCharBudget?: number;
+}
+/**
+ * A natural-language locator. Lazily resolves an English description to a
+ * concrete selector via the configured AI provider, then delegates to a
+ * regular Locator for the actual action.
+ *
+ * Resolution happens once per AILocator instance. Subsequent actions reuse
+ * the cached selector.
+ *
+ * @example
+ *   await device.ai('the Continue button').tap();
+ *   await device.ai('the email input').fill('me@example.com');
+ */
+declare class AILocator {
+    readonly description: string;
+    private readonly browser;
+    private readonly platform;
+    private readonly provider;
+    private readonly options;
+    /** Cached resolution. Populated on first action. */
+    private resolved;
+    /** Cached underlying Locator. Populated on first action. */
+    private locator;
+    constructor(browser: Browser, platform: Platform, provider: AIProvider, description: string, options?: AILocatorOptions);
+    /**
+     * Resolve the description to a Locator. Called automatically on first action.
+     * Exposed for advanced use / debugging.
+     */
+    resolve(): Promise<Locator>;
+    /** Validate the AI's response before trusting it. */
+    private validate;
+    /** Build a mobwright selector string from the AI's strategy + value. */
+    private buildSelectorString;
+    /** Tap the resolved element. Resolves on first call. */
+    tap(): Promise<void>;
+    /** Type text into the resolved element. */
+    fill(text: string): Promise<void>;
+    /** Get the visible text of the resolved element. */
+    getText(): Promise<string>;
+    /** Check visibility of the resolved element (snapshot, no waiting). */
+    isVisible(): Promise<boolean>;
+    /** Wait for the resolved element to be visible. */
+    waitFor(options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /** Check if the resolved element is enabled (snapshot, no waiting). */
+    isEnabled(): Promise<boolean>;
+    /**
+     * Inspect the resolved selector. Returns null if not yet resolved.
+     * Useful for debugging or "save back to a stable selector" workflows.
+     */
+    getResolved(): ResolveLocatorResult | null;
+}
+
+declare class Device {
+    readonly stub: false;
+    readonly project: string;
+    readonly platform: Platform;
+    readonly browser: Browser;
+    /** Optional AI provider — only set if AI is configured. */
+    readonly aiProvider: AIProvider | undefined;
+    private readonly defaultTimeout;
+    constructor(browser: Browser, project: ProjectConfig, aiProvider?: AIProvider);
+    /**
+     * Create a lazy reference to a UI element by selector string.
+     *
+     * Selector syntax:
+     *   ~foo     → accessibility id
+     *   #foo     → resource id (ends-with match; package prefix optional)
+     *   //...    → xpath
+     *   foo      → accessibility id (no prefix)
+     */
+    locator(selector: string, options?: LocatorOptions): Locator;
+    /**
+     * Convenience: locate an element by its visible text or label (exact match).
+     */
+    getByText(text: string, options?: LocatorOptions): Locator;
+    /**
+     * Locate an element whose visible text **contains** the substring.
+     * Case-insensitive by default.
+     *
+     * @example
+     *   device.getByContainingText('get started');   // matches "Get Started", "GET STARTED", etc.
+     *   device.getByContainingText('Started', { ignoreCase: false }); // case-sensitive substring
+     */
+    getByContainingText(text: string, options?: LocatorOptions & {
+        ignoreCase?: boolean;
+    }): Locator;
+    /**
+     * Take a screenshot. Returns raw PNG bytes.
+     */
+    screenshot(): Promise<Buffer>;
+    /**
+     * Get the current accessibility tree as an XML string.
+     * Used later by AI locator resolution.
+     */
+    getPageSource(): Promise<string>;
+    /**
+   * Create a natural-language locator. Resolves on first action via AI.
+   *
+   * Requires AI to be configured (MOBWRIGHT_AI_PROVIDER + MOBWRIGHT_AI_API_KEY).
+   * Throws AIError immediately if AI is not configured.
+   *
+   * @example
+   *   await device.ai('the blue Continue button at the bottom').tap();
+   *   await device.ai('the email input field').fill('me@example.com');
+   */
+    ai(description: string, options?: AILocatorOptions): AILocator;
+    /**
+     * Get cumulative token usage from the AI provider (if it tracks tokens).
+     * Returns null if AI is not configured or if the provider doesn't support token tracking.
+     */
+    getAITokenUsage(): unknown;
+}
+
+declare const test: _playwright_test.TestType<_playwright_test.PlaywrightTestArgs & _playwright_test.PlaywrightTestOptions & {
+    device: Device;
+}, _playwright_test.PlaywrightWorkerArgs & _playwright_test.PlaywrightWorkerOptions>;
+
+/**
+ * Anything our matchers know how to assert on.
+ * Both Locator and AILocator have the methods we need.
+ */
+type AssertableLocator = Pick<Locator, 'isVisible' | 'getText' | 'selector'> & {
+    isEnabled?: () => Promise<boolean>;
+};
+interface MatcherResult {
+    pass: boolean;
+    message: () => string;
+    name?: string;
+    expected?: unknown;
+    actual?: unknown;
+}
+/**
+ * Match modes for text assertions.
+ */
+type TextMatcher = string | RegExp;
+/**
+ * Mobwright's expect — extends Playwright's with mobile-aware matchers.
+ *
+ * Each matcher auto-retries up to `timeout` ms (default 5000).
+ */
+declare const expect: _playwright_test.Expect<{
+    /**
+     * Assert the element is currently visible (present + displayed).
+     * Auto-retries until visible or timeout.
+     */
+    toBeVisible(this: _playwright_test.ExpectMatcherState, received: AssertableLocator, options?: {
+        timeout?: number;
+    }): Promise<MatcherResult>;
+    /**
+     * Assert the element's visible text matches.
+     * Pass a string for exact match, or a RegExp for pattern match.
+     * Auto-retries until match or timeout.
+     */
+    toHaveText(this: _playwright_test.ExpectMatcherState, received: AssertableLocator, expected: TextMatcher, options?: {
+        timeout?: number;
+    }): Promise<MatcherResult>;
+    /**
+     * Assert the element's visible text **contains** the expected substring.
+     * Case-insensitive by default. Pass `ignoreCase: false` for exact-case check.
+     * Also accepts a RegExp.
+     * Auto-retries until match or timeout.
+     */
+    toContainText(this: _playwright_test.ExpectMatcherState, received: AssertableLocator, expected: TextMatcher, options?: {
+        timeout?: number;
+        ignoreCase?: boolean;
+    }): Promise<MatcherResult>;
+    /**
+     * Assert the element is enabled (interactable).
+     * Auto-retries until enabled or timeout.
+     */
+    toBeEnabled(this: _playwright_test.ExpectMatcherState, received: AssertableLocator, options?: {
+        timeout?: number;
+    }): Promise<MatcherResult>;
+}>;
+
+/**
+ * Define mobwright config with full type inference.
+ *
+ * @example
+ * import { defineConfig, Platform } from 'mobwright';
+ *
+ * export default defineConfig({
+ *   projects: [
+ *     {
+ *       name: 'android',
+ *       use: {
+ *         platform: Platform.ANDROID,
+ *         device: { provider: 'emulator', name: 'Pixel_6_API_34' },
+ *         buildPath: './app.apk',
+ *       },
+ *     },
+ *   ],
+ * });
+ */
+declare function defineConfig(config: MobwrightConfig): MobwrightConfig;
+
+/**
+ * Base class for all AI-related errors so callers can catch them generically.
+ */
+declare class AIError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/** The provider's HTTP call failed or timed out. */
+declare class AIRequestError extends AIError {
+    constructor(message: string, cause?: unknown);
+}
+/** The provider returned a response we couldn't parse. */
+declare class AIResponseError extends AIError {
+    readonly raw?: string | undefined;
+    constructor(message: string, raw?: string | undefined, cause?: unknown);
+}
+/** The provider's response didn't meet our validation criteria. */
+declare class AIValidationError extends AIError {
+    constructor(message: string, cause?: unknown);
+}
+
+interface OpenAICompatibleProviderOptions extends ProviderConfig {
+    /** Override the provider name in logs. Defaults to 'openai'. */
+    name?: string;
+}
+/**
+ * OpenAI-compatible provider.
+ *
+ * Used directly for OpenAI, and as the base for DeepSeek (which exposes
+ * an OpenAI-compatible API at a different base URL).
+ */
+declare class OpenAICompatibleProvider implements AIProvider {
+    readonly name: string;
+    private readonly client;
+    private readonly model;
+    constructor(config: OpenAICompatibleProviderOptions);
+    resolveLocator(input: ResolveLocatorInput): Promise<ResolveLocatorResult>;
+}
+
+/**
+ * DeepSeek uses an OpenAI-compatible API at a different base URL.
+ * This is just a thin wrapper for ergonomics + correct defaults.
+ *
+ * Default model: deepseek-chat (general purpose, cheap).
+ * For reasoning-heavy tasks: deepseek-reasoner.
+ */
+declare class DeepSeekProvider extends OpenAICompatibleProvider {
+    constructor(config: ProviderConfig);
+}
+
+declare class AnthropicProvider implements AIProvider {
+    readonly name = "anthropic";
+    private readonly client;
+    private readonly model;
+    private totalInputTokens;
+    private totalOutputTokens;
+    constructor(config: ProviderConfig);
+    resolveLocator(input: ResolveLocatorInput): Promise<ResolveLocatorResult>;
+    /** Get cumulative token usage across all requests. */
+    getTokenUsage(): {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+}
+
+/**
+ * Create an AIProvider from a mobwright AIConfig.
+ *
+ * @example
+ *   const provider = createProvider({
+ *     provider: 'deepseek',
+ *     model: 'deepseek-chat',
+ *     apiKey: process.env.MOBWRIGHT_AI_API_KEY!,
+ *   });
+ */
+declare function createProvider(config: AIConfig): AIProvider;
+
+/**
+ * Get a cleaned-up accessibility tree for AI consumption.
+ *
+ * Returns serialized XML with:
+ *   - Layout/coordinate noise stripped
+ *   - false-valued boolean attributes removed
+ *   - empty attributes removed
+ *
+ * Intent: a much smaller payload that still preserves selector-relevant info
+ * (text, content-desc, resource-id, class, name, label, value).
+ */
+declare function getCleanTree(browser: Browser, platform: Platform): Promise<string>;
+/**
+ * Pure function — exported for unit testing.
+ */
+declare function cleanTree(raw: string, platform: Platform): string;
+/** Conservative tree budget — leaves room for system prompt + user prompt + response. */
+declare const DEFAULT_TREE_CHAR_BUDGET = 12000;
+/**
+ * Truncate a tree to fit within a character budget.
+ * Preference: keep the start of the tree (usually contains the main interactive content).
+ * Logs a warning if truncation happens.
+ */
+declare function fitTreeToBudget(tree: string, budget?: number): string;
+/** Estimate tokens for a string. Rough but useful for cost forecasting. */
+declare function estimateTokens(text: string): number;
+
+export { type AIConfig, AIError, AILocator, type AILocatorOptions, type AIProvider, type AIProviderName, AIRequestError, AIResponseError, AIValidationError, AnthropicProvider, DEFAULT_TREE_CHAR_BUDGET, DeepSeekProvider, Device, type DeviceConfig, type DeviceProvider, Locator, type LocatorOptions, type MobwrightConfig, OpenAICompatibleProvider, Platform, type ProjectConfig, type ProviderConfig, type ResolveLocatorInput, type ResolveLocatorResult, type SelectorStrategy, cleanTree, createProvider, defineConfig, estimateTokens, expect, fitTreeToBudget, getCleanTree, test };