codeceptjs 3.3.3 → 3.3.5-beta.2

package/CHANGELOG.md

@@ -1,3 +1,41 @@
+## 3.3.4
+
+* Added support for masking fields in objects via `secret` function:
+
+```js
+I.sendPostRequest('/auth', secret({ name: 'jon', password: '123456' }, 'password'));
+```
+* Added [a guide about using of `secret`](/secrets) function
+* [Appium] Use `touchClick` when interacting with elements in iOS. See #3317 by @mikk150
+* [Playwright] Added `cdpConnection` option to connect over CDP. See #3309 by @Hmihaly 
+* [customLocator plugin] Allowed to specify multiple attributes for custom locator. Thanks to @aruiz-caritsqa
+
+```js
+plugins: {
+ customLocator: {
+   enabled: true,
+   prefix: '$',
+   attribute: ['data-qa', 'data-test'],
+ }
+}
+```
+* [retryTo plugin] Fixed #3147 using `pollInterval` option. See #3351 by @cyonkee
+* [Playwright] Fixed grabbing of browser console messages and window resize in new tab. Thanks to @mirao
+* [REST] Added `prettyPrintJson` option to print JSON in nice way by @PeterNgTr 
+* [JSONResponse] Updated response validation to iterate over array items if response is array. Thanks to @PeterNgTr
+
+```js
+// response.data == [
+//   { user: { name: 'jon', email: 'jon@doe.com' } },
+//   { user: { name: 'matt', email: 'matt@doe.com' } },
+//]
+
+I.seeResponseContainsKeys(['user']);
+I.seeResponseContainsJson({ user: { email: 'jon@doe.com' } });
+I.seeResponseContainsJson({ user: { email: 'matt@doe.com' } });
+I.dontSeeResponseContainsJson({ user: 2 });
+```
+
 ## 3.3.3
 
 * Fixed `DataCloneError: () => could not be cloned` when running data tests in run-workers

package/docs/api.md

@@ -263,6 +263,8 @@ The most basic thing to check in response is existence of keys in JSON object. U
 I.seeResponseContainsKeys(['name', 'email']);
 ```
 
+> ℹ️ If response is an array, it will check that every element in array have provided keys
+
 However, this is a very naive approach. It won't work for arrays or nested objects.
 To check complex JSON structures `JSONResponse` helper uses [`joi`](https://joi.dev) library. 
 It has rich API to validate JSON by the schema defined using JavaScript. 
@@ -296,6 +298,8 @@ I.seeResponseContainsJson({
 })
 ```
 
+> ℹ️ If response is an array, it will check that at least one element in array matches JSON
+
 To perform arbitrary assertions on a response object use `seeResponseValidByCallback`. 
 It allows you to do any kind of assertions by using `expect` from [`chai`](https://www.chaijs.com) library.
 

package/docs/basics.md

@@ -212,6 +212,8 @@ To fill in sensitive data use the `secret` function, it won't expose actual valu
 I.fillField('password', secret('123456'));
 ```
 
+> ℹ️ Learn more about [masking secret](/secrets/) output
+
 ### Assertions
 
 In order to verify the expected behavior of a web application, its content should be checked.

package/docs/bdd.md

@@ -356,6 +356,18 @@ In case scenarios represent the same logic but differ on data, we can use *Scena
       | 50    | 45    |
 ```
 
+It might be the case that the same column value needs to be utilized multiple times in the same step, that also can be possible with scenario outline.
+
+```gherkin
+  Scenario Outline: check parameter substitution
+    Given I have a defined step
+    When I see "<text>" text and "<text>" is not "xyz"
+    Examples:
+      | text   |
+      | Google |
+
+```
+
 ### Long Strings
 
 Text values inside a scenarios can be set inside a `"""` block:

package/docs/build/JSONResponse.js

@@ -1,3 +1,4 @@
+const assert = require('assert');
 const chai = require('chai');
 const joi = require('joi');
 const chaiDeepMatch = require('chai-deep-match');
@@ -173,12 +174,30 @@ class JSONResponse extends Helper {
    *
    * I.seeResponseContainsJson({ user: { email: 'jon@doe.com' } });
    * ```
+   * If an array is received, checks that at least one element contains JSON
+   * ```js
+   * // response.data == [{ user: { name: 'jon', email: 'jon@doe.com' } }]
+   *
+   * I.seeResponseContainsJson({ user: { email: 'jon@doe.com' } });
+   * ```
    *
    * @param {object} json
    */
   seeResponseContainsJson(json = {}) {
     this._checkResponseReady();
-    expect(this.response.data).to.deep.match(json);
+    if (Array.isArray(this.response.data)) {
+      let fails = 0;
+      for (const el of this.response.data) {
+        try {
+          expect(el).to.deep.match(json);
+        } catch (err) {
+          fails++;
+        }
+      }
+      assert.ok(fails < this.response.data.length, `No elements in array matched ${JSON.stringify(json)}`);
+    } else {
+      expect(this.response.data).to.deep.match(json);
+    }
   }
 
   /**
@@ -189,12 +208,22 @@ class JSONResponse extends Helper {
    *
    * I.dontSeeResponseContainsJson({ user: 2 });
    * ```
+   * If an array is received, checks that no element of array contains json:
+   * ```js
+   * // response.data == [{ user: 1 }, { user: 3 }]
+   *
+   * I.dontSeeResponseContainsJson({ user: 2 });
+   * ```
    *
    * @param {object} json
    */
   dontSeeResponseContainsJson(json = {}) {
     this._checkResponseReady();
-    expect(this.response.data).not.to.deep.match(json);
+    if (Array.isArray(this.response.data)) {
+      this.response.data.forEach(data => expect(data).not.to.deep.match(json));
+    } else {
+      expect(this.response.data).not.to.deep.match(json);
+    }
   }
 
   /**
@@ -206,11 +235,23 @@ class JSONResponse extends Helper {
    * I.seeResponseContainsKeys(['user']);
    * ```
    *
+   * If an array is received, check is performed for each element of array:
+   *
+   * ```js
+   * // response.data == [{ user: 'jon' }, { user: 'matt'}]
+   *
+   * I.seeResponseContainsKeys(['user']);
+   * ```
+   *
    * @param {array} keys
    */
   seeResponseContainsKeys(keys = []) {
     this._checkResponseReady();
-    expect(this.response.data).to.include.keys(keys);
+    if (Array.isArray(this.response.data)) {
+      this.response.data.forEach(data => expect(data).to.include.keys(keys));
+    } else {
+      expect(this.response.data).to.include.keys(keys);
+    }
   }
 
   /**

package/docs/build/Playwright.js

@@ -44,6 +44,46 @@ const {
 } = require('./extras/PlaywrightRestartOpts');
 const { createValueEngine, createDisabledEngine } = require('./extras/PlaywrightPropEngine');
 
+/**
+ * ## Configuration
+ *
+ * This helper should be configured in codecept.conf.js
+ *
+ * @typedef PlaywrightConfig
+ * @type {object}
+ * @prop {string} url - base url of website to be tested
+ * @prop {string} browser - a browser to test on, either: `chromium`, `firefox`, `webkit`, `electron`. Default: chromium.
+ * @prop {boolean} [show=false] - show browser window.
+ * @prop {string|boolean} [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
+ * @prop {number} [timeout=1000] - -  [timeout](https://playwright.dev/docs/api/class-page#page-set-default-timeout) in ms of all Playwright actions .
+ * @prop {boolean} [disableScreenshots=false] - don't save screenshot on failure.
+ * @prop {any} [emulate] - browser in device emulation mode.
+ * @prop {boolean} [video=false] - enables video recording for failed tests; videos are saved into `output/videos` folder
+ * @prop {boolean} [trace=false] - record [tracing information](https://playwright.dev/docs/trace-viewer) with screenshots and snapshots.
+ * @prop {boolean} [fullPageScreenshots=false] - make full page screenshots on failure.
+ * @prop {boolean} [uniqueScreenshotNames=false] - option to prevent screenshot override if you have scenarios with the same name in different suites.
+ * @prop {boolean} [keepBrowserState=false] - keep browser state between tests when `restart` is set to 'session'.
+ * @prop {boolean} [keepCookies=false] - keep cookies between tests when `restart` is set to 'session'.
+ * @prop {number} [waitForAction] - how long to wait after click, doubleClick or PressKey actions in ms. Default: 100.
+ * @prop {number} [waitForNavigation] - When to consider navigation succeeded. Possible options: `load`, `domcontentloaded`, `networkidle`. Choose one of those options is possible. See [Playwright API](https://github.com/microsoft/playwright/blob/main/docs/api.md#pagewaitfornavigationoptions).
+ * @prop {number} [pressKeyDelay=10] - Delay between key presses in ms. Used when calling Playwrights page.type(...) in fillField/appendField
+ * @prop {number} [getPageTimeout] - config option to set maximum navigation time in milliseconds.
+ * @prop {number} [waitForTimeout] - default wait* timeout in ms. Default: 1000.
+ * @prop {object} [basicAuth] - the basic authentication to pass to base url. Example: {username: 'username', password: 'password'}
+ * @prop {string} [windowSize] - default window size. Set a dimension like `640x480`.
+ * @prop {string} [colorScheme] - default color scheme. Possible values: `dark` | `light` | `no-preference`.
+ * @prop {string} [userAgent] - user-agent string.
+ * @prop {string} [locale] - locale string. Example: 'en-GB', 'de-DE', 'fr-FR', ...
+ * @prop {boolean} [manualStart] - do not start browser before a test, start it manually inside a helper with `this.helpers["Playwright"]._startBrowser()`.
+ * @prop {object} [chromium] - pass additional chromium options
+ * @prop {object} [electron] - (pass additional electron options
+ * @prop {any} [channel] - (While Playwright can operate against the stock Google Chrome and Microsoft Edge browsers available on the machine. In particular, current Playwright version will support Stable and Beta channels of these browsers. See [Google Chrome & Microsoft Edge](https://playwright.dev/docs/browsers/#google-chrome--microsoft-edge).
+ */
+const config = {};
+
 /**
  * Uses [Playwright](https://github.com/microsoft/playwright) library to run tests inside:
  *
@@ -65,46 +105,14 @@ const { createValueEngine, createDisabledEngine } = require('./extras/Playwright
  *
  * Using playwright-core package, will prevent the download of browser binaries and allow connecting to an existing browser installation or for connecting to a remote one.
  *
- * ## Configuration
  *
- * This helper should be configured in codecept.json or codecept.conf.js
- *
- * * `url`: base url of website to be tested
- * * `browser`: a browser to test on, either: `chromium`, `firefox`, `webkit`, `electron`. Default: chromium.
- * * `show`: (optional, default: false) - show browser window.
- * * `restart`: (optional, default: 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
- * * `timeout`: (optional, default: 1000) -  [timeout](https://playwright.dev/docs/api/class-page#page-set-default-timeout) in ms of all Playwright actions .
- * * `disableScreenshots`: (optional, default: false)  - don't save screenshot on failure.
- * * `emulate`: (optional, default: {}) launch browser in device emulation mode.
- * * `video`: (optional, default: false) enables video recording for failed tests; videos are saved into `output/videos` folder
- * * `trace`: (optional, default: false) record [tracing information](https://playwright.dev/docs/trace-viewer) with screenshots and snapshots.
- * * `fullPageScreenshots` (optional, default: false) - make full page screenshots on failure.
- * * `uniqueScreenshotNames`: (optional, default: false)  - option to prevent screenshot override if you have scenarios with the same name in different suites.
- * * `keepBrowserState`: (optional, default: false) - keep browser state between tests when `restart` is set to 'session'.
- * * `keepCookies`: (optional, default: false) - keep cookies between tests when `restart` is set to 'session'.
- * * `waitForAction`: (optional) how long to wait after click, doubleClick or PressKey actions in ms. Default: 100.
- * * `waitForNavigation`: (optional, default: 'load'). When to consider navigation succeeded. Possible options: `load`, `domcontentloaded`, `networkidle`. Choose one of those options is possible. See [Playwright API](https://github.com/microsoft/playwright/blob/main/docs/api.md#pagewaitfornavigationoptions).
- * * `pressKeyDelay`: (optional, default: '10'). Delay between key presses in ms. Used when calling Playwrights page.type(...) in fillField/appendField
- * * `getPageTimeout` (optional, default: '0') config option to set maximum navigation time in milliseconds.
- * * `waitForTimeout`: (optional) default wait* timeout in ms. Default: 1000.
- * * `basicAuth`: (optional) the basic authentication to pass to base url. Example: {username: 'username', password: 'password'}
- * * `windowSize`: (optional) default window size. Set a dimension like `640x480`.
- * * `colorScheme`: (optional) default color scheme. Possible values: `dark` | `light` | `no-preference`.
- * * `userAgent`: (optional) user-agent string.
- * * `locale`: (optional) locale string. Example: 'en-GB', 'de-DE', 'fr-FR', ...
- * * `manualStart`: (optional, default: false) - do not start browser before a test, start it manually inside a helper with `this.helpers["Playwright"]._startBrowser()`.
- * * `chromium`: (optional) pass additional chromium options
- * * `electron`: (optional) pass additional electron options
- * * `channel`: (optional) While Playwright can operate against the stock Google Chrome and Microsoft Edge browsers available on the machine. In particular, current Playwright version will support Stable and Beta channels of these browsers. See [Google Chrome & Microsoft Edge](https://playwright.dev/docs/browsers/#google-chrome--microsoft-edge).
+ * <!-- configuration -->
  *
  * #### Video Recording Customization
  *
  * By default, video is saved to `output/video` dir. You can customize this path by passing `dir` option to `recordVideo` option.
  *
- * * `video`: enables video recording for failed tests; videos are saved into `output/videos` folder
+ * `video`: enables video recording for failed tests; videos are saved into `output/videos` folder
  * * `keepVideoForPassedTests`: - save videos for passed tests
  * * `recordVideo`: [additional options for videos customization](https://playwright.dev/docs/next/api/class-browser#browser-new-context)
  *
@@ -167,7 +175,8 @@ const { createValueEngine, createDisabledEngine } = require('./extras/Playwright
  *      Playwright: {
  *        url: "http://localhost",
  *        chromium: {
- *          browserWSEndpoint: 'ws://localhost:9222/devtools/browser/c5aa6160-b5bc-4d53-bb49-6ecb36cd2e0a'
+ *          browserWSEndpoint: 'ws://localhost:9222/devtools/browser/c5aa6160-b5bc-4d53-bb49-6ecb36cd2e0a',
+ *          cdpConnection: false // default is false
  *        }
  *      }
  *    }
@@ -256,8 +265,6 @@ const { createValueEngine, createDisabledEngine } = require('./extras/Playwright
  * const { browserContext } = this.helpers.Playwright;
  * await browserContext.cookies(); // get current browser context
  * ```
- *
- * ## Methods
  */
 class Playwright extends Helper {
   constructor(config) {
@@ -272,6 +279,7 @@ class Playwright extends Helper {
     this.sessionPages = {};
     this.activeSessionName = '';
     this.isElectron = false;
+    this.isCDPConnection = false;
     this.electronSessions = [];
     this.storageState = null;
 
@@ -347,6 +355,7 @@ class Playwright extends Helper {
     this.isRemoteBrowser = !!this.playwrightOptions.browserWSEndpoint;
     this.isElectron = this.options.browser === 'electron';
     this.userDataDir = this.playwrightOptions.userDataDir;
+    this.isCDPConnection = this.playwrightOptions.cdpConnection;
     popupStore.defaultAction = this.options.defaultPopupAction;
   }
 
@@ -699,6 +708,15 @@ class Playwright extends Helper {
   async _startBrowser() {
     if (this.isElectron) {
       this.browser = await playwright._electron.launch(this.playwrightOptions);
+    } else if (this.isRemoteBrowser && this.isCDPConnection) {
+      try {
+        this.browser = await playwright[this.options.browser].connectOverCDP(this.playwrightOptions);
+      } catch (err) {
+        if (err.toString().indexOf('ECONNREFUSED')) {
+          throw new RemoteBrowserConnectionRefused(err);
+        }
+        throw err;
+      }
     } else if (this.isRemoteBrowser) {
       try {
         this.browser = await playwright[this.options.browser].connect(this.playwrightOptions);
@@ -1157,6 +1175,7 @@ class Playwright extends Helper {
     if (!page) {
       throw new Error(`There is no ability to switch to next tab with offset ${num}`);
     }
+    targetCreatedHandler.call(this, page);
     await this._setPage(page);
     return this._waitForAction();
   }
@@ -1239,7 +1258,9 @@ class Playwright extends Helper {
     if (this.isElectron) {
       throw new Error('Cannot open new tabs inside an Electron container');
     }
-    await this._setPage(await this.browserContext.newPage(options));
+    const page = await this.browserContext.newPage(options);
+    targetCreatedHandler.call(this, page);
+    await this._setPage(page);
     return this._waitForAction();
   }
 
@@ -2071,9 +2092,11 @@ class Playwright extends Helper {
    * Get JS log from browser.
    *
    * ```js
-   * let logs = await I.grabBrowserLogs();
-   * console.log(JSON.stringify(logs))
+   * const logs = await I.grabBrowserLogs();
+   * const errors = logs.map(l => ({ type: l.type(), text: l.text() })).filter(l => l.type === 'error');
+   * console.log(JSON.stringify(errors));
    * ```
+   * [Learn more about console messages](https://playwright.dev/docs/api/class-consolemessage)
    * @return {Promise<any[]>}
    */
   async grabBrowserLogs() {

package/docs/build/Puppeteer.js

@@ -39,6 +39,35 @@ let perfTiming;
 const popupStore = new Popup();
 const consoleLogStore = new Console();
 
+/**
+ * ## Configuration
+ *
+ * This helper should be configured in codecept.conf.js
+ *
+ * @typedef PuppeteerConfig
+ * @type {object}
+ * @prop {string} url - base url of website to be tested
+ * @prop {object} [basicAuth] (optional) the basic authentication to pass to base url. Example: {username: 'username', password: 'password'}
+ * @prop {boolean} [show] - show Google Chrome window for debug.
+ * @prop {boolean} [restart=true] - restart browser between tests.
+ * @prop {boolean} [disableScreenshots=false]  - don't save screenshot on failure.
+ * @prop {boolean} [fullPageScreenshots=false] - make full page screenshots on failure.
+ * @prop {boolean} [uniqueScreenshotNames=false]  - option to prevent screenshot override if you have scenarios with the same name in different suites.
+ * @prop {boolean} [keepBrowserState=false] - keep browser state between tests when `restart` is set to false.
+ * @prop {boolean} [keepCookies=false] - keep cookies between tests when `restart` is set to false.
+ * @prop {number} [waitForAction=100] - how long to wait after click, doubleClick or PressKey actions in ms. Default: 100.
+ * @prop {string} [waitForNavigation=load] - when to consider navigation succeeded. Possible options: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`. See [Puppeteer API](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagewaitfornavigationoptions). Array values are accepted as well.
+ * @prop {number} [pressKeyDelay=10] - delay between key presses in ms. Used when calling Puppeteers page.type(...) in fillField/appendField
+ * @prop {number} [getPageTimeout=30000] - config option to set maximum navigation time in milliseconds. If the timeout is set to 0, then timeout will be disabled.
+ * @prop {number} [waitForTimeout=1000] - default wait* timeout in ms.
+ * @prop {string} [windowSize] - default window size. Set a dimension in format WIDTHxHEIGHT like `640x480`.
+ * @prop {string} [userAgent] - user-agent string.
+ * @prop {boolean} [manualStart=false] - do not start browser before a test, start it manually inside a helper with `this.helpers["Puppeteer"]._startBrowser()`.
+ * @prop {string} [browser=chrome] - can be changed to `firefox` when using [puppeteer-firefox](https://codecept.io/helpers/Puppeteer-firefox).
+ * @prop {object} [chrome] - pass additional [Puppeteer run options](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions).
+*/
+const config = {};
+
 /**
  * Uses [Google Chrome's Puppeteer](https://github.com/GoogleChrome/puppeteer) library to run tests inside headless Chrome.
  * Browser control is executed via DevTools Protocol (instead of Selenium).
@@ -56,30 +85,7 @@ const consoleLogStore = new Console();
  *
  * > Experimental Firefox support [can be activated](https://codecept.io/helpers/Puppeteer-firefox).
  *
- * ## Configuration
- *
- * This helper should be configured in codecept.json or codecept.conf.js
- *
- * * `url`: base url of website to be tested
- * * `basicAuth`: (optional) the basic authentication to pass to base url. Example: {username: 'username', password: 'password'}
- * * `show`: (optional, default: false) - show Google Chrome window for debug.
- * * `restart`: (optional, default: true) - restart browser between tests.
- * * `disableScreenshots`: (optional, default: false)  - don't save screenshot on failure.
- * * `fullPageScreenshots` (optional, default: false) - make full page screenshots on failure.
- * * `uniqueScreenshotNames`: (optional, default: false)  - option to prevent screenshot override if you have scenarios with the same name in different suites.
- * * `keepBrowserState`: (optional, default: false) - keep browser state between tests when `restart` is set to false.
- * * `keepCookies`: (optional, default: false) - keep cookies between tests when `restart` is set to false.
- * * `waitForAction`: (optional) how long to wait after click, doubleClick or PressKey actions in ms. Default: 100.
- * * `waitForNavigation`: (optional, default: 'load'). When to consider navigation succeeded. Possible options: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`. See [Puppeteer API](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagewaitfornavigationoptions). Array values are accepted as well.
- * * `pressKeyDelay`: (optional, default: '10'). Delay between key presses in ms. Used when calling Puppeteers page.type(...) in fillField/appendField
- * * `getPageTimeout` (optional, default: '30000') config option to set maximum navigation time in milliseconds. If the timeout is set to 0, then timeout will be disabled.
- * * `waitForTimeout`: (optional) default wait* timeout in ms. Default: 1000.
- * * `windowSize`: (optional) default window size. Set a dimension like `640x480`.
- * * `userAgent`: (optional) user-agent string.
- * * `manualStart`: (optional, default: false) - do not start browser before a test, start it manually inside a helper with `this.helpers["Puppeteer"]._startBrowser()`.
- * * `browser`: (optional, default: chrome) - can be changed to `firefox` when using [puppeteer-firefox](https://codecept.io/helpers/Puppeteer-firefox).
- * * `chrome`: (optional) pass additional [Puppeteer run options](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions).
- *
+ * <!-- configuration -->
  *
  * #### Example #1: Wait for 0 network connections.
  *
@@ -192,7 +198,6 @@ class Puppeteer extends Helper {
     super(config);
 
     puppeteer = requireWithFallback('puppeteer', 'puppeteer-core');
-
     // set defaults
     this.isRemoteBrowser = false;
     this.isRunning = false;
@@ -372,22 +377,22 @@ class Puppeteer extends Helper {
   }
 
   /**
-  * Use Puppeteer API inside a test.
-  *
-  * First argument is a description of an action.
-  * Second argument is async function that gets this helper as parameter.
-  *
-  * { [`page`](https://github.com/puppeteer/puppeteer/blob/master/docs/api.md#class-page), [`browser`](https://github.com/puppeteer/puppeteer/blob/master/docs/api.md#class-browser) } from Puppeteer API are available.
-  *
-  * ```js
-  * I.usePuppeteerTo('emulate offline mode', async ({ page }) {
-  *   await page.setOfflineMode(true);
-  * });
-  * ```
-  *
-  * @param {string} description used to show in logs.
-  * @param {function} fn async function that is executed with Puppeteer as argument
-  */
+   * Use Puppeteer API inside a test.
+   *
+   * First argument is a description of an action.
+   * Second argument is async function that gets this helper as parameter.
+   *
+   * { [`page`](https://github.com/puppeteer/puppeteer/blob/master/docs/api.md#class-page), [`browser`](https://github.com/puppeteer/puppeteer/blob/master/docs/api.md#class-browser) } from Puppeteer API are available.
+   *
+   * ```js
+   * I.usePuppeteerTo('emulate offline mode', async ({ page }) {
+   *   await page.setOfflineMode(true);
+   * });
+   * ```
+   *
+   * @param {string} description used to show in logs.
+   * @param {function} fn async function that is executed with Puppeteer as argument
+   */
   usePuppeteerTo(description, fn) {
     return this._useTo(...arguments);
   }
@@ -816,7 +821,8 @@ class Puppeteer extends Helper {
     if (locator) {
       const els = await this._locate(locator);
       assertElementExists(els, locator, 'Element');
-      await els[0]._scrollIntoViewIfNeeded();
+      const el = els[0];
+      await el.evaluate((el) => el.scrollIntoView());
       const elementCoordinates = await getClickablePoint(els[0]);
       await this.executeScript((x, y) => window.scrollBy(x, y), elementCoordinates.x + offsetX, elementCoordinates.y + offsetY);
     } else {
@@ -1268,7 +1274,12 @@ class Puppeteer extends Helper {
       fs.mkdirSync(downloadPath, '0777');
     }
     fsExtra.emptyDirSync(downloadPath);
-    return this.page._client.send('Page.setDownloadBehavior', { behavior: 'allow', downloadPath });
+
+    try {
+      return this.page._client.send('Page.setDownloadBehavior', { behavior: 'allow', downloadPath });
+    } catch (e) {
+      return this.page._client().send('Page.setDownloadBehavior', { behavior: 'allow', downloadPath });
+    }
   }
 
   /**

package/docs/build/REST.js

@@ -2,18 +2,28 @@ const axios = require('axios').default;
 const Secret = require('../secret');
 
 const Helper = require('../helper');
+const { beautify } = require('../utils');
+
+/**
+ * ## Configuration
+ *
+ * @typedef RESTConfig
+ * @type {object}
+ * @prop {string} endpoint - API base URL
+ * @prop {boolean} [prettyPrintJson=false] - pretty print json for response/request on console logs
+ * @prop {number} [timeout=1000] - timeout for requests in milliseconds. 10000ms by default
+ * @prop {object} [defaultHeaders] - a list of default headers
+ * @prop {function} [onRequest] - a async function which can update request object.
+ * @prop {function} [onResponse] - a async function which can update response object.
+ * @prop {number} [maxUploadFileSize] - set the max content file size in MB when performing api calls.
+ */
+const config = {};
 
 /**
  * REST helper allows to send additional requests to the REST API during acceptance tests.
  * [Axios](https://github.com/axios/axios) library is used to perform requests.
  *
- * ## Configuration
- *
- * * endpoint: API base URL
- * * timeout: timeout for requests in milliseconds. 10000ms by default
- * * defaultHeaders: a list of default headers
- * * onRequest: a async function which can update request object.
- * * maxUploadFileSize: set the max content file size in MB when performing api calls.
+ * <!-- configuration -->
  *
  * ## Example
  *
@@ -22,6 +32,7 @@ const Helper = require('../helper');
  *   helpers: {
  *     REST: {
  *       endpoint: 'http://site.com/api',
+ *       prettyPrintJson: true,
  *       onRequest: (request) => {
  *       request.headers.auth = '123';
  *     }
@@ -49,6 +60,9 @@ class REST extends Helper {
       timeout: 10000,
       defaultHeaders: {},
       endpoint: '',
+      prettyPrintJson: false,
+      onRequest: null,
+      onResponse: null,
     };
 
     if (this.options.maxContentLength) {
@@ -137,7 +151,7 @@ class REST extends Helper {
       await this.config.onRequest(request);
     }
 
-    this.debugSection('Request', JSON.stringify(_debugRequest));
+    this.options.prettyPrintJson ? this.debugSection('Request', beautify(JSON.stringify(_debugRequest))) : this.debugSection('Request', JSON.stringify(_debugRequest));
 
     let response;
     try {
@@ -150,7 +164,7 @@ class REST extends Helper {
     if (this.config.onResponse) {
       await this.config.onResponse(response);
     }
-    this.debugSection('Response', JSON.stringify(response.data));
+    this.options.prettyPrintJson ? this.debugSection('Response', beautify(JSON.stringify(response.data))) : this.debugSection('Response', JSON.stringify(response.data));
     return response;
   }