donobu/dist/lib/ai/locate/locateTypes.d.ts

Create browser automations with an LLM agent and replay them as Playwright scripts.

import type { LanguageModel } from 'ai';
import type { GptClient } from '../../../clients/GptClient';
/**
 * A single step in a Playwright locator chain. Uses a flat structure with
 * optional fields (rather than a discriminated union) so the JSON Schema
 * stays tool-call friendly. The consumer reads `method` to decide which
 * fields are relevant.
 */
export type LocatorStep = {
    method: 'getByRole' | 'getByText' | 'getByLabel' | 'getByPlaceholder' | 'getByTestId' | 'locator';
    /** ARIA role name — used when method is "getByRole". */
    role?: string;
    /** Accessible name — used with "getByRole". */
    name?: string;
    /** Text to match — used with "getByText", "getByLabel", "getByPlaceholder". */
    text?: string;
    /** data-testid value — used with "getByTestId". */
    testId?: string;
    /** CSS or XPath selector — used with "locator". */
    selector?: string;
    /** Whether text/name matching should be exact. */
    exact?: boolean;
    /**
     * When true, `name` is treated as a regex pattern compiled via
     * `new RegExp(name)` rather than a literal string. Mutually exclusive
     * with `exact: true`. Used with `getByRole`.
     *
     * Env-var placeholders are interpolated **before** regex compilation, so
     * `'\\d+ {{$.env.NOUN}}'` with `NOUN='comments'` compiles as
     * `/\d+ comments/`.
     */
    nameIsRegex?: boolean;
    /**
     * When true, `text` is treated as a regex pattern compiled via
     * `new RegExp(text)` rather than a literal string. Mutually exclusive with
     * `exact: true`. Used with `getByText`, `getByLabel`, `getByPlaceholder`.
     *
     * Env-var placeholders are interpolated **before** regex compilation.
     */
    textIsRegex?: boolean;
};
/**
 * Identifies an iframe to scope into before applying {@link LocatorStep}s.
 * Multiple entries represent nested frames, applied outermost-first.
 */
export type FrameStep = {
    method: 'frameLocator' | 'frame';
    /** CSS selector for the iframe — used with "frameLocator". */
    selector?: string;
    /** iframe name attribute — used with "frame". */
    name?: string;
};
/**
 * The complete structured output the LLM returns when resolving a
 * natural-language description to a Playwright locator.
 */
export type LocateResult = {
    /** If the target element is inside one or more iframes, list frames outermost-first. */
    frames?: FrameStep[];
    /** Locator chain applied to the page (or innermost frame). Max 3 steps. */
    steps: LocatorStep[];
    /** Appended as `.nth(n)` when the chain matches multiple elements. */
    nth?: number;
};
/**
 * Options accepted by {@link PageAiCallable.locate}.
 */
export type LocateOptions = {
    gptClient?: GptClient | Exclude<LanguageModel, string>;
    /**
     * Timeout in milliseconds for the entire locate operation (default: 30 000).
     *
     * On cache hit this budgets the hydration patience window — the cached
     * locator gets up to this long to attach to a matching element before the
     * cache is treated as stale and the AI is re-run. On cache miss (or
     * stale-cache fallthrough) this budgets the AI call. Whatever the cache
     * path consumes is deducted from the AI path's remaining budget; the total
     * never exceeds `timeout`.
     */
    timeout?: number;
    /**
     * Whether to use the on-disk cache. Defaults to true.
     *
     * Cached `LocateResult` step fields preserve `{{$.env.*}}` placeholders for
     * any value that came from an env var, so changing an env value between
     * runs replays the same cached locator with the new value rather than
     * re-invoking the AI.
     */
    cache?: boolean;
    /**
     * Explicit environment variable names (in addition to the heuristically
     * derived ones) that the description may read via `{{$.env.*}}`
     * interpolations.
     */
    envVars?: string[];
    /**
     * Explicitly supply environment variable values that amend (or override)
     * the environment observed by this `page.ai.locate` call. Keys are merged
     * with any names derived from {@link LocateOptions.envVars} and from
     * `{{$.env.*}}` interpolations in the description.
     *
     * - A `string` value sets or overrides the variable for this invocation.
     * - An `undefined` value *removes* the variable, even if it would
     *   otherwise be resolved from persistence.
     *
     * Only the **names** (keys) influence cache lookup; changing a value
     * replays the cached locator with the new value via `{{$.env.*}}`
     * placeholder substitution rather than busting the cache. If a referenced
     * env var is absent at replay, the placeholder is left literal — the
     * locator will then match zero elements and fail loudly.
     */
    envVals?: Record<string, string | undefined>;
};
//# sourceMappingURL=locateTypes.d.ts.map