@unotest/web 0.5.0

package/dist/interfaces-iTfjd1zT.d.ts

@@ -0,0 +1,407 @@
+import { Matcher } from '@unotest/protocol';
+import { Browser, BrowserChannel } from './config/schema.js';
+
+type LocatorStep = {
+    kind: 'css';
+    selector: string;
+} | {
+    kind: 'getByRole';
+    role: string;
+    name?: Matcher;
+    exact?: boolean;
+} | {
+    kind: 'getByText';
+    text: Matcher;
+    exact?: boolean;
+} | {
+    kind: 'getByLabel';
+    text: Matcher;
+    exact?: boolean;
+} | {
+    kind: 'getByPlaceholder';
+    text: Matcher;
+    exact?: boolean;
+} | {
+    kind: 'getByTestId';
+    id: string;
+} | {
+    kind: 'getByAltText';
+    text: Matcher;
+    exact?: boolean;
+} | {
+    kind: 'getByTitle';
+    text: Matcher;
+    exact?: boolean;
+} | {
+    kind: 'filter';
+    hasText?: Matcher;
+    hasNotText?: Matcher;
+    has?: LocatorValue;
+    hasNot?: LocatorValue;
+} | {
+    kind: 'first';
+} | {
+    kind: 'last';
+} | {
+    kind: 'nth';
+    index: number;
+} | {
+    kind: 'contentFrame';
+} | {
+    kind: 'ref';
+    ref: string;
+};
+interface LocatorValue {
+    readonly kind: 'locator';
+    readonly steps: readonly LocatorStep[];
+}
+declare function isLocatorValue(value: unknown): value is LocatorValue;
+/** Internal: build a new LocatorValue by appending one step. Immutable. */
+declare function appendStep(loc: LocatorValue, step: LocatorStep): LocatorValue;
+/** Internal: construct a fresh LocatorValue rooted at one step. */
+declare function rootedAt(step: LocatorStep): LocatorValue;
+/** Debug-friendly string repr. NOT a selector — for logs / errors only. */
+declare function describeLocator(loc: LocatorValue): string;
+
+interface LaunchOptions {
+    browser: Browser;
+    /** Playwright channel — `'chrome'` / `'msedge'` to use a system-
+     *  installed browser, `null`/undefined to fall back to bundled
+     *  Chromium. Only meaningful when `browser === 'chromium'`. */
+    channel?: BrowserChannel;
+    /** Run with visible window. Default: false in CI, true in dev. */
+    headless?: boolean;
+    /** Slow each operation by N ms — for dev debugging. Default: 0. */
+    slowMo?: number;
+}
+interface Viewport {
+    width: number;
+    height: number;
+}
+interface ContextOptions {
+    baseUrl?: string;
+    viewport?: Viewport;
+    /** Path to storageState JSON (D-23 caching, optional). */
+    storageState?: string;
+    /** Per-context override for dialog policy. Defaults to config.dialogPolicy. */
+    dialogPolicy?: "accept" | "dismiss" | "manual";
+    /** User-Agent string override. */
+    userAgent?: string;
+    /** Locale, e.g. "en-US". */
+    locale?: string;
+    /** Timezone, e.g. "Europe/Moscow". */
+    timezoneId?: string;
+    /**
+     * Default action timeout in milliseconds — applied to every Playwright
+     * `click` / `fill` / `waitFor` / etc. via `context.setDefaultTimeout`.
+     * Single source of truth lives in `UnotestConfigSchema.defaultTimeoutMs`
+     * (default 3000ms); `UNOTEST_DEFAULT_TIMEOUT_MS` env overrides.
+     */
+    defaultTimeoutMs?: number;
+    /**
+     * Default navigation timeout in milliseconds — applied to `goto` /
+     * `reload` / `waitForUrl` via `context.setDefaultNavigationTimeout`.
+     * Action timeout (3s) is too aggressive for real-world page loads;
+     * keep navigation at Playwright stock 30000ms by default.
+     * Single source of truth lives in `UnotestConfigSchema.defaultNavigationTimeoutMs`;
+     * `UNOTEST_DEFAULT_NAVIGATION_TIMEOUT_MS` env overrides.
+     */
+    defaultNavigationTimeoutMs?: number;
+}
+interface ActionTimeout {
+    /** Override default action timeout (D-7 actionability wait). Milliseconds. */
+    timeout?: number;
+}
+interface ClickOptions extends ActionTimeout {
+    /** Bypass actionability checks (D-5 — replaces testoid5 `forceClick`). */
+    force?: boolean;
+    /** Click at specific offset within element. */
+    position?: {
+        x: number;
+        y: number;
+    };
+    /** Hold these modifiers during click. */
+    modifiers?: ReadonlyArray<"Alt" | "Control" | "Meta" | "Shift">;
+    /** Mouse button. Default: 'left'. */
+    button?: "left" | "right" | "middle";
+    /** Number of clicks. Default: 1. */
+    clickCount?: number;
+}
+interface FillOptions extends ActionTimeout {
+    force?: boolean;
+}
+interface PressOptions extends ActionTimeout {
+    /** Delay between keydown and keyup, in ms. */
+    delay?: number;
+}
+interface CheckOptions extends ActionTimeout {
+    force?: boolean;
+}
+interface SelectOptions extends ActionTimeout {
+    force?: boolean;
+}
+interface HoverOptions extends ActionTimeout {
+    force?: boolean;
+    position?: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * State to wait for. Default: 'visible'.
+ * - 'attached' — element exists in DOM
+ * - 'detached' — element removed from DOM
+ * - 'visible' — exists + visible (non-zero size, not hidden)
+ * - 'hidden' — exists with zero size OR not in DOM
+ */
+type WaitState = "attached" | "detached" | "visible" | "hidden";
+interface WaitOptions extends ActionTimeout {
+    state?: WaitState;
+}
+interface NavigationOptions extends ActionTimeout {
+    /**
+     * When to consider navigation done. Default: 'load'.
+     * - 'load' — `load` event fired
+     * - 'domcontentloaded' — `DOMContentLoaded` fired
+     * - 'networkidle' — no network requests for 500ms
+     * - 'commit' — initial response received
+     */
+    waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit";
+}
+type GotoOptions = NavigationOptions;
+type ReloadOptions = NavigationOptions;
+interface ScreenshotOptions {
+    /** Capture full page (scroll), not just viewport. Default: false. */
+    fullPage?: boolean;
+    /** Crop to a specific element. */
+    clip?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** PNG quality (1-100). Only honoured for JPEG. */
+    quality?: number;
+}
+interface CookieOptions {
+    domain?: string;
+    path?: string;
+    expires?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: "Strict" | "Lax" | "None";
+}
+
+interface WebDriver {
+    /**
+     * Launch the underlying browser process. Idempotent — subsequent calls
+     * resolve immediately if already launched. Must be called before
+     * newContext().
+     */
+    launch(opts: LaunchOptions): Promise<void>;
+    /**
+     * Create a fresh context (D-23). Cookies / localStorage / sessionStorage
+     * / tabs / frames start clean. Per-test isolation lives at this layer —
+     * each test calls newContext() at start and ctx.close() at end.
+     */
+    newContext(opts?: ContextOptions): Promise<DriverContext>;
+    /**
+     * Tear down all open contexts and the browser process. Idempotent.
+     * Errors logged but not re-thrown (must not mask test failures in
+     * `finally` blocks).
+     */
+    close(): Promise<void>;
+}
+interface DriverContext {
+    /** Currently-open tabs/windows in this context. Index 0 = first opened. */
+    pages(): ReadonlyArray<DriverPage>;
+    /** The page that subsequent operations target. */
+    activePage(): DriverPage;
+    /** Switch the active page index (D-4 setPage). 0 = first opened, etc.
+     *  Implementations MUST also reset the frame stack — a frame scope
+     *  established on tab A is not valid on tab B. */
+    setActivePage(index: number): Promise<void>;
+    /**
+     * Subscribe to new-page events. Listener fires when a tab/window opens
+     * in this context (`target="_blank"`, `window.open`, etc.). Returns an
+     * unsubscribe function — call it to detach the listener. Cross-browser:
+     * Playwright abstracts the underlying CDP / Juggler / WebKit signal so
+     * this works in Chromium, Firefox, and WebKit identically.
+     *
+     * Used by the explore tool's popup-watcher; tests can fan out
+     * synchronously into a buffer.
+     */
+    onNewPage(listener: (info: {
+        index: number;
+        url: string;
+    }) => void): () => void;
+    /**
+     * Enter a frame scope (D-4 stateful pair). All subsequent locators
+     * resolve inside this frame until `exitFrame()` is called. Stacks (calling
+     * enterFrame twice nests, exitFrame pops one level).
+     */
+    enterFrame(locator: LocatorValue): Promise<void>;
+    exitFrame(): Promise<void>;
+    /** Current frame-stack depth — 0 when no `enterFrame` is active. Used
+     *  by the popup-watcher to know how many `exit_frame` entries to emit
+     *  before auto-switching to a popup (frame scope does not survive tab
+     *  changes). */
+    frameDepth(): number;
+    /** Typed storage shortcuts (D-6). */
+    setLocalStorage(key: string, value: string): Promise<void>;
+    getLocalStorage(key: string): Promise<string | null>;
+    setCookie(name: string, value: string, opts?: CookieOptions): Promise<void>;
+    getCookie(name: string): Promise<string | null>;
+    /**
+     * Persist current storage state to disk (D-23 opt-in caching). Used by
+     * project helpers like loginAndCacheState().
+     */
+    saveStorageState(path: string): Promise<void>;
+    /** Run JS in the page context (D-6 escape hatch). */
+    evaluate<T = unknown>(js: string): Promise<T>;
+    /**
+     * Snapshot of console entries captured since context creation, oldest
+     * first. Used by failure-bundle capture (D-16 tier 1). The driver wires
+     * a `page.on('console', …)` listener at newContext() time so the
+     * runner can pull the tail when a test fails.
+     */
+    consoleEntries(): ReadonlyArray<{
+        level: "log" | "info" | "warn" | "error" | "debug";
+        text: string;
+        timestamp: string;
+    }>;
+    /** Close all pages in this context. Idempotent. */
+    close(): Promise<void>;
+}
+interface DriverPage {
+    /** Current URL. Synchronous — reads cached state. */
+    url(): string;
+    /** Current document title. */
+    title(): Promise<string>;
+    click(loc: LocatorValue, opts?: ClickOptions): Promise<void>;
+    doubleClick(loc: LocatorValue, opts?: ClickOptions): Promise<void>;
+    fill(loc: LocatorValue, value: string, opts?: FillOptions): Promise<void>;
+    press(loc: LocatorValue, key: string, opts?: PressOptions): Promise<void>;
+    check(loc: LocatorValue, opts?: CheckOptions): Promise<void>;
+    uncheck(loc: LocatorValue, opts?: CheckOptions): Promise<void>;
+    selectOption(loc: LocatorValue, value: string | ReadonlyArray<string>, opts?: SelectOptions): Promise<void>;
+    hover(loc: LocatorValue, opts?: HoverOptions): Promise<void>;
+    scrollIntoView(loc: LocatorValue): Promise<void>;
+    /** Drag the source element onto the target. */
+    dragAndDrop(from: LocatorValue, to: LocatorValue, opts?: ClickOptions): Promise<void>;
+    /** Set the input element's selected files. Accepts one or many paths. */
+    uploadFile(loc: LocatorValue, files: string | ReadonlyArray<string>): Promise<void>;
+    /** Focus the locator then dispatch a paste-like input with `text`. */
+    clipboardPaste(loc: LocatorValue, text: string): Promise<void>;
+    count(loc: LocatorValue): Promise<number>;
+    textContent(loc: LocatorValue): Promise<string | null>;
+    inputValue(loc: LocatorValue): Promise<string>;
+    isVisible(loc: LocatorValue): Promise<boolean>;
+    /** Read a DOM attribute on the matched element. Returns null if absent. */
+    getAttribute(loc: LocatorValue, name: string): Promise<string | null>;
+    waitFor(loc: LocatorValue, opts?: WaitOptions): Promise<void>;
+    waitForUrl(pattern: string | RegExp, opts?: NavigationOptions): Promise<void>;
+    waitForText(text: string, opts?: WaitOptions): Promise<void>;
+    waitForNavigation(opts?: NavigationOptions): Promise<void>;
+    goto(url: string, opts?: GotoOptions): Promise<void>;
+    reload(opts?: ReloadOptions): Promise<void>;
+    goBack(opts?: NavigationOptions): Promise<void>;
+    goForward(opts?: NavigationOptions): Promise<void>;
+    evaluate<T = unknown>(js: string): Promise<T>;
+    evaluateOnLocator<T = unknown>(loc: LocatorValue, js: string): Promise<T>;
+    screenshot(opts?: ScreenshotOptions): Promise<Buffer>;
+    inspectElement(loc: LocatorValue): Promise<ElementHint | null>;
+    /** outerHTML of the element the locator matches (first match), or null
+     *  when it resolves to zero elements. Used by debug logging to persist
+     *  "what did this locator actually resolve to" as agent-readable proof —
+     *  NOT part of the DSL / action surface. */
+    outerHTML(loc: LocatorValue): Promise<string | null>;
+}
+/**
+ * Identifying attributes of a single DOM element. Populated by
+ * `DriverPage.inspectElement`. Consumers (RefResolver) pick the highest-
+ * priority signal to synthesise a stable LocatorValue. All fields are
+ * optional — an element might have only a role+name, or only a testId,
+ * or nothing stable at all (in which case the resolver throws).
+ */
+interface ElementHint {
+    /** The wire-only ref the resolver is acting on. Echoed back so the
+     *  resolver can verify the resolved locator still points at the same
+     *  element. */
+    ref: string;
+    /** data-testid / data-qa value, if present. Highest-priority signal. */
+    testId?: string;
+    /** Computed ARIA role (Playwright's locator role inference). */
+    role?: string;
+    /** Computed accessible name (W3C accname algorithm). */
+    name?: string;
+    /** aria-label attribute when the accessible name path is not desired
+     *  (e.g. icon-only buttons where role+name would still match). */
+    ariaLabel?: string;
+    /** placeholder attribute on `<input>`/`<textarea>`. Crucial for form
+     *  fields that lack `<label>` or `aria-label` (common pattern in
+     *  non-English UIs where placeholder doubles as the visible label).
+     *  Resolver emits `getByPlaceholder(text)`. */
+    placeholder?: string;
+    /** `alt` on `<img>` / `<area>` / `<input type="image">`. Resolver
+     *  emits `getByAltText(text)`. */
+    alt?: string;
+    /** `title` attribute — tooltip fallback for icon-only buttons / links
+     *  that have no other label. Named `titleAttr` to avoid collision
+     *  with `page.title()`. Resolver emits `getByTitle(text)`. */
+    titleAttr?: string;
+    /** textContent (trimmed, clipped). Last-resort semantic fallback
+     *  before the CSS escape hatch. */
+    text?: string;
+    /** href attribute for `<a>` elements lacking any of the above.
+     *  Resolver emits `locator('a[href="..."]')`. */
+    href?: string;
+    /** `id` attribute when it looks stable (not framework-generated).
+     *  Heuristic filters out `:r0:`, `__next_xxx`, long random-hash
+     *  patterns. Resolver emits `locator('#id')` as a CSS fallback. */
+    elementId?: string;
+    /** `name` attribute on form fields — stable selector for inputs
+     *  without testId/label/placeholder. Resolver emits
+     *  `locator('[name="..."]')`. */
+    nameAttr?: string;
+    /** A stable, app-authored `data-*` identifier (e.g. `data-id`, `data-guid`,
+     *  `data-row-id`) — NOT framework noise (`data-v-*`, `data-reactid`) and NOT
+     *  our own `data-unotest-*`. The single highest-value fallback for grid rows
+     *  / custom widgets that carry no role+name: the resolver emits
+     *  `locator('[data-x="..."]')`, turning an otherwise-unaddressable element
+     *  into a durable locator. Detected generically (name ends in id/guid/uid/
+     *  key/code, value looks stable). */
+    dataAttr?: {
+        name: string;
+        value: string;
+    };
+    /** A custom tooltip/label `data-*` attribute (name ends in `-title` /
+     *  `-tooltip` / `-label`: `data-shadow-title`, `data-original-title`,
+     *  `data-tooltip`, …). Carries the visible label of icon-only controls
+     *  that the W3C accname can't see. Generic — matched by suffix, not by a
+     *  hardcoded attribute name. The resolver emits `locator('[data-x="…"]')`. */
+    tooltipAttr?: {
+        name: string;
+        value: string;
+    };
+    /** Identifying signals of the element's ancestors (nearest first, ≤6) used
+     *  to DISAMBIGUATE when the target's own locator is ambiguous: the resolver
+     *  anchors to the nearest uniquely-locatable ancestor and scopes the
+     *  candidate within it (`ancestor.locator(candidate)`) — the robust
+     *  alternative to a positional `nth` (Playwright codegen / Robula+ approach). */
+    ancestors?: AncestorHint[];
+}
+/** Compact, cheap-to-compute identifying signals of an ancestor — enough to
+ *  synthesise a scope anchor. No accname/role (too costly per ancestor). */
+interface AncestorHint {
+    testId?: string;
+    dataAttr?: {
+        name: string;
+        value: string;
+    };
+    elementId?: string;
+    /** A single stable, semantic class token (not a hash / utility class). */
+    className?: string;
+}
+
+export { type ActionTimeout as A, type ContextOptions as C, type DriverContext as D, type ElementHint as E, type FillOptions as F, type GotoOptions as G, type HoverOptions as H, type LaunchOptions as L, type NavigationOptions as N, type PressOptions as P, type ReloadOptions as R, type ScreenshotOptions as S, type Viewport as V, type WebDriver as W, type CheckOptions as a, type ClickOptions as b, type CookieOptions as c, type DriverPage as d, type SelectOptions as e, type WaitOptions as f, type WaitState as g, type LocatorValue as h, type LocatorStep as i, appendStep as j, describeLocator as k, isLocatorValue as l, rootedAt as r };

package/dist/mcp/server.d.ts

@@ -0,0 +1,2 @@
+
+export {  }