@civitas-cerebrum/element-interactions 0.1.1

package/dist/steps/CommonSteps.d.ts

@@ -0,0 +1,576 @@
+import { Page, Response } from '@playwright/test';
+import { ElementRepository } from '@civitas-cerebrum/element-repository';
+import { EmailCredentials, EmailSendOptions, EmailReceiveOptions, ReceivedEmail, EmailMarkAction, EmailFilter } from '@civitas-cerebrum/email-client';
+import { DropdownSelectOptions, TextVerifyOptions, CountVerifyOptions, DragAndDropOptions, ListedElementMatch, VerifyListedOptions, GetListedDataOptions, FillFormValue, GetAllOptions, ScreenshotOptions } from '../enum/Options';
+/**
+ * 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 page;
+    private repo;
+    private interact;
+    private navigate;
+    private extract;
+    private verify;
+    private utils;
+    private email;
+    /**
+     * Initializes the Steps class with the required Playwright page and element repository.
+     * @param page - The current Playwright Page object.
+     * @param repo - An initialized instance of `ElementRepository` containing your locators.
+     * @param timeout - Optional global timeout override (in milliseconds).
+     * @param emailCredentials - Optional email credentials to enable the email sub-API.
+     */
+    constructor(page: Page, repo: ElementRepository, timeout?: number, emailCredentials?: EmailCredentials);
+    /**
+     * Navigates the browser to the specified URL.
+     * @param url - The URL or path to navigate to (e.g. `'/dashboard'` or `'https://example.com'`).
+     */
+    navigateTo(url: string): 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.
+     * The element is scrolled into view before clicking.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     */
+    click(pageName: string, elementName: string): Promise<void>;
+    /**
+     * Clicks on an element without scrolling it into view first.
+     * Useful for elements in fixed or sticky positions (e.g. headers, floating buttons).
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     */
+    clickWithoutScrolling(pageName: string, elementName: string): Promise<void>;
+    /**
+     * Clicks a random visible element from a group of elements matching the locator.
+     * Useful for lists, grids, or repeated components where any item is acceptable.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     * @throws Error if no visible element is found for the given locator.
+     */
+    clickRandom(pageName: string, elementName: string): Promise<void>;
+    /**
+     * Clicks on an element only if it is present in the DOM.
+     * Does nothing if the element is not found — no error is thrown.
+     * Useful for dismissing optional modals, banners, or cookie notices.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     */
+    clickIfPresent(pageName: string, elementName: string): Promise<boolean>;
+    /**
+     * Right-clicks on an element identified by page and element name from the repository.
+     * Triggers the browser's context menu event on the element.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     */
+    rightClick(pageName: string, elementName: string): Promise<void>;
+    /**
+     * Double-clicks on an element identified by page and element name from the repository.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     */
+    doubleClick(pageName: string, elementName: string): Promise<void>;
+    /**
+     * Checks a checkbox or radio button. Idempotent — does nothing if already checked.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     */
+    check(pageName: string, elementName: string): Promise<void>;
+    /**
+     * Unchecks a checkbox. Idempotent — does nothing if already unchecked.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     */
+    uncheck(pageName: string, elementName: string): Promise<void>;
+    /**
+     * Hovers over an element, triggering any hover-based UI effects (tooltips, menus, etc.).
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     */
+    hover(pageName: string, elementName: string): Promise<void>;
+    /**
+     * Scrolls the specified element into the visible viewport.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     */
+    scrollIntoView(pageName: string, elementName: string): Promise<void>;
+    /**
+     * Clears the input field and fills it with the specified text.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     * @param text - The text to fill into the input field.
+     */
+    fill(pageName: string, elementName: string, text: string): Promise<void>;
+    /**
+     * Uploads a file to a file input element.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     * @param filePath - The path to the file to upload (e.g. `'tests/fixtures/file.pdf'`).
+     */
+    uploadFile(pageName: string, elementName: string, filePath: string): Promise<void>;
+    /**
+     * Selects an option from a `<select>` dropdown element.
+     * By default, a random option is selected. Use the `options` parameter
+     * to select by value, index, or explicitly random.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     * @param options - Optional selection strategy (random, by value, or by index).
+     * @returns The value of the selected option.
+     */
+    selectDropdown(pageName: string, elementName: string, options?: DropdownSelectOptions): Promise<string>;
+    /**
+     * Performs a drag-and-drop action on an element.
+     * The target can be specified as another locator or as x/y pixel offsets.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     * @param options - Drag target: either `{ target: Locator }` or `{ xOffset, yOffset }`.
+     */
+    dragAndDrop(pageName: string, elementName: string, options: DragAndDropOptions): Promise<void>;
+    /**
+     * Performs a drag-and-drop action on a specific element within a list,
+     * identified by its visible text content.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     * @param elementText - The visible text of the specific list item to drag.
+     * @param options - Drag target: either `{ target: Locator }` or `{ xOffset, yOffset }`.
+     * @throws Error if no element with the specified text is found.
+     */
+    dragAndDropListedElement(pageName: string, elementName: string, elementText: string, options: DragAndDropOptions): Promise<void>;
+    /**
+     * Sets the value of a range/slider input element.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     * @param value - The numeric value to set on the slider.
+     */
+    setSliderValue(pageName: string, elementName: string, value: number): Promise<void>;
+    /**
+     * Presses a keyboard key at the page level (not bound to a specific element).
+     * Useful for keyboard shortcuts like Escape, Enter, Tab, or combos like 'Control+A'.
+     * @param key - The key to press (e.g. `'Escape'`, `'Enter'`, `'Tab'`, `'Control+A'`).
+     */
+    pressKey(key: string): Promise<void>;
+    /**
+     * Retrieves the visible text content of an element.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     * @returns The text content of the element, or `null` if unavailable.
+     */
+    getText(pageName: string, elementName: string): Promise<string | null>;
+    /**
+     * Retrieves the value of a specific HTML attribute from an element.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     * @param attributeName - The name of the attribute to retrieve (e.g. `'href'`, `'src'`, `'data-id'`).
+     * @returns The attribute value, or `null` if the attribute does not exist.
+     */
+    getAttribute(pageName: string, elementName: string, attributeName: string): Promise<string | null>;
+    /**
+     * Asserts that the element is present and visible in the DOM.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     */
+    verifyPresence(pageName: string, elementName: string): Promise<void>;
+    /**
+     * Asserts that the element is not present in the DOM.
+     * Uses the raw selector string rather than a locator to avoid waiting for an element that should not exist.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     */
+    verifyAbsence(pageName: string, elementName: string): Promise<void>;
+    /**
+     * Asserts that an element's text content matches the expected value.
+     * Can also verify that the text is simply not empty.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     * @param expectedText - The exact text to match against. Omit when using `{ notEmpty: true }`.
+     * @param options - Optional verification options (e.g. `{ notEmpty: true }` to only check non-emptiness).
+     */
+    verifyText(pageName: string, elementName: string, expectedText?: string, options?: TextVerifyOptions): Promise<void>;
+    /**
+     * Asserts the number of elements matching the locator satisfies the given condition.
+     * Supports exact count, greaterThan, and lessThan comparisons.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     * @param options - Count condition: `{ exact: number }`, `{ greaterThan: number }`, or `{ lessThan: number }`.
+     */
+    verifyCount(pageName: string, elementName: string, options: CountVerifyOptions): Promise<void>;
+    /**
+     * Asserts that all image elements matching the locator have loaded successfully
+     * (i.e. their `naturalWidth` is greater than 0).
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     * @param scroll - Whether to scroll each image into view before checking. Defaults to `true`.
+     */
+    verifyImages(pageName: string, elementName: string, scroll?: boolean): Promise<void>;
+    /**
+     * Asserts that an element's text content contains the specified substring.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     * @param expectedText - The substring expected to be found within the element's text.
+     */
+    verifyTextContains(pageName: string, elementName: string, expectedText: string): Promise<void>;
+    /**
+     * Asserts that an element is in the specified state.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     * @param state - The expected state: `'enabled'`, `'disabled'`, `'editable'`, `'checked'`,
+     *   `'focused'`, `'visible'`, `'hidden'`, `'attached'`, or `'inViewport'`.
+     * @param timeout - Optional timeout in milliseconds, overrides the default ELEMENT_TIMEOUT.
+     */
+    verifyState(pageName: string, elementName: 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.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     * @param attributeName - The name of the HTML attribute to check (e.g. `'class'`, `'href'`, `'data-status'`).
+     * @param expectedValue - The expected value of the attribute.
+     */
+    verifyAttribute(pageName: string, elementName: string, attributeName: string, expectedValue: string): Promise<void>;
+    /**
+     * Asserts that the current page URL contains the specified substring.
+     * Useful for verifying navigation outcomes without matching the full URL.
+     * @param text - The substring expected to be found in the current URL (e.g. `'/dashboard'`).
+     */
+    verifyUrlContains(text: string): Promise<void>;
+    /**
+     * Asserts that an input, textarea, or select element has the expected value.
+     * Unlike `verifyText` which checks `textContent`, this checks the `value` property.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     * @param expectedValue - The expected value of the input.
+     */
+    verifyInputValue(pageName: string, elementName: string, expectedValue: string): 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>;
+    /**
+     * Clicks a specific element within a list (e.g. a table row, card, or list item)
+     * identified by its visible text or an HTML attribute. Optionally drills into a
+     * child element before clicking.
+     *
+     * The base locator is resolved from the repository using `pageName` and `elementName`,
+     * then filtered using the criteria in `options` to find the exact match.
+     *
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page (should resolve to a list of elements).
+     * @param options - Match criteria: provide `text` to match by visible text, or `attribute` to match by an HTML
+     *   attribute name-value pair. Optionally include `child` (a CSS selector string or a `{ pageName, elementName }`
+     *   page-repository reference) to target a sub-element within the matched item.
+     * @throws Error if neither `text` nor `attribute` is provided, or if no matching element is found.
+     */
+    clickListedElement(pageName: string, elementName: string, options: ListedElementMatch): Promise<void>;
+    /**
+     * Verifies a specific element within a list by checking its text content or an HTML attribute.
+     * The element is first located by matching visible text or an attribute from the list,
+     * then the assertion is performed on the resolved (and optionally child-targeted) element.
+     *
+     * Verification behavior is determined by the `options` fields:
+     * - `expectedText` — asserts that the resolved element's text content matches this value.
+     * - `expected` — asserts that the resolved element has the specified attribute name-value pair.
+     * - If neither is provided, the method asserts that the matched element is visible.
+     *
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page (should resolve to a list of elements).
+     * @param options - Match and assertion criteria. Must include `text` or `attribute` for identification.
+     *   Optionally include `child` to drill into a sub-element, and `expectedText` or `expected` for the assertion.
+     * @throws Error if neither `text` nor `attribute` is provided, if the element is not found,
+     *   or if the assertion fails.
+     */
+    verifyListedElement(pageName: string, elementName: string, options: VerifyListedOptions): Promise<void>;
+    /**
+     * Extracts data from a specific element within a list — either its text content
+     * or the value of a specified HTML attribute.
+     *
+     * The element is first located by matching visible text or an attribute from the list,
+     * then data is extracted from the resolved (and optionally child-targeted) element.
+     *
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page (should resolve to a list of elements).
+     * @param options - Match and extraction criteria. Must include `text` or `attribute` for identification.
+     *   Optionally include `child` to drill into a sub-element. If `extractAttribute` is set, that attribute's
+     *   value is returned; otherwise the element's text content is returned.
+     * @returns The extracted text content or attribute value, or `null` if unavailable.
+     * @throws Error if neither `text` nor `attribute` is provided, or if the element is not found.
+     */
+    getListedElementData(pageName: string, elementName: string, options: GetListedDataOptions): Promise<string | null>;
+    /**
+     * Waits for an element to reach the specified state before proceeding.
+     * Useful for synchronizing tests with dynamic page content.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     * @param state - The desired state to wait for: `'visible'` (default), `'attached'`, `'hidden'`, or `'detached'`.
+     */
+    waitForState(pageName: string, elementName: string, state?: 'visible' | 'attached' | 'hidden' | 'detached'): Promise<void>;
+    /**
+     * Types text into an input field one character at a time with a delay between keystrokes.
+     * Useful for inputs with debounced search, autocomplete, or real-time validation
+     * that require realistic keystroke timing.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     * @param text - The text to type character by character.
+     * @param delay - The delay in milliseconds between each keystroke. Defaults to `100`.
+     */
+    typeSequentially(pageName: string, elementName: string, text: string, delay?: number): Promise<void>;
+    /**
+     * Fills multiple form fields on the same page in a single call.
+     * Each key in the `fields` map is an `elementName` from the repository.
+     * String values are filled into text inputs; `DropdownSelectOptions` values
+     * trigger a dropdown selection.
+     *
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param fields - A map of `elementName` → value. Use a string for text inputs
+     *   or a `DropdownSelectOptions` object for `<select>` elements.
+     *
+     * @example
+     * ```ts
+     * await steps.fillForm('FormsPage', {
+     *   nameInput: 'John Doe',
+     *   emailInput: 'john@example.com',
+     *   genderDropdown: { type: DropdownSelectType.VALUE, value: 'male' }
+     * });
+     * ```
+     */
+    fillForm(pageName: string, fields: Record<string, FillFormValue>): Promise<void>;
+    /**
+     * Waits until there are no in-flight network requests for at least 500ms.
+     * Useful after actions that trigger background API calls, lazy loading, or analytics.
+     */
+    waitForNetworkIdle(): Promise<void>;
+    /**
+     * Executes an action and waits for a matching network response to complete.
+     * The response is captured concurrently with the action to avoid race conditions.
+     * @param urlPattern - A string substring or RegExp to match against the response URL.
+     * @param action - An async function that triggers the network request (e.g. a form submit or click).
+     * @returns The captured Playwright Response object.
+     */
+    waitForResponse(urlPattern: string | RegExp, action: () => Promise<void>): Promise<Response>;
+    /**
+     * Retries an action until a verification passes, or until the maximum number of
+     * attempts is reached. Useful for interactions with elements that may take multiple
+     * attempts to succeed (e.g. flaky modals, race conditions with animations).
+     *
+     * @param action - An async function performing the interaction (e.g. a click).
+     * @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`.
+     * @throws The last verification error if all retries are exhausted.
+     */
+    retryUntil(action: () => Promise<void>, verification: () => Promise<void>, maxRetries?: number, delayMs?: number): Promise<void>;
+    /**
+     * Clears the value of an input or textarea element without filling it with new text.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     */
+    clearInput(pageName: string, elementName: string): Promise<void>;
+    /**
+     * Selects multiple options from a `<select multiple>` element by their `value` attributes.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     * @param values - An array of `value` attribute strings to select simultaneously.
+     * @returns An array of the actually selected `value` strings.
+     */
+    selectMultiple(pageName: string, elementName: string, values: string[]): Promise<string[]>;
+    /**
+     * Waits for an element to reach a specific state, then clicks it.
+     * Useful when an element exists in the DOM but is not yet interactive
+     * (e.g. waiting for `'attached'` before clicking a lazily rendered button).
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     * @param state - The state to wait for before clicking. Defaults to `'visible'`.
+     */
+    waitAndClick(pageName: string, elementName: string, state?: 'visible' | 'attached' | 'hidden' | 'detached'): Promise<void>;
+    /**
+     * Clicks the element at a specific zero-based index from all elements matching the locator.
+     * Use this when elements cannot be distinguished by text or attributes and index is
+     * the only reliable identifier.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     * @param index - The zero-based index of the element to click.
+     * @throws Error if no element exists at the specified index.
+     */
+    clickNth(pageName: string, elementName: string, index: number): Promise<void>;
+    /**
+     * Extracts text content or attribute values from all elements matching the locator.
+     * Optionally drills into a child element within each match before extracting.
+     *
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     * @param options - Optional extraction configuration. Use `child` to drill into a sub-element,
+     *   and `extractAttribute` to extract an attribute instead of text content.
+     * @returns An array of extracted strings. Null attribute values are filtered out.
+     *
+     * @example
+     * ```ts
+     * // Get all name-column texts from table rows
+     * const names = await steps.getAll('TablePage', 'rows', { child: 'td:nth-child(2)' });
+     *
+     * // Get all href attributes from links
+     * const hrefs = await steps.getAll('LinksPage', 'links', { extractAttribute: 'href' });
+     * ```
+     */
+    getAll(pageName: string, elementName: string, options?: GetAllOptions): Promise<string[]>;
+    /**
+     * Returns the number of DOM elements matching the locator.
+     * Unlike `verifyCount` which asserts, this returns the count for use in test logic.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     * @returns The count of matching elements.
+     */
+    getCount(pageName: string, elementName: string): Promise<number>;
+    /**
+     * Retrieves the current value of an input, textarea, or select element.
+     * Unlike `getText` which reads `textContent`, this reads the `value` property.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     * @returns The current value of the input.
+     */
+    getInputValue(pageName: string, elementName: string): Promise<string>;
+    /**
+     * Retrieves a computed CSS property value from an element.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     * @param property - The CSS property name (e.g. `'color'`, `'font-size'`, `'display'`).
+     * @returns The computed value as a string (e.g. `'rgb(255, 0, 0)'`, `'16px'`, `'block'`).
+     */
+    getCssProperty(pageName: string, elementName: string, property: string): Promise<string>;
+    /**
+     * Asserts that the text contents of all elements matching the locator appear
+     * in the exact order specified. Each element's text is compared against the
+     * corresponding entry in the array.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     * @param expectedTexts - The expected text values in their expected order.
+     */
+    verifyOrder(pageName: string, elementName: string, expectedTexts: string[]): Promise<void>;
+    /**
+     * Asserts that a computed CSS property of an element matches the expected value.
+     * Values are in their computed form (e.g. `'rgb(255, 0, 0)'` not `'red'`).
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     * @param property - The CSS property name (e.g. `'color'`, `'font-size'`, `'display'`).
+     * @param expectedValue - The expected computed value.
+     */
+    verifyCssProperty(pageName: string, elementName: string, property: string, expectedValue: string): Promise<void>;
+    /**
+     * Asserts that the text contents of all elements matching the locator are sorted
+     * in the specified direction using locale-aware string comparison.
+     * @param pageName - The page name as defined in `page-repository.json`.
+     * @param elementName - The element name as defined under the given page.
+     * @param direction - `'asc'` for ascending (A→Z) or `'desc'` for descending (Z→A).
+     */
+    verifyListOrder(pageName: string, elementName: string, direction: 'asc' | 'desc'): Promise<void>;
+    /**
+     * Captures a screenshot of the full page or a specific element.
+     *
+     * @param pageNameOrOptions - Either a page name string (for element screenshots)
+     *   or `ScreenshotOptions` (for page screenshots), or omitted entirely for a default page screenshot.
+     * @param elementName - The element name (required when first arg is a page name).
+     * @param options - Optional screenshot configuration.
+     * @returns The screenshot image as a Buffer.
+     *
+     * @example
+     * ```ts
+     * // Full page screenshot
+     * await steps.screenshot();
+     * await steps.screenshot({ fullPage: true, path: 'full-page.png' });
+     *
+     * // Element screenshot
+     * await steps.screenshot('PageName', 'elementName');
+     * await steps.screenshot('PageName', 'elementName', { path: 'element.png' });
+     * ```
+     */
+    screenshot(pageNameOrOptions?: string | ScreenshotOptions, elementName?: string, options?: ScreenshotOptions): Promise<Buffer>;
+    /**
+     * Sends an email using the configured SMTP credentials.
+     * @param options - The email configuration (to, subject, text, html, or htmlFile).
+     */
+    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, including its downloaded file path and content.
+     */
+    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. If filters are provided, only matching emails are deleted.
+     * Otherwise, the entire inbox is cleared.
+     * @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 (READ, UNREAD, FLAGGED, UNFLAGGED, or ARCHIVED).
+     * @param action - The marking action to apply (e.g., EmailMarkAction.READ, EmailMarkAction.FLAGGED, etc.).
+     * @param options - Optional options to target specific emails with filters.
+     * @returns The number of emails successfully marked.
+     *
+     * @example
+     * ```ts
+     * // Mark all OTP emails as read
+     * await steps.markEmail('markEmailsAsRead', EmailMarkAction.READ, {
+     *   filters: [{ type: EmailFilterType.SUBJECT, value: 'OTP' }]
+     * });
+     *
+     * // Mark all emails as unread
+     * await steps.markEmail('markEmailsAsUnread', EmailMarkAction.UNREAD);
+     *
+     * // Mark specific emails as flagged
+     * await steps.markEmail('flagImportantEmails', EmailMarkAction.FLAGGED, {
+     *   filters: [{ type: EmailFilterType.FROM, value: 'noreply@example.com' }]
+     * });
+     *
+     * // Archive emails matching a filter
+     * await steps.markEmail('archiveEmails', EmailMarkAction.ARCHIVED, {
+     *   filters: [{ type: EmailFilterType.SUBJECT, value: 'Report' }]
+     * });
+     * ```
+     */
+    markEmail(action: EmailMarkAction | string[], options?: {
+        filters?: EmailFilter[];
+        folder?: string;
+        archiveFolder?: string;
+    }): Promise<number>;
+}