@uuv/playwright 3.61.0 → 3.62.0

package/dist/cucumber/step_definitions/playwright/core-engine.d.ts

@@ -11,8 +11,10 @@
  * understanding English or French.
  */
 import { World } from "../../preprocessor/run/world";
-import { Cookie } from "@playwright/test";
-import { Locator } from "playwright";
+import { Cookie, Locator as LocatorTest } from "@playwright/test";
+import { EN_ROLES } from "@uuv/dictionary";
+import { Locator, Page } from "playwright";
+export type AccessibleRole = (typeof EN_ROLES)[number]["id"];
 export declare enum COOKIE_NAME {
     TIMEOUT = "uuv.timeout",
     SELECTED_ELEMENT = "uuv.withinFocusedElement",
@@ -64,22 +66,255 @@ export type FilterType = {
     name: FILTER_TYPE;
     value: any;
 };
-export declare function getPageOrElement(world: World): Promise<any>;
+/**
+ * Retrieves the current page or element based on the selected element cookie filters.
+ * Applies all filters from the cookie to locate the specific element or page.
+ * @param world - The Cucumber world object containing context and test info
+ * @returns A Promise that resolves to either a Locator or Page instance
+ */
+export declare function getPageOrElement(world: World): Promise<Locator | Page>;
+/**
+ * Adds a cookie to the browser context with a test-specific name.
+ * Handles different cookie types: MOCK_URL (with consumption tracking), SELECTED_ELEMENT, and TIMEOUT.
+ * @param world - The Cucumber world object containing context
+ * @param cookieName - The type of cookie to add (from COOKIE_NAME enum)
+ * @param newCookie - The cookie value object to add
+ */
 export declare function addCookie(world: World, cookieName: COOKIE_NAME, newCookie: CustomCookieValue): Promise<void>;
+/**
+ * Retrieves a cookie from the browser context by name.
+ * Returns a CustomCookie instance with the cookie data or a default empty cookie if not found.
+ * @param world - The Cucumber world object containing context
+ * @param cookieName - The name of the cookie to retrieve (from COOKIE_NAME enum)
+ * @returns A Promise that resolves to the CustomCookie instance
+ */
 export declare function getCookie(world: World, cookieName: COOKIE_NAME): Promise<CustomCookie>;
+/**
+ * Deletes a cookie by setting its expiration date to 0.
+ * @param world - The Cucumber world object containing context
+ * @param cookieName - The name of the cookie to delete (from COOKIE_NAME enum)
+ */
 export declare function deleteCookieByName(world: World, cookieName: COOKIE_NAME): Promise<void>;
+/**
+ * Finds exactly one element by role and name.
+ * @param world - The Cucumber world object containing context
+ * @param role - The accessible role to search for
+ * @param name - The accessible name of the element to find
+ * @param otherRoleOptions - Additional role options to pass to Playwright
+ * @returns A Promise that resolves to the LocatorTest instance
+ */
 export declare function findWithRoleAndName(world: World, role: string, name: string, otherRoleOptions?: {}): Promise<any>;
+/**
+ * Locates an element within a specific role and name, then saves it as the selected element cookie.
+ * Subsequent operations will be relative to this element until cleared.
+ * @param world - The Cucumber world object containing context
+ * @param role - The accessible role to search for
+ * @param name - The accessible name of the element to find
+ */
 export declare function withinRoleAndName(world: World, role: string, name: string): Promise<void>;
+/**
+ * Locates an element by CSS selector and saves it as the selected element cookie.
+ * Subsequent operations will be relative to this element until cleared.
+ * @param world - The Cucumber world object containing context
+ * @param selector - The CSS selector string to find the element
+ * @returns A Promise that resolves when the element is found and cookie is set
+ */
+export declare function withinSelector(world: World, selector: string): Promise<void>;
+/**
+ * Finds an element by role and name, verifying it does NOT exist (count should be 0).
+ * @param world - The Cucumber world object containing context
+ * @param role - The accessible role to search for
+ * @param name - The accessible name of the element to verify doesn't exist
+ */
 export declare function notFoundWithRoleAndName(world: World, role: string, name: string): Promise<void>;
-export declare function findWithRoleAndNameAndContent(world: World, expectedRole: string, name: string, expectedTextContent?: string | undefined, otherRoleOptions?: {}): Promise<any>;
-export declare function findWithRoleAndNameFocused(world: World, expectedRole: string, name: string): Promise<any>;
-export declare function findWithRoleAndNameAndChecked(world: World, expectedRole: string, name: string): Promise<any>;
-export declare function findWithRoleAndNameAndUnchecked(world: World, expectedRole: string, name: string): Promise<any>;
-export declare function findWithRoleAndNameAndContentDisabled(world: World, expectedRole: string, name: string, expectedTextContent: string): Promise<void>;
-export declare function findWithRoleAndNameDisabled(world: World, expectedRole: string, name: string): Promise<void>;
-export declare function findWithRoleAndNameAndContentEnabled(world: World, expectedRole: string, name: string, expectedTextContent: string): Promise<void>;
-export declare function findWithRoleAndNameEnabled(world: World, expectedRole: string, name: string): Promise<void>;
+/**
+ * Finds exactly one element by CSS selector relative to the current selected element or page.
+ * Verifies the element exists and focuses it.
+ * @param world - The Cucumber world object containing context
+ * @param selector - The CSS selector string to find the element
+ * @returns A Promise that resolves to the LocatorTest instance
+ */
+export declare function findWithSelector(world: World, selector: string): Promise<LocatorTest>;
+/**
+ * Gets all elements matching the text content relative to the current selected element or page.
+ * Use this when you expect multiple matching elements.
+ * @param world - The Cucumber world object containing context
+ * @param textContent - The text content to search for
+ * @returns A Promise that resolves to the LocatorTest instance
+ */
+export declare function getWithContent(world: World, textContent: string): Promise<LocatorTest>;
+/**
+ * Gets all elements matching the test ID relative to the current selected element or page.
+ * Use this when you expect multiple matching elements.
+ * @param world - The Cucumber world object containing context
+ * @param testId - The test ID attribute value to search for
+ * @returns A Promise that resolves to the LocatorTest instance
+ */
+export declare function getWithTestId(world: World, testId: string): Promise<LocatorTest>;
+/**
+ * Finds exactly one element by test ID relative to the current selected element or page.
+ * Verifies the element exists and returns its locator.
+ * @param world - The Cucumber world object containing context
+ * @param testId - The test ID attribute value to search for
+ * @returns A Promise that resolves to the LocatorTest instance
+ */
+export declare function findWithTestId(world: World, testId: string): Promise<LocatorTest>;
+/**
+ * Gets all elements matching the ARIA label relative to the current selected element or page.
+ * Use this when you expect multiple matching elements.
+ * @param world - The Cucumber world object containing context
+ * @param expectedAriaLabel - The ARIA label to search for
+ * @returns A Promise that resolves to the LocatorTest instance
+ */
+export declare function getWithAriaLabel(world: World, expectedAriaLabel: string): Promise<LocatorTest>;
+/**
+ * Finds exactly one element by ARIA label relative to the current selected element or page.
+ * Verifies the element exists and returns its locator.
+ * @param world - The Cucumber world object containing context
+ * @param expectedAriaLabel - The ARIA label to search for
+ * @returns A Promise that resolves to the LocatorTest instance
+ */
+export declare function findWithAriaLabel(world: World, expectedAriaLabel: string): Promise<LocatorTest>;
+/**
+ * Finds exactly one element by role and name, with optional text content match.
+ * Verifies the element count is 1, optionally checks text content, and focuses the element.
+ * @param world - The Cucumber world object containing context
+ * @param expectedRole - The accessible role to search for
+ * @param name - The accessible name of the element to find
+ * @param expectedTextContent - Optional text content to verify
+ * @param otherRoleOptions - Additional role options to pass to Playwright
+ * @returns A Promise that resolves to the LocatorTest instance
+ */
+export declare function findWithRoleAndNameAndContent(world: World, expectedRole: string, name: string, expectedTextContent?: string | undefined, otherRoleOptions?: {}): Promise<LocatorTest>;
+/**
+ * Finds exactly one element by role and name that is currently focused.
+ * Verifies the element exists and is focused.
+ * @param world - The Cucumber world object containing context
+ * @param expectedRole - The accessible role to search for
+ * @param name - The accessible name of the element to find
+ * @returns A Promise that resolves to the LocatorTest instance
+ */
+export declare function findWithRoleAndNameFocused(world: World, expectedRole: string, name: string): Promise<LocatorTest>;
+/**
+ * Finds exactly one element by role and name that is currently checked (e.g., checkbox/radio).
+ * Verifies the element exists and is checked.
+ * @param world - The Cucumber world object containing context
+ * @param expectedRole - The accessible role to search for
+ * @param name - The accessible name of the element to find
+ * @returns A Promise that resolves to the LocatorTest instance
+ */
+export declare function findWithRoleAndNameAndChecked(world: World, expectedRole: string, name: string): Promise<LocatorTest>;
+/**
+ * Finds exactly one element by role and name that is currently unchecked (e.g., checkbox/radio).
+ * Verifies the element exists and is unchecked.
+ * @param world - The Cucumber world object containing context
+ * @param expectedRole - The accessible role to search for
+ * @param name - The accessible name of the element to find
+ * @returns A Promise that resolves to the LocatorTest instance
+ */
+export declare function findWithRoleAndNameAndUnchecked(world: World, expectedRole: string, name: string): Promise<LocatorTest>;
+/**
+ * Finds exactly one element by role and name with specific text content that is disabled.
+ * Verifies the element exists, has the specified text content, and is disabled.
+ * @param world - The Cucumber world object containing context
+ * @param expectedRole - The accessible role to search for
+ * @param name - The accessible name of the element to find
+ * @param expectedTextContent - The expected text content to verify
+ * @returns A Promise that resolves to the LocatorTest instance
+ */
+export declare function findWithRoleAndNameAndContentDisabled(world: World, expectedRole: string, name: string, expectedTextContent: string): Promise<LocatorTest>;
+/**
+ * Finds exactly one element by role and name that is disabled.
+ * Verifies the element exists and is disabled.
+ * @param world - The Cucumber world object containing context
+ * @param expectedRole - The accessible role to search for
+ * @param name - The accessible name of the element to find
+ * @returns A Promise that resolves to the LocatorTest instance
+ */
+export declare function findWithRoleAndNameDisabled(world: World, expectedRole: string, name: string): Promise<LocatorTest>;
+/**
+ * Finds exactly one element by role and name with specific text content that is enabled.
+ * Verifies the element exists, has the specified text content, and is enabled.
+ * @param world - The Cucumber world object containing context
+ * @param expectedRole - The accessible role to search for
+ * @param name - The accessible name of the element to find
+ * @param expectedTextContent - The expected text content to verify
+ * @returns A Promise that resolves to the LocatorTest instance
+ */
+export declare function findWithRoleAndNameAndContentEnabled(world: World, expectedRole: string, name: string, expectedTextContent: string): Promise<LocatorTest>;
+/**
+ * Finds exactly one element by role and name that is enabled.
+ * Verifies the element exists and is enabled.
+ * @param world - The Cucumber world object containing context
+ * @param expectedRole - The accessible role to search for
+ * @param name - The accessible name of the element to find
+ * @returns A Promise that resolves to the LocatorTest instance
+ */
+export declare function findWithRoleAndNameEnabled(world: World, expectedRole: string, name: string): Promise<LocatorTest>;
+/**
+ * Finds exactly one element by role and name that has a specific value.
+ * Verifies the element exists and has the expected value attribute.
+ * @param world - The Cucumber world object containing context
+ * @param expectedRole - The accessible role to search for
+ * @param name - The accessible name of the element to find
+ * @param expectedValue - The expected value attribute to verify
+ * @returns A Promise that resolves to the LocatorTest instance
+ */
+export declare function findWithRoleAndNameAndValue(world: World, expectedRole: string, name: string, expectedValue: string): Promise<LocatorTest>;
+/**
+ * Displays all attribute names and values of a DOM element for debugging purposes.
+ * Logs the attributes to the console.
+ * @param element - The Playwright Locator element to inspect
+ */
 export declare function showAttributesInLocator(element: any): Promise<void>;
+/**
+ * Checks if a locator has the expected text content by trying multiple methods.
+ * Tries value, attribute value, checked state, and text content in sequence.
+ * @param locator - The Playwright Locator to check
+ * @param expectedTextContent - The expected text content to verify
+ * @returns A Promise that resolves when the check is complete
+ */
 export declare function checkTextContentLocator(locator: Locator, expectedTextContent: string): Promise<void>;
-export declare function click(world: World, role: any, name: string): Promise<void>;
+/**
+ * Clicks on an element by role and name, then clears the selected element cookie.
+ * @param world - The Cucumber world object containing context
+ * @param role - The accessible role of the element to click
+ * @param name - The accessible name of the element to click
+ */
+export declare function click(world: World, role: any, name: string): Promise<LocatorTest>;
+/**
+ * Clicks on the currently focused element in the browser.
+ * Uses the :focus selector to identify the active element and clicks it.
+ * If no element is focused, clicks on the current page/selected element.
+ * @param world - The Cucumber world object containing context
+ */
+export declare function clickFocusedElement(world: World): Promise<void>;
+/**
+ * Types text into an element by role and name, then clears the selected element cookie.
+ * @param world - The Cucumber world object containing context
+ * @param role - The accessible role of the element to type into
+ * @param name - The accessible name of the element to type into
+ * @param textToType - The text to type into the element
+ * @returns A Promise that resolves to the LocatorTest instance
+ */
+export declare function type(world: World, role: any, name: string, textToType: string): Promise<LocatorTest>;
+/**
+ * Types text into the currently focused element.
+ * If no element is focused, focuses the current page/selected element first.
+ * @param world - The Cucumber world object containing context
+ * @param textToType - The text to type into the focused element
+ */
+export declare function typeFocusedElement(world: World, textToType: string): Promise<void>;
+export declare function keyBoardFocusTarget(world: World): LocatorTest;
+/**
+ * Gets the current timeout value from the TIMEOUT cookie, or returns the default timeout.
+ * @param world - The Cucumber world object containing context
+ * @returns A Promise that resolves to the timeout value in milliseconds
+ */
 export declare function getTimeout(world: World): Promise<number>;
+/**
+ * Sets a new timeout value by storing it in the TIMEOUT cookie.
+ * @param world - The Cucumber world object containing context
+ * @param newTimeout - The new timeout value in milliseconds
+ */
+export declare function setTimeout(world: World, newTimeout: number): Promise<void>;