codeceptjs 3.4.1 → 3.5.1

package/typings/promiseBasedTypes.d.ts

@@ -756,6 +756,8 @@ declare namespace CodeceptJS {
          *
          * ```js
          * I.appendField('#myTextField', 'appended');
+         * // typing secret
+         * I.appendField('password', secret('123456'));
          * ```
          * @param field - located by label|name|CSS|XPath|strict locator
          * @param value - text value to append.
@@ -1655,16 +1657,16 @@ declare namespace CodeceptJS {
          *
          * I.seeResponseMatchesJsonSchema(joi => {
          *   return joi.object({
-         *     name: joi.string();
-         *     id: joi.number();
+         *     name: joi.string(),
+         *     id: joi.number()
          *   })
          * });
          *
          * // or pass a valid schema
-         * const joi = require('joi);
+         * const joi = require('joi');
          *
          * I.seeResponseMatchesJsonSchema(joi.object({
-         *   name: joi.string();
+         *   name: joi.string(),
          *   id: joi.number();
          * });
          * ```
@@ -2167,6 +2169,8 @@ declare namespace CodeceptJS {
          *
          * ```js
          * I.appendField('#myTextField', 'appended');
+         * // typing secret
+         * I.appendField('password', secret('123456'));
          * ```
          * @param field - located by label|name|CSS|XPath|strict locator
          * @param value - text value to append.
@@ -2671,6 +2675,46 @@ declare namespace CodeceptJS {
          */
         grabPageScrollPosition(): Promise<PageScrollPosition>;
     }
+    /**
+     * OpenAI Helper for CodeceptJS.
+     *
+     * This helper class provides integration with the OpenAI GPT-3.5 or 4 language model for generating responses to questions or prompts within the context of web pages. It allows you to interact with the GPT-3.5 model to obtain intelligent responses based on HTML fragments or general prompts.
+     * This helper should be enabled with any web helpers like Playwright or Puppeteer or WebDrvier to ensure the HTML context is available.
+     *
+     * ## Configuration
+     *
+     * This helper should be configured in codecept.json or codecept.conf.js
+     *
+     * * `chunkSize`: (optional, default: 80000) - The maximum number of characters to send to the OpenAI API at once. We split HTML fragments by 8000 chars to not exceed token limit. Increase this value if you use GPT-4.
+     */
+    class OpenAITs {
+        /**
+         * Asks the OpenAI GPT language model a question based on the provided prompt within the context of the current page's HTML.
+         *
+         * ```js
+         * I.askGptOnPage('what does this page do?');
+         * ```
+         * @param prompt - The question or prompt to ask the GPT model.
+         * @returns - A Promise that resolves to the generated responses from the GPT model, joined by newlines.
+         */
+        askGptOnPage(prompt: string): Promise<string>;
+        /**
+         * Asks the OpenAI GPT-3.5 language model a question based on the provided prompt within the context of a specific HTML fragment on the current page.
+         *
+         * ```js
+         * I.askGptOnPageFragment('describe features of this screen', '.screen');
+         * ```
+         * @param prompt - The question or prompt to ask the GPT-3.5 model.
+         * @param locator - The locator or selector used to identify the HTML fragment on the page.
+         * @returns - A Promise that resolves to the generated response from the GPT model.
+         */
+        askGptOnPageFragment(prompt: string, locator: string): Promise<string>;
+        /**
+         * Send a general request to ChatGPT and return response.
+         * @returns - A Promise that resolves to the generated response from the GPT model.
+         */
+        askGptGeneralPrompt(prompt: string): Promise<string>;
+    }
     /**
      * Uses [Playwright](https://github.com/microsoft/playwright) library to run tests inside:
      *
@@ -2705,7 +2749,7 @@ declare namespace CodeceptJS {
      *
      * #### Trace Recording Customization
      *
-     * Trace recording provides a complete information on test execution and includes DOM snapshots, screenshots, and network requests logged during run.
+     * Trace recording provides complete information on test execution and includes DOM snapshots, screenshots, and network requests logged during run.
      * Traces will be saved to `output/trace`
      *
      * * `trace`: enables trace recording for failed tests; trace are saved into `output/trace` folder
@@ -2835,6 +2879,22 @@ declare namespace CodeceptJS {
      * }
      * ```
      *
+     * * #### Example #9: Launch electron test
+     *
+     * ```js
+     * {
+     *  helpers: {
+     *     Playwright: {
+     *       browser: 'electron',
+     *       electron: {
+     *         executablePath: require("electron"),
+     *         args: [path.join('../', "main.js")],
+     *       },
+     *     }
+     *   },
+     * }
+     * ```
+     *
      * Note: When connecting to remote browser `show` and specific `chrome` options (e.g. `headless` or `devtools`) are ignored.
      *
      * ## Access From Helpers
@@ -2999,6 +3059,39 @@ declare namespace CodeceptJS {
          * ⚠️ returns a _promise_ which is synchronized internally by recorder
          */
         moveCursorTo(locator: CodeceptJS.LocatorOrString, offsetX?: number, offsetY?: number): Promise<any>;
+        /**
+         * Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the matching element.
+         *
+         * Examples:
+         *
+         * ```js
+         * I.dontSee('#add-to-cart-btn');
+         * I.focus('#product-tile')
+         * I.see('#add-to-cart-bnt');
+         * ```
+         * @param locator - field located by label|name|CSS|XPath|strict locator.
+         * @param [options] - Playwright only: [Additional options](https://playwright.dev/docs/api/class-locator#locator-focus) for available options object as 2nd argument.
+         */
+        focus(locator: CodeceptJS.LocatorOrString, options?: any): Promise<any>;
+        /**
+         * Remove focus from a text input, button, etc.
+         * Calls [blur](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the element.
+         *
+         * Examples:
+         *
+         * ```js
+         * I.blur('.text-area')
+         * ```
+         * ```js
+         * //element `#product-tile` is focused
+         * I.see('#add-to-cart-btn');
+         * I.blur('#product-tile')
+         * I.dontSee('#add-to-cart-btn');
+         * ```
+         * @param locator - field located by label|name|CSS|XPath|strict locator.
+         * @param [options] - Playwright only: [Additional options](https://playwright.dev/docs/api/class-locator#locator-blur) for available options object as 2nd argument.
+         */
+        blur(locator: CodeceptJS.LocatorOrString, options?: any): Promise<any>;
         /**
          * Drag an item to a destination element.
          *
@@ -3015,7 +3108,7 @@ declare namespace CodeceptJS {
          * I.dragAndDrop('img.src', 'img.dst', { sourcePosition: {x: 10, y: 10} })
          * ```
          *
-         * > By default option `force: true` is set
+         * > When no option is set, custom drag and drop would be used, to use the dragAndDrop API from Playwright, please set options, for example `force: true`
          */
         dragAndDrop(srcElement: LocatorOrString, destElement: LocatorOrString, options?: any): Promise<any>;
         /**
@@ -3299,7 +3392,7 @@ declare namespace CodeceptJS {
          * @param locator - 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 a _promise_ which is synchronized internally by recorder
-         * @param [opts] - [Additional options](https://playwright.dev/docs/api/class-page#page-click) for click available as 3rd argument.
+         * @param [options] - [Additional options](https://playwright.dev/docs/api/class-page#page-click) for click available as 3rd argument.
          *
          * Examples:
          *
@@ -3311,7 +3404,7 @@ declare namespace CodeceptJS {
          * I.click('.edit', null, { modifiers: ['Ctrl'] } )
          * ```
          */
-        click(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString | null, opts?: any): Promise<any>;
+        click(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString | null, options?: any): Promise<any>;
         /**
          * Clicks link and waits for navigation (deprecated)
          */
@@ -3562,6 +3655,9 @@ declare namespace CodeceptJS {
          *
          * // passing in an array
          * I.type(['T', 'E', 'X', 'T']);
+         *
+         * // passing a secret
+         * I.type(secret('123456'));
          * ```
          * @param key - or array of keys to type.
          * @param [delay = null] - (optional) delay in ms between key presses
@@ -3588,23 +3684,30 @@ declare namespace CodeceptJS {
          */
         fillField(field: CodeceptJS.LocatorOrString, value: CodeceptJS.StringOrSecret): Promise<any>;
         /**
-         * Clears a `<textarea>` or text `<input>` element's value.
+         * Clears the text input element: `<input>`, `<textarea>` or `[contenteditable]` .
+         *
+         *
+         * Examples:
          *
          * ```js
-         * I.clearField('Email');
-         * I.clearField('user[email]');
-         * I.clearField('#email');
+         * I.clearField('.text-area')
+         *
+         * // if this doesn't work use force option
+         * I.clearField('#submit', { force: true })
          * ```
-         * @param editable - field located by label|name|CSS|XPath|strict locator.
-         * ⚠️ returns a _promise_ which is synchronized internally by recorder.
+         * Use `force` to bypass the [actionability](https://playwright.dev/docs/actionability) checks.
+         * @param locator - field located by label|name|CSS|XPath|strict locator.
+         * @param [options] - [Additional options](https://playwright.dev/docs/api/class-locator#locator-clear) for available options object as 2nd argument.
          */
-        clearField(editable: LocatorOrString): Promise<any>;
+        clearField(locator: CodeceptJS.LocatorOrString, options?: any): Promise<any>;
         /**
          * Appends text to a input field or textarea.
          * Field is located by name, label, CSS or XPath
          *
          * ```js
          * I.appendField('#myTextField', 'appended');
+         * // typing secret
+         * I.appendField('password', secret('123456'));
          * ```
          * @param field - located by label|name|CSS|XPath|strict locator
          * @param value - text value to append.
@@ -4334,7 +4437,7 @@ declare namespace CodeceptJS {
          *
          * See [Playwright's reference](https://playwright.dev/docs/api/class-page?_highlight=waitfornavi#pagewaitfornavigationoptions)
          */
-        waitForNavigation(opts: any): Promise<any>;
+        waitForNavigation(options: any): Promise<any>;
         /**
          * Waits for an element to become not attached to the DOM on a page (by default waits for 1sec).
          * Element can be located by CSS or XPath.
@@ -4859,6 +4962,8 @@ declare namespace CodeceptJS {
          *
          * ```js
          * I.appendField('#myTextField', 'appended');
+         * // typing secret
+         * I.appendField('password', secret('123456'));
          * ```
          * @param field - located by label|name|CSS|XPath|strict locator
          * @param value - text value to append.
@@ -6031,6 +6136,39 @@ declare namespace CodeceptJS {
          * {{ react }}
          */
         moveCursorTo(locator: CodeceptJS.LocatorOrString, offsetX?: number, offsetY?: number): Promise<any>;
+        /**
+         * Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the matching element.
+         *
+         * Examples:
+         *
+         * ```js
+         * I.dontSee('#add-to-cart-btn');
+         * I.focus('#product-tile')
+         * I.see('#add-to-cart-bnt');
+         * ```
+         * @param locator - field located by label|name|CSS|XPath|strict locator.
+         * @param [options] - Playwright only: [Additional options](https://playwright.dev/docs/api/class-locator#locator-focus) for available options object as 2nd argument.
+         */
+        focus(locator: CodeceptJS.LocatorOrString, options?: any): Promise<any>;
+        /**
+         * Remove focus from a text input, button, etc.
+         * Calls [blur](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the element.
+         *
+         * Examples:
+         *
+         * ```js
+         * I.blur('.text-area')
+         * ```
+         * ```js
+         * //element `#product-tile` is focused
+         * I.see('#add-to-cart-btn');
+         * I.blur('#product-tile')
+         * I.dontSee('#add-to-cart-btn');
+         * ```
+         * @param locator - field located by label|name|CSS|XPath|strict locator.
+         * @param [options] - Playwright only: [Additional options](https://playwright.dev/docs/api/class-locator#locator-blur) for available options object as 2nd argument.
+         */
+        blur(locator: CodeceptJS.LocatorOrString, options?: any): Promise<any>;
         /**
          * Drag an item to a destination element.
          *
@@ -6567,6 +6705,9 @@ declare namespace CodeceptJS {
          *
          * // passing in an array
          * I.type(['T', 'E', 'X', 'T']);
+         *
+         * // passing a secret
+         * I.type(secret('123456'));
          * ```
          * @param key - or array of keys to type.
          * @param [delay = null] - (optional) delay in ms between key presses
@@ -6612,6 +6753,8 @@ declare namespace CodeceptJS {
          *
          * ```js
          * I.appendField('#myTextField', 'appended');
+         * // typing secret
+         * I.appendField('password', secret('123456'));
          * ```
          * @param field - located by label|name|CSS|XPath|strict locator
          * @param value - text value to append.
@@ -7471,7 +7614,8 @@ declare namespace CodeceptJS {
      *       endpoint: 'http://site.com/api',
      *       prettyPrintJson: true,
      *       onRequest: (request) => {
-     *       request.headers.auth = '123';
+     *         request.headers.auth = '123';
+     *       }
      *     }
      *   }
      * }
@@ -7530,7 +7674,7 @@ declare namespace CodeceptJS {
          * ```js
          * I.sendGetRequest('/api/users.json');
          * ```
-         * @param [headers = {}] - the headers object to be sent. By default it is sent as an empty object
+         * @param [headers = {}] - the headers object to be sent. By default, it is sent as an empty object
          * @returns response
          */
         sendGetRequest(url: any, headers?: any): Promise<any>;
@@ -7544,8 +7688,8 @@ declare namespace CodeceptJS {
          * I.sendPostRequest('/api/users.json', secret({ "email": "user@user.com" }));
          *
          * ```
-         * @param [payload = {}] - the payload to be sent. By default it is sent as an empty object
-         * @param [headers = {}] - the headers object to be sent. By default it is sent as an empty object
+         * @param [payload = {}] - the payload to be sent. By default, it is sent as an empty object
+         * @param [headers = {}] - the headers object to be sent. By default, it is sent as an empty object
          * @returns response
          */
         sendPostRequest(url: any, payload?: any, headers?: any): Promise<any>;
@@ -7585,7 +7729,7 @@ declare namespace CodeceptJS {
          * ```js
          * I.sendDeleteRequest('/api/users/1');
          * ```
-         * @param [headers = {}] - the headers object to be sent. By default it is sent as an empty object
+         * @param [headers = {}] - the headers object to be sent. By default, it is sent as an empty object
          * @returns response
          */
         sendDeleteRequest(url: any, headers?: any): Promise<any>;
@@ -7774,6 +7918,39 @@ declare namespace CodeceptJS {
          * ⚠️ returns a _promise_ which is synchronized internally by recorder
          */
         resizeWindow(width: number, height: number): Promise<any>;
+        /**
+         * Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the matching element.
+         *
+         * Examples:
+         *
+         * ```js
+         * I.dontSee('#add-to-cart-btn');
+         * I.focus('#product-tile')
+         * I.see('#add-to-cart-bnt');
+         * ```
+         * @param locator - field located by label|name|CSS|XPath|strict locator.
+         * @param [options] - Playwright only: [Additional options](https://playwright.dev/docs/api/class-locator#locator-focus) for available options object as 2nd argument.
+         */
+        focus(locator: CodeceptJS.LocatorOrString, options?: any): Promise<any>;
+        /**
+         * Remove focus from a text input, button, etc.
+         * Calls [blur](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the element.
+         *
+         * Examples:
+         *
+         * ```js
+         * I.blur('.text-area')
+         * ```
+         * ```js
+         * //element `#product-tile` is focused
+         * I.see('#add-to-cart-btn');
+         * I.blur('#product-tile')
+         * I.dontSee('#add-to-cart-btn');
+         * ```
+         * @param locator - field located by label|name|CSS|XPath|strict locator.
+         * @param [options] - Playwright only: [Additional options](https://playwright.dev/docs/api/class-locator#locator-blur) for available options object as 2nd argument.
+         */
+        blur(locator: CodeceptJS.LocatorOrString, options?: any): Promise<any>;
         /**
          * Perform a click on a link or a button, given by a locator.
          * If a fuzzy locator is given, the page will be searched for a button, link, or image matching the locator string.
@@ -7859,6 +8036,8 @@ declare namespace CodeceptJS {
          *
          * ```js
          * I.appendField('#myTextField', 'appended');
+         * // typing secret
+         * I.appendField('password', secret('123456'));
          * ```
          * @param field - located by label|name|CSS|XPath|strict locator
          * @param value - text value to append.
@@ -8274,7 +8453,7 @@ declare namespace CodeceptJS {
          * ⚠️ returns a _promise_ which is synchronized internally by recorder
          *
          *
-         * If a function returns a Promise It will wait for it resolution.
+         * If a function returns a Promise It will wait for its resolution.
          */
         executeScript(fn: string | ((...params: any[]) => any), ...args: any[]): Promise<any>;
         /**
@@ -8966,7 +9145,7 @@ declare namespace CodeceptJS {
          */
         _locate(locator: CodeceptJS.LocatorOrString): Promise<any>;
         /**
-         * Find a checkbox by providing human readable text:
+         * Find a checkbox by providing human-readable text:
          *
          * ```js
          * this.helpers['WebDriver']._locateCheckable('I agree with terms and conditions').then // ...
@@ -8975,7 +9154,7 @@ declare namespace CodeceptJS {
          */
         _locateCheckable(locator: CodeceptJS.LocatorOrString): Promise<any>;
         /**
-         * Find a clickable element by providing human readable text:
+         * Find a clickable element by providing human-readable text:
          *
          * ```js
          * const els = await this.helpers.WebDriver._locateClickable('Next page');
@@ -8985,7 +9164,7 @@ declare namespace CodeceptJS {
          */
         _locateClickable(locator: CodeceptJS.LocatorOrString): Promise<any>;
         /**
-         * Find field elements by providing human readable text:
+         * Find field elements by providing human-readable text:
          *
          * ```js
          * this.helpers['WebDriver']._locateFields('Your email').then // ...
@@ -9168,6 +9347,8 @@ declare namespace CodeceptJS {
          *
          * ```js
          * I.appendField('#myTextField', 'appended');
+         * // typing secret
+         * I.appendField('password', secret('123456'));
          * ```
          * @param field - located by label|name|CSS|XPath|strict locator
          * @param value - text value to append.
@@ -10047,6 +10228,9 @@ declare namespace CodeceptJS {
          *
          * // passing in an array
          * I.type(['T', 'E', 'X', 'T']);
+         *
+         * // passing a secret
+         * I.type(secret('123456'));
          * ```
          * @param key - or array of keys to type.
          * @param [delay = null] - (optional) delay in ms between key presses
@@ -10063,6 +10247,39 @@ declare namespace CodeceptJS {
          * Appium: not tested in web, in apps doesn't work
          */
         resizeWindow(width: number, height: number): Promise<any>;
+        /**
+         * Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the matching element.
+         *
+         * Examples:
+         *
+         * ```js
+         * I.dontSee('#add-to-cart-btn');
+         * I.focus('#product-tile')
+         * I.see('#add-to-cart-bnt');
+         * ```
+         * @param locator - field located by label|name|CSS|XPath|strict locator.
+         * @param [options] - Playwright only: [Additional options](https://playwright.dev/docs/api/class-locator#locator-focus) for available options object as 2nd argument.
+         */
+        focus(locator: CodeceptJS.LocatorOrString, options?: any): Promise<any>;
+        /**
+         * Remove focus from a text input, button, etc.
+         * Calls [blur](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the element.
+         *
+         * Examples:
+         *
+         * ```js
+         * I.blur('.text-area')
+         * ```
+         * ```js
+         * //element `#product-tile` is focused
+         * I.see('#add-to-cart-btn');
+         * I.blur('#product-tile')
+         * I.dontSee('#add-to-cart-btn');
+         * ```
+         * @param locator - field located by label|name|CSS|XPath|strict locator.
+         * @param [options] - Playwright only: [Additional options](https://playwright.dev/docs/api/class-locator#locator-blur) for available options object as 2nd argument.
+         */
+        blur(locator: CodeceptJS.LocatorOrString, options?: any): Promise<any>;
         /**
          * Drag an item to a destination element.
          *