codeceptjs 4.0.1-beta.8 → 4.0.2-beta.1

package/typings/types.d.ts

@@ -872,9 +872,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
@@ -888,11 +892,11 @@ 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.
          * @returns automatically synchronized promise through #recorder
          */
-        click(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString | null): void;
+        click(locator?: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString | null): void;
         /**
          * Verifies that the specified checkbox is not checked.
          *
@@ -1752,28 +1756,28 @@ declare namespace CodeceptJS {
          */
         seeResponseEquals(resp: any): void;
         /**
-         * 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): void;
@@ -2780,6 +2784,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
      *
@@ -2789,7 +2800,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.
@@ -2831,8 +2841,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';
@@ -3303,20 +3311,6 @@ declare namespace CodeceptJS {
          * @returns automatically synchronized promise through #recorder
          */
         dragAndDrop(srcElement: LocatorOrString, destElement: LocatorOrString, options?: any): void;
-        /**
-         * 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): void;
         /**
          * Reload the current page.
          *
@@ -3612,9 +3606,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
@@ -3636,12 +3634,12 @@ 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.
          * @returns automatically synchronized promise through #recorder
          */
-        click(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString | null, options?: any): void;
+        click(locator?: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString | null, options?: any): void;
         /**
          * Clicks link and waits for navigation (deprecated)
          */
@@ -3707,6 +3705,23 @@ declare namespace CodeceptJS {
          * @returns automatically synchronized promise through #recorder
          */
         rightClick(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString): void;
+        /**
+         * 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.
          *
@@ -4447,6 +4462,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.
@@ -5035,6 +5068,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.
      *
@@ -6356,6 +6398,11 @@ declare namespace CodeceptJS {
          */
         setCookie(cookie: Cookie | Cookie[]): void;
     }
+    /**
+     * 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
      *
@@ -6383,8 +6430,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;
@@ -6986,9 +7031,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
@@ -7002,14 +7051,14 @@ 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.
          * @returns automatically synchronized promise through #recorder
          *
          *
          * {{ react }}
          */
-        click(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString | null): void;
+        click(locator?: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString | null): void;
         /**
          * 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.
@@ -7117,6 +7166,23 @@ declare namespace CodeceptJS {
          * {{ react }}
          */
         rightClick(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString): void;
+        /**
+         * 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.
@@ -8365,8 +8431,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;
@@ -9555,6 +9619,11 @@ declare namespace CodeceptJS {
          */
         waitForText(text: string, sec?: number, context?: CodeceptJS.LocatorOrString): void;
     }
+    /**
+     * 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
      *
@@ -9582,8 +9651,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;
@@ -10043,6 +10110,11 @@ declare namespace CodeceptJS {
          * @param locator - element located by CSS|XPath|strict locator.
          */
         _locateFields(locator: CodeceptJS.LocatorOrString): void;
+        /**
+         * Locate elements by ARIA role using WebdriverIO accessibility selectors
+         * @param locator - role locator object { role: string, text?: string, exact?: boolean }
+         */
+        _locateByRole(locator: any): void;
         /**
          * Grab WebElements for given locator
          * Resumes test execution, so **should be used inside an async function with `await`** operator.
@@ -10096,9 +10168,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
@@ -10112,14 +10188,14 @@ 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.
          * @returns automatically synchronized promise through #recorder
          *
          *
          * {{ react }}
          */
-        click(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString | null): void;
+        click(locator?: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString | null): void;
         /**
          * 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.
@@ -10190,6 +10266,23 @@ declare namespace CodeceptJS {
          * {{ react }}
          */
         rightClick(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString): void;
+        /**
+         * 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.
@@ -11585,8 +11678,8 @@ declare namespace CodeceptJS {
          */
         requireModules(requiringModules: string[]): void;
         /**
-         * Initialize CodeceptJS at specific directory.
-         * If async initialization is required, pass callback as second parameter.
+         * Initialize CodeceptJS at specific dir.
+         * Loads config, requires factory methods
          */
         init(dir: string): void;
         /**
@@ -11793,6 +11886,10 @@ declare namespace CodeceptJS {
          * Get translation
          */
         static translation(): void;
+        /**
+         * Get TypeScript file mapping for error stack fixing
+         */
+        static tsFileMapping(): void;
         /**
          * Get Mocha instance
          */
@@ -11865,6 +11962,7 @@ declare namespace CodeceptJS {
          */
         transpose(): void;
     }
+    function within(context: CodeceptJS.LocatorOrString, fn: (...params: any[]) => any): Promise<any> | undefined;
     /**
      * - Designed for use in CodeceptJS tests as a "soft assertion."
      *   Unlike standard assertions, it does not stop the test execution on failure.
@@ -11977,29 +12075,6 @@ declare namespace CodeceptJS {
          */
         function cleanDispatcher(): void;
     }
-    /**
-     * Index file for loading CodeceptJS programmatically.
-     *
-     * Includes Public API objects
-     */
-    namespace index {
-        var codecept: typeof CodeceptJS.Codecept;
-        var Codecept: typeof CodeceptJS.Codecept;
-        var output: typeof CodeceptJS.output;
-        var container: typeof CodeceptJS.Container;
-        var event: typeof CodeceptJS.event;
-        var recorder: CodeceptJS.recorder;
-        var config: typeof CodeceptJS.Config;
-        var actor: CodeceptJS.actor;
-        var helper: typeof CodeceptJS.Helper;
-        var Helper: typeof CodeceptJS.Helper;
-        var pause: typeof CodeceptJS.pause;
-        var within: typeof CodeceptJS.within;
-        var dataTable: typeof CodeceptJS.DataTable;
-        var dataTableArgument: typeof CodeceptJS.DataTableArgument;
-        var store: typeof CodeceptJS.store;
-        var locator: typeof CodeceptJS.Locator;
-    }
     class Locator {
         constructor(locator: CodeceptJS.LocatorOrString, defaultType?: string);
         toString(): string;
@@ -12008,6 +12083,7 @@ declare namespace CodeceptJS {
         isFrame(): boolean;
         isCSS(): boolean;
         isPlaywrightLocator(): boolean;
+        isRole(): boolean;
         isNull(): boolean;
         isXPath(): boolean;
         isCustom(): boolean;
@@ -12125,7 +12201,10 @@ declare namespace CodeceptJS {
          * Print a text in console log
          */
         function say(message: string, color?: string): void;
-        function result(passed: number, failed: number, skipped: number, duration: number | string): void;
+        /**
+         * Prints the stats of a test run to the console.
+         */
+        function result(passed: number, failed: number, skipped: number, duration: number | string, failedHooks?: number): void;
     }
     /**
      * Pauses test execution and starts interactive shell
@@ -12416,7 +12495,6 @@ declare namespace CodeceptJS {
     type ScenarioConfigCallback = (test: CodeceptJS.Test) => {
         [key: string]: any;
     };
-    function addStep(step: any, fn: any): void;
     /**
      * Creates a new Hook instance
      * @property suite - The test suite this hook belongs to
@@ -12457,10 +12535,6 @@ declare namespace CodeceptJS {
         */
         err: Error | null;
     }
-    /**
-     * TODO: move to effects
-     */
-    function within(context: CodeceptJS.LocatorOrString, fn: (...params: any[]) => any): Promise<any> | undefined;
     /**
      * This is a wrapper on top of [Detox](https://github.com/wix/Detox) library, aimied to unify testing experience for CodeceptJS framework.
      * Detox provides a grey box testing for mobile applications, playing especially good for React Native apps.
@@ -13075,3 +13149,5 @@ declare var helperMethod: string;
  */
 declare var collsapsed: boolean;
 
+declare var currentStepFile: any;
+