import { Page, Response } from '@playwright/test';
import { ElementRepository } from '@civitas-cerebrum/element-repository';
import { EmailClientConfig, EmailSendOptions, EmailReceiveOptions, ReceivedEmail, EmailMarkAction, EmailFilter } from '@civitas-cerebrum/email-client';
import { ApiResponse } from '@civitas-cerebrum/wasapi';
import { SqlResult, QueryBuilder } from '@civitas-cerebrum/sql-client';
import { StepOptions, DropdownSelectOptions, TextVerifyOptions, CountVerifyOptions, DragAndDropOptions, ListedElementMatch, VerifyListedOptions, GetListedDataOptions, FillFormValue, GetAllOptions, ScreenshotOptions, IsVisibleOptions, StorageVerifyOptions, WindowVerifyOptions, VisualMatchOptions } from '../enum/Options';
import { BrowserResponse, BrowserRequestOptions } from '../interactions/BrowserRequest';
import { ExpectNoRequestOptions, WaitUntilState, WaitForNetworkIdleOptions, LoadState } from '../interactions/Navigation';
import { ElementAction } from './ElementAction';
import { ExpectBuilder } from './ExpectMatchers';
/**
 * The `Steps` class serves as a unified Facade for test orchestration.
 * It combines element acquisition (via `@civitas-cerebrum/element-repository`) with
 * Playwright interactions, navigation, and verifications to keep test files clean,
 * readable, and free of raw locators.
 */
export declare class Steps {
    private repo;
    private page;
    private interact;
    private navigate;
    private extract;
    private verify;
    private request;
    private utils;
    private email;
    private apiClients;
    /** Lazily-built SqlClient cache, keyed by provider name (constructed on first DB step). */
    private dbClients;
    /** Provider name → connection string. Clients are built on first use so a missing driver fails at the first DB step, not at fixture setup. */
    private dbConfigs;
    private dbConnectTimeoutMs?;
    private timeout?;
    private interceptionRetry?;
    /**
     * Initializes the Steps class with the element repository.
     * The Playwright Page is obtained from the repository's driver.
     * @param repo - An initialized instance of `ElementRepository` containing your locators and the bound driver.
     * @param options - Optional configuration: emailCredentials, timeout, interceptionRetry, apiBaseUrl, and/or apiProviders.
     */
    constructor(repo: ElementRepository, options?: {
        emailCredentials?: EmailClientConfig;
        timeout?: number;
        /**
         * When a click is intercepted by an overlaying element, retry it as a
         * dispatched DOM click event. Default `true` (compat). Set `false` so
         * genuine overlay bugs (stuck modals, cookie walls) fail the click.
         */
        interceptionRetry?: boolean;
        apiBaseUrl?: string;
        apiProviders?: Record<string, string>;
        dbUrl?: string;
        dbProviders?: Record<string, string>;
        /**
         * Connect-timeout (ms) applied to every SQL client, so a wrong/unreachable
         * `dbUrl` fails fast in CI instead of hanging on the first query.
         */
        dbConnectTimeoutMs?: number;
    });
    /**
     * Maps StepOptions to ElementResolutionOptions for the repository.
     */
    private toResolutionOptions;
    /**
     * Returns resolution options that force the ALL strategy (no .first() narrowing).
     * Used by collection-based methods like getCount, verifyCount, getAll, verifyOrder.
     */
    private toAllResolutionOptions;
    /**
     * Resolves an element from the repository and narrows its type to
     * `WebElement`. This package is Playwright-only, so every resolved element
     * is in practice a `WebElement`. Calling this once at the repo boundary
     * lets every downstream call use the richer `WebElement` type (with its
     * `locator` / `rightClick` / `selectOption` / `getAllAttributes`) without
     * per-call casts.
     */
    private getWebElement;
    /**
     * Same as `getWebElement` but forces the ALL strategy. For collection-based
     * methods (getCount, verifyOrder, verifyImages, etc.).
     */
    private getAllWebElement;
    /**
     * Returns a fluent `ElementAction` with the caller's `StepOptions` strategy
     * applied via the fluent strategy selectors. Lets the legacy positional
     * `verify*` methods delegate into the matcher tree without losing the
     * `{ strategy: 'random' | 'index' | 'text' | 'attribute' }` escape hatch.
     */
    private actionWithStrategy;
    /**
     * Returns a fluent builder for performing actions on a repository element.
     * Chain a strategy selector (optional) and terminate with an action.
     *
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @returns An `ElementAction` builder.
     *
     * @example
     * ```ts
     * await steps.on('mainNavItems', 'HomePage').first().hover();
     * await steps.on('subcategoryItems', 'HomePage').random().click({ withoutScrolling: true });
     * await steps.on('productCards', 'CollectionsPage').verifyPresence();
     * const price = await steps.on('price', 'ProductPage').nth(0).getText();
     * ```
     */
    on(elementName: string, pageName: string): ElementAction;
    /**
     * Navigates the browser to the specified URL.
     * Optionally appends query parameters and/or chooses the lifecycle state to
     * wait for.
     * @param url - The URL or path to navigate to (e.g. `'/dashboard'` or `'https://example.com'`).
     * @param options - Optional settings. `query` is a key-value map appended as
     *   query parameters. `waitUntil` chooses the page lifecycle state to wait
     *   for (default `'load'`); pass `'domcontentloaded'` for SPA navigations
     *   that stall a cold WebKit/Safari on the full `load` event.
     * @returns The navigation `Response` (last redirect's response), or `null`
     *   when navigation triggered no network request (same-document hash nav).
     *   Read `res.status()` to assert 404 / redirect contracts; ignore the
     *   return value when you only care about side-effects.
     */
    navigateTo(url: string, options?: {
        query?: Record<string, string>;
        waitUntil?: WaitUntilState;
    }): Promise<Response | null>;
    /**
     * Returns the current page URL (the full href). The value-returning
     * companion to {@link verifyUrlContains} — use it when a test needs the live
     * URL to compute a path, diff against a start URL, or build a pattern.
     */
    getUrl(): string;
    /**
     * Returns the `pathname` of the current page URL (no origin, query, or hash).
     * Convenience over `new URL(steps.getUrl()).pathname`.
     */
    getCurrentPath(): string;
    /**
     * Waits until the page URL matches `url`. A string is a glob pattern, a
     * RegExp is a contains-style match, and a predicate receives the live `URL`.
     *
     * Pass `action` to arm the wait **before** the navigation-triggering action
     * runs (issued concurrently via `Promise.all`) so a fast client-side route
     * change cannot complete in the gap between acting and waiting — the
     * race-safe form for rapid navigations.
     *
     * @param url - Glob string, RegExp, or `(url: URL) => boolean` predicate.
     * @param action - Optional navigation-triggering action, run concurrently.
     *   Its return value is ignored, so a value-returning call (e.g.
     *   `() => steps.navigateTo('/x')`, which now resolves a `Response | null`)
     *   is accepted without a `void`-assignability error.
     * @param options - Optional `{ timeout, waitUntil }`.
     */
    waitForUrl(url: string | RegExp | ((url: URL) => boolean), action?: () => Promise<unknown>, options?: {
        timeout?: number;
        waitUntil?: WaitUntilState;
    }): Promise<void>;
    /**
     * Refreshes (reloads) the current page.
     */
    refresh(): Promise<void>;
    /**
     * Navigates the browser history backwards or forwards.
     * @param direction - The direction to navigate: `'back'` or `'forward'`.
     */
    backOrForward(direction: 'back' | 'forward'): Promise<void>;
    /**
     * Sets the browser viewport to the specified dimensions.
     * @param width - The viewport width in pixels.
     * @param height - The viewport height in pixels.
     */
    setViewport(width: number, height: number): Promise<void>;
    /**
     * Executes an action that opens a new browser tab/window, waits for it to load,
     * and returns the new Page object.
     * @param action - An async function that triggers the new tab (e.g. a click).
     * @returns The newly opened Page object.
     */
    switchToNewTab(action: () => Promise<void>): Promise<Page>;
    /**
     * Closes the specified tab (or the current page's tab) and returns the remaining page.
     * @param targetPage - The page to close. Defaults to the current page.
     * @returns The page that received focus after closing.
     */
    closeTab(targetPage?: Page): Promise<Page>;
    /**
     * Returns the number of open tabs/pages in the current browser context.
     * @returns The count of open pages.
     */
    getTabCount(): number;
    /**
     * Clicks on an element identified by page and element name from the repository.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param options - Optional step options for element resolution and click modifiers.
     */
    click(elementName: string, pageName: string, options?: StepOptions): Promise<boolean | void>;
    /**
     * Clicks a random visible element from a group of elements matching the locator.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param options - Optional step options.
     * @throws Error if no visible element is found for the given locator.
     */
    clickRandom(elementName: string, pageName: string, options?: StepOptions): Promise<void>;
    /**
     * Clicks on an element only if it is present in the DOM.
     * Does nothing and returns false if the element is not found.
     *
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param options - Optional step options for element resolution.
     */
    clickIfPresent(elementName: string, pageName: string, options?: StepOptions): Promise<boolean>;
    /**
     * Right-clicks on an element identified by page and element name from the repository.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param options - Optional step options for element resolution.
     */
    rightClick(elementName: string, pageName: string, options?: StepOptions): Promise<void>;
    /**
     * Double-clicks on an element identified by page and element name from the repository.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param options - Optional step options for element resolution.
     */
    doubleClick(elementName: string, pageName: string, options?: StepOptions): Promise<void>;
    /**
     * Checks a checkbox or radio button. Idempotent.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param options - Optional step options for element resolution.
     */
    check(elementName: string, pageName: string, options?: StepOptions): Promise<void>;
    /**
     * Unchecks a checkbox. Idempotent.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param options - Optional step options for element resolution.
     */
    uncheck(elementName: string, pageName: string, options?: StepOptions): Promise<void>;
    /**
     * Hovers over an element, triggering any hover-based UI effects.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param options - Optional step options for element resolution.
     */
    hover(elementName: string, pageName: string, options?: StepOptions): Promise<void>;
    /**
     * Scrolls the specified element into the visible viewport.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param options - Optional step options for element resolution.
     */
    scrollIntoView(elementName: string, pageName: string, options?: StepOptions): Promise<void>;
    /**
     * Clears the input field and fills it with the specified text.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param text - The text to fill into the input field.
     * @param options - Optional step options for element resolution.
     */
    fill(elementName: string, pageName: string, text: string, options?: StepOptions): Promise<void>;
    /**
     * Uploads one or more files to a file input element.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param filePath - Path to the file, or an array of paths for multi-file inputs.
     * @param options - Optional step options for element resolution.
     */
    uploadFile(elementName: string, pageName: string, filePath: string | string[], options?: StepOptions): Promise<void>;
    /**
     * Simulates dropping files onto a drop-zone element by dispatching
     * `dragenter`, `dragover`, and `drop` events with a populated `DataTransfer`.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param filenames - File name(s) to include in the drop (basename only; no real file is read).
     * @param options - Optional `mimeType` (default `'application/octet-stream'`) and step options.
     */
    dropFiles(elementName: string, pageName: string, filenames: string[], options?: {
        mimeType?: string;
    } & StepOptions): Promise<void>;
    /**
     * Selects an option from a `<select>` dropdown element.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param dropdownOptions - Optional selection strategy (random, by value, or by index).
     * @param options - Optional step options for element resolution.
     * @returns The value of the selected option.
     */
    selectDropdown(elementName: string, pageName: string, dropdownOptions?: DropdownSelectOptions, options?: StepOptions): Promise<string>;
    /**
     * Performs a drag-and-drop action on an element.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param dragOptions - Drag target: either `{ target: Element }` or `{ xOffset, yOffset }`.
     * @param options - Optional step options for element resolution.
     */
    dragAndDrop(elementName: string, pageName: string, dragOptions: DragAndDropOptions, options?: StepOptions): Promise<void>;
    /**
     * Performs a drag-and-drop action on a specific element within a list,
     * identified by its visible text content.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param elementText - The visible text of the specific list item to drag.
     * @param dragOptions - Drag target: either `{ target: Element }` or `{ xOffset, yOffset }`.
     * @throws Error if no element with the specified text is found.
     */
    dragAndDropListedElement(elementName: string, pageName: string, elementText: string, dragOptions: DragAndDropOptions): Promise<void>;
    /**
     * Sets the value of a range/slider input element.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param value - The numeric value to set on the slider.
     * @param options - Optional step options for element resolution.
     */
    setSliderValue(elementName: string, pageName: string, value: number, options?: StepOptions): Promise<void>;
    /**
     * Presses a keyboard key at the page level (not bound to a specific element).
     * @param key - The key to press (e.g. `'Escape'`, `'Enter'`, `'Tab'`, `'Control+A'`).
     */
    pressKey(key: string): Promise<void>;
    /**
     * Presses a multi-key chord at the page level. Parts are joined with `+`, so
     * `['Control', 'A']` presses `Control+A`. The intent-revealing companion to
     * {@link pressKey} for shortcuts where listing the modifiers reads clearer.
     * @param keys - The keys to press together, e.g. `['Meta', 'K']` or `['Control', 'Shift', 'P']`.
     */
    pressKeys(keys: string[]): Promise<void>;
    /**
     * Dispatches a synthetic DOM event on a named element, optionally with an
     * `eventInit` payload. Drives event handlers directly WITHOUT actionability
     * checks — reach for it only when a real interaction can't express the case
     * (custom events, firing `input`/`change` on a widget that swallows
     * synthetic typing). Prefer `click` / `fill` / `pressKey` for real user input.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param type - The DOM event type, e.g. `'click'`, `'input'`, `'focus'`.
     * @param eventInit - Optional event properties, e.g. `{ key: 'Enter', bubbles: true }`.
     * @param options - Optional step options for element resolution.
     */
    dispatchEvent(elementName: string, pageName: string, type: string, eventInit?: Record<string, unknown>, options?: StepOptions): Promise<void>;
    /**
     * Types text into an input field one character at a time with a delay between keystrokes.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param text - The text to type character by character.
     * @param delay - The delay in milliseconds between each keystroke. Defaults to `100`.
     * @param options - Optional step options for element resolution.
     */
    typeSequentially(elementName: string, pageName: string, text: string, delay?: number, options?: StepOptions): Promise<void>;
    /**
     * Clears the value of an input or textarea element without filling it with new text.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param options - Optional step options for element resolution.
     */
    clearInput(elementName: string, pageName: string, options?: StepOptions): Promise<void>;
    /**
     * Selects multiple options from a `<select multiple>` element by their `value` attributes.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param values - An array of `value` attribute strings to select simultaneously.
     * @param options - Optional step options for element resolution.
     * @returns An array of the actually selected `value` strings.
     */
    selectMultiple(elementName: string, pageName: string, values: string[], options?: StepOptions): Promise<string[]>;
    /**
     * Retrieves the visible text content of an element.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param options - Optional step options for element resolution.
     * @returns The text content of the element, or `null` if unavailable.
     */
    getText(elementName: string, pageName: string, options?: StepOptions): Promise<string | null>;
    /**
     * Retrieves the value of a specific HTML attribute from an element.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param attributeName - The name of the attribute to retrieve.
     * @param options - Optional step options for element resolution.
     * @returns The attribute value, or `null` if the attribute does not exist.
     */
    getAttribute(elementName: string, pageName: string, attributeName: string, options?: StepOptions): Promise<string | null>;
    /**
     * Returns the number of DOM elements matching the locator.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param options - Optional step options for element resolution.
     * @returns The count of matching elements.
     */
    getCount(elementName: string, pageName: string, options?: StepOptions): Promise<number>;
    /**
     * Retrieves the current value of an input, textarea, or select element.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param options - Optional step options for element resolution.
     * @returns The current value of the input.
     */
    getInputValue(elementName: string, pageName: string, options?: StepOptions): Promise<string>;
    /**
     * Retrieves a computed CSS property value from an element.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param property - The CSS property name.
     * @param options - Optional step options for element resolution.
     * @returns The computed value as a string.
     */
    getCssProperty(elementName: string, pageName: string, property: string, options?: StepOptions): Promise<string>;
    /**
     * Returns the element's bounding box (`{ x, y, width, height }` in CSS
     * pixels, relative to the main frame) or `null` when it is not rendered.
     * Use for geometry the DOM doesn't surface: overlap, off-screen placement,
     * collapsed (`0×0`) regions.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param options - Optional step options for element resolution.
     */
    getBoundingBox(elementName: string, pageName: string, options?: StepOptions): Promise<{
        x: number;
        y: number;
        width: number;
        height: number;
    } | null>;
    /**
     * Retrieves the raw HTML of an element. Defaults to `innerHTML`; pass
     * `{ outer: true }` to get the element's `outerHTML` (the tag itself plus its subtree).
     *
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param options - `outer` switches between innerHTML/outerHTML; other fields control strategy.
     */
    getHtml(elementName: string, pageName: string, options?: StepOptions & {
        outer?: boolean;
    }): Promise<string>;
    /**
     * Retrieves the HTML of the current page. Defaults to `document.body.innerHTML`;
     * pass `{ outer: true }` to get the full `<html>` document outerHTML (including `<head>`).
     *
     * Use this for page-level scans where no single element is the natural scope —
     * e.g. confirming an injected payload was HTML-escaped anywhere on the page.
     */
    getPageHtml(options?: {
        outer?: boolean;
    }): Promise<string>;
    /**
     * Retrieves the rendered text of the current page (`document.body.innerText`).
     * The text companion to {@link getPageHtml} — use for page-level text
     * assertions where no single element is the natural scope (e.g. a 404 body).
     *
     * @example
     * ```ts
     * await steps.navigateTo('/no-such-route');
     * expect(await steps.getPageText()).toContain('Page not found');
     * ```
     */
    getPageText(): Promise<string>;
    /**
     * Reads a `window`-level value by dotted path — e.g. `'__XSS_FIRED'`,
     * `'dataLayer.length'`, `'document.title'`. Walks the path key-by-key and
     * returns `undefined` for any missing segment (never throws on a missing
     * path). Use to assert window-state the DOM doesn't surface: analytics
     * layers, injected sentinels, feature flags.
     *
     * @example
     * ```ts
     * const fired = await steps.getWindowProperty<boolean>('__XSS_FIRED');
     * const n = await steps.getWindowProperty<number>('dataLayer.length');
     * const title = await steps.getWindowProperty<string>('document.title');
     * ```
     */
    getWindowProperty<T = unknown>(path: string): Promise<T | undefined>;
    /**
     * Sets a `window`-level value by dotted path, creating intermediate objects
     * as needed — the mutating companion to {@link getWindowProperty}. Use to
     * seed window-level state a test depends on.
     *
     * @example
     * ```ts
     * await steps.setWindowProperty('__test.flag', true);
     * ```
     */
    setWindowProperty(path: string, value: unknown): Promise<void>;
    /**
     * The SINGLE labelled escape hatch for arbitrary in-page JavaScript:
     * `page.evaluate(fn, arg)`, typed and logged. This is the LAST RESORT —
     * prefer the targeted steps (`getWindowProperty`, `verifyWindowProperty`,
     * the matcher tree, scoped queries) which stay named, retrying, and
     * grep-able. Reach here only when no targeted step expresses the read.
     *
     * @example
     * ```ts
     * const links = await steps.evaluateScript<number>(() => document.querySelectorAll('a').length);
     * ```
     */
    evaluateScript<T = unknown>(fn: (arg?: unknown) => T | Promise<T>, arg?: unknown): Promise<T>;
    /**
     * Reads a value from the browser's `window.localStorage`. Returns `null`
     * when the key is absent — same contract as the native `getItem`.
     *
     * Use for state the framework cannot reach through the DOM: persisted
     * theme preference, dismissed-banner flag, feature toggle, auth tokens, etc.
     *
     * @example
     * ```ts
     * await steps.click('themeToggle', 'NavBar');
     * expect(await steps.getLocalStorage('theme')).toBe('dark');
     * ```
     */
    getLocalStorage(key: string): Promise<string | null>;
    /**
     * Reads a value from the browser's `window.sessionStorage`. Returns `null`
     * when the key is absent — same contract as the native `getItem`.
     */
    getSessionStorage(key: string): Promise<string | null>;
    /**
     * Returns every key currently set in `window.localStorage`. The enumerating
     * companion to {@link getLocalStorage} — use when the test needs to know
     * *which* keys exist (e.g. asserting a logout cleared persisted state)
     * rather than reading one known key.
     *
     * @example
     * ```ts
     * await steps.click('logout', 'NavBar');
     * expect(await steps.getLocalStorageKeys()).not.toContain('authToken');
     * ```
     */
    getLocalStorageKeys(): Promise<string[]>;
    /**
     * Returns every key currently set in `window.sessionStorage`. The
     * enumerating companion to {@link getSessionStorage}.
     */
    getSessionStorageKeys(): Promise<string[]>;
    /**
     * Writes a value to the browser's `window.localStorage` — the mutating
     * companion to {@link getLocalStorage}. Use to seed persisted state a test
     * depends on, or to drive resilience checks with deliberately malformed
     * values (e.g. corrupt JSON the app must tolerate).
     *
     * @example
     * ```ts
     * await steps.setLocalStorage('wishlist', 'not-json-{[bogus');
     * await steps.refresh();
     * await steps.verifyPresence('wishlistEmptyState', 'WishlistPage');
     * ```
     */
    setLocalStorage(key: string, value: string): Promise<void>;
    /**
     * Writes a value to the browser's `window.sessionStorage` — the mutating
     * companion to {@link getSessionStorage}.
     */
    setSessionStorage(key: string, value: string): Promise<void>;
    /**
     * Removes a single key from `window.localStorage` (no-op when absent —
     * native `removeItem` contract). Use to clear one piece of persisted state
     * without disturbing the rest.
     */
    removeLocalStorage(key: string): Promise<void>;
    /**
     * Removes a single key from `window.sessionStorage` (no-op when absent —
     * native `removeItem` contract).
     */
    removeSessionStorage(key: string): Promise<void>;
    /**
     * Removes every key from `window.localStorage` (native `clear` contract).
     * Use to reset persisted state between phases of a test.
     */
    clearLocalStorage(): Promise<void>;
    /**
     * Removes every key from `window.sessionStorage` (native `clear` contract).
     */
    clearSessionStorage(): Promise<void>;
    /**
     * Extracts text content or attribute values from all elements matching the locator.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param getAllOptions - Optional extraction configuration.
     * @param options - Optional step options for element resolution.
     * @returns An array of extracted strings.
     */
    getAll(elementName: string, pageName: string, getAllOptions?: GetAllOptions, options?: StepOptions): Promise<string[]>;
    /**
     * Asserts that the element is present and visible in the DOM.
     *
     * Equivalent to the fluent form `steps.on(elementName, pageName).verifyPresence()` —
     * both share the same underlying implementation (the matcher tree). Use whichever
     * form is more readable in the call site.
     *
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param options - Optional step options for element resolution.
     */
    verifyPresence(elementName: string, pageName: string, options?: StepOptions): Promise<void>;
    /**
     * Asserts that every element in the list is visible in the DOM, running all
     * checks concurrently. Equivalent to calling `verifyPresence` for each entry
     * inside a `Promise.all`, but with a single log line and no boilerplate.
     *
     * Use this when a test needs to assert the presence of many independent
     * elements on the same already-loaded page — the parallel resolution
     * removes the per-step serial overhead without changing the underlying
     * assertion semantics.
     *
     * @param targets - Array of `{ elementName, pageName, options? }` descriptors.
     * @example
     * await steps.verifyAllPresent([
     *   { elementName: 'productTitle', pageName: 'ProductDetailsPage' },
     *   { elementName: 'productPrice', pageName: 'ProductDetailsPage' },
     *   { elementName: 'addToCart',    pageName: 'ProductDetailsPage' },
     * ]);
     */
    verifyAllPresent(targets: Array<{
        elementName: string;
        pageName: string;
        options?: StepOptions;
    }>): Promise<void>;
    /**
     * Checks whether an element is currently present and visible in the DOM.
     * Returns a boolean instead of throwing.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param options - Optional step options for element resolution.
     * @returns `true` if the element is visible, `false` otherwise.
     */
    isPresent(elementName: string, pageName: string, options?: StepOptions): Promise<boolean>;
    /**
     * Unified visibility entry point. Returns a `VisibleChain` that is both:
     *
     * - **awaitable as `Promise<boolean>`** — the probe, never throws. Backwards
     *   compatible with the old `isVisible(): Promise<boolean>` signature —
     *   `await steps.isVisible('banner', 'Page', { timeout: 500 })` still
     *   resolves to a boolean at runtime.
     * - **chainable with action methods and the matcher tree** — the gate,
     *   silently skips when the element is hidden. Replaces `steps.on(...).ifVisible()`.
     *
     * Every probe and gate decision is logged under `tester:visible` with a
     * `[probe]` or `[gate]` tag so silently-skipped actions stay debuggable.
     *
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param options - `{ timeout?: 2000, containsText?: string }`.
     *
     * @example
     * ```ts
     * // Probe — returns boolean
     * const ok = await steps.isVisible('banner', 'Page', { timeout: 500 });
     *
     * // Gate — skips when hidden
     * await steps.isVisible('cookieBanner', 'Page').click();
     *
     * // Gate + containsText
     * await steps.isVisible('promo', 'Page', { containsText: '50% off' }).click();
     *
     * // Matcher tree — silently skipped when hidden
     * await steps.isVisible('banner', 'Page').text.toBe('Hello');
     * ```
     */
    isVisible(elementName: string, pageName: string, options?: IsVisibleOptions): import("./VisibleChain").VisibleChain;
    /**
     * Asserts that the element is not present in the DOM.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param options - Optional step options (strategy not applicable for absence checks).
     */
    verifyAbsence(elementName: string, pageName: string, options?: StepOptions): Promise<void>;
    /**
     * Asserts that an element's text content matches the expected value.
     *
     * Call with no `expectedText` to assert the element has any non-empty text:
     * `await steps.verifyText('status', 'Page');`
     *
     * Equivalent to the fluent form `steps.on(elementName, pageName).verifyText(expectedText)`.
     *
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param expectedText - The exact text to match against. Omit to assert "not empty".
     * @param verifyOptions - Optional verification options. Passing `{ notEmpty: true }`
     *   is redundant — omit `expectedText` to get the same behavior. The `notEmpty`
     *   flag on `TextVerifyOptions` is itself deprecated.
     * @param options - Optional step options for element resolution.
     */
    verifyText(elementName: string, pageName: string, expectedText?: string, verifyOptions?: TextVerifyOptions, options?: StepOptions): Promise<void>;
    /**
     * Asserts the number of elements matching the locator satisfies the given condition.
     *
     * Equivalent to `steps.on(elementName, pageName).verifyCount(countOptions)`.
     *
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param countOptions - Count condition.
     * @param options - Optional step options for element resolution.
     */
    verifyCount(elementName: string, pageName: string, countOptions: CountVerifyOptions, options?: StepOptions): Promise<void>;
    /**
     * Asserts that all image elements matching the locator have loaded successfully.
     *
     * Equivalent to `steps.on(elementName, pageName).verifyImages(scroll, options)`.
     *
     * By default checks visibility, `src` attribute, and non-zero `naturalWidth`.
     * Pass `{ verifyDecoded: true }` to also run `Image.decode()` per image —
     * this adds a CDP round-trip per image and is most useful for thoroughness testing
     * rather than smoke checks.
     *
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param scroll - Whether to scroll each image into view before checking. Defaults to `true`.
     * @param options - Step options for element resolution, plus `verifyDecoded` to run `Image.decode()` per image.
     */
    verifyImages(elementName: string, pageName: string, scroll?: boolean, options?: StepOptions & {
        verifyDecoded?: boolean;
    }): Promise<void>;
    /**
     * Asserts that an element's text content contains the specified substring.
     *
     * Equivalent to `steps.on(elementName, pageName).verifyTextContains(expectedText)`.
     *
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param expectedText - The substring expected to be found within the element's text.
     * @param options - Optional step options for element resolution.
     */
    verifyTextContains(elementName: string, pageName: string, expectedText: string, options?: StepOptions): Promise<void>;
    /**
     * Asserts that an element is in the specified state.
     *
     * Equivalent to `steps.on(elementName, pageName).verifyState(state)`.
     *
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param state - The expected state.
     * @param timeout - Optional timeout in milliseconds. When omitted, the fixture default is used.
     */
    verifyState(elementName: string, pageName: string, state: 'enabled' | 'disabled' | 'editable' | 'checked' | 'focused' | 'visible' | 'hidden' | 'attached' | 'inViewport', timeout?: number): Promise<void>;
    /**
     * Asserts that an element has a specific HTML attribute with the expected value.
     *
     * Equivalent to `steps.on(elementName, pageName).verifyAttribute(attributeName, expectedValue)`.
     *
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param attributeName - The name of the HTML attribute to check.
     * @param expectedValue - The expected value of the attribute.
     * @param options - Optional step options for element resolution.
     */
    verifyAttribute(elementName: string, pageName: string, attributeName: string, expectedValue: string, options?: StepOptions): Promise<void>;
    /**
     * Asserts that an element's HTML equals the expected string exactly.
     * Defaults to `innerHTML`; pass `{ outer: true }` for `outerHTML`.
     *
     * Equivalent to `steps.on(elementName, pageName).verifyHtml(expected, htmlOptions)`.
     *
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param expected - The expected HTML string.
     * @param htmlOptions - `outer` switches between innerHTML/outerHTML.
     * @param options - Optional step options for element resolution.
     */
    verifyHtml(elementName: string, pageName: string, expected: string, htmlOptions?: {
        outer?: boolean;
    }, options?: StepOptions): Promise<void>;
    /**
     * Asserts that an element's HTML contains the specified substring.
     * Defaults to `innerHTML`; pass `{ outer: true }` for `outerHTML`.
     *
     * Equivalent to `steps.on(elementName, pageName).verifyHtmlContains(substring, htmlOptions)`.
     *
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param substring - The substring expected to appear in the element's HTML.
     * @param htmlOptions - `outer` switches between innerHTML/outerHTML.
     * @param options - Optional step options for element resolution.
     */
    verifyHtmlContains(elementName: string, pageName: string, substring: string, htmlOptions?: {
        outer?: boolean;
    }, options?: StepOptions): Promise<void>;
    /**
     * Asserts that an element's HTML matches a regular expression.
     * Defaults to `innerHTML`; pass `{ outer: true }` for `outerHTML`.
     *
     * Equivalent to `steps.on(elementName, pageName).verifyHtmlMatches(regex, htmlOptions)`.
     */
    verifyHtmlMatches(elementName: string, pageName: string, regex: RegExp, htmlOptions?: {
        outer?: boolean;
    }, options?: StepOptions): Promise<void>;
    /**
     * Asserts that the page-level HTML equals the expected string exactly.
     * Defaults to `document.body.innerHTML`; pass `{ outer: true }` for the full
     * `<html>` document outerHTML.
     *
     * @param expected - The expected HTML string.
     * @param options - `outer` switches between body.innerHTML / documentElement.outerHTML;
     *   `negated` flips the assertion; `timeout` overrides the default; `errorMessage` adds a header.
     */
    verifyPageHtml(expected: string, options?: {
        outer?: boolean;
        negated?: boolean;
        timeout?: number;
        errorMessage?: string;
    }): Promise<void>;
    /**
     * Asserts that the page-level HTML contains the specified substring.
     * Defaults to `document.body.innerHTML`; pass `{ outer: true }` for the full document outerHTML.
     *
     * Use this to confirm an injected payload appears unescaped (`negated: false`)
     * or was correctly escaped (`negated: true`) anywhere on the rendered page.
     *
     * @example
     * ```ts
     * // XSS probe — payload must NOT appear raw in rendered HTML
     * await steps.verifyPageHtmlContains('<img src=x onerror=alert(1)>', { negated: true });
     * ```
     */
    verifyPageHtmlContains(substring: string, options?: {
        outer?: boolean;
        negated?: boolean;
        timeout?: number;
        errorMessage?: string;
    }): Promise<void>;
    /**
     * Asserts that the page-level HTML matches a regular expression.
     * Defaults to `document.body.innerHTML`; pass `{ outer: true }` for the full document outerHTML.
     */
    verifyPageHtmlMatches(regex: RegExp, options?: {
        outer?: boolean;
        negated?: boolean;
        timeout?: number;
        errorMessage?: string;
    }): Promise<void>;
    /**
     * Asserts a property of `localStorage[key]`. Pick one matcher: `equals`
     * (exact match), `contains` (substring), `matches` (regex), or `present`
     * (existence). The chosen matcher is enforced at the type level by the
     * `StorageVerifyOptions` discriminated union — passing two is a type error.
     *
     * Polls until the predicate holds or the timeout expires, so this survives
     * the race between a UI action firing and its persistence side-effect.
     *
     * @example
     * ```ts
     * await steps.verifyLocalStorage('theme', { equals: 'dark' });
     * await steps.verifyLocalStorage('flag', { contains: 'enabled' });
     * await steps.verifyLocalStorage('build', { matches: /^v\d+$/ });
     * await steps.verifyLocalStorage('seen', { present: true });
     * await steps.verifyLocalStorage('seen', { present: false });          // absence
     * await steps.verifyLocalStorage('seen', { present: true, negated: true });  // same
     * ```
     */
    verifyLocalStorage(key: string, options: StorageVerifyOptions): Promise<void>;
    /** See `verifyLocalStorage` — same matcher shape, against `window.sessionStorage`. */
    verifySessionStorage(key: string, options: StorageVerifyOptions): Promise<void>;
    /** Single dispatcher for `verifyLocalStorage` / `verifySessionStorage`. */
    private verifyStorage;
    /**
     * Retrying assertion over a `window`-level value read by dotted path. Pick
     * EXACTLY ONE matcher in the `WindowVerifyOptions` union: `equals` |
     * `contains` | `matches` (RegExp) | `present` (boolean) | `truthy` (boolean)
     * | `greaterThan` | `lessThan`. Supports `{ negated?, timeout?, errorMessage? }`
     * modifiers, exactly like the storage verifiers. Polls until the predicate
     * holds (or its negation) or the timeout expires.
     *
     * @example
     * ```ts
     * await steps.verifyWindowProperty('dataLayer.length', { greaterThan: 0 });
     * await steps.verifyWindowProperty('__test.flag', { equals: true });
     * await steps.verifyWindowProperty('__XSS_FIRED', { present: false });
     * await steps.verifyWindowProperty('document.title', { matches: /Vue/i });
     * ```
     */
    verifyWindowProperty(path: string, options: WindowVerifyOptions): Promise<void>;
    /** Session-aware `GET`. Shares the browser context's cookies. */
    requestGet(url: string, opts?: BrowserRequestOptions): Promise<BrowserResponse>;
    /** Session-aware `POST`. Shares the browser context's cookies. */
    requestPost(url: string, opts?: BrowserRequestOptions): Promise<BrowserResponse>;
    /** Session-aware `PUT`. Shares the browser context's cookies. */
    requestPut(url: string, opts?: BrowserRequestOptions): Promise<BrowserResponse>;
    /** Session-aware `PATCH`. Shares the browser context's cookies. */
    requestPatch(url: string, opts?: BrowserRequestOptions): Promise<BrowserResponse>;
    /** Session-aware `DELETE`. Shares the browser context's cookies. */
    requestDelete(url: string, opts?: BrowserRequestOptions): Promise<BrowserResponse>;
    /** Session-aware `HEAD`. Shares the browser context's cookies. */
    requestHead(url: string, opts?: BrowserRequestOptions): Promise<BrowserResponse>;
    /**
     * Asserts a {@link BrowserResponse}'s status equals `code`. Simple throw
     * helper — not a retrying assertion (the response is already resolved).
     */
    verifyRequestStatus(res: BrowserResponse, code: number): Promise<void>;
    /**
     * Asserts a {@link BrowserResponse} carries a header. Name match is
     * case-insensitive (header names are, per RFC 9110). When `value` is
     * omitted, asserts presence only; a string asserts exact equality —
     * header VALUES are case-sensitive (ETags, redirect Location paths,
     * nonces), matching `verifyApiHeader`; use a RegExp with the `i` flag
     * for case-insensitive matching.
     */
    verifyRequestHeader(res: BrowserResponse, name: string, value?: string | RegExp): Promise<void>;
    /** Asserts a {@link BrowserResponse} is a 2xx success. Simple throw helper. */
    verifyRequestOk(res: BrowserResponse): Promise<void>;
    /**
     * Asserts that the current page URL contains the specified substring.
     * @param text - The substring expected to be found in the current URL.
     */
    verifyUrlContains(text: string): Promise<void>;
    /**
     * Asserts the document body contains the given text — the page-level mirror
     * of {@link verifyTextContains}. Accepts a substring or a RegExp and retries
     * with web-first semantics until the body matches or the timeout expires.
     *
     * Use for page-wide copy checks where no single element is the natural scope
     * (a flash message anywhere on the page, a "404 / niet gevonden" body, etc.).
     *
     * @param text - Substring or RegExp expected somewhere in the rendered body text.
     * @param options - `{ timeout?, errorMessage? }`.
     * @example
     * ```ts
     * await steps.verifyPageContainsText('Wishlist');
     * await steps.verifyPageContainsText(/404|niet gevonden/i);
     * ```
     */
    verifyPageContainsText(text: string | RegExp, options?: {
        timeout?: number;
        errorMessage?: string;
    }): Promise<void>;
    /**
     * Asserts the document body does NOT contain the given text — the negated
     * companion to {@link verifyPageContainsText}. Use for "not a 404" /
     * no-error-copy body checks.
     *
     * NOTE: this is a TEXT-level check (`toContainText` reads rendered text),
     * so it can never see raw markup — injected `<script>` that executes does
     * not appear in the body text, while inert, escaped markup DOES show up as
     * text. For markup-level assertions use
     * {@link verifyPageHtmlContains} with `{ negated: true }`.
     *
     * @param text - Substring or RegExp expected to be absent from the body text.
     * @param options - `{ timeout?, errorMessage? }`.
     * @example
     * ```ts
     * await steps.verifyPageNotContainsText(/page not found/i);
     * await steps.verifyPageNotContainsText(/server error/i);
     * ```
     */
    verifyPageNotContainsText(text: string | RegExp, options?: {
        timeout?: number;
        errorMessage?: string;
    }): Promise<void>;
    /**
     * Asserts the page `<title>` equals the given string or matches the RegExp.
     * Wraps Playwright's `expect(page).toHaveTitle`.
     *
     * @param title - Exact title string or a RegExp the title must match.
     * @param options - `{ timeout?, errorMessage? }`.
     * @example
     * ```ts
     * await steps.verifyPageTitle('Dashboard');
     * await steps.verifyPageTitle(/Wishlist/i);
     * ```
     */
    verifyPageTitle(title: string | RegExp, options?: {
        timeout?: number;
        errorMessage?: string;
    }): Promise<void>;
    /**
     * Asserts that an input, textarea, or select element has the expected value.
     *
     * Equivalent to `steps.on(elementName, pageName).verifyInputValue(expectedValue)`.
     *
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param expectedValue - The expected value of the input.
     * @param options - Optional step options for element resolution.
     */
    verifyInputValue(elementName: string, pageName: string, expectedValue: string, options?: StepOptions): Promise<void>;
    /**
     * Asserts the number of open browser tabs/pages matches the expected count.
     * @param expectedCount - The expected number of open tabs.
     */
    verifyTabCount(expectedCount: number): Promise<void>;
    /**
     * Entry point for the matcher tree. Resolves the named element and returns
     * an `ExpectBuilder` that exposes field-scoped matchers (`.text`, `.value`,
     * `.attributes`, `.count`, `.visible`, `.enabled`, `.css(prop)`, `.not`)
     * plus the predicate escape hatch `.satisfy(predicate)` for assertions the
     * matcher tree doesn't cover.
     *
     * @example
     * // Matcher tree
     * await steps.expect('price', 'ProductPage').text.toBe('$19.99');
     * await steps.expect('items', 'ListPage').count.toBeGreaterThan(3);
     * await steps.expect('link', 'Page').attributes.get('href').toBe('/x');
     * await steps.expect('error', 'Page').not.text.toContain('crash');
     *
     * // Predicate chain — assertion executes when awaited
     * await steps.expect('price', 'ProductPage')
     *   .satisfy(el => parseFloat(el.text.slice(1)) > 10)
     *   .throws('price must be above $10');
     */
    expect(elementName: string, pageName: string): ExpectBuilder;
    /**
     * Asserts that the text contents of all elements matching the locator appear
     * in the exact order specified.
     *
     * Equivalent to `steps.on(elementName, pageName).verifyOrder(expectedTexts)`.
     *
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param expectedTexts - The expected text values in their expected order.
     * @param options - Optional step options for element resolution.
     */
    verifyOrder(elementName: string, pageName: string, expectedTexts: string[], options?: StepOptions): Promise<void>;
    /**
     * Asserts that a computed CSS property of an element matches the expected value.
     *
     * Equivalent to `steps.on(elementName, pageName).verifyCssProperty(property, expectedValue)`.
     *
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param property - The CSS property name.
     * @param expectedValue - The expected computed value.
     * @param options - Optional step options for element resolution.
     */
    verifyCssProperty(elementName: string, pageName: string, property: string, expectedValue: string, options?: StepOptions): Promise<void>;
    /**
     * Asserts that the text contents of all elements matching the locator are sorted
     * in the specified direction.
     *
     * Equivalent to `steps.on(elementName, pageName).verifyListOrder(direction)`.
     *
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param direction - `'asc'` for ascending or `'desc'` for descending.
     * @param options - Optional step options for element resolution.
     */
    verifyListOrder(elementName: string, pageName: string, direction: 'asc' | 'desc', options?: StepOptions): Promise<void>;
    /**
     * Clicks a specific element within a list identified by its visible text or an HTML attribute.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param options - Match criteria.
     */
    clickListedElement(elementName: string, pageName: string, options: ListedElementMatch): Promise<void>;
    /**
     * Verifies a specific element within a list.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param options - Match and assertion criteria.
     */
    verifyListedElement(elementName: string, pageName: string, options: VerifyListedOptions): Promise<void>;
    /**
     * Extracts data from a specific element within a list.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param options - Match and extraction criteria.
     * @returns The extracted text content or attribute value, or `null`.
     */
    getListedElementData(elementName: string, pageName: string, options: GetListedDataOptions): Promise<string | null>;
    /**
     * Waits for an element to reach the specified state before proceeding.
     * Throws on timeout as of 0.3.7; pass `{ optional: true }` to probe
     * without failing (resolves `false` instead).
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param state - The desired state to wait for.
     * @param options - Optional step options: element resolution, `timeout` (per-call override), `optional` (soft probe).
     * @returns `true` when the state was reached; `false` only when `optional` and the wait timed out.
     */
    waitForState(elementName: string, pageName: string, state?: 'visible' | 'attached' | 'hidden' | 'detached', options?: StepOptions): Promise<boolean>;
    /**
     * Waits for an element to reach a specific state, then clicks it.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param state - The state to wait for before clicking. Defaults to `'visible'`.
     * @param options - Optional step options for element resolution.
     */
    waitAndClick(elementName: string, pageName: string, state?: 'visible' | 'attached' | 'hidden' | 'detached', options?: StepOptions): Promise<void>;
    /**
     * Clicks the element at a specific zero-based index from all elements matching the locator.
     * @param elementName - The element name as defined under the given page.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param index - The zero-based index of the element to click.
     * @throws Error if no element exists at the specified index.
     */
    clickNth(elementName: string, pageName: string, index: number): Promise<void>;
    /**
     * Fills multiple form fields on the same page in a single call.
     * @param pageName - The page name as defined in `page-repository.json`.
     * @param fields - A map of `elementName` to value.
     */
    fillForm(pageName: string, fields: Record<string, FillFormValue>): Promise<void>;
    /**
     * Waits until there are no in-flight network requests for at least 500ms.
     * @param options - Optional `{ timeout, optional }`. `timeout` bounds the
     *   wait; `optional: true` resolves quietly on timeout instead of throwing
     *   (best-effort settling). With no options, behaviour is unchanged.
     */
    waitForNetworkIdle(options?: WaitForNetworkIdleOptions): Promise<void>;
    /**
     * Waits for the page to reach the given lifecycle `state`. The general
     * lifecycle-wait companion to {@link waitForNetworkIdle} (which is fixed to
     * `'networkidle'`): exposes `'load'` and `'domcontentloaded'` too. Use for a
     * standalone wait **after an action** that does not navigate — e.g. waiting
     * for `'domcontentloaded'` once a client-side view swap finishes.
     * @param state - `'load'`, `'domcontentloaded'`, or `'networkidle'`.
     * @param options - Optional `{ timeout }` bounding the wait.
     */
    waitForLoadState(state: LoadState, options?: {
        timeout?: number;
    }): Promise<void>;
    /**
     * Deliberate pause for `ms` milliseconds. Named `pace` — NOT `wait` — to
     * signal intentional timing control (settling a debounce, spacing
     * rapid-fire actions), never a substitute for a wait-for-state. Whenever you
     * are actually waiting for the app to reach a condition, prefer
     * {@link waitForState}, {@link waitForUrl}, or a web-first assertion.
     * @param ms - Pause duration in milliseconds (non-negative).
     */
    pace(ms: number): Promise<void>;
    /**
     * Runs `action` `times` times in sequence, passing the zero-based index, and
     * returns each result in order. With `intervalMs`, paces BETWEEN iterations
     * (never before the first or after the last). The intent-revealing form of a
     * hand-rolled "do X rapidly N times" loop — repeated swatch clicks,
     * double-submit probes, hammering a flaky toggle.
     *
     * @example
     * ```ts
     * await steps.repeat(i => steps.on('swatch', 'PDP').nth(i).click(), 3, { intervalMs: 120 });
     * ```
     * @param action - Callback run per iteration; receives the zero-based index.
     * @param times - Number of iterations (non-negative integer).
     * @param options - Optional `{ intervalMs }` pacing between iterations.
     * @returns The array of every iteration's resolved result, in order.
     */
    repeat<T>(action: (index: number) => Promise<T> | T, times: number, options?: {
        intervalMs?: number;
    }): Promise<T[]>;
    /**
     * Executes an action and waits for a matching network response to complete.
     * @param urlPattern - A string substring or RegExp to match against the response URL.
     * @param action - An async function that triggers the network request.
     * @returns The captured Playwright Response object.
     */
    waitForResponse(urlPattern: string | RegExp, action: () => Promise<void>): Promise<Response>;
    /**
     * Asserts that **no** network request matching `urlPattern` fires while
     * `action` runs (and for an observation window afterwards). Negative
     * companion to {@link waitForResponse}.
     *
     * Use to prove a client-side block — HTML5 `required`, native `type=email`
     * validation, custom JS guards — short-circuits before any XHR is issued.
     * URL-unchanged and cookie-unset surrogates prove the outcome; this
     * asserts the mechanism.
     *
     * Matching delegates to Playwright's own URL matcher (via `page.route`),
     * so strings are interpreted as **glob patterns** — same as
     * {@link waitForResponse}, not naive substrings. Reach for a RegExp when
     * you want a contains-style match.
     *
     * If `action` throws, the route handler is removed and the action's error
     * is propagated; the observation window is skipped and any matches
     * captured before the throw are discarded.
     *
     * **Secret-leak surface**: on failure, the offender URL is embedded
     * verbatim in the thrown error — which flows into runner output, reporter
     * artifacts, and Playwright traces (often uploaded as CI artifacts). If
     * your URLs carry secrets in query parameters, pass `{ redactQuery: true }`.
     *
     * @param urlPattern - Playwright glob string or RegExp matched against the request URL.
     * @param action - The action whose absence-of-request is being asserted.
     * @param options - `timeout` is the observation window after `action`
     *   resolves (default 1000ms). `methods` restricts to specific HTTP
     *   methods (e.g. `['POST']`) so a permitted GET preflight doesn't trip
     *   the assertion. `redactQuery` scrubs query strings from the failure
     *   message when offender URLs may carry secrets.
     *
     * @example
     * ```ts
     * // HTML5 required blocks submission — no XHR fires.
     * await steps.expectNoRequest(/\/api\/auth\/signup/, async () => {
     *   await steps.click('submitButton', 'SignupPage');
     * });
     *
     * // Restrict to POST so a permitted GET preflight doesn't trip.
     * await steps.expectNoRequest('**\/api/users', async () => {
     *   await steps.click('saveButton', 'ProfilePage');
     * }, { methods: ['POST'], timeout: 500 });
     *
     * // Scrub query strings from the failure message when URLs may
     * // carry tokens or API keys.
     * await steps.expectNoRequest('**\/api/signed', async () => {
     *   await steps.click('downloadButton', 'ReportsPage');
     * }, { redactQuery: true });
     * ```
     */
    expectNoRequest(urlPattern: string | RegExp, action: () => Promise<void>, options?: ExpectNoRequestOptions): Promise<void>;
    /**
     * Retries an action until a verification passes, or until the maximum number of
     * attempts is reached.
     * @param action - An async function performing the interaction.
     * @param verification - An async function performing the assertion. Must throw on failure.
     * @param maxRetries - Maximum number of retry attempts. Defaults to `3`.
     * @param delayMs - Milliseconds to wait between retry attempts. Defaults to `1000`.
     */
    retryUntil(action: () => Promise<void>, verification: () => Promise<void>, maxRetries?: number, delayMs?: number): Promise<void>;
    /**
     * Captures a screenshot of the full page or a specific element.
     * @param elementNameOrOptions - Either an element name string or `ScreenshotOptions`.
     * @param pageName - The page name (required when first arg is an element name).
     * @param options - Optional screenshot configuration.
     * @returns The screenshot image as a Buffer.
     */
    screenshot(elementNameOrOptions?: string | ScreenshotOptions, pageName?: string, options?: ScreenshotOptions): Promise<Buffer>;
    /**
     * Asserts the current page (or a named element) matches its stored
     * baseline screenshot. Dynamic regions — clocks, generated ids, live
     * counters, "updated N minutes ago" badges, avatars — can be masked
     * by name so the pixel diff stays stable across runs.
     *
     * Two call shapes:
     *
     *   // page-level
     *   await steps.verifyVisualMatch('dashboard.png', {
     *     mask: [
     *       { elementName: 'currentTime',   pageName: 'dashboard' },
     *       { elementName: 'transactionId', pageName: 'dashboard' },
     *     ],
     *   });
     *
     *   // element-level (scope = the named element)
     *   await steps.verifyVisualMatch('header.png', {
     *     elementName: 'header',
     *     pageName:    'dashboard',
     *     mask: [{ elementName: 'liveCounter', pageName: 'dashboard' }],
     *   });
     *
     * Mask entries may also use a raw selector when the masked region
     * isn't worth a ElementRepository entry:
     *
     *   mask: [{ selector: '[data-testid="current-time"]' }]
     *
     * Behaviour notes (inherited from Playwright's `toHaveScreenshot`):
     *   • CSS animations are disabled during the snapshot — no need to
     *     freeze them manually.
     *   • The first run writes the baseline; subsequent runs diff.
     *   • Masked regions are painted with a solid colour (pink by
     *     default) BEFORE the pixel diff, so dynamic content there
     *     doesn't fail the comparison.
     *
     * @param snapshotName  — baseline file name (e.g. `dashboard.png`).
     *                        Playwright derives OS/browser sub-paths.
     * @param options       — see {@link VisualMatchOptions}; the
     *                        `elementName`/`pageName` pair below is the
     *                        step-level extension over the lower-level
     *                        Verifications shape (which only knows
     *                        page vs element via its argument).
     */
    verifyVisualMatch(snapshotName: string, options?: VisualMatchOptions & {
        elementName?: string;
        pageName?: string;
    }): Promise<void>;
    /**
     * Resolve {@link VisualMaskTarget} entries to Playwright Locators.
     * `{ elementName, pageName }` entries are looked up through the
     * ElementRepository (the canonical, page-aware path); `{ selector }`
     * entries are passed straight to `page.locator`.
     */
    private resolveVisualMaskLocators;
    /**
     * Sends an email using the configured SMTP credentials.
     * @param options - The email configuration.
     */
    sendEmail(options: EmailSendOptions): Promise<void>;
    /**
     * Polls the inbox and returns the latest email matching the provided filters.
     * @param options - The receive options, including mandatory filters.
     * @returns The matched email.
     */
    receiveEmail(options: EmailReceiveOptions): Promise<ReceivedEmail>;
    /**
     * Polls the inbox and returns all emails matching the provided filters.
     * @param options - The receive options, including mandatory filters.
     * @returns An array of matched emails.
     */
    receiveAllEmails(options: EmailReceiveOptions): Promise<ReceivedEmail[]>;
    /**
     * Deletes emails from the inbox.
     * @param options - Optional receive options containing filters to target specific emails.
     */
    cleanEmails(options?: EmailReceiveOptions): Promise<number>;
    /**
     * Marks emails in the mailbox with a specific action.
     * @param action - The marking action to apply.
     * @param options - Optional options to target specific emails with filters.
     * @returns The number of emails successfully marked.
     */
    markEmail(action: EmailMarkAction | string[], options?: {
        filters?: EmailFilter[];
        folder?: string;
        archiveFolder?: string;
    }): Promise<number>;
    /**
     * Resolves the named `WasapiClient` from the internal registry. Defaults to
     * the `'default'` client (configured via `apiBaseUrl`). Named providers come
     * from `apiProviders` on the fixture options.
     */
    private getApiClient;
    /**
     * Issues an HTTP GET against the default API client, or the named provider
     * when the first argument matches a key in `apiProviders`.
     *
     * @example
     * ```ts
     * const res = await steps.apiGet<User>('/users/42');
     * const res = await steps.apiGet<User[]>('billing', '/users', { query: { active: 'true' } });
     * ```
     */
    apiGet<T>(pathOrProvider: string, pathOrOptions?: string | {
        query?: Record<string, string>;
        headers?: Record<string, string>;
    }, maybeOptions?: {
        query?: Record<string, string>;
        headers?: Record<string, string>;
    }): Promise<ApiResponse<T>>;
    /**
     * Issues an HTTP POST with an optional JSON body against the default API
     * client, or the named provider when the first argument matches a key in
     * `apiProviders`.
     */
    apiPost<T>(pathOrProvider: string, bodyOrPath?: unknown, optionsOrBody?: unknown, maybeOptions?: {
        pathParams?: Record<string, string>;
        query?: Record<string, string>;
        headers?: Record<string, string>;
    }): Promise<ApiResponse<T>>;
    /**
     * Issues an HTTP PUT with an optional JSON body against the default API
     * client, or the named provider when the first argument matches a key in
     * `apiProviders`.
     */
    apiPut<T>(pathOrProvider: string, bodyOrPath?: unknown, optionsOrBody?: unknown, maybeOptions?: {
        pathParams?: Record<string, string>;
        headers?: Record<string, string>;
    }): Promise<ApiResponse<T>>;
    /**
     * Issues an HTTP DELETE against the default API client, or the named
     * provider when the first argument matches a key in `apiProviders`.
     */
    apiDelete<T>(pathOrProvider: string, pathOrOptions?: string | {
        pathParams?: Record<string, string>;
        headers?: Record<string, string>;
    }, maybeOptions?: {
        pathParams?: Record<string, string>;
        headers?: Record<string, string>;
    }): Promise<ApiResponse<T>>;
    /**
     * Issues an HTTP PATCH with an optional JSON body against the default API
     * client, or the named provider when the first argument matches a key in
     * `apiProviders`.
     */
    apiPatch<T>(pathOrProvider: string, bodyOrPath?: unknown, optionsOrBody?: unknown, maybeOptions?: {
        pathParams?: Record<string, string>;
        headers?: Record<string, string>;
    }): Promise<ApiResponse<T>>;
    /**
     * Issues an HTTP HEAD and returns the response headers as a flat record.
     */
    apiHead(pathOrProvider: string, maybePath?: string): Promise<Record<string, string>>;
    private resolveApiArgs;
    private resolveApiArgsWithBody;
    /**
     * Asserts that an `ApiResponse` returned the expected HTTP status code.
     * Throws with the response body embedded on failure.
     */
    verifyApiStatus(response: ApiResponse<unknown>, expectedStatus: number): Promise<void>;
    /**
     * Asserts that an `ApiResponse` contains the given header (case-insensitive),
     * and optionally matches the expected value exactly.
     */
    verifyApiHeader(response: ApiResponse<unknown>, headerName: string, expectedValue?: string): Promise<void>;
    /**
     * Resolves the named `SqlClient` from the internal registry. Defaults to the
     * `'default'` client (configured via `dbUrl`). Named connections come from
     * `dbProviders` on the fixture options.
     */
    private getDbClient;
    /**
     * Splits `(sqlOrProvider, sql?, params?)` into a resolved client + sql + params.
     * If the second arg is a string, the first is treated as a provider name.
     */
    private resolveSqlArgs;
    /**
     * Runs a parametrised read query (SELECT) against the default SQL client, or
     * the named provider when the first argument matches a key in `dbProviders`.
     *
     * @example
     * ```ts
     * const res = await steps.sqlQuery<{ title: string }>('SELECT title FROM books WHERE genre = $1', ['Fiction']);
     * const res = await steps.sqlQuery('analytics', 'SELECT count(*) FROM orders');
     * ```
     */
    sqlQuery<T = Record<string, unknown>>(sqlOrProvider: string, sql?: string | unknown[], params?: unknown[]): Promise<SqlResult<T>>;
    /**
     * Runs a parametrised write statement (INSERT/UPDATE/DELETE) and returns the
     * affected `rowCount`. Same provider-overload as {@link sqlQuery}.
     */
    sqlExecute(sqlOrProvider: string, sql?: string | unknown[], params?: unknown[]): Promise<SqlResult>;
    /**
     * Runs `fn` inside a transaction (BEGIN/COMMIT, auto-ROLLBACK on throw).
     * Pass a provider name as the first argument to target a named connection:
     * `steps.sqlTransaction('analytics', async (tx) => { ... })`.
     */
    sqlTransaction<R>(fnOrProvider: string | ((tx: import('@civitas-cerebrum/sql-client').SqlTransaction) => Promise<R>), fn?: (tx: import('@civitas-cerebrum/sql-client').SqlTransaction) => Promise<R>): Promise<R>;
    /**
     * Connectivity probe against the default (or named) SQL client — runs the
     * engine-correct `SELECT 1` and throws if the database is unreachable. Use in
     * a Playwright `globalSetup` so a misconfigured `dbUrl` fails the run up front
     * with a clear error instead of a hung first query.
     */
    sqlPing(provider?: string): Promise<void>;
    /**
     * Execute a multi-statement SQL script (schema/seed file) against the default
     * or named client. The script is split with the engine's rules (Oracle `/`,
     * SQL Server `GO`, comment/quote aware) and each statement runs in order.
     * Provider-overloaded like {@link sqlQuery}:
     * `steps.sqlScript(readFileSync('seed.sql','utf8'))` or
     * `steps.sqlScript('analytics', schemaSql)`.
     */
    sqlScript(sqlTextOrProvider: string, maybeSqlText?: string): Promise<void>;
    /** Begin a fluent SELECT builder pre-bound to the default (or named) client. */
    sqlSelect(table: string, provider?: string): QueryBuilder & {
        run<T = Record<string, unknown>>(): Promise<SqlResult<T>>;
    };
    /** Begin a fluent INSERT builder. Call `.values({...}).run()`. */
    sqlInsert(table: string, provider?: string): QueryBuilder & {
        run<T = Record<string, unknown>>(): Promise<SqlResult<T>>;
    };
    /** Begin a fluent UPDATE builder. Call `.set({...}).where(...).run()`. */
    sqlUpdate(table: string, provider?: string): QueryBuilder & {
        run<T = Record<string, unknown>>(): Promise<SqlResult<T>>;
    };
    /** Begin a fluent DELETE builder. Call `.where(...).run()`. */
    sqlDelete(table: string, provider?: string): QueryBuilder & {
        run<T = Record<string, unknown>>(): Promise<SqlResult<T>>;
    };
    /**
     * Rebinds a builder's `.run()` so the test author needs no client argument:
     * `.run()` dispatches through the resolved SqlClient.
     */
    private bindBuilder;
    /** Closes all open SQL connection pools. Called by the fixture in teardown. Safe to call more than once. */
    closeDbConnections(): Promise<void>;
    /** Asserts the result row count equals `expected`, or falls within `{min,max}`. */
    verifySqlRowCount(result: SqlResult<unknown>, expected: number | {
        min?: number;
        max?: number;
    }): Promise<void>;
    /** Asserts a single cell at `rowIndex`/`column` equals `expected` (loose `==` after String()). */
    verifySqlValue(result: SqlResult<Record<string, unknown>>, rowIndex: number, column: string, expected: unknown): Promise<void>;
    /** Asserts at least one row matches every column/value pair in `partialRow`. */
    verifySqlContains(result: SqlResult<Record<string, unknown>>, partialRow: Record<string, unknown>): Promise<void>;
    /** Asserts the ordered values of `column` across all rows equal `expected`. */
    verifySqlColumn(result: SqlResult<Record<string, unknown>>, column: string, expected: unknown[]): Promise<void>;
    /** Asserts the result has zero rows. */
    verifySqlEmpty(result: SqlResult<unknown>): Promise<void>;
    /** Asserts the result has at least one row. */
    verifySqlNotEmpty(result: SqlResult<unknown>): Promise<void>;
}