codeceptjs 4.0.1-beta.18 → 4.0.1-beta.19

package/typings/promiseBasedTypes.d.ts

@@ -1125,10 +1125,25 @@ declare namespace CodeceptJS {
          * I.selectOption({css: 'form select[name=account]'}, 'Premium');
          * ```
          *
+         * You can also use ARIA role locators:
+         *
+         * ```js
+         * I.selectOption({ role: 'combobox', name: 'Country' }, 'United States');
+         * I.selectOption({ role: 'listbox', name: 'options' }, 'Option 1');
+         * ```
+         *
+         * Or JSON string locators:
+         *
+         * ```js
+         * I.selectOption('{"role": "combobox", "name": "Country"}', 'United States');
+         * I.selectOption('{"role": "listbox", "name": "options"}', 'Option 1');
+         * ```
+         *
          * Provide an array for the second argument to select multiple options.
          *
          * ```js
          * I.selectOption('Which OS do you use?', ['Android', 'iOS']);
+         * I.selectOption({ role: 'combobox', name: 'OS' }, ['Android', 'iOS']);
          * ```
          * @param select - field located by label|name|CSS|XPath|strict locator.
          * @param option - visible text or value of option.
@@ -1729,28 +1744,28 @@ declare namespace CodeceptJS {
          */
         seeResponseEquals(resp: any): Promise<any>;
         /**
-         * Validates JSON structure of response using [joi library](https://joi.dev).
-         * See [joi API](https://joi.dev/api/) for complete reference on usage.
+         * Validates JSON structure of response using [Zod library](https://zod.dev).
+         * See [Zod API](https://zod.dev/) for complete reference on usage.
          *
-         * Use pre-initialized joi instance by passing function callback:
+         * Use pre-initialized Zod instance by passing function callback:
          *
          * ```js
          * // response.data is { name: 'jon', id: 1 }
          *
-         * I.seeResponseMatchesJsonSchema(joi => {
-         *   return joi.object({
-         *     name: joi.string(),
-         *     id: joi.number()
+         * I.seeResponseMatchesJsonSchema(z => {
+         *   return z.object({
+         *     name: z.string(),
+         *     id: z.number()
          *   })
          * });
          *
          * // or pass a valid schema
-         * const joi = require('joi');
+         * import { z } from 'zod';
          *
-         * I.seeResponseMatchesJsonSchema(joi.object({
-         *   name: joi.string(),
-         *   id: joi.number();
-         * });
+         * I.seeResponseMatchesJsonSchema(z.object({
+         *   name: z.string(),
+         *   id: z.number()
+         * }));
          * ```
          */
         seeResponseMatchesJsonSchema(fnOrSchema: any): Promise<any>;
@@ -1763,8 +1778,6 @@ declare namespace CodeceptJS {
      * @property [host = "0.0.0.0"] - Mock server host
      * @property [httpsOpts] - key & cert values are the paths to .key and .crt files
      */
-    // @ts-ignore
-    // @ts-ignore
     type MockServerConfig = {
         port?: number;
         host?: string;
@@ -1889,8 +1902,6 @@ declare namespace CodeceptJS {
      *
      * ## Methods
      */
-    // @ts-ignore
-    // @ts-ignore
     class MockServer {
         /**
          * Start the mock server
@@ -1983,9 +1994,14 @@ declare namespace CodeceptJS {
      * @property [highlightElement] - highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose).
      * @property [recordHar] - record HAR and will be saved to `output/har`. See more of [HAR options](https://playwright.dev/docs/api/class-browser#browser-new-context-option-record-har).
      * @property [testIdAttribute = data-testid] - locate elements based on the testIdAttribute. See more of [locate by test id](https://playwright.dev/docs/locators#locate-by-test-id).
+     * @property [customLocatorStrategies] - custom locator strategies. An object with keys as strategy names and values as JavaScript functions. Example: `{ byRole: (selector, root) => { return root.querySelector(`[role="${selector}"]`) } }`
+     * @property [storageState] - Playwright storage state (path to JSON file or object)
+     *   passed directly to `browser.newContext`.
+     *   If a Scenario is declared with a `cookies` option (e.g. `Scenario('name', { cookies: [...] }, fn)`),
+     *   those cookies are used instead and the configured `storageState` is ignored (no merge).
+     *   May include session cookies, auth tokens, localStorage and (if captured with
+     *   `grabStorageState({ indexedDB: true })`) IndexedDB data; treat as sensitive and do not commit.
      */
-    // @ts-ignore
-    // @ts-ignore
     type PlaywrightConfig = {
         url?: string;
         browser?: 'chromium' | 'firefox' | 'webkit' | 'electron';
@@ -2023,6 +2039,8 @@ declare namespace CodeceptJS {
         highlightElement?: boolean;
         recordHar?: any;
         testIdAttribute?: string;
+        customLocatorStrategies?: any;
+        storageState?: string | any;
     };
     /**
      * Uses [Playwright](https://github.com/microsoft/playwright) library to run tests inside:
@@ -2825,6 +2843,23 @@ declare namespace CodeceptJS {
          * @param [context = null] - (optional, `null` by default) element located by CSS|XPath|strict locator.
          */
         rightClick(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString): Promise<any>;
+        /**
+         * Performs click at specific coordinates.
+         * If locator is provided, the coordinates are relative to the element.
+         * If locator is not provided, the coordinates are global page coordinates.
+         *
+         * ```js
+         * // Click at global coordinates (100, 200)
+         * I.clickXY(100, 200);
+         *
+         * // Click at coordinates (50, 30) relative to element
+         * I.clickXY('#someElement', 50, 30);
+         * ```
+         * @param locator - Element to click on or X coordinate if no element.
+         * @param [x] - X coordinate relative to element, or Y coordinate if locator is a number.
+         * @param [y] - Y coordinate relative to element.
+         */
+        clickXY(locator: CodeceptJS.LocatorOrString | number, x?: number, y?: number): Promise<void>;
         /**
          * [Additional options](https://playwright.dev/docs/api/class-elementhandle#element-handle-check) for check available as 3rd argument.
          *
@@ -2924,7 +2959,7 @@ declare namespace CodeceptJS {
          */
         pressKeyUp(key: string): Promise<any>;
         /**
-         * _Note:_ Shortcuts like `'Meta'` + `'A'` do not work on macOS ([GoogleChrome/Puppeteer#1313](https://github.com/GoogleChrome/puppeteer/issues/1313)).
+         * _Note:_ Shortcuts like `'Meta'` + `'A'` do not work on macOS ([puppeteer/puppeteer#1313](https://github.com/puppeteer/puppeteer/issues/1313)).
          *
          * Presses a key in the browser (on a focused element).
          *
@@ -3109,10 +3144,25 @@ declare namespace CodeceptJS {
          * I.selectOption({css: 'form select[name=account]'}, 'Premium');
          * ```
          *
+         * You can also use ARIA role locators:
+         *
+         * ```js
+         * I.selectOption({ role: 'combobox', name: 'Country' }, 'United States');
+         * I.selectOption({ role: 'listbox', name: 'options' }, 'Option 1');
+         * ```
+         *
+         * Or JSON string locators:
+         *
+         * ```js
+         * I.selectOption('{"role": "combobox", "name": "Country"}', 'United States');
+         * I.selectOption('{"role": "listbox", "name": "options"}', 'Option 1');
+         * ```
+         *
          * Provide an array for the second argument to select multiple options.
          *
          * ```js
          * I.selectOption('Which OS do you use?', ['Android', 'iOS']);
+         * I.selectOption({ role: 'combobox', name: 'OS' }, ['Android', 'iOS']);
          * ```
          * @param select - field located by label|name|CSS|XPath|strict locator.
          * @param option - visible text or value of option.
@@ -3323,6 +3373,27 @@ declare namespace CodeceptJS {
          * @param [name = null] - cookie name.
          */
         grabCookie(name?: string): Promise<any>;
+        /**
+         * Grab the current storage state (cookies, localStorage, etc.) via Playwright's `browserContext.storageState()`.
+         * Returns the raw object that Playwright provides.
+         *
+         * Security: The returned object can contain authentication tokens, session cookies
+         * and (when `indexedDB: true` is used) data that may include user PII. Treat it as a secret.
+         * Avoid committing it to source control and prefer storing it in a protected secrets store / CI artifact vault.
+         * @param [options.indexedDB] - set to true to include IndexedDB in snapshot (Playwright >=1.51)
+         *
+         * ```js
+         * // basic usage
+         * const state = await I.grabStorageState();
+         * require('fs').writeFileSync('authState.json', JSON.stringify(state));
+         *
+         * // include IndexedDB when using Firebase Auth, etc.
+         * const stateWithIDB = await I.grabStorageState({ indexedDB: true });
+         * ```
+         */
+        grabStorageState(options?: {
+            indexedDB?: boolean;
+        }): Promise<any>;
         /**
          * Clears a cookie by name,
          * if none provided clears all cookies.
@@ -3771,7 +3842,7 @@ declare namespace CodeceptJS {
         /**
          * Waits for navigation to finish. By default, it takes configured `waitForNavigation` option.
          *
-         * See [Playwright's reference](https://playwright.dev/docs/api/class-page?_highlight=waitfornavi#pagewaitfornavigationoptions)
+         * See [Playwright's reference](https://playwright.dev/docs/api/class-page#page-wait-for-navigation)
          */
         waitForNavigation(options: any): Promise<any>;
         /**
@@ -5364,7 +5435,7 @@ declare namespace CodeceptJS {
      * @property [keepBrowserState = false] - keep browser state between tests when `restart` is set to false.
      * @property [keepCookies = false] - keep cookies between tests when `restart` is set to false.
      * @property [waitForAction = 100] - how long to wait after click, doubleClick or PressKey actions in ms. Default: 100.
-     * @property [waitForNavigation = load] - when to consider navigation succeeded. Possible options: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`. See [Puppeteer API](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagewaitfornavigationoptions). Array values are accepted as well.
+     * @property [waitForNavigation = load] - when to consider navigation succeeded. Possible options: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`. See [Puppeteer API](https://github.com/puppeteer/puppeteer/blob/main/docs/api/puppeteer.waitforoptions.md). Array values are accepted as well.
      * @property [pressKeyDelay = 10] - delay between key presses in ms. Used when calling Puppeteers page.type(...) in fillField/appendField
      * @property [getPageTimeout = 30000] - config option to set maximum navigation time in milliseconds. If the timeout is set to 0, then timeout will be disabled.
      * @property [waitForTimeout = 1000] - default wait* timeout in ms.
@@ -5372,11 +5443,9 @@ declare namespace CodeceptJS {
      * @property [userAgent] - user-agent string.
      * @property [manualStart = false] - do not start browser before a test, start it manually inside a helper with `this.helpers["Puppeteer"]._startBrowser()`.
      * @property [browser = chrome] - can be changed to `firefox` when using [puppeteer-firefox](https://codecept.io/helpers/Puppeteer-firefox).
-     * @property [chrome] - pass additional [Puppeteer run options](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions).
+     * @property [chrome] - pass additional [Puppeteer run options](https://github.com/puppeteer/puppeteer/blob/main/docs/api/puppeteer.launchoptions.md).
      * @property [highlightElement] - highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose).
      */
-    // @ts-ignore
-    // @ts-ignore
     type PuppeteerConfig = {
         url: string;
         basicAuth?: any;
@@ -5390,7 +5459,7 @@ declare namespace CodeceptJS {
         keepBrowserState?: boolean;
         keepCookies?: boolean;
         waitForAction?: number;
-        waitForNavigation?: string;
+        waitForNavigation?: string | string[];
         pressKeyDelay?: number;
         getPageTimeout?: number;
         waitForTimeout?: number;
@@ -5402,7 +5471,7 @@ declare namespace CodeceptJS {
         highlightElement?: boolean;
     };
     /**
-     * Uses [Google Chrome's Puppeteer](https://github.com/GoogleChrome/puppeteer) library to run tests inside headless Chrome.
+     * Uses [Google Chrome's Puppeteer](https://github.com/puppeteer/puppeteer) library to run tests inside headless Chrome.
      * Browser control is executed via DevTools Protocol (instead of Selenium).
      * This helper works with a browser out of the box with no additional tools required to install.
      *
@@ -5800,6 +5869,17 @@ declare namespace CodeceptJS {
          * {{ react }}
          */
         _locate(): Promise<any>;
+        /**
+         * Get single element by different locator types, including strict locator
+         * Should be used in custom helpers:
+         *
+         * ```js
+         * const element = await this.helpers['Puppeteer']._locateElement({name: 'password'});
+         * ```
+         *
+         * {{ react }}
+         */
+        _locateElement(): Promise<any>;
         /**
          * Find a checkbox by providing human-readable text:
          * NOTE: Assumes the checkable element exists
@@ -5836,6 +5916,17 @@ declare namespace CodeceptJS {
          * @returns WebElement of being used Web helper
          */
         grabWebElements(locator: CodeceptJS.LocatorOrString): Promise<any>;
+        /**
+         * Grab WebElement for given locator
+         * Resumes test execution, so **should be used inside an async function with `await`** operator.
+         *
+         * ```js
+         * const webElement = await I.grabWebElement('#button');
+         * ```
+         * @param locator - element located by CSS|XPath|strict locator.
+         * @returns WebElement of being used Web helper
+         */
+        grabWebElement(locator: CodeceptJS.LocatorOrString): Promise<any>;
         /**
          * Switch focus to a particular tab by its number. It waits tabs loading and then switch tab
          *
@@ -6047,6 +6138,23 @@ declare namespace CodeceptJS {
          * @param [context = null] - (optional, `null` by default) element located by CSS|XPath|strict locator.
          */
         rightClick(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString): Promise<any>;
+        /**
+         * Performs click at specific coordinates.
+         * If locator is provided, the coordinates are relative to the element.
+         * If locator is not provided, the coordinates are global page coordinates.
+         *
+         * ```js
+         * // Click at global coordinates (100, 200)
+         * I.clickXY(100, 200);
+         *
+         * // Click at coordinates (50, 30) relative to element
+         * I.clickXY('#someElement', 50, 30);
+         * ```
+         * @param locator - Element to click on or X coordinate if no element.
+         * @param [x] - X coordinate relative to element, or Y coordinate if locator is a number.
+         * @param [y] - Y coordinate relative to element.
+         */
+        clickXY(locator: CodeceptJS.LocatorOrString | number, x?: number, y?: number): Promise<void>;
         /**
          * Selects a checkbox or radio button.
          * Element is located by label or name or CSS or XPath.
@@ -6126,7 +6234,7 @@ declare namespace CodeceptJS {
          */
         pressKeyUp(key: string): Promise<any>;
         /**
-         * _Note:_ Shortcuts like `'Meta'` + `'A'` do not work on macOS ([GoogleChrome/puppeteer#1313](https://github.com/GoogleChrome/puppeteer/issues/1313)).
+         * _Note:_ Shortcuts like `'Meta'` + `'A'` do not work on macOS ([puppeteer/puppeteer#1313](https://github.com/puppeteer/puppeteer/issues/1313)).
          *
          * Presses a key in the browser (on a focused element).
          *
@@ -6307,10 +6415,25 @@ declare namespace CodeceptJS {
          * I.selectOption({css: 'form select[name=account]'}, 'Premium');
          * ```
          *
+         * You can also use ARIA role locators:
+         *
+         * ```js
+         * I.selectOption({ role: 'combobox', name: 'Country' }, 'United States');
+         * I.selectOption({ role: 'listbox', name: 'options' }, 'Option 1');
+         * ```
+         *
+         * Or JSON string locators:
+         *
+         * ```js
+         * I.selectOption('{"role": "combobox", "name": "Country"}', 'United States');
+         * I.selectOption('{"role": "listbox", "name": "options"}', 'Option 1');
+         * ```
+         *
          * Provide an array for the second argument to select multiple options.
          *
          * ```js
          * I.selectOption('Which OS do you use?', ['Android', 'iOS']);
+         * I.selectOption({ role: 'combobox', name: 'OS' }, ['Android', 'iOS']);
          * ```
          * @param select - field located by label|name|CSS|XPath|strict locator.
          * @param option - visible text or value of option.
@@ -6974,7 +7097,7 @@ declare namespace CodeceptJS {
         /**
          * Waits for navigation to finish. By default, takes configured `waitForNavigation` option.
          *
-         * See [Puppeteer's reference](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagewaitfornavigationoptions)
+         * See [Puppeteer's reference](https://github.com/puppeteer/puppeteer/blob/main/docs/api/puppeteer.page.waitfornavigation.md)
          */
         waitForNavigation(opts: any): Promise<any>;
         /**
@@ -7175,6 +7298,22 @@ declare namespace CodeceptJS {
          */
         flushWebSocketMessages(): Promise<any>;
     }
+    /**
+     * Find elements using Puppeteer's native element discovery methods
+     * Note: Unlike Playwright, Puppeteer's Locator API doesn't have .all() method for multiple elements
+     * @param matcher - Puppeteer context to search within
+     * @param locator - Locator specification
+     * @returns Array of ElementHandle objects
+     */
+    function findElements(matcher: any, locator: any | string): Promise<any[]>;
+    /**
+     * Find a single element using Puppeteer's native element discovery methods
+     * Note: Puppeteer Locator API doesn't have .first() method like Playwright
+     * @param matcher - Puppeteer context to search within
+     * @param locator - Locator specification
+     * @returns Single ElementHandle object
+     */
+    function findElement(matcher: any, locator: any | string): Promise<object>;
     /**
      * ## Configuration
      * @property [endpoint] - API base URL
@@ -7187,8 +7326,6 @@ declare namespace CodeceptJS {
      * @property [onResponse] - an async function which can update response object.
      * @property [maxUploadFileSize] - set the max content file size in MB when performing api calls.
      */
-    // @ts-ignore
-    // @ts-ignore
     type RESTConfig = {
         endpoint?: string;
         prettyPrintJson?: boolean;
@@ -7314,6 +7451,16 @@ declare namespace CodeceptJS {
          * @returns response
          */
         sendGetRequest(url: any, headers?: any): Promise<any>;
+        /**
+         * Send HEAD request to REST API
+         *
+         * ```js
+         * I.sendHeadRequest('/api/users.json');
+         * ```
+         * @param [headers = {}] - the headers object to be sent. By default, it is sent as an empty object
+         * @returns response
+         */
+        sendHeadRequest(url: any, headers?: any): Promise<any>;
         /**
          * Sends POST request to API.
          *
@@ -7413,8 +7560,6 @@ declare namespace CodeceptJS {
      * @property [highlightElement] - highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose).
      * @property [logLevel = silent] - level of logging verbosity. Default: silent. Options: trace | debug | info | warn | error | silent. More info: https://webdriver.io/docs/configuration/#loglevel
      */
-    // @ts-ignore
-    // @ts-ignore
     type WebDriverConfig = {
         url: string;
         browser: string;
@@ -7890,6 +8035,17 @@ declare namespace CodeceptJS {
          * @returns WebElement of being used Web helper
          */
         grabWebElements(locator: CodeceptJS.LocatorOrString): Promise<any>;
+        /**
+         * Grab WebElement for given locator
+         * Resumes test execution, so **should be used inside an async function with `await`** operator.
+         *
+         * ```js
+         * const webElement = await I.grabWebElement('#button');
+         * ```
+         * @param locator - element located by CSS|XPath|strict locator.
+         * @returns WebElement of being used Web helper
+         */
+        grabWebElement(locator: CodeceptJS.LocatorOrString): Promise<any>;
         /**
          * Set [WebDriver timeouts](https://webdriver.io/docs/timeouts.html) in realtime.
          *
@@ -8002,6 +8158,23 @@ declare namespace CodeceptJS {
          * @param [context = null] - (optional, `null` by default) element located by CSS|XPath|strict locator.
          */
         rightClick(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString): Promise<any>;
+        /**
+         * Performs click at specific coordinates.
+         * If locator is provided, the coordinates are relative to the element's top-left corner.
+         * If locator is not provided, the coordinates are relative to the body element.
+         *
+         * ```js
+         * // Click at coordinates (100, 200) relative to body
+         * I.clickXY(100, 200);
+         *
+         * // Click at coordinates (50, 30) relative to element's top-left corner
+         * I.clickXY('#someElement', 50, 30);
+         * ```
+         * @param locator - Element to click on or X coordinate if no element.
+         * @param [x] - X coordinate relative to element's top-left, or Y coordinate if locator is a number.
+         * @param [y] - Y coordinate relative to element's top-left.
+         */
+        clickXY(locator: CodeceptJS.LocatorOrString | number, x?: number, y?: number): Promise<void>;
         /**
          * Emulates right click on an element.
          * Unlike normal click instead of sending native event, emulates a click with JavaScript.
@@ -8077,10 +8250,25 @@ declare namespace CodeceptJS {
          * I.selectOption({css: 'form select[name=account]'}, 'Premium');
          * ```
          *
+         * You can also use ARIA role locators:
+         *
+         * ```js
+         * I.selectOption({ role: 'combobox', name: 'Country' }, 'United States');
+         * I.selectOption({ role: 'listbox', name: 'options' }, 'Option 1');
+         * ```
+         *
+         * Or JSON string locators:
+         *
+         * ```js
+         * I.selectOption('{"role": "combobox", "name": "Country"}', 'United States');
+         * I.selectOption('{"role": "listbox", "name": "options"}', 'Option 1');
+         * ```
+         *
          * Provide an array for the second argument to select multiple options.
          *
          * ```js
          * I.selectOption('Which OS do you use?', ['Android', 'iOS']);
+         * I.selectOption({ role: 'combobox', name: 'OS' }, ['Android', 'iOS']);
          * ```
          * @param select - field located by label|name|CSS|XPath|strict locator.
          * @param option - visible text or value of option.