codeceptjs 3.3.0-beta.5 → 3.3.2

package/CHANGELOG.md

@@ -1,3 +1,48 @@
+## 3.3.2
+
+* [REST] Fixed override of headers/token in `haveRequestHeaders()` and `amBearerAuthenticated()`. See #3304 by @mirao
+* Reverted typings change introduced in #3245. [More details on this](https://twitter.com/CodeceptJS/status/1519725963856207873) 
+
+## 3.3.1
+
+🛩️ Features:
+
+* Add option to avoid duplicate gherkin step definitions (#3257) - @raywiis
+* Added `step.*` for run-workers #3272. Thanks to @abhimanyupandian
+* Fixed loading tests for `codecept run` using glob patterns. By @jayudey-wf 
+
+```
+npx codeceptjs run test-dir/*"
+```
+
+* [Playwright] **Possible breaking change.** By default `timeout` is changed to 5000ms. The value set in 3.3.0 was too low. Please set `timeout` explicitly to not depend on release values.
+* [Playwright] Added for color scheme option by @PeterNgTr
+
+```js
+ helpers: {
+  Playwright : {
+    url: "http://localhost",
+    colorScheme: "dark",
+  }
+ }
+```
+
+
+🐛 Bugfixes:
+
+* [Playwright] Fixed `Cannot read property 'video' of undefined`
+* Fixed haveRequestHeaders() and amBearerAuthenticated() of REST helper (#3260) - @mirao
+* Fixed: allure attachment fails if screenshot failed #3298 by @ruudvanderweijde 
+* Fixed #3105 using autoLogin() plugin with TypeScript. Fix #3290 by @PeterNgTr 
+* [Playwright] Added extra params for click and dragAndDrop to type definitions by @mirao
+
+
+📖 Documentation
+* Improving the typings in many places
+* Improving the return type of helpers for TS users (#3245) - @nlespiaucq
+
+🇺🇦 Added #StandWithUkraine hashtag notice to CLI
+
 ## 3.3.0
 
 🛩️ Features:
@@ -9,6 +54,10 @@
   * Added dependency on `joi` and `chai`
 * [Playwright] Added `timeout` option to set [timeout](https://playwright.dev/docs/api/class-page#page-set-default-timeout) for all Playwright actions. If an action fails, Playwright keeps retrying it for a time set by timeout.
 * [Playwright] **Possible breaking change.** By default `timeout` is set to 1000ms. *Previous default was set by Playwright internally to 30s. This was causing contradiction to CodeceptJS retries, so triggered up to 3 retries for 30s of time. This timeout option was lowered so retryFailedStep plugin would not cause long delays.*
+* [Playwright] Updated `restart` config option to include 3 restart strategies:
+  * '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 prior CodeceptJS 3.1
 * [Playwright] Extended methods to provide more options from engine. These methods were updated so additional options can be be passed as the last argument:
   * [`click`](/helpers/Playwright#click)
   * [`dragAndDrop`](/helpers/Playwright#dragAndDrop)
@@ -42,7 +91,7 @@ await eachElement('click all links in .list', '.list a', (el) => {
 
 📖 Documentation
 
-* Added [Testomat.io reporter](/reporters#testomatio)
+* Added [Testomat.io reporter](/reports#testomatio)
 * Added [api testing](/api) guides
 * Added [internal api](/internal-api) guides
 * [Appium] Fixed documentation for `performSwipe`

package/README.md

@@ -1,4 +1,9 @@
+[![Stand With Ukraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner-direct-single.svg)](https://stand-with-ukraine.pp.ua)
+
+
+
 [<img src="https://img.shields.io/badge/slack-@codeceptjs-purple.svg?logo=slack">](https://join.slack.com/t/codeceptjs/shared_invite/enQtMzA5OTM4NDM2MzA4LWE4MThhN2NmYTgxNTU5MTc4YzAyYWMwY2JkMmZlYWI5MWQ2MDM5MmRmYzZmYmNiNmY5NTAzM2EwMGIwOTNhOGQ) [<img src="https://img.shields.io/badge/discourse-codeceptjs-purple">](https://codecept.discourse.group) [![NPM version][npm-image]][npm-url]
+[![StandWithUkraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/badges/StandWithUkraine.svg)](https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md) 
 
 Build Status:
 
@@ -8,7 +13,7 @@ Build Status:
 [![Appium Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/appium.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/appium.yml)
 [![TestCafe Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/testcafe.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/testcafe.yml)
 
-# CodeceptJS
+# CodeceptJS [![Made in Ukraine](https://img.shields.io/badge/made_in-ukraine-ffd700.svg?labelColor=0057b7)](https://stand-with-ukraine.pp.ua)
 
 Reference: [Helpers API](https://github.com/codeceptjs/CodeceptJS/tree/master/docs/helpers)
 

package/docs/api.md

@@ -86,8 +86,15 @@ They were used to perform API requests for browser tests. As so, they lack asser
 
 > 💡 In CodeceptJS assertions start with `see` prefix. Learn more about assertions by [opening reference for JSONResponse](/helpers/JSONResponse/) helper.
 
-After helpers were configured, you can start writing first API test. By default, CodeceptJS saves tests in `tests` directory and uses `*_test.js` suffix. The `init` command created the first test for you to start.
+Generate TypeScript definitions to get auto-completions for JSONResponse:
 
+```
+npx codeceptjs def
+```
+
+After helpers were configured and typings were generated, you can start writing first API test. By default, CodeceptJS saves tests in `tests` directory and uses `*_test.js` suffix. The `init` command created the first test for you to start.
+
+> Check [API Examples](https://github.com/codeceptjs/api-examples) to see tests implementations.
 
 ## Requests
 
@@ -148,22 +155,26 @@ Authentication headers can be set in [helper's config](https://codecept.io/helpe
 Example:
 
 ```js
-// this way we pass Bearer token
-I.amBearerAuthenticated(secret('token-is-here'));
-// for custom authorization with headers use
-// I.haveRequestHeaders method
-
-// here we send a POST request
-const response = await I.sendPostRequest('/users', {
-  name: 'joe',
-  email: 'joe@mail.com'
-});
-// usually we won't need direct access to response object for API testing 
-// but you can obtain it from request
-
-// check the last request was successful
-// this method introduced by JSONResponse helper
-I.seeResponseCodeIsSuccessful();
+Feature('Users endpoint')
+
+Scenario('create user', ({ I }) => {
+    // this way we pass Bearer token
+  I.amBearerAuthenticated(secret('token-is-here'));
+  // for custom authorization with headers use
+  // I.haveRequestHeaders method
+
+  // here we send a POST request
+  const response = await I.sendPostRequest('/users', {
+    name: 'joe',
+    email: 'joe@mail.com'
+  });
+  // usually we won't need direct access to response object for API testing 
+  // but you can obtain it from request
+
+  // check the last request was successful
+  // this method introduced by JSONResponse helper
+  I.seeResponseCodeIsSuccessful();
+})
 ```
 
 ### GraphQL
@@ -173,21 +184,25 @@ It's plain old JSON. This why `JSONResponse` helper works for both API types.
 Configure authorization headers in `codecept.conf.js` and make your first query:  
 
 ```js
-// make GraphQL query or mutation
-const resp = await I.sendQuery('{ user(id: 0) { id name email }}');
-I.seeResponseCodeIsSuccessful();
+Feature('Users endpoint')
 
-// GraphQL always returns key data as part of response
-I.seeResponseContainsKeys(['data']);
+Scenario('get user by query', ({ I }) => {
+  // make GraphQL query or mutation
+  const resp = await I.sendQuery('{ user(id: 0) { id name email }}');
+  I.seeResponseCodeIsSuccessful();
 
-// check data for partial inclusion
-I.seeResponseContainsJson({
-  data: {
-    user: {
-      name: 'john doe',
-      email: 'johnd@mutex.com',
+  // GraphQL always returns key data as part of response
+  I.seeResponseContainsKeys(['data']);
+
+  // check data for partial inclusion
+  I.seeResponseContainsJson({
+    data: {
+      user: {
+        name: 'john doe',
+        email: 'johnd@mutex.com',
+      },
     },
-  },
+  });
 });
 ```
 
@@ -285,7 +300,7 @@ To perform arbitrary assertions on a response object use `seeResponseValidByCall
 It allows you to do any kind of assertions by using `expect` from [`chai`](https://www.chaijs.com) library.
 
 ```js
-I.seeResponseValidByCallback({ data, status, expect } => {
+I.seeResponseValidByCallback(({ data, status, expect }) => {
   // we receive data and expect to combine them for good assertion
   expect(data.users.length).to.be.gte(10);
 })

package/docs/bdd.md

@@ -399,6 +399,7 @@ Tag should be placed before *Scenario:* or before *Feature:* keyword. In the las
 * `gherkin`
   * `features` - path to feature files, or an array of feature file paths
   * `steps` - array of files with step definitions
+  * `avoidDuplicateSteps` - attempts to avoid duplicate step definitions by shallow compare
 
 ```js
 "gherkin": {

package/docs/best.md

@@ -215,7 +215,7 @@ include: {
 * When you need to customize access to API and go beyond what ApiDataFactory provides, implement DAO:
 
 ```js
-const faker = require('faker');
+const faker = require('@faker-js/faker');
 const { I } = inject();
 const { output } = require('codeceptjs');
 

package/docs/build/ApiDataFactory.js

@@ -36,7 +36,7 @@ const REST = require('./REST');
  * Install [Rosie](https://github.com/rosiejs/rosie) and [Faker](https://www.npmjs.com/package/faker) libraries.
  *
  * ```sh
- * npm i rosie faker --save-dev
+ * npm i rosie @faker-js/faker --save-dev
  * ```
  *
  * Create a factory file for a resource.
@@ -46,8 +46,8 @@ const REST = require('./REST');
  * ```js
  * // tests/factories/posts.js
  *
- * var Factory = require('rosie').Factory;
- * var faker = require('faker');
+ * const Factory = require('rosie').Factory;
+ * const faker = require('@faker-js/faker');
  *
  * module.exports = new Factory()
  *    // no need to set id, it will be set by REST API
@@ -264,6 +264,7 @@ class ApiDataFactory extends Helper {
    * @param {*} factory factory to use
    * @param {*} params predefined parameters
    * @param {*} options options for programmatically generate the attributes
+   * @returns {Promise<*>}
    */
   have(factory, params, options) {
     const item = this._createItem(factory, params, options);

package/docs/build/Appium.js

@@ -124,6 +124,7 @@ const webRoot = 'body';
 class Appium extends Webdriver {
   /**
    * Appium Special Methods for Mobile only
+   * @augments WebDriver
    */
 
   constructor(config) {
@@ -331,7 +332,6 @@ class Appium extends Webdriver {
    *
    * @param {*} caps
    * @param {*} fn
-   * @return {Promise<any>}
    */
   async runOnIOS(caps, fn) {
     if (this.platform !== 'ios') return;
@@ -374,7 +374,6 @@ class Appium extends Webdriver {
    *
    * @param {*} caps
    * @param {*} fn
-   * @return {Promise<any>}
    */
   async runOnAndroid(caps, fn) {
     if (this.platform !== 'android') return;
@@ -395,7 +394,6 @@ class Appium extends Webdriver {
    * ```
    *
    * @param {*} fn
-   * @return {Promise<any>}
    */
   /* eslint-disable */
   async runInWeb(fn) {
@@ -599,7 +597,6 @@ class Appium extends Webdriver {
    * ```
    *
    * @param {'LANDSCAPE'|'PORTRAIT'} orientation LANDSCAPE or PORTRAIT
-   * @return {Promise<any>}
    *
    * Appium: support Android and iOS
    */
@@ -728,7 +725,6 @@ class Appium extends Webdriver {
    * Switch to the specified context.
    *
    * @param {*} context the context to switch to
-
    */
   async _switchToContext(context) {
     return this.browser.switchContext(context);
@@ -774,7 +770,7 @@ class Appium extends Webdriver {
    * // or set context explicitly
    * I.switchToNative('SOME_OTHER_CONTEXT');
    * ```
-   * @param {*} context
+   * @param {*} [context]
    * @return {Promise<void>}
    */
   async switchToNative(context = null) {
@@ -834,7 +830,6 @@ class Appium extends Webdriver {
    * ```
    *
    * @param {object} settings object
-   * @return {Promise<any>}
    *
    * Appium: support Android and iOS
    */
@@ -955,7 +950,7 @@ class Appium extends Webdriver {
    *
    * [See complete reference](http://webdriver.io/api/mobile/swipe.html)
    *
-   * @param {string | object} locator
+   * @param {CodeceptJS.LocatorOrString} locator
    * @param {number} xoffset
    * @param {number} yoffset
    * @param {number} [speed=1000] (optional), 1000 by default
@@ -1010,7 +1005,7 @@ class Appium extends Webdriver {
    * I.swipeDown(locator, 1200, 1000); // set offset and speed
    * ```
    *
-   * @param {string | object} locator
+   * @param {CodeceptJS.LocatorOrString} locator
    * @param {number} [yoffset] (optional)
    * @param {number} [speed=1000] (optional), 1000 by default
    * @return {Promise<void>}
@@ -1039,7 +1034,7 @@ class Appium extends Webdriver {
    * I.swipeLeft(locator, 1200, 1000); // set offset and speed
    * ```
    *
-   * @param {string | object} locator
+   * @param {CodeceptJS.LocatorOrString} locator
    * @param {number} [xoffset] (optional)
    * @param {number} [speed=1000] (optional), 1000 by default
    * @return {Promise<void>}
@@ -1066,7 +1061,7 @@ class Appium extends Webdriver {
    * I.swipeRight(locator, 1200, 1000); // set offset and speed
    * ```
    *
-   * @param {string | object} locator
+   * @param {CodeceptJS.LocatorOrString} locator
    * @param {number} [xoffset] (optional)
    * @param {number} [speed=1000] (optional), 1000 by default
    * @return {Promise<void>}
@@ -1093,7 +1088,7 @@ class Appium extends Webdriver {
    * I.swipeUp(locator, 1200, 1000); // set offset and speed
    * ```
    *
-   * @param {string | object} locator
+   * @param {CodeceptJS.LocatorOrString} locator
    * @param {number} [yoffset] (optional)
    * @param {number} [speed=1000] (optional), 1000 by default
    * @return {Promise<void>}
@@ -1335,8 +1330,9 @@ class Appium extends Webdriver {
    * ```js
    * I.appendField('#myTextField', 'appended');
    * ```
-   * @param {string | object} field located by label|name|CSS|XPath|strict locator
+   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator
    * @param {string} value text value to append.
+   * [!] returns a _promise_ which is synchronized internally by recorder
    *
    */
   async appendField(field, value) {
@@ -1355,8 +1351,9 @@ class Appium extends Webdriver {
    * I.checkOption('I Agree to Terms and Conditions');
    * I.checkOption('agree', '//form');
    * ```
-   * @param {string | object} field checkbox located by label | name | CSS | XPath | strict locator.
-   * @param {?string | object} [context=null] (optional, `null` by default) element located by CSS | XPath | strict locator.
+   * @param {CodeceptJS.LocatorOrString} field checkbox located by label | name | CSS | XPath | strict locator.
+   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS | XPath | strict locator.
+   * [!] returns a _promise_ which is synchronized internally by recorder
    *
    */
   async checkOption(field) {
@@ -1387,8 +1384,9 @@ class Appium extends Webdriver {
    * I.click({css: 'nav a.login'});
    * ```
    * 
-   * @param {string | object} locator clickable link or button located by text, or any element located by CSS|XPath|strict locator.
-   * @param {?string | object} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator clickable link or button located by text, or any element located by CSS|XPath|strict locator.
+   * @param {?CodeceptJS.LocatorOrString | null} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.
+   * [!] returns a _promise_ which is synchronized internally by recorder
    * 
    *
    */
@@ -1406,8 +1404,8 @@ class Appium extends Webdriver {
    * I.dontSeeCheckboxIsChecked('agree'); // located by name
    * ```
    * 
-   * @param {string | object} field located by label|name|CSS|XPath|strict locator.
-   * 
+   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
+   * [!] returns a _promise_ which is synchronized internally by recorder
    *
    */
   async dontSeeCheckboxIsChecked(field) {
@@ -1422,7 +1420,8 @@ class Appium extends Webdriver {
    * I.dontSeeElement('.modal'); // modal is not shown
    * ```
    * 
-   * @param {string | object} locator located by CSS|XPath|Strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|Strict locator.
+   * [!] returns a _promise_ which is synchronized internally by recorder
    */
   async dontSeeElement(locator) {
     if (this.isWeb) return super.dontSeeElement(locator);
@@ -1438,8 +1437,9 @@ class Appium extends Webdriver {
    * I.dontSeeInField({ css: 'form input.email' }, 'user@user.com'); // field by CSS
    * ```
    * 
-   * @param {string | object} field located by label|name|CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
    * @param {string} value value to check.
+   * [!] returns a _promise_ which is synchronized internally by recorder
    *
    */
   async dontSeeInField(field, value) {
@@ -1457,8 +1457,8 @@ class Appium extends Webdriver {
    * ```
    * 
    * @param {string} text which is not present.
-   * @param {string | object} [context] (optional) element located by CSS|XPath|strict locator in which to perfrom search.
-   * 
+   * @param {CodeceptJS.LocatorOrString} [context] (optional) element located by CSS|XPath|strict locator in which to perfrom search.
+   * [!] returns a _promise_ which is synchronized internally by recorder
    */
   async dontSee(text, context = null) {
     if (this.isWeb) return super.dontSee(text, context);
@@ -1479,9 +1479,9 @@ class Appium extends Webdriver {
    * // or by strict locator
    * I.fillField({css: 'form#login input[name=username]'}, 'John');
    * ```
-   * @param {string | object} field located by label|name|CSS|XPath|strict locator.
-   * @param {string | object} value text value to fill.
-   * 
+   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
+   * @param {CodeceptJS.StringOrSecret} value text value to fill.
+   * [!] returns a _promise_ which is synchronized internally by recorder
    *
    */
   async fillField(field, value) {
@@ -1498,7 +1498,7 @@ class Appium extends Webdriver {
    * let pins = await I.grabTextFromAll('#pin li');
    * ```
    * 
-   * @param {string | object} locator element located by CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
    * @returns {Promise<string[]>} attribute value
    * 
    *
@@ -1517,7 +1517,7 @@ class Appium extends Webdriver {
    * ```
    * If multiple elements found returns first element.
    * 
-   * @param {string | object} locator element located by CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
    * @returns {Promise<string>} attribute value
    * 
    *
@@ -1535,7 +1535,7 @@ class Appium extends Webdriver {
    * let numOfElements = await I.grabNumberOfVisibleElements('p');
    * ```
    * 
-   * @param {string | object} locator located by CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
    * @returns {Promise<number>} number of visible elements
    */
   async grabNumberOfVisibleElements(locator) {
@@ -1553,7 +1553,7 @@ class Appium extends Webdriver {
    * ```js
    * let hint = await I.grabAttributeFrom('#tooltip', 'title');
    * ```
-   * @param {string | object} locator element located by CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
    * @param {string} attr attribute name.
    * @returns {Promise<string>} attribute value
    * 
@@ -1571,7 +1571,7 @@ class Appium extends Webdriver {
    * ```js
    * let hints = await I.grabAttributeFromAll('.tooltip', 'title');
    * ```
-   * @param {string | object} locator element located by CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
    * @param {string} attr attribute name.
    * @returns {Promise<string[]>} attribute value
    * 
@@ -1588,7 +1588,7 @@ class Appium extends Webdriver {
    * ```js
    * let inputs = await I.grabValueFromAll('//form/input');
    * ```
-   * @param {string | object} locator field located by label|name|CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator field located by label|name|CSS|XPath|strict locator.
    * @returns {Promise<string[]>} attribute value
    * 
    *
@@ -1606,7 +1606,7 @@ class Appium extends Webdriver {
    * ```js
    * let email = await I.grabValueFrom('input[name=email]');
    * ```
-   * @param {string | object} locator field located by label|name|CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator field located by label|name|CSS|XPath|strict locator.
    * @returns {Promise<string>} attribute value
    * 
    *
@@ -1640,9 +1640,9 @@ class Appium extends Webdriver {
    * I.scrollIntoView('#submit', { behavior: "smooth", block: "center", inline: "center" });
    * ```
    * 
-   * @param {string | object} locator located by CSS|XPath|strict locator.
+   * @param {LocatorOrString} locator located by CSS|XPath|strict locator.
    * @param {ScrollIntoViewOptions} scrollIntoViewOptions see https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView.
-   * 
+   * [!] returns a _promise_ which is synchronized internally by recorder
    *
    * Supported only for web testing
    */
@@ -1659,8 +1659,8 @@ class Appium extends Webdriver {
    * I.seeCheckboxIsChecked({css: '#signup_form input[type=checkbox]'});
    * ```
    * 
-   * @param {string | object} field located by label|name|CSS|XPath|strict locator.
-   * 
+   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
+   * [!] returns a _promise_ which is synchronized internally by recorder
    *
    */
   async seeCheckboxIsChecked(field) {
@@ -1675,7 +1675,8 @@ class Appium extends Webdriver {
    * ```js
    * I.seeElement('#modal');
    * ```
-   * @param {string | object} locator located by CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
+   * [!] returns a _promise_ which is synchronized internally by recorder
    *
    */
   async seeElement(locator) {
@@ -1693,9 +1694,9 @@ class Appium extends Webdriver {
    * I.seeInField('form input[type=hidden]','hidden_value');
    * I.seeInField('#searchform input','Search');
    * ```
-   * @param {string | object} field located by label|name|CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
    * @param {string} value value to check.
-   * 
+   * [!] returns a _promise_ which is synchronized internally by recorder
    *
    */
   async seeInField(field, value) {
@@ -1713,7 +1714,8 @@ class Appium extends Webdriver {
    * I.see('Register', {css: 'form.register'}); // use strict locator
    * ```
    * @param {string} text expected on page.
-   * @param {?string | object} [context=null] (optional, `null` by default) element located by CSS|Xpath|strict locator in which to search for text.
+   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS|Xpath|strict locator in which to search for text.
+   * [!] returns a _promise_ which is synchronized internally by recorder
    *
    */
   async see(text, context) {
@@ -1740,9 +1742,9 @@ class Appium extends Webdriver {
    * ```js
    * I.selectOption('Which OS do you use?', ['Android', 'iOS']);
    * ```
-   * @param {string | object} select field located by label|name|CSS|XPath|strict locator.
+   * @param {LocatorOrString} select field located by label|name|CSS|XPath|strict locator.
    * @param {string|Array<*>} option visible text or value of option.
-   * 
+   * [!] returns a _promise_ which is synchronized internally by recorder
    *
    * Supported only for web testing
    */
@@ -1760,8 +1762,9 @@ class Appium extends Webdriver {
    * I.waitForElement('.btn.continue', 5); // wait for 5 secs
    * ```
    * 
-   * @param {string | object} locator element located by CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
    * @param {number} [sec] (optional, `1` by default) time in seconds to wait
+   * [!] returns a _promise_ which is synchronized internally by recorder
    *
    */
   async waitForElement(locator, sec = null) {
@@ -1777,9 +1780,9 @@ class Appium extends Webdriver {
    * I.waitForVisible('#popup');
    * ```
    * 
-   * @param {string | object} locator element located by CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
    * @param {number} [sec=1] (optional, `1` by default) time in seconds to wait
-   * 
+   * [!] returns a _promise_ which is synchronized internally by recorder
    *
    */
   async waitForVisible(locator, sec = null) {
@@ -1795,8 +1798,9 @@ class Appium extends Webdriver {
    * I.waitForInvisible('#popup');
    * ```
    * 
-   * @param {string | object} locator element located by CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
    * @param {number} [sec=1] (optional, `1` by default) time in seconds to wait
+   * [!] returns a _promise_ which is synchronized internally by recorder
    *
    */
   async waitForInvisible(locator, sec = null) {
@@ -1816,7 +1820,8 @@ class Appium extends Webdriver {
    * 
    * @param {string }text to wait for.
    * @param {number} [sec=1] (optional, `1` by default) time in seconds to wait
-   * @param {string | object} [context] (optional) element located by CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} [context] (optional) element located by CSS|XPath|strict locator.
+   * [!] returns a _promise_ which is synchronized internally by recorder
    *
    */
   async waitForText(text, sec = null, context = null) {

package/docs/build/GraphQL.js

@@ -112,15 +112,15 @@ class GraphQL extends Helper {
    *
    * @param {object} operation
    * @param {object} headers
+   * @return {object} graphQLRequest
    */
   _prepareGraphQLRequest(operation, headers) {
-    const request = {
+    return {
       baseURL: this.options.endpoint,
       method: 'POST',
       data: operation,
       headers,
     };
-    return request;
   }
 
   /**
@@ -142,6 +142,7 @@ class GraphQL extends Helper {
    * @param {object} variables that may go along with the query
    * @param {object} options are additional query options
    * @param {object} headers
+   * @return Promise<any>
    */
   async sendQuery(query, variables, options = {}, headers = {}) {
     if (typeof query !== 'string') {
@@ -181,6 +182,7 @@ class GraphQL extends Helper {
    * @param {object} variables that may go along with the mutation
    * @param {object} options are additional query options
    * @param {object} headers
+   * @return Promise<any>
    */
   async sendMutation(mutation, variables, options = {}, headers = {}) {
     if (typeof mutation !== 'string') {

package/docs/build/GraphQLDataFactory.js

@@ -36,7 +36,7 @@ const GraphQL = require('./GraphQL');
  * Install [Rosie](https://github.com/rosiejs/rosie) and [Faker](https://www.npmjs.com/package/faker) libraries.
  *
  * ```sh
- * npm i rosie faker --save-dev
+ * npm i rosie @faker-js/faker --save-dev
  * ```
  *
  * Create a factory file for a resource.
@@ -46,8 +46,8 @@ const GraphQL = require('./GraphQL');
  * ```js
  * // tests/factories/users.js
  *
- * var Factory = require('rosie').Factory;
- * var faker = require('faker');
+ * const Factory = require('rosie').Factory;
+ * const faker = require('@faker-js/faker');
  *
  * // Used with a constructor function passed to Factory, so that the final build
  * // object matches the necessary pattern to be sent as the variables object.

package/docs/build/JSONResponse.js

@@ -218,7 +218,7 @@ class JSONResponse extends Helper {
    * Use it to perform custom checks of response data
    *
    * ```js
-   * I.seeResponseValidByCallback({ data, status, expect } => {
+   * I.seeResponseValidByCallback(({ data, status, expect }) => {
    *   expect(status).to.eql(200);
    *   expect(data).keys.to.include(['user', 'company']);
    * });