/**
 * The role locator reflects how users and assistive technology perceive the page,
 * for example whether some element is a button or a checkbox.
 * When locating by role, you should usually pass the accessible name as well,
 * so that the locator pinpoints the exact element.
 */
export interface QueryByRole {
    /**
     * The role to use to locate the element. Only values from the [WAI-ARIA
     * Roles list](https://www.w3.org/TR/wai-aria-1.2/#roles) are allowed.
     */
    role: string;
}
/**
 * Most form controls usually have dedicated labels that could be conveniently used
 * to interact with the form. In this case, you can locate the control by its associated label
 * using the `label` locator strategy.
 */
export interface QueryByLabel {
    /**
     * The accessible name to use to locate the element. This should be the text content of the label.
     */
    label: string;
}
/**
 * Inputs may have a placeholder attribute to hint to the user what value should be entered.
 * You can locate such an input using the `placeholder` locator strategy.
 */
export interface QueryByPlaceholder {
    /**
     * The placeholder text to use to locate the element. This should be the text content of the placeholder.
     */
    placeholder: string;
}
/**
 * Find an element by the text it contains. You can match by a substring,
 * exact string, or a regular expression when using the `text` locator strategy.
 */
export interface QueryByText {
    /**
     * The text to use to locate the element.
     */
    text: string;
}
/**
 * All images should have an alt attribute that describes the image.
 * You can locate an image based on the text alternative using the `altText` locator strategy.
 */
export interface QueryByAltText {
    /**
     * The alt text to use to locate the element. This should be the text content of the alt attribute.
     */
    altText: string;
}
/**
 * Locate an element with a matching title attribute using the `title` locator strategy.
 */
export interface QueryByTitle {
    /**
     * The title text to use to locate the element. This should be the text content of the title attribute.
     */
    title: string;
}
/**
 * Use this locator to find elements by their data-testid attribute.
 */
export interface QueryByTestId {
    /**
     * The test id to use to locate the element. This should be the text content of the test id attribute.
     */
    testId: string;
}
/**
 * Use this locator to find elements by their CSS selector.
 */
export interface QueryByCss {
    /**
     * The CSS selector to use to locate the element.
     */
    css: string;
}
/**
 * Use this locator to find elements by their XPath.
 */
export interface QueryByXPath {
    /**
     * The XPath to use to locate the element.
     */
    xpath: string;
}
/**
 * Set of supported locator queries.
 */
export type LocatorQuery = QueryByRole | QueryByText | QueryByLabel | QueryByPlaceholder | QueryByText | QueryByAltText | QueryByTitle | QueryByTestId | QueryByCss | QueryByXPath;
/**
 * Set of supported locator actions.
 */
export type SupportedLocatorAction = 'blur' | 'clear' | 'check' | 'click' | 'dblclick' | 'fill' | 'hover' | 'press' | 'pressSequentially' | 'tap' | 'uncheck' | 'dragTo' | 'selectOption' | 'screenshot' | 'setInputFiles';
/**
 * Payload for locator actions.
 * Used internally by the runner to execute locator actions.
 */
export interface LocatorActionPayload {
    /**
     * The action to perform on the element.
     */
    action: SupportedLocatorAction;
    /**
     * The query to use to locate the element.
     */
    query: LocatorQuery;
    /**
     * Additional arguments for the action.
     */
    args?: unknown;
}
/**
 * Options that can be passed to locator actions.
 */
export interface TimeoutOption {
    /**
     * Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `actionTimeout`
     * option in the config, or by using the
     * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout)
     * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
     */
    timeout?: number;
}
/**
 * Options that can be passed to locator actions.
 */
export interface ForceOption {
    /**
     * Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
     */
    force?: boolean;
}
/**
 * Options that can be passed to locator actions.
 */
export interface StrictOption {
    /**
     * When true, the call requires selector to resolve to a single element. If given selector resolves to more than one
     * element, the call throws an exception.
     */
    strict?: boolean;
}
/**
 * Options that can be passed to locator actions.
 */
export interface TrialOption {
    /**
     * When set, this method only performs the [actionability](https://playwright.dev/docs/actionability) checks and skips the action. Defaults
     * to `false`. Useful to wait until the element is ready for the action without performing it.
     */
    trial?: boolean;
}
/**
 * Options that can be passed to locator actions.
 */
export interface ModifiersOption {
    /**
     * Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores
     * current modifiers back. If not specified, currently pressed modifiers are used. "ControlOrMeta" resolves to
     * "Control" on Windows and Linux and to "Meta" on macOS.
     */
    modifiers?: ('Alt' | 'Control' | 'ControlOrMeta' | 'Meta' | 'Shift')[];
}
/**
 * Options that can be passed to locator actions.
 */
export interface PositionOption {
    /**
     * A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
     * the element.
     */
    position?: {
        /**
         * X coordinate
         */
        x: number;
        /**
         * Y coordinate
         */
        y: number;
    };
}
/**
 * Options for the blur action.
 */
export interface BlurOptions extends TimeoutOption {
}
/**
 * Options for the clear action.
 */
export interface ClearOptions extends TimeoutOption, ForceOption {
}
export interface ClickOptions extends TimeoutOption, ForceOption, StrictOption, TrialOption, ModifiersOption, PositionOption {
    /**
     * Defaults to `left`.
     */
    button?: 'left' | 'right' | 'middle';
    /**
     * defaults to 1. See [UIEvent.detail].
     */
    clickCount?: number;
    /**
     * Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
     */
    delay?: number;
}
/**
 * Options for the check action.
 */
export interface CheckOptions extends TimeoutOption, ForceOption, StrictOption, TrialOption, PositionOption {
}
/**
 * Options for the fill action.
 */
export interface FillOptions extends TimeoutOption, ForceOption, StrictOption {
}
/**
 * Options for the type action.
 */
export interface TypeOptions extends TimeoutOption, ForceOption, ModifiersOption {
    /**
     * Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0.
     */
    delay?: number;
}
/**
 * Options for the pressSequentially action.
 */
export interface PressSequentiallyOptions extends TimeoutOption {
    /**
     * Time to wait between key presses in milliseconds. Defaults to 0.
     */
    delay?: number;
    /**
     * Actions that initiate navigations are waiting for the navigation to finish and to return its result.
     */
    noWaitAfter?: boolean;
}
/**
 * Options for the double click action.
 */
export interface DoubleClickOptions extends TimeoutOption, ForceOption, TrialOption, ModifiersOption, PositionOption {
    /**
     * Defaults to `left`.
     */
    button?: 'left' | 'right' | 'middle';
    /**
     * Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
     */
    delay?: number;
    /**
     * Defaults to 1. Sends `n` interpolated `mousemove` events to represent travel between Playwright's current cursor
     * position and the provided destination. When set to 1, emits a single `mousemove` event at the destination location.
     */
    steps?: number;
}
/**
 * Options for the hover action.
 */
export interface HoverOptions extends TimeoutOption, ForceOption, TrialOption, ModifiersOption, PositionOption {
}
/**
 * Options for the press action.
 */
export interface PressOptions extends TimeoutOption {
    /**
     * Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0.
     */
    delay?: number;
}
/**
 * Options for the tap action.
 */
export interface TapOptions extends TimeoutOption, ForceOption, TrialOption, ModifiersOption, PositionOption {
}
/**
 * Options for the uncheck action.
 */
export interface UncheckOptions extends TimeoutOption, ForceOption, TrialOption, PositionOption {
}
/**
 * Options for the dragTo action.
 */
export interface DragToOptions extends TimeoutOption, ForceOption, TrialOption {
    /**
     * A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
     * the element.
     */
    sourcePosition?: {
        /**
         * X coordinate
         */
        x: number;
        /**
         * Y coordinate
         */
        y: number;
    };
    /**
     * A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of
     * the element.
     */
    targetPosition?: {
        /**
         * X coordinate
         */
        x: number;
        /**
         * Y coordinate
         */
        y: number;
    };
}
/**
 * Representation of option selection values for matching options.
 */
export type SelectOptionValue = string | {
    value?: string;
    label?: string;
    index?: number;
};
/**
 * Values to select in the element. Can be a single value, an array of values, or null.
 */
export type SelectOptionValues = SelectOptionValue | SelectOptionValue[] | null;
/**
 * Options for the selectOption action.
 */
export interface SelectOptionOptions extends TimeoutOption, ForceOption {
}
/**
 * Options for the screenshot action on a locator.
 */
export interface ElementScreenshotOptions {
    /**
     * The file path to save the screenshot to.
     */
    path: string;
    /**
     * The image format. Defaults to 'png'.
     */
    type?: 'png' | 'jpeg';
    /**
     * The quality of the image, between 0-100. Only for jpeg.
     */
    quality?: number;
    /**
     * Hides default white background and allows capturing screenshots with transparency.
     */
    omitBackground?: boolean;
    /**
     * Maximum time in milliseconds. Defaults to 30000.
     */
    timeout?: number;
}
/**
 * Options for the setInputFiles action on a locator.
 */
export interface SetInputFilesOptions extends TimeoutOption {
    /**
     * Actions that initiate navigations are waiting for the navigation to finish and to return its result.
     */
    noWaitAfter?: boolean;
}
/**
 * Creates a locator that can execute multiple actions like click, type, etc.
 * It interacts with the Playwright's Page object, but via RPC calls.
 *
 * @example Clicking on a button with text "Submit".
 * ```typescript
 * import { query } from '@pawel-up/lupa/commands'
 *
 * await query({ text: 'Submit' }).click()
 * ```
 *
 * @example Checking a checkbox with label "Subscribe".
 * ```typescript
 * import { query } from '@pawel-up/lupa/commands'
 *
 * await query({ label: 'Subscribe' }).check()
 * ```
 *
 * @example Filling a text input with "admin" username.
 * ```typescript
 * import { query } from '@pawel-up/lupa/commands'
 *
 * await query({ placeholder: 'Username' }).fill('admin')
 * ```
 *
 * @param query - The query to use to locate the element.
 * @returns A locator.
 */
export declare function query(query: LocatorQuery): Locator;
/**
 * A bridge to Playwright's Locator object, used to locate elements on the page
 * and execute actions on them. It uses RPC calls to interact with the Playwright's Page object.
 *
 * Not all Playwright's Locator actions are supported. Only actions that are relevant to testing
 * are implemented.
 */
export declare class Locator {
    protected query: LocatorQuery;
    /**
     * Creates a locator.
     *
     * @param query - The query to use to locate the element.
     * @returns A locator.
     */
    constructor(query: LocatorQuery);
    protected executeAction<R = void>(action: SupportedLocatorAction, args?: unknown): Promise<R>;
    /**
     * Calls blur on the element.
     *
     * @example Calling blur on the focused element.
     * ```typescript
     * import { query } from '@pawel-up/lupa/commands'
     *
     * await query({ text: 'Focus me' }).blur()
     * ```
     *
     * @param options - Optional settings to modify the action.
     * @returns A promise that resolves when the blur action is completed.
     */
    blur(options?: BlurOptions): Promise<void>;
    /**
     * Clear the input field.
     *
     * @example Clearing the input field.
     * ```typescript
     * import { query } from '@pawel-up/lupa/commands'
     *
     * await query({ label: 'Email' }).clear()
     * ```
     *
     * @param options - Optional settings to modify the action.
     * @returns A promise that resolves when the clear action is completed.
     */
    clear(options?: ClearOptions): Promise<void>;
    /**
     * Ensure that checkbox or radio element is checked.
     *
     * @example Checking a checkbox.
     * ```typescript
     * import { query } from '@pawel-up/lupa/commands'
     *
     * await query({ label: 'Subscribe' }).check()
     * ```
     *
     * @param options - Optional settings to modify the action.
     * @returns A promise that resolves when the check action is completed.
     */
    check(options?: CheckOptions): Promise<void>;
    /**
     * Clicks on the element.
     *
     * @example Clicking on a button with text "Submit".
     * ```typescript
     * import { query } from '@pawel-up/lupa/commands'
     *
     * await query({ text: 'Submit' }).click()
     * ```
     *
     * @param options - Optional settings to modify the action.
     * @returns A promise that resolves when the click action is completed.
     */
    click(options?: ClickOptions): Promise<void>;
    /**
     * Fills the input field.
     *
     * @example Filling a text input with "admin" username.
     * ```typescript
     * import { query } from '@pawel-up/lupa/commands'
     *
     * await query({ placeholder: 'Username' }).fill('admin')
     * ```
     *
     * @param text - Value to set for the `<input>`, `<textarea>` or `[contenteditable]` element.
     * @param options - Optional settings to modify the action.
     * @returns A promise that resolves when the fill action is completed.
     */
    fill(text: string, options?: FillOptions): Promise<void>;
    /**
     * Double clicks the element.
     *
     * @example Double clicking on a button with text "Submit".
     * ```typescript
     * import { query } from '@pawel-up/lupa/commands'
     *
     * await query({ text: 'Submit' }).dblclick()
     * ```
     *
     * @param options - Optional settings to modify the action.
     * @returns A promise that resolves when the double click action is completed.
     */
    dblclick(options?: DoubleClickOptions): Promise<void>;
    /**
     * Hovers over the element.
     *
     * @example Hovering over an element with text "Submit".
     * ```typescript
     * import { query } from '@pawel-up/lupa/commands'
     *
     * await query({ text: 'Submit' }).hover()
     * ```
     *
     * @param options - Optional settings to modify the action.
     * @returns A promise that resolves when the hover action is completed.
     */
    hover(options?: HoverOptions): Promise<void>;
    /**
     * Presses the given key.
     *
     * @example Pressing the "Enter" key.
     * ```typescript
     * import { query } from '@pawel-up/lupa/commands'
     *
     * await query({ text: 'Submit' }).press('Enter')
     * ```
     *
     * @param key - The key to press.
     * @param options - Optional settings to modify the action.
     * @returns A promise that resolves when the press action is completed.
     */
    press(key: string, options?: PressOptions): Promise<void>;
    /**
     * Focuses the element, and then sends a keydown, keypress/input, and keyup event for each character in the text.
     *
     * @use when
     * - Typing characters one by one into an element when the page has special keyboard handling
     *   (e.g. custom autocomplete, real-time input validation, or keyboard shortcuts).
     *
     * @dont use when
     * - In most cases, you should use `locator.fill()` instead. `fill()` is faster, more reliable, and
     *   automatically clears the input.
     *
     * @example
     * ```typescript
     * import { query } from '@pawel-up/lupa/commands'
     *
     * await query({ css: 'input' }).pressSequentially('Hello World', { delay: 100 })
     * ```
     *
     * @param text - Value to type character by character.
     * @param options - Optional settings to control the key press.
     * @returns A promise that resolves when the action is completed.
     */
    pressSequentially(text: string, options?: PressSequentiallyOptions): Promise<void>;
    /**
     * Captures a screenshot of the element.
     *
     * @use when
     * - You want to capture the visual state of a specific DOM element (e.g. a button, modal, or form).
     *
     * @dont use when
     * - You want to capture the entire page or viewport. Use `screenshot.take(...)` instead.
     *
     * @example
     * ```typescript
     * import { query } from '@pawel-up/lupa/commands'
     *
     * await query({ text: 'Submit' }).screenshot({ path: 'screenshots/submit-button.png' })
     * ```
     *
     * @param options - Options for the screenshot, requires `path`.
     * @returns A promise that resolves when the screenshot is saved.
     */
    screenshot(options: ElementScreenshotOptions): Promise<void>;
    /**
     * Taps the element.
     *
     * @example Tapping on an element with text "Submit".
     * ```typescript
     * import { query } from '@pawel-up/lupa/commands'
     *
     * await query({ text: 'Submit' }).tap()
     * ```
     *
     * @param options - Optional settings to modify the action.
     * @returns A promise that resolves when the tap action is completed.
     */
    tap(options?: TapOptions): Promise<void>;
    /**
     * Ensure that checkbox or radio element is unchecked.
     *
     * @example Unchecking an element with text "Subscribe".
     * ```typescript
     * import { query } from '@pawel-up/lupa/commands'
     *
     * await query({ text: 'Subscribe' }).uncheck()
     * ```
     *
     * @param options - Optional settings to modify the action.
     * @returns A promise that resolves when the uncheck action is completed.
     */
    uncheck(options?: UncheckOptions): Promise<void>;
    /**
     * Drags the element to another target element or locator query.
     *
     * @use when
     * - Performing a drag and drop interaction between two elements on the page (e.g., drag an item
     *   into a dropzone/trash bin).
     *
     * @dont use when
     * - You want to simulate file drag events from the operating system. In those cases, use browser-side
     *   helpers like `createFileDragEvent`.
     *
     * @example
     * ```typescript
     * import { query } from '@pawel-up/lupa/commands'
     *
     * await query({ testId: 'draggable-item' }).dragTo(query({ testId: 'trash-bin' }))
     * ```
     *
     * @param target - The target locator or locator query to drag to.
     * @param options - Optional settings to customize the drag-and-drop interaction.
     * @returns A promise that resolves when the drag action is completed.
     */
    dragTo(target: Locator | LocatorQuery, options?: DragToOptions): Promise<void>;
    /**
     * Selects one or multiple options in a `<select>` element.
     *
     * @use when
     * - Interacting with standard `<select>` dropdown controls in the UI.
     * - Setting selection on a single or multi-select HTML `<select>` element.
     *
     * @dont use when
     * - Interacting with custom UI select/dropdown component libraries (e.g. Material Select,
     *   custom divs/buttons dropdowns) that do not use native `<select>` and `<option>` elements.
     *   For those, click on the dropdown button and select options via standard click.
     *
     * @example Selecting single option by value
     * ```typescript
     * import { query } from '@pawel-up/lupa/commands'
     *
     * const selected = await query({ css: '#test-select' }).selectOption('2')
     * ```
     *
     * @example Selecting single option by label
     * ```typescript
     * import { query } from '@pawel-up/lupa/commands'
     *
     * const selected = await query({ css: '#test-select' }).selectOption({ label: 'Two' })
     * ```
     *
     * @example Selecting multiple options in a `<select multiple>` dropdown
     * ```typescript
     * import { query } from '@pawel-up/lupa/commands'
     *
     * const selected = await query({ css: '#multi-select' }).selectOption(['1', '3'])
     * ```
     *
     * @param values - Single value/object or array of values/objects to select.
     * @param options - Optional settings to control actionability checks or timeouts.
     * @returns A promise that resolves to an array of option values that were successfully selected.
     */
    selectOption(values: SelectOptionValues, options?: SelectOptionOptions): Promise<string[]>;
    /**
     * Sets the value of a file input to the specified file paths.
     *
     * @use when
     * - Setting files on a native HTML `<input type="file">` element.
     *
     * @dont use when
     * - Interacting with custom file upload buttons that trigger a native dialog rather than exposing the
     *   underlying file input directly. In those cases, use the `fileChooser` API instead.
     *
     * @example
     * ```typescript
     * import { query } from '@pawel-up/lupa/commands'
     *
     * await query({ css: 'input[type=file]' }).setInputFiles('myfile.png')
     * ```
     *
     * @param files - A file path or array of file paths.
     * @param options - Optional settings to modify the action.
     * @returns A promise that resolves when the file paths have been set.
     */
    setInputFiles(files: string | string[], options?: SetInputFilesOptions): Promise<void>;
}