@razohq/razo 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,336 @@
+import { Page, Locator } from '@playwright/test';
+export { A as AI_STEP_ATTACHMENT, S as StepEvent, e as emitStepEvent } from './events-D_lCLx1V.js';
+
+interface SentenceContext {
+    controlType: string;
+    name: string;
+    detail?: string;
+    expected?: string;
+}
+/**
+ * Sentence grammar: one fixed template per verb, in a single place,
+ * so the narration is predictable and parseable by an AI.
+ */
+declare const SENTENCES: {
+    readonly click: (c: SentenceContext) => string;
+    readonly fill: (c: SentenceContext) => string;
+    readonly clear: (c: SentenceContext) => string;
+    readonly select: (c: SentenceContext) => string;
+    readonly check: (c: SentenceContext) => string;
+    readonly uncheck: (c: SentenceContext) => string;
+    readonly choose: (c: SentenceContext) => string;
+    readonly 'choose-many': (c: SentenceContext) => string;
+    readonly open: (c: SentenceContext) => string;
+    readonly attach: (c: SentenceContext) => string;
+    readonly set: (c: SentenceContext) => string;
+    readonly 'assert-visible': (c: SentenceContext) => string;
+    readonly 'assert-enabled': (c: SentenceContext) => string;
+    readonly 'assert-disabled': (c: SentenceContext) => string;
+    readonly 'assert-text': (c: SentenceContext) => string;
+    readonly 'assert-checked': (c: SentenceContext) => string;
+    readonly 'assert-unchecked': (c: SentenceContext) => string;
+    readonly 'assert-selected': (c: SentenceContext) => string;
+    readonly 'assert-value': (c: SentenceContext) => string;
+    readonly 'assert-href': (c: SentenceContext) => string;
+    readonly hover: (c: SentenceContext) => string;
+    readonly 'double-click': (c: SentenceContext) => string;
+    readonly 'right-click': (c: SentenceContext) => string;
+    readonly press: (c: SentenceContext) => string;
+    readonly focus: (c: SentenceContext) => string;
+    readonly 'scroll-to': (c: SentenceContext) => string;
+    readonly drag: (c: SentenceContext) => string;
+    readonly 'assert-hidden': (c: SentenceContext) => string;
+    readonly 'assert-focused': (c: SentenceContext) => string;
+    readonly 'assert-contains-text': (c: SentenceContext) => string;
+    readonly 'assert-attribute': (c: SentenceContext) => string;
+    readonly 'assert-empty': (c: SentenceContext) => string;
+    readonly 'turn-on': (c: SentenceContext) => string;
+    readonly 'turn-off': (c: SentenceContext) => string;
+    readonly 'assert-on': (c: SentenceContext) => string;
+    readonly 'assert-off': (c: SentenceContext) => string;
+    readonly pick: (c: SentenceContext) => string;
+    readonly 'assert-row-count': (c: SentenceContext) => string;
+    readonly 'assert-row-contains': (c: SentenceContext) => string;
+    readonly close: (c: SentenceContext) => string;
+    readonly 'assert-open': (c: SentenceContext) => string;
+    readonly 'assert-closed': (c: SentenceContext) => string;
+    readonly 'open-tab': (c: SentenceContext) => string;
+    readonly 'assert-active-tab': (c: SentenceContext) => string;
+    readonly 'assert-alt': (c: SentenceContext) => string;
+    readonly 'assert-loaded': (c: SentenceContext) => string;
+    readonly 'pick-date': (c: SentenceContext) => string;
+    readonly 'assert-count': (c: SentenceContext) => string;
+    readonly 'assert-tooltip': (c: SentenceContext) => string;
+};
+type StepAction = keyof typeof SENTENCES;
+interface StepOptions {
+    /** Action payload (typed text, chosen option) */
+    detail?: string;
+    /** Assertions only: expected value */
+    expected?: string;
+    /** On assertion failure: how to read the value actually found */
+    readActual?: () => Promise<string>;
+    /** Sentence override for business-level narration ("Confirm the export") */
+    as?: string;
+}
+interface ControlOptions {
+    /** Scope the control inside another one (e.g. a button within a dialog). */
+    within?: Control;
+    /**
+     * Deterministic healing alternatives, tried in order when the primary
+     * locator stops resolving. After these, the implicit `role + name`
+     * fallback derived from the control type is tried. See RAZO_HEALING.
+     */
+    fallbacks?: LocatorSpec[];
+}
+type AriaRole = Parameters<Page['getByRole']>[0];
+/**
+ * How to find a control. A plain string means data-testid (the recommended,
+ * stable path — see the auto-testid Vite plugin); the object forms map 1:1
+ * to Playwright's user-facing locators, so razo works on apps that were
+ * never instrumented. `{ locator }` is the full escape hatch.
+ */
+type LocatorSpec = string | {
+    testId: string;
+} | {
+    role: AriaRole;
+    name?: string;
+    exact?: boolean;
+} | {
+    label: string;
+    exact?: boolean;
+} | {
+    placeholder: string;
+} | {
+    text: string;
+    exact?: boolean;
+} | {
+    altText: string;
+} | {
+    title: string;
+} | {
+    css: string;
+} | {
+    locator: Locator;
+};
+declare abstract class Control {
+    readonly page: Page;
+    readonly name: string;
+    protected abstract readonly controlType: string;
+    /** @deprecated Only set when the control was located by testid; use `selector`. */
+    readonly testId: string;
+    private _locator;
+    private _selector;
+    private readonly parent?;
+    private readonly fallbacks;
+    /**
+     * Root that fallbacks resolve against — read lazily so a child control
+     * follows its `within` parent even after the PARENT healed.
+     */
+    private get healRoot();
+    private get withinPrefix();
+    /** The Playwright locator currently backing this control. */
+    get locator(): Locator;
+    /** Readable selector, chained through `within` parents; travels in every StepEvent. */
+    get selector(): string;
+    constructor(page: Page, locate: LocatorSpec, name: string, options?: ControlOptions);
+    /**
+     * Core of the framework: runs `fn` inside a test.step titled with the
+     * grammar sentence, and emits the matching structured StepEvent —
+     * also (especially) when it fails.
+     */
+    protected step<T>(action: StepAction, options: StepOptions, fn: () => Promise<T>): Promise<T>;
+    /** True when the primary locator currently matches nothing (safe: never throws). */
+    private primaryGone;
+    /** First fallback (explicit, then implicit role+name) resolving to exactly one element. */
+    private findHealingSpec;
+    /**
+     * Same-role elements on the page, as evidence for the analyzer to propose
+     * a replacement locator. Best-effort: capped, time-boxed, never throws.
+     */
+    private collectDomCandidates;
+    expectVisible(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectEnabled(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectDisabled(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectText(expected: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    /** The control as it appears in the narration: `button "Export"`. */
+    describe(): string;
+    hover(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    doubleClick(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    rightClick(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    press(key: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    focus(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    scrollTo(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    dragTo(target: Control, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectHidden(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectFocused(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectContainsText(expected: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectAttribute(attribute: string, expected: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    /** For repeated testids (list items): how many elements the control matches. */
+    expectCount(expected: number, options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+declare class Button extends Control {
+    protected readonly controlType = "button";
+    click(options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+declare class Input extends Control {
+    protected readonly controlType: string;
+    /** For a field, "text" means its value, not its DOM content. */
+    expectText(expected: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    fill(value: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    clear(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectEmpty(options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+/** Radio group: the testId points at the group container. */
+declare class RadioButton extends Control {
+    protected readonly controlType = "radio group";
+    select(option: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectSelected(option: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+declare class Checkbox extends Control {
+    protected readonly controlType = "checkbox";
+    private readActualState;
+    expectChecked(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectUnchecked(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    check(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    uncheck(options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+declare class Select extends Control {
+    protected readonly controlType = "select";
+    /** Chooses an option by its visible label. */
+    choose(option: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    /** Chooses several options by label (for <select multiple>). */
+    chooseMany(optionLabels: string[], options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+declare class Link extends Control {
+    protected readonly controlType = "link";
+    open(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectHref(expected: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+/**
+ * Read-only element (status messages, headings). It has no actions:
+ * it exists so outcome verifications are narrated too.
+ */
+declare class Label extends Control {
+    protected readonly controlType = "label";
+}
+
+declare class FileInput extends Control {
+    protected readonly controlType = "file input";
+    /** Attaches one or more files by path. The narration shows the file names. */
+    attach(files: string | string[], options?: Pick<StepOptions, 'as'>): Promise<void>;
+    clear(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    /** Asserts the name of the file currently selected. */
+    expectFile(expectedName: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+declare class Slider extends Control {
+    protected readonly controlType = "slider";
+    /**
+     * Sets the slider value. Range inputs cannot be filled, so the value is
+     * set in the DOM and the input/change events the app listens to are fired.
+     */
+    setValue(value: number | string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectValue(expected: number | string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+/** Same behavior as Input; only the narration names it differently. */
+declare class TextArea extends Input {
+    protected readonly controlType = "text area";
+}
+
+/** ARIA switch (role="switch" with aria-checked). Actions are idempotent. */
+declare class Switch extends Control {
+    protected readonly controlType = "switch";
+    private readState;
+    turnOn(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    turnOff(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectOn(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectOff(options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+/**
+ * ARIA combobox: the testId points at the text input; options are looked up
+ * by role anywhere on the page (comboboxes often render their listbox in a
+ * portal outside the input's subtree).
+ */
+declare class Combobox extends Control {
+    protected readonly controlType = "combobox";
+    search(text: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    pick(option: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectSelected(expected: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+/** Read-only table assertions over tbody rows. */
+declare class Table extends Control {
+    protected readonly controlType = "table";
+    private rows;
+    expectRowCount(expected: number, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectRowContains(expected: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+/** Native <dialog> or role="dialog". close() sends Escape. */
+declare class Dialog extends Control {
+    protected readonly controlType = "dialog";
+    private readState;
+    close(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectOpen(options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectClosed(options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+/** ARIA tablist: the testId points at the tablist container. */
+declare class Tabs extends Control {
+    protected readonly controlType = "tabs";
+    open(tab: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectActive(expected: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+declare class Image extends Control {
+    protected readonly controlType = "image";
+    expectAlt(expected: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectLoaded(options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+/** Native input[type="date"]; dates travel in ISO format (YYYY-MM-DD). */
+declare class DatePicker extends Control {
+    protected readonly controlType = "date picker";
+    pick(isoDate: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    expectDate(expected: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+/**
+ * Dropdown menu: the testId points at the trigger button; menu items are
+ * looked up by role anywhere on the page (menus often render in portals).
+ */
+declare class Menu extends Control {
+    protected readonly controlType = "menu";
+    choose(item: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+/**
+ * Tooltip: the testId points at the TRIGGER element. The tooltip content is
+ * resolved through the trigger's aria-describedby (the accessible pattern),
+ * so it works wherever the tooltip node is rendered.
+ */
+declare class Tooltip extends Control {
+    protected readonly controlType = "tooltip";
+    private tooltipText;
+    /** Hovers the trigger and asserts the tooltip content. */
+    expectContent(expected: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+/** contenteditable region. Inherits expectText/expectContainsText from the base. */
+declare class Editor extends Control {
+    protected readonly controlType = "editor";
+    write(text: string, options?: Pick<StepOptions, 'as'>): Promise<void>;
+    clear(options?: Pick<StepOptions, 'as'>): Promise<void>;
+}
+
+export { Button, Checkbox, Combobox, Control, type ControlOptions, DatePicker, Dialog, Editor, FileInput, Image, Input, Label, Link, type LocatorSpec, Menu, RadioButton, Select, Slider, type StepAction, type StepOptions, Switch, Table, Tabs, TextArea, Tooltip };