@nyssance/tauri-hasgard 0.1.2 → 0.3.0

package/dist/types.d.ts

@@ -6,10 +6,17 @@ export type HasgardTarget = {
     ref: string;
 } | {
     selector: string;
+    index?: number;
 } | {
     x: number;
     y: number;
 };
+export interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
 export interface SnapshotElement {
     ref: string;
     role: string;
@@ -26,11 +33,18 @@ export interface SnapshotOptions {
     interactive?: boolean;
     selector?: string;
     depth?: number;
+    /**
+     * Take the snapshot inside this chain of same-origin iframes, one CSS
+     * selector per nesting level, instead of in the top document.
+     */
+    frame?: string[];
 }
 export interface WindowInfo {
     label: string;
     url: string;
     title: string;
+    /** Operating-system window id. Present only where native capture exists. */
+    nativeId?: number;
 }
 export interface WindowState {
     url: string;
@@ -54,6 +68,270 @@ export interface WaitOptions {
     state: "attached" | "detached";
     timeoutMs: number;
 }
+export interface ScrollOptions {
+    direction: "up" | "down" | "left" | "right" | "top" | "bottom";
+    amount?: number;
+}
+export interface DragOffset {
+    x: number;
+    y: number;
+}
+/** A held keyboard modifier. Named as the platform reports them on the event. */
+export type KeyModifier = "Alt" | "Control" | "Meta" | "Shift";
+export type MouseButton = "left" | "middle" | "right";
+/** A point inside the element, measured from its top-left corner. */
+export interface ElementPosition {
+    x: number;
+    y: number;
+}
+export interface ClickOptions {
+    /**
+     * Modifiers held for the whole gesture. `Meta` is Command on macOS and the
+     * Windows key elsewhere -- the platform's own accelerator, which is why
+     * multi-select lists usually bind it rather than `Control`.
+     */
+    modifiers?: KeyModifier[];
+    /**
+     * Which button. `right` raises `contextmenu` and `middle` raises `auxclick`;
+     * neither raises `click`, exactly as a real press does not.
+     */
+    button?: MouseButton;
+    /** Presses in one gesture. `2` also raises a single `dblclick` at the end. */
+    clickCount?: number;
+    /** Where inside the element to press. Defaults to its centre. */
+    position?: ElementPosition;
+}
+export interface DropFile {
+    name: string;
+    /** Base64-encoded file contents. */
+    data: string;
+    type?: string;
+}
+/**
+ * A file to hand to the page: either a path on the test machine, which is read
+ * and encoded for you, or an in-memory payload for content that never existed
+ * as a file.
+ */
+export type FileInput = string | DropFile;
+/** Refinement applied to an existing locator. Both may be combined. */
+export interface FilterOptions {
+    /** Keep only elements whose subtree text matches. */
+    hasText?: string;
+    /** Drop elements whose subtree text matches. */
+    hasNotText?: string;
+    /** Require a whole-string match instead of a substring one. */
+    exact?: boolean;
+}
+export type DialogType = "alert" | "confirm" | "prompt";
+/** A modal the page opened while the standing policy decided its outcome. */
+export interface DialogRecord {
+    id: number;
+    timestamp: number;
+    type: DialogType;
+    message: string;
+    /** Whether the policy accepted it. A one-button `alert` is always accepted. */
+    accepted: boolean;
+    /** The page's suggested answer, for `prompt` only. */
+    defaultValue?: string;
+    /** What the page received back, for an accepted `prompt`. */
+    returned?: string;
+}
+/**
+ * How the next dialog will be answered.
+ *
+ * This is a standing policy rather than Playwright's per-event handler: the
+ * bridge must answer synchronously inside the page's `confirm()` call, with no
+ * chance to await a decision from the test process.
+ */
+export interface DialogPolicy {
+    action: "accept" | "dismiss";
+    promptText: string | null;
+}
+export interface DialogListing {
+    dialogs: DialogRecord[];
+    policy: DialogPolicy;
+}
+/** How a matched request is answered. */
+export interface RouteOptions {
+    /**
+     * Glob against the full URL. `*` stays inside one path segment, `**` crosses
+     * separators, and the pattern is anchored at both ends -- so `**\/api` does
+     * not also intercept `/v2/api-docs`.
+     */
+    pattern: string;
+    /** Restrict to one HTTP verb. Any verb matches when omitted. */
+    method?: string;
+    /** Stop matching after this many requests, letting later ones through. */
+    times?: number;
+}
+export interface FulfillOptions extends RouteOptions {
+    /** Defaults to 200. */
+    status?: number;
+    body?: string;
+    /** Defaults to `text/plain`. */
+    contentType?: string;
+}
+export interface RouteRule {
+    id: number;
+    pattern: string;
+    method: string | null;
+    action: "fulfill" | "abort";
+    status: number;
+    times: number | null;
+    /** How many requests this rule has already answered. */
+    used: number;
+}
+export interface InterceptedRequest {
+    id: number;
+    timestamp: number;
+    route_id: number;
+    method: string;
+    url: string;
+    action: "fulfill" | "abort";
+    status: number;
+}
+export interface RouteListing {
+    routes: RouteRule[];
+    intercepted: InterceptedRequest[];
+}
+export interface ConsoleLogOptions {
+    level?: "log" | "warn" | "error" | "info";
+    since?: number;
+    sinceId?: number;
+    last?: number;
+}
+export interface ConsoleLogEntry {
+    id: number;
+    timestamp: number;
+    level: string;
+    args: JsonValue[];
+    source: string | null;
+}
+export interface NetworkRequestOptions {
+    filter?: string;
+    failedOnly?: boolean;
+    sinceId?: number;
+    last?: number;
+}
+export interface NetworkRequestEntry {
+    id: number;
+    timestamp: number;
+    method: string;
+    url: string;
+    status: number;
+    duration_ms: number;
+    error: string | null;
+    request_size: number;
+    response_size: number;
+}
+export interface StorageOptions {
+    /** Read and write `sessionStorage` instead of `localStorage`. */
+    session?: boolean;
+}
+export interface StorageEntry {
+    key: string;
+    value: string;
+}
+export interface StorageListing {
+    entries: StorageEntry[];
+    truncated: boolean;
+}
+export interface FormField {
+    tag: string;
+    type: string | null;
+    name: string;
+    value: string | string[];
+    checked?: boolean;
+}
+export interface FormEntry {
+    id: string;
+    name: string;
+    action: string;
+    method: string;
+    fields: FormField[];
+    fieldsTruncated?: boolean;
+}
+export interface FormsDump {
+    forms: FormEntry[];
+    truncated: boolean;
+}
+export type QueryDimension = "text" | "label" | "placeholder" | "testid" | "alt" | "title";
+export interface TextQuery {
+    /** Full, case-sensitive match. Whitespace is normalized either way. */
+    exact?: boolean;
+}
+export interface WaitForFunctionOptions {
+    timeoutMs?: number;
+    /** How often to re-evaluate the expression. Defaults to 50ms in the bridge. */
+    pollMs?: number;
+}
+export interface WatchOptions {
+    selector?: string;
+    timeoutMs?: number;
+    stableMs?: number;
+    requireMutation?: boolean;
+}
+export interface WatchNode {
+    tag: string;
+    id?: string;
+    class?: string;
+    text?: string;
+    attr?: string;
+    value?: string;
+}
+export interface WatchChanges {
+    added: WatchNode[];
+    removed: WatchNode[];
+    modified: WatchNode[];
+    truncated: boolean;
+}
+export interface DiffOptions extends SnapshotOptions {
+    /** Compare against this snapshot instead of the plugin's last stored one. */
+    reference?: Snapshot;
+}
+export interface DiffChange {
+    old: SnapshotElement;
+    new: SnapshotElement;
+    changes: string[];
+}
+export interface SnapshotDiff {
+    added: SnapshotElement[];
+    removed: SnapshotElement[];
+    changed: DiffChange[];
+}
+export interface NativeScreenshotOptions {
+    /** Absolute path; the parent directory must already exist. */
+    outputPath: string;
+    /**
+     * Operating-system window id. Resolved from the window's own label when
+     * omitted; pass it only to capture a window Hasgard does not own.
+     */
+    windowId?: number;
+}
+export interface NativeScreenshot {
+    output_path: string;
+    window_id: number;
+    width: number;
+    height: number;
+    scale_factor: number;
+    byte_size: number;
+    backend: string;
+    tcc_denied: boolean;
+}
+export interface RecorderEntry {
+    action: string;
+    timestamp: number;
+    [key: string]: JsonValue;
+}
+export interface RecorderStatus {
+    active: boolean;
+    count: number;
+    elapsed_ms: number;
+}
+export interface RecorderResult {
+    entries: RecorderEntry[];
+    count: number;
+}
 export interface HasgardLaunchConfig {
     command: string;
     args: string[];

package/dist/window.d.ts

@@ -1,5 +1,5 @@
 import { HasgardRpcClient } from "./rpc-client.js";
-import type { HasgardTarget, JsonValue, RoleQuery, Snapshot, SnapshotOptions, WaitOptions, WindowInfo, WindowState } from "./types.js";
+import type { BoundingBox, ClickOptions, ConsoleLogEntry, ConsoleLogOptions, DialogListing, DialogPolicy, DiffOptions, DragOffset, DropFile, FileInput, FilterOptions, FormsDump, FulfillOptions, HasgardTarget, JsonValue, NativeScreenshot, NativeScreenshotOptions, NetworkRequestEntry, NetworkRequestOptions, QueryDimension, RecorderEntry, RecorderResult, RecorderStatus, RoleQuery, RouteListing, RouteOptions, ScrollOptions, Snapshot, SnapshotDiff, SnapshotOptions, StorageListing, StorageOptions, TextQuery, WaitForFunctionOptions, WaitOptions, WatchChanges, WatchOptions, WindowInfo, WindowState } from "./types.js";
 export declare const byRef: (ref: string) => HasgardTarget;
 export declare const bySelector: (selector: string) => HasgardTarget;
 export declare const byPoint: (x: number, y: number) => HasgardTarget;
@@ -14,6 +14,16 @@ export declare class HasgardApplication {
     waitForWindow(label: string, timeoutMs: number): Promise<HasgardWindow>;
     waitForWindowReady(label: string, readySelector: string, timeoutMs: number): Promise<HasgardWindow>;
     window(label: string): HasgardWindow;
+    /**
+     * Action recorder. Captures the RPC calls this connection makes into a
+     * replayable scenario — this is not video capture.
+     */
+    readonly recorder: {
+        start: () => Promise<void>;
+        stop: () => Promise<RecorderResult>;
+        status: () => Promise<RecorderStatus>;
+        add: (entry: RecorderEntry) => Promise<void>;
+    };
 }
 export declare class HasgardWindow {
     readonly label: string;
@@ -21,41 +31,285 @@ export declare class HasgardWindow {
     constructor(rpc: HasgardRpcClient, label: string);
     locator(selector: string): HasgardLocator;
     getByRole(role: string, query?: RoleQuery): HasgardLocator;
+    /**
+     * Locate by visible text. Matching runs in the page against the live DOM, not
+     * against a snapshot's `name`: that field collapses aria-label, alt, `<label>`,
+     * placeholder, and text into one 50-character string, so a button with an
+     * aria-label would never be findable by the text it actually shows.
+     */
+    getByText(text: string, query?: TextQuery): HasgardLocator;
+    getByLabel(text: string, query?: TextQuery): HasgardLocator;
+    getByPlaceholder(text: string, query?: TextQuery): HasgardLocator;
+    getByAltText(text: string, query?: TextQuery): HasgardLocator;
+    getByTitle(text: string, query?: TextQuery): HasgardLocator;
+    /** Test ids always match exactly, so `save` cannot select `save-draft`. */
+    getByTestId(testId: string): HasgardLocator;
+    /**
+     * Scope locators to a same-origin `<iframe>`.
+     *
+     * Cross-origin frames are out of reach: the same-origin policy binds injected
+     * script exactly as it binds the page's own, so no bridge can see into a
+     * third-party payment or OAuth frame. Those raise an error naming the origin
+     * problem rather than reporting a missing element.
+     */
+    frameLocator(selector: string): HasgardFrameLocator;
     snapshot(options?: SnapshotOptions): Promise<Snapshot>;
     state(): Promise<WindowState>;
+    url(): Promise<string>;
+    title(): Promise<string>;
+    /**
+     * Navigate this webview by assigning `location.href`. Unlike Playwright's
+     * `goto`, this does not wait for the load to finish and returns no response —
+     * follow it with `waitFor` or `waitForWindowReady`.
+     */
+    navigate(url: string): Promise<void>;
+    /** Scroll the document by a relative amount, or to `top`/`bottom`. */
+    scrollBy(options: ScrollOptions): Promise<void>;
     press(key: string): Promise<void>;
+    diff(options?: DiffOptions): Promise<SnapshotDiff>;
+    /**
+     * Poll a JavaScript expression in the webview until it returns a truthy
+     * value, and return that value. The expression is polled rather than driven
+     * by DOM mutations, so predicates that flip on a timer or a resolved fetch
+     * are caught too. A predicate that throws rejects instead of being retried.
+     */
+    waitForFunction<T = JsonValue>(expression: string, options?: WaitForFunctionOptions): Promise<T>;
+    /** Observe DOM mutations until they settle, or reject when nothing changes. */
+    watch(options?: WatchOptions): Promise<WatchChanges>;
+    consoleLogs(options?: ConsoleLogOptions): Promise<ConsoleLogEntry[]>;
+    clearConsole(): Promise<void>;
+    networkRequests(options?: NetworkRequestOptions): Promise<NetworkRequestEntry[]>;
+    clearNetwork(): Promise<void>;
+    /** `localStorage` by default; pass `{ session: true }` for `sessionStorage`. */
+    readonly storage: {
+        get: (key: string, options?: StorageOptions) => Promise<string | null>;
+        set: (key: string, value: string, options?: StorageOptions) => Promise<void>;
+        list: (options?: StorageOptions) => Promise<StorageListing>;
+        clear: (options?: StorageOptions) => Promise<void>;
+    };
+    forms(selector?: string): Promise<FormsDump>;
     evaluate<T>(script: string): Promise<T>;
     invoke<T>(command: string, args: Record<string, JsonValue>): Promise<T>;
     screenshot(selector?: string): Promise<Buffer>;
+    /**
+     * Capture this window through the native compositor, writing a PNG to
+     * `outputPath`. macOS only.
+     *
+     * Unlike `screenshot`, which renders the DOM inside the page, this records
+     * what the window server actually shows — so it sees native chrome, layered
+     * content, and anything the DOM renderer cannot reproduce.
+     *
+     * The operating-system window id is resolved from this window's label, so
+     * callers do not have to discover it themselves.
+     */
+    screenshotNative(options: NativeScreenshotOptions): Promise<NativeScreenshot>;
+    /**
+     * Scroll the page by wheel.
+     *
+     * The document sees a real `wheel` event first and may cancel it; the scroll
+     * only follows if it does not. Resolves to whether the page cancelled — which
+     * is how you tell "the app intercepted my wheel" from "nothing was
+     * listening". Use the locator method to scroll a nested scrollport.
+     */
+    wheel(deltaX: number, deltaY: number): Promise<boolean>;
+    /**
+     * The page's modal dialogs (`alert`, `confirm`, `prompt`).
+     *
+     * These block the webview until answered, so the bridge always answers them —
+     * dismissing by default, as Playwright does. A test that never touches this
+     * namespace still cannot hang on a `confirm()`, and can read back what the
+     * app tried to ask.
+     */
+    readonly dialogs: {
+        /** Answer every subsequent dialog with OK. `promptText` fills a `prompt`. */
+        accept: (promptText?: string) => Promise<DialogPolicy>;
+        /** Answer every subsequent dialog with Cancel. This is the default. */
+        dismiss: () => Promise<DialogPolicy>;
+        /** Every dialog the page has opened so far, oldest first. */
+        list: () => Promise<DialogListing>;
+        /** Forget the recorded dialogs. Leaves the accept/dismiss policy alone. */
+        clear: () => Promise<void>;
+    };
+    /**
+     * Shape what the page's own requests receive, without a real backend.
+     *
+     * Rules are declarative rather than Playwright's per-request callback: the
+     * bridge only ever answers requests, so it cannot call back into this process
+     * and await a handler while the page sits inside `fetch`. The same constraint
+     * shaped `dialogs`.
+     *
+     * Rules are checked in registration order and the first match wins, so
+     * register the narrow ones before a catch-all. Both `fetch` and
+     * `XMLHttpRequest` are covered; resources the webview loads itself -- the
+     * document, `<img src>`, stylesheets -- are not, since no page script sees
+     * them.
+     */
+    readonly routes: {
+        /** Answer matching requests with this response instead of the network. */
+        fulfill: (options: FulfillOptions) => Promise<{
+            id: number;
+        }>;
+        /** Fail matching requests the way a dropped connection does. */
+        abort: (options: RouteOptions) => Promise<{
+            id: number;
+        }>;
+        /** The active rules, their use counts, and every request they answered. */
+        list: () => Promise<RouteListing>;
+        /** Remove every rule and its interception log. */
+        clear: () => Promise<{
+            removed: number;
+        }>;
+    };
+    /** This window's operating-system window id, where the platform exposes one. */
+    nativeId(): Promise<number>;
     call<T>(method: string, params?: Record<string, JsonValue>): Promise<T>;
     runExclusive<T>(operation: () => Promise<T>): Promise<T>;
 }
-type LocatorQuery = {
+type LocatorQuery = ({
     kind: "selector";
     selector: string;
 } | {
     kind: "role";
     role: string;
     query: RoleQuery;
+} | {
+    kind: "query";
+    by: QueryDimension;
+    value: string;
+    query: TextQuery;
+}) & {
+    index?: number;
+    filters?: FilterOptions[];
+    frame?: string[];
 };
+/**
+ * The locator factories of a window, scoped to a chain of same-origin iframes.
+ *
+ * Mirrors the window's own factories rather than wrapping a locator, because a
+ * frame is a document to search in, not an element to search under: `#pay`
+ * inside the frame is not a descendant of `#pay` outside it.
+ */
+export declare class HasgardFrameLocator {
+    private readonly windowRef;
+    private readonly frame;
+    constructor(window: HasgardWindow, frame: string[]);
+    /** Descend into a frame nested inside this one. */
+    frameLocator(selector: string): HasgardFrameLocator;
+    locator(selector: string): HasgardLocator;
+    getByRole(role: string, query?: RoleQuery): HasgardLocator;
+    getByText(text: string, query?: TextQuery): HasgardLocator;
+    getByLabel(text: string, query?: TextQuery): HasgardLocator;
+    getByPlaceholder(text: string, query?: TextQuery): HasgardLocator;
+    getByAltText(text: string, query?: TextQuery): HasgardLocator;
+    getByTitle(text: string, query?: TextQuery): HasgardLocator;
+    getByTestId(testId: string): HasgardLocator;
+    /** Snapshot the frame's own document rather than the top one. */
+    snapshot(options?: SnapshotOptions): Promise<Snapshot>;
+    private byDimension;
+}
 export declare class HasgardLocator {
     readonly window: HasgardWindow;
     private readonly query;
     constructor(window: HasgardWindow, query: LocatorQuery);
-    click(): Promise<void>;
+    /**
+     * Click this element.
+     *
+     * A right or middle click raises `contextmenu`/`auxclick` and no `click`, and
+     * `clickCount: 2` escalates `detail` across the presses before a single
+     * `dblclick` -- both matching what the platform does, so a listener bound to
+     * the wrong event fails here rather than in front of a user.
+     */
+    click(options?: ClickOptions): Promise<void>;
     fill(value: string): Promise<void>;
     type(text: string): Promise<void>;
+    /** Empty the control, firing `input` and `change` as `fill` does. */
+    clear(): Promise<void>;
+    /**
+     * Select files on an `<input type="file">` without a native file chooser,
+     * which an embedded webview gives no way to drive.
+     *
+     * Strings are read from the test machine's disk; `DropFile` payloads let you
+     * supply content that never existed as a file. An empty array deselects.
+     */
+    setInputFiles(files: FileInput | FileInput[]): Promise<void>;
+    /**
+     * Scroll this element by wheel.
+     *
+     * The page sees a real `wheel` event first and may cancel it; the scroll only
+     * follows if it does not — the same two steps a physical wheel produces.
+     * Resolves to whether the page cancelled.
+     */
+    wheel(deltaX: number, deltaY: number): Promise<boolean>;
     selectOption(value: string): Promise<void>;
+    /** Drive the checkbox to checked. A no-op when it is already checked. */
     check(): Promise<void>;
+    /** Drive the checkbox to unchecked. A no-op when it is already unchecked. */
+    uncheck(): Promise<void>;
+    /** Flip the checkbox, whatever its current state. */
+    toggle(): Promise<void>;
+    hover(): Promise<void>;
+    /** Shorthand for `click({ clickCount: 2 })`; other options still apply. */
+    dblclick(options?: Omit<ClickOptions, "clickCount">): Promise<void>;
+    focus(): Promise<void>;
+    blur(): Promise<void>;
+    /** Scroll this element's own scrollport. */
+    scrollBy(options: ScrollOptions): Promise<void>;
+    boundingBox(): Promise<BoundingBox>;
+    isDisabled(): Promise<boolean>;
+    isEnabled(): Promise<boolean>;
     textContent(): Promise<string>;
     inputValue(): Promise<string>;
+    innerHTML(): Promise<string>;
+    getAttribute(name: string): Promise<string | null>;
+    /** Drag this element onto another one in the same window. */
+    dragTo(target: HasgardLocator): Promise<void>;
+    /** Drag this element by a pixel offset from its centre. */
+    dragBy(offset: DragOffset): Promise<void>;
+    /** Dispatch a file drop onto this element. `data` is base64-encoded. */
+    dropFiles(files: DropFile[]): Promise<void>;
     attributes(): Promise<Record<string, string>>;
     isVisible(): Promise<boolean>;
     isChecked(): Promise<boolean>;
     count(): Promise<number>;
     waitFor(options: WaitOptions): Promise<void>;
+    /**
+     * Narrow this locator to a single match by position. A negative index counts
+     * back from the end, so `last()` stays one round trip.
+     */
+    nth(index: number): HasgardLocator;
+    /**
+     * Narrow this locator to the elements whose text matches.
+     *
+     * Filters accumulate, so `filter({hasText}).filter({hasNotText})` applies
+     * both. Ordering matters against `nth`: filtering happens first, so
+     * `filter({hasText: "x"}).first()` is the first *matching* element, which is
+     * the reading that makes `first()` mean what it says.
+     */
+    filter(options: FilterOptions): HasgardLocator;
+    first(): HasgardLocator;
+    last(): HasgardLocator;
     private resolveUnique;
+    /**
+     * Serialize a target together with the frame chain this locator lives in.
+     *
+     * A ref carries its own document, so the bridge ignores `frame` for one; the
+     * chain still travels so that a selector or coordinate target -- which the
+     * bridge must resolve itself -- lands in the right document.
+     */
+    private scoped;
+    private frameParams;
     private withTarget;
     private resolveAll;
+    private resolveBase;
+    /**
+     * Apply each accumulated filter, one round trip per filter.
+     *
+     * Filters run server-side rather than against a snapshot because the text a
+     * filter matches on is not carried in snapshot entries — deliberately, so
+     * that every unrelated `snapshot` call stays small.
+     */
+    private applyFilters;
+    private runQuery;
+    private parseElements;
 }
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nyssance/tauri-hasgard",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Playwright Test fixtures for native Tauri Hasgard automation",
   "type": "module",
   "main": "./dist/index.js",