codeceptjs 4.0.1-beta.9 → 4.0.2-beta.2

package/typings/promiseBasedTypes.d.ts

@@ -870,9 +870,13 @@ declare namespace CodeceptJS {
          * For buttons, the "value" attribute, "name" attribute, and inner text are searched. For links, the link text is searched.
          * For images, the "alt" attribute and inner text of any parent links are searched.
          *
+         * If no locator is provided, defaults to clicking the body element (`'//body'`).
+         *
          * The second parameter is a context (CSS or XPath locator) to narrow the search.
          *
          * ```js
+         * // click body element (default)
+         * I.click();
          * // simple link
          * I.click('Logout');
          * // button of form
@@ -886,10 +890,10 @@ declare namespace CodeceptJS {
          * // using strict locator
          * I.click({css: 'nav a.login'});
          * ```
-         * @param locator - clickable link or button located by text, or any element located by CSS|XPath|strict locator.
+         * @param [locator = '//body'] - (optional, `'//body'` by default) clickable link or button located by text, or any element located by CSS|XPath|strict locator.
          * @param [context = null] - (optional, `null` by default) element to search in CSS|XPath|Strict locator.
          */
-        click(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString | null): Promise<any>;
+        click(locator?: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString | null): Promise<any>;
         /**
          * Verifies that the specified checkbox is not checked.
          *
@@ -1725,28 +1729,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>;
@@ -2690,6 +2694,13 @@ declare namespace CodeceptJS {
          */
         grabPageScrollPosition(): Promise<PageScrollPosition>;
     }
+    /**
+     * Creates a Playwright selector engine factory for a custom locator strategy.
+     * @param name - Strategy name for error messages
+     * @param func - The locator function (selector, root) => Element|Element[]
+     * @returns Selector engine factory
+     */
+    function createCustomSelectorEngine(name: string, func: (...params: any[]) => any): (...params: any[]) => any;
     /**
      * ## Configuration
      *
@@ -2699,7 +2710,6 @@ declare namespace CodeceptJS {
      * @property [show = true] - show browser window.
      * @property [restart = false] - restart strategy between tests. Possible values:
      *   * 'context' or **false** - restarts [browser context](https://playwright.dev/docs/api/class-browsercontext) but keeps running browser. Recommended by Playwright team to keep tests isolated.
-     *   * 'browser' or **true** - closes browser and opens it again between tests.
      *   * 'session' or 'keep' - keeps browser context and session, but cleans up cookies and localStorage between tests. The fastest option when running tests in windowed mode. Works with `keepCookies` and `keepBrowserState` options. This behavior was default before CodeceptJS 3.1
      * @property [timeout = 1000] - -  [timeout](https://playwright.dev/docs/api/class-page#page-set-default-timeout) in ms of all Playwright actions .
      * @property [disableScreenshots = false] - don't save screenshot on failure.
@@ -2741,8 +2751,6 @@ declare namespace CodeceptJS {
      *   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';
@@ -3206,20 +3214,6 @@ declare namespace CodeceptJS {
          * @param [options] - [Additional options](https://playwright.dev/docs/api/class-page#page-drag-and-drop) can be passed as 3rd argument.
          */
         dragAndDrop(srcElement: LocatorOrString, destElement: LocatorOrString, options?: any): Promise<any>;
-        /**
-         * Restart browser with a new context and a new page
-         *
-         * ```js
-         * // Restart browser and use a new timezone
-         * I.restartBrowser({ timezoneId: 'America/Phoenix' });
-         * // Open URL in a new page in changed timezone
-         * I.amOnPage('/');
-         * // Restart browser, allow reading/copying of text from/into clipboard in Chrome
-         * I.restartBrowser({ permissions: ['clipboard-read', 'clipboard-write'] });
-         * ```
-         * @param [contextOptions] - [Options for browser context](https://playwright.dev/docs/api/class-browser#browser-new-context) when starting new browser
-         */
-        restartBrowser(contextOptions?: any): Promise<any>;
         /**
          * Reload the current page.
          *
@@ -3503,9 +3497,13 @@ declare namespace CodeceptJS {
          * For buttons, the "value" attribute, "name" attribute, and inner text are searched. For links, the link text is searched.
          * For images, the "alt" attribute and inner text of any parent links are searched.
          *
+         * If no locator is provided, defaults to clicking the body element (`'//body'`).
+         *
          * The second parameter is a context (CSS or XPath locator) to narrow the search.
          *
          * ```js
+         * // click body element (default)
+         * I.click();
          * // simple link
          * I.click('Logout');
          * // button of form
@@ -3527,11 +3525,11 @@ declare namespace CodeceptJS {
          * // make ctrl-click
          * I.click('.edit', null, { modifiers: ['Ctrl'] } )
          * ```
-         * @param locator - clickable link or button located by text, or any element located by CSS|XPath|strict locator.
+         * @param [locator = '//body'] - (optional, `'//body'` by default) clickable link or button located by text, or any element located by CSS|XPath|strict locator.
          * @param [context = null] - (optional, `null` by default) element to search in CSS|XPath|Strict locator.
          * @param [options] - [Additional options](https://playwright.dev/docs/api/class-page#page-click) for click available as 3rd argument.
          */
-        click(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString | null, options?: any): Promise<any>;
+        click(locator?: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString | null, options?: any): Promise<any>;
         /**
          * Clicks link and waits for navigation (deprecated)
          */
@@ -3594,6 +3592,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.
          *
@@ -4302,6 +4317,24 @@ declare namespace CodeceptJS {
          * @returns attribute value
          */
         grabAttributeFromAll(locator: CodeceptJS.LocatorOrString, attr: string): Promise<string[]>;
+        /**
+         * Retrieves the ARIA snapshot for an element using Playwright's [`locator.ariaSnapshot`](https://playwright.dev/docs/api/class-locator#locator-aria-snapshot).
+         * This method returns a YAML representation of the accessibility tree that can be used for assertions.
+         * If no locator is provided, it captures the snapshot of the entire page body.
+         *
+         * ```js
+         * const snapshot = await I.grabAriaSnapshot();
+         * expect(snapshot).toContain('heading "Sign up"');
+         *
+         * const formSnapshot = await I.grabAriaSnapshot('#login-form');
+         * expect(formSnapshot).toContain('textbox "Email"');
+         * ```
+         *
+         * [Learn more about ARIA snapshots](https://playwright.dev/docs/aria-snapshots)
+         * @param [locator = '//body'] - element located by CSS|XPath|strict locator. Defaults to body element.
+         * @returns YAML representation of the accessibility tree
+         */
+        grabAriaSnapshot(locator?: string | any): Promise<string>;
         /**
          * Saves screenshot of the specified locator to ouput folder (set in codecept.conf.ts or codecept.conf.js).
          * Filename is relative to output folder.
@@ -4863,6 +4896,15 @@ declare namespace CodeceptJS {
          */
         grabMetrics(): Promise<object[]>;
     }
+    /**
+     * Checks if a locator is a role locator object (e.g., {role: 'button', text: 'Submit', exact: true})
+     */
+    function isRoleLocatorObject(): void;
+    /**
+     * Handles role locator objects by converting them to Playwright's getByRole() API
+     * Returns elements array if role locator, null otherwise
+     */
+    function handleRoleLocator(): void;
     /**
      * Protractor helper is based on [Protractor library](http://www.protractortest.org) and used for testing web applications.
      *
@@ -6115,6 +6157,11 @@ declare namespace CodeceptJS {
          */
         setCookie(cookie: Cookie | Cookie[]): Promise<any>;
     }
+    /**
+     * Wraps error objects that don't have a proper message property
+     * This is needed for ESM compatibility with Puppeteer error handling
+     */
+    function wrapError(): void;
     /**
      * ## Configuration
      *
@@ -6142,8 +6189,6 @@ declare namespace CodeceptJS {
      * @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;
@@ -6721,9 +6766,13 @@ declare namespace CodeceptJS {
          * For buttons, the "value" attribute, "name" attribute, and inner text are searched. For links, the link text is searched.
          * For images, the "alt" attribute and inner text of any parent links are searched.
          *
+         * If no locator is provided, defaults to clicking the body element (`'//body'`).
+         *
          * The second parameter is a context (CSS or XPath locator) to narrow the search.
          *
          * ```js
+         * // click body element (default)
+         * I.click();
          * // simple link
          * I.click('Logout');
          * // button of form
@@ -6737,10 +6786,10 @@ declare namespace CodeceptJS {
          * // using strict locator
          * I.click({css: 'nav a.login'});
          * ```
-         * @param locator - clickable link or button located by text, or any element located by CSS|XPath|strict locator.
+         * @param [locator = '//body'] - (optional, `'//body'` by default) clickable link or button located by text, or any element located by CSS|XPath|strict locator.
          * @param [context = null] - (optional, `null` by default) element to search in CSS|XPath|Strict locator.
          */
-        click(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString | null): Promise<any>;
+        click(locator?: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString | null): Promise<any>;
         /**
          * Perform an emulated click on a link or a button, given by a locator.
          * Unlike normal click instead of sending native event, emulates a click with JavaScript.
@@ -6832,6 +6881,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.
@@ -7988,8 +8054,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;
@@ -9118,6 +9182,11 @@ declare namespace CodeceptJS {
          */
         waitForText(text: string, sec?: number, context?: CodeceptJS.LocatorOrString): Promise<any>;
     }
+    /**
+     * Wraps error objects that don't have a proper message property
+     * This is needed for ESM compatibility with Puppeteer error handling
+     */
+    function wrapError(): void;
     /**
      * ## Configuration
      *
@@ -9145,8 +9214,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;
@@ -9606,6 +9673,11 @@ declare namespace CodeceptJS {
          * @param locator - element located by CSS|XPath|strict locator.
          */
         _locateFields(locator: CodeceptJS.LocatorOrString): Promise<any>;
+        /**
+         * Locate elements by ARIA role using WebdriverIO accessibility selectors
+         * @param locator - role locator object { role: string, text?: string, exact?: boolean }
+         */
+        _locateByRole(locator: any): Promise<any>;
         /**
          * Grab WebElements for given locator
          * Resumes test execution, so **should be used inside an async function with `await`** operator.
@@ -9658,9 +9730,13 @@ declare namespace CodeceptJS {
          * For buttons, the "value" attribute, "name" attribute, and inner text are searched. For links, the link text is searched.
          * For images, the "alt" attribute and inner text of any parent links are searched.
          *
+         * If no locator is provided, defaults to clicking the body element (`'//body'`).
+         *
          * The second parameter is a context (CSS or XPath locator) to narrow the search.
          *
          * ```js
+         * // click body element (default)
+         * I.click();
          * // simple link
          * I.click('Logout');
          * // button of form
@@ -9674,10 +9750,10 @@ declare namespace CodeceptJS {
          * // using strict locator
          * I.click({css: 'nav a.login'});
          * ```
-         * @param locator - clickable link or button located by text, or any element located by CSS|XPath|strict locator.
+         * @param [locator = '//body'] - (optional, `'//body'` by default) clickable link or button located by text, or any element located by CSS|XPath|strict locator.
          * @param [context = null] - (optional, `null` by default) element to search in CSS|XPath|Strict locator.
          */
-        click(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString | null): Promise<any>;
+        click(locator?: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString | null): Promise<any>;
         /**
          * Perform an emulated click on a link or a button, given by a locator.
          * Unlike normal click instead of sending native event, emulates a click with JavaScript.
@@ -9736,6 +9812,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.