codeceptjs 3.2.3 → 3.3.0-beta.1

package/docs/build/Playwright.js

@@ -19,6 +19,7 @@ const {
   getNormalizedKeyAttributeValue,
   isModifierKey,
   clearString,
+  requireWithFallback,
 } = require('../utils');
 const {
   isColorProperty,
@@ -38,6 +39,9 @@ const popupStore = new Popup();
 const consoleLogStore = new Console();
 const availableBrowsers = ['chromium', 'webkit', 'firefox', 'electron'];
 
+const {
+  setRestartStrategy, restartsSession, restartsContext, restartsBrowser,
+} = require('./extras/PlaywrightRestartOpts');
 const { createValueEngine, createDisabledEngine } = require('./extras/PlaywrightPropEngine');
 
 /**
@@ -49,12 +53,18 @@ const { createValueEngine, createDisabledEngine } = require('./extras/Playwright
  *
  * This helper works with a browser out of the box with no additional tools required to install.
  *
- * Requires `playwright` package version ^1 to be installed:
+ * Requires `playwright` or `playwright-core` package version ^1 to be installed:
  *
  * ```
- * npm i playwright@^1 --save
+ * npm i playwright@^1.18 --save
+ * ```
+ * or
+ * ```
+ * npm i playwright-core@^1.18 --save
  * ```
  *
+ * 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
@@ -62,15 +72,19 @@ const { createValueEngine, createDisabledEngine } = require('./extras/Playwright
  * * `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: true) - restart browser between tests.
+ * * `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 false.
- * * `keepCookies`: (optional, default: false) - keep cookies between tests when `restart` is set to false.
+ * * `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
@@ -235,7 +249,7 @@ class Playwright extends Helper {
   constructor(config) {
     super(config);
 
-    playwright = require('playwright');
+    playwright = requireWithFallback('playwright', 'playwright-core');
 
     // set defaults
     this.isRemoteBrowser = false;
@@ -259,8 +273,10 @@ class Playwright extends Helper {
       waitForAction: 100,
       waitForTimeout: 1000,
       pressKeyDelay: 10,
+      timeout: 1000,
       fullPageScreenshots: false,
       disableScreenshots: false,
+      ignoreLog: ['warning', 'log'],
       uniqueScreenshotNames: false,
       manualStart: false,
       getPageTimeout: 0,
@@ -270,6 +286,7 @@ class Playwright extends Helper {
       keepBrowserState: false,
       show: false,
       defaultPopupAction: 'accept',
+      use: { actionTimeout: 0 },
       ignoreHTTPSErrors: false, // Adding it here o that context can be set up to ignore the SSL errors
     };
 
@@ -297,6 +314,7 @@ class Playwright extends Helper {
 
   _setConfig(config) {
     this.options = this._validateConfig(config);
+    setRestartStrategy(this.options);
     this.playwrightOptions = {
       headless: !this.options.show,
       ...this._getOptionsForBrowser(config),
@@ -334,9 +352,9 @@ class Playwright extends Helper {
 
   static _checkRequirements() {
     try {
-      require('playwright');
+      requireWithFallback('playwright', 'playwright-core');
     } catch (e) {
-      return ['playwright@^1'];
+      return ['playwright@^1.18'];
     }
   }
 
@@ -353,7 +371,7 @@ class Playwright extends Helper {
   }
 
   _beforeSuite() {
-    if (!this.options.restart && !this.options.manualStart && !this.isRunning) {
+    if ((restartsSession() || restartsContext()) && !this.options.manualStart && !this.isRunning) {
       this.debugSection('Session', 'Starting singleton browser session');
       return this._startBrowser();
     }
@@ -371,7 +389,7 @@ class Playwright extends Helper {
       },
     });
 
-    if (this.options.restart && !this.options.manualStart) await this._startBrowser();
+    if (restartsBrowser() && !this.options.manualStart) await this._startBrowser();
     if (!this.isRunning && !this.options.manualStart) await this._startBrowser();
 
     this.isAuthenticated = false;
@@ -393,7 +411,9 @@ class Playwright extends Helper {
       if (this.storageState) contextOptions.storageState = this.storageState;
       if (this.options.userAgent) contextOptions.userAgent = this.options.userAgent;
       if (this.options.locale) contextOptions.locale = this.options.locale;
-      this.browserContext = await this.browser.newContext(contextOptions); // Adding the HTTPSError ignore in the context so that we can ignore those errors
+      if (!this.browserContext || !restartsSession()) {
+        this.browserContext = await this.browser.newContext(contextOptions); // Adding the HTTPSError ignore in the context so that we can ignore those errors
+      }
     }
 
     let mainPage;
@@ -421,7 +441,11 @@ class Playwright extends Helper {
       return;
     }
 
-    if (this.options.restart) {
+    if (restartsSession()) {
+      return refreshContextSession.bind(this)();
+    }
+
+    if (restartsBrowser()) {
       this.isRunning = false;
       return this._stopBrowser();
     }
@@ -443,11 +467,10 @@ class Playwright extends Helper {
     return this.browser;
   }
 
-  _afterSuite() {
-  }
+  _afterSuite() {}
 
-  _finishTest() {
-    if (!this.options.restart && this.isRunning) return this._stopBrowser();
+  async _finishTest() {
+    if ((restartsSession() || restartsContext()) && this.isRunning) return this._stopBrowser();
   }
 
   _session() {
@@ -506,16 +529,16 @@ class Playwright extends Helper {
   * First argument is a description of an action.
   * Second argument is async function that gets this helper as parameter.
   *
-  * { [`page`](https://github.com/microsoft/playwright/blob/main/docs/src/api/class-page.md), [`context`](https://github.com/microsoft/playwright/blob/main/docs/src/api/class-browsercontext.md) [`browser`](https://github.com/microsoft/playwright/blob/main/docs/src/api/class-browser.md) } objects from Playwright API are available.
+  * { [`page`](https://github.com/microsoft/playwright/blob/main/docs/src/api/class-page.md), [`browserContext`](https://github.com/microsoft/playwright/blob/main/docs/src/api/class-browsercontext.md) [`browser`](https://github.com/microsoft/playwright/blob/main/docs/src/api/class-browser.md) } objects from Playwright API are available.
   *
   * ```js
-  * I.usePlaywrightTo('emulate offline mode', async ({ context }) => {
-  *   await context.setOffline(true);
+  * I.usePlaywrightTo('emulate offline mode', async ({ browserContext }) => {
+  *   await browserContext.setOffline(true);
   * });
   * ```
   *
   * @param {string} description used to show in logs.
-  * @param {function} fn async functuion that executed with Playwright helper as argument
+  * @param {function} fn async function that executed with Playwright helper as argument
   */
   usePlaywrightTo(description, fn) {
     return this._useTo(...arguments);
@@ -590,7 +613,9 @@ class Playwright extends Helper {
     this._addPopupListener(page);
     this.page = page;
     if (!page) return;
+    this.browserContext.setDefaultTimeout(0);
     page.setDefaultNavigationTimeout(this.options.getPageTimeout);
+    page.setDefaultTimeout(this.options.timeout);
 
     page.on('crash', async () => {
       console.log('ERROR: Page has crashed, closing page!');
@@ -691,7 +716,6 @@ class Playwright extends Helper {
     this._setPage(null);
     this.context = null;
     popupStore.clear();
-
     await this.browser.close();
   }
 
@@ -839,7 +863,7 @@ class Playwright extends Helper {
    * I.moveCursorTo('#submit', 5,5);
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
+   * @param {string | object} locator located by CSS|XPath|strict locator.
    * @param {number} [offsetX=0] (optional, `0` by default) X-axis offset.
    * @param {number} [offsetY=0] (optional, `0` by default) Y-axis offset.
    * 
@@ -862,12 +886,24 @@ class Playwright extends Helper {
    * I.dragAndDrop('#dragHandle', '#container');
    * ```
    * 
-   * @param {LocatorOrString} srcElement located by CSS|XPath|strict locator.
-   * @param {LocatorOrString} destElement located by CSS|XPath|strict locator.
+   * @param {string | object} srcElement located by CSS|XPath|strict locator.
+   * @param {string | object} destElement located by CSS|XPath|strict locator.
    * 
+   *
+   * [Additional options](https://playwright.dev/docs/api/class-page#page-drag-and-drop) can be passed as 3rd argument.
+   *
+   * ```js
+   * // specify coordinates for source position
+   * I.dragAndDrop('img.src', 'img.dst', { sourcePosition: {x: 10, y: 10} })
+   * ```
+   *
+   * > By default option `force: true` is set
    */
-  async dragAndDrop(srcElement, destElement) {
-    return proceedDragAndDrop.call(this, srcElement, destElement);
+  async dragAndDrop(srcElement, destElement, options = { force: true }) {
+    const src = new Locator(srcElement, 'css');
+    const dst = new Locator(destElement, 'css');
+
+    return this.page.dragAndDrop(buildLocatorString(src), buildLocatorString(dst), options);
   }
 
   /**
@@ -924,7 +960,7 @@ class Playwright extends Helper {
    * I.scrollTo('#submit', 5, 5);
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
+   * @param {string | object} locator located by CSS|XPath|strict locator.
    * @param {number} [offsetX=0] (optional, `0` by default) X-axis offset.
    * @param {number} [offsetY=0] (optional, `0` by default) Y-axis offset.
    */
@@ -1212,7 +1248,7 @@ class Playwright extends Helper {
    * ```js
    * I.seeElement('#modal');
    * ```
-   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
+   * @param {string | object} locator located by CSS|XPath|strict locator.
    *
    */
   async seeElement(locator) {
@@ -1228,7 +1264,7 @@ class Playwright extends Helper {
    * I.dontSeeElement('.modal'); // modal is not shown
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|Strict locator.
+   * @param {string | object} locator located by CSS|XPath|Strict locator.
    *
    */
   async dontSeeElement(locator) {
@@ -1244,7 +1280,7 @@ class Playwright extends Helper {
    * ```js
    * I.seeElementInDOM('#modal');
    * ```
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {string | object} locator element located by CSS|XPath|strict locator.
    * 
    */
   async seeElementInDOM(locator) {
@@ -1259,7 +1295,7 @@ class Playwright extends Helper {
    * I.dontSeeElementInDOM('.nav'); // checks that element is not on page visible or not
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|Strict locator.
+   * @param {string | object} locator located by CSS|XPath|Strict locator.
    */
   async dontSeeElementInDOM(locator) {
     const els = await this._locate(locator);
@@ -1319,14 +1355,25 @@ class Playwright extends Helper {
    * I.click({css: 'nav a.login'});
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator clickable link or button located by text, or any element located by CSS|XPath|strict locator.
-   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.
+   * @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.
    * 
    *
+   * [Additional options](https://playwright.dev/docs/api/class-page#page-click) for click available as 3rd argument.
+   *
+   * Examples:
+   *
+   * ```js
+   * // click on element at position
+   * I.click('canvas', '.model', { position: { x: 20, y: 40 } })
+   *
+   * // make ctrl-click
+   * I.click('.edit', null, { modifiers: ['Ctrl'] } )
+   * ```
    *
    */
-  async click(locator, context = null) {
-    return proceedClick.call(this, locator, context);
+  async click(locator, context = null, opts = {}) {
+    return proceedClick.call(this, locator, context, opts);
   }
 
   /**
@@ -1364,8 +1411,8 @@ class Playwright extends Helper {
    * I.forceClick({css: 'nav a.login'});
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator clickable link or button located by text, or any element located by CSS|XPath|strict locator.
-   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.
+   * @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.
    * 
    */
   async forceClick(locator, context = null) {
@@ -1383,8 +1430,8 @@ class Playwright extends Helper {
    * I.doubleClick('.btn.edit');
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator clickable link or button located by text, or any element located by CSS|XPath|strict locator.
-   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.
+   * @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.
    * 
    *
    *
@@ -1405,8 +1452,8 @@ class Playwright extends Helper {
    * I.rightClick('Click me', '.context');
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator clickable element located by CSS|XPath|strict locator.
-   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS|XPath|strict locator.
+   * @param {string | object} locator clickable element located by CSS|XPath|strict locator.
+   * @param {?string | object} [context=null] (optional, `null` by default) element located by CSS|XPath|strict locator.
    * 
    *
    *
@@ -1426,18 +1473,23 @@ class Playwright extends Helper {
    * I.checkOption('I Agree to Terms and Conditions');
    * I.checkOption('agree', '//form');
    * ```
-   * @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.
+   * @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.
+   *
+   * [Additional options](https://playwright.dev/docs/api/class-elementhandle#element-handle-check) for check available as 3rd argument.
+   *
+   * Examples:
+   *
+   * ```js
+   * // click on element at position
+   * I.checkOption('Agree', '.signup', { position: { x: 5, y: 5 } })
+   * ```
+   * > ⚠️ To avoid flakiness, option `force: true` is set by default
    */
-  async checkOption(field, context = null) {
+  async checkOption(field, context = null, options = { force: true }) {
     const elm = await this._locateCheckable(field, context);
-    const curentlyChecked = await elm.getProperty('checked')
-      .then(checkedProperty => checkedProperty.jsonValue());
-    // Only check if NOT currently checked
-    if (!curentlyChecked) {
-      await elm.click();
-      return this._waitForAction();
-    }
+    await elm.check(options);
+    return this._waitForAction();
   }
 
   /**
@@ -1451,18 +1503,23 @@ class Playwright extends Helper {
    * I.uncheckOption('I Agree to Terms and Conditions');
    * I.uncheckOption('agree', '//form');
    * ```
-   * @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.
+   * @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.
+   *
+   * [Additional options](https://playwright.dev/docs/api/class-elementhandle#element-handle-uncheck) for uncheck available as 3rd argument.
+   *
+   * Examples:
+   *
+   * ```js
+   * // click on element at position
+   * I.uncheckOption('Agree', '.signup', { position: { x: 5, y: 5 } })
+   * ```
+   * > ⚠️ To avoid flakiness, option `force: true` is set by default
    */
-  async uncheckOption(field, context = null) {
+  async uncheckOption(field, context = null, options = { force: true }) {
     const elm = await this._locateCheckable(field, context);
-    const curentlyChecked = await elm.getProperty('checked')
-      .then(checkedProperty => checkedProperty.jsonValue());
-    // Only uncheck if currently checked
-    if (curentlyChecked) {
-      await elm.click();
-      return this._waitForAction();
-    }
+    await elm.uncheck(options);
+    return this._waitForAction();
   }
 
   /**
@@ -1474,7 +1531,7 @@ class Playwright extends Helper {
    * I.seeCheckboxIsChecked({css: '#signup_form input[type=checkbox]'});
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
+   * @param {string | object} field located by label|name|CSS|XPath|strict locator.
    * 
    */
   async seeCheckboxIsChecked(field) {
@@ -1490,7 +1547,7 @@ class Playwright extends Helper {
    * I.dontSeeCheckboxIsChecked('agree'); // located by name
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
+   * @param {string | object} field located by label|name|CSS|XPath|strict locator.
    * 
    */
   async dontSeeCheckboxIsChecked(field) {
@@ -1671,8 +1728,8 @@ class Playwright extends Helper {
    * // or by strict locator
    * I.fillField({css: 'form#login input[name=username]'}, 'John');
    * ```
-   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
-   * @param {CodeceptJS.StringOrSecret} value text value to fill.
+   * @param {string | object} field located by label|name|CSS|XPath|strict locator.
+   * @param {string | object} value text value to fill.
    * 
    *
    */
@@ -1699,7 +1756,7 @@ class Playwright extends Helper {
    * I.clearField('user[email]');
    * I.clearField('#email');
    * ```
-   * @param {LocatorOrString} editable field located by label|name|CSS|XPath|strict locator.
+   * @param {string | object} editable field located by label|name|CSS|XPath|strict locator.
    * 
    */
   async clearField(field) {
@@ -1713,7 +1770,7 @@ class Playwright extends Helper {
    * ```js
    * I.appendField('#myTextField', 'appended');
    * ```
-   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator
+   * @param {string | object} field located by label|name|CSS|XPath|strict locator
    * @param {string} value text value to append.
    *
    *
@@ -1736,7 +1793,7 @@ class Playwright extends Helper {
    * I.seeInField('form input[type=hidden]','hidden_value');
    * I.seeInField('#searchform input','Search');
    * ```
-   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
+   * @param {string | object} field located by label|name|CSS|XPath|strict locator.
    * @param {string} value value to check.
    * 
    */
@@ -1753,7 +1810,7 @@ class Playwright extends Helper {
    * I.dontSeeInField({ css: 'form input.email' }, 'user@user.com'); // field by CSS
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
+   * @param {string | object} field located by label|name|CSS|XPath|strict locator.
    * @param {string} value value to check.
    */
   async dontSeeInField(field, value) {
@@ -1770,7 +1827,7 @@ class Playwright extends Helper {
    * I.attachFile('form input[name=avatar]', 'data/avatar.jpg');
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator field located by label|name|CSS|XPath|strict locator.
+   * @param {string | object} locator field located by label|name|CSS|XPath|strict locator.
    * @param {string} pathToFile local file path relative to codecept.json config file.
    *
    */
@@ -1805,7 +1862,7 @@ class Playwright extends Helper {
    * ```js
    * I.selectOption('Which OS do you use?', ['Android', 'iOS']);
    * ```
-   * @param {LocatorOrString} select field located by label|name|CSS|XPath|strict locator.
+   * @param {string | object} select field located by label|name|CSS|XPath|strict locator.
    * @param {string|Array<*>} option visible text or value of option.
    * 
    */
@@ -1846,7 +1903,7 @@ class Playwright extends Helper {
    * let numOfElements = await I.grabNumberOfVisibleElements('p');
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
+   * @param {string | object} locator located by CSS|XPath|strict locator.
    * @returns {Promise<number>} number of visible elements
    *
    */
@@ -1919,7 +1976,7 @@ class Playwright extends Helper {
    * I.see('Register', {css: 'form.register'}); // use strict locator
    * ```
    * @param {string} text expected on page.
-   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS|Xpath|strict locator in which to search for text.
+   * @param {?string | object} [context=null] (optional, `null` by default) element located by CSS|Xpath|strict locator in which to search for text.
    *
    *
    */
@@ -1935,7 +1992,7 @@ class Playwright extends Helper {
    * ```
    * 
    * @param {string} text element value to check.
-   * @param {CodeceptJS.LocatorOrString?} [context=null]  element located by CSS|XPath|strict locator.
+   * @param {(string | object)?} [context=null]  element located by CSS|XPath|strict locator.
    */
   async seeTextEquals(text, context = null) {
     return proceedSee.call(this, 'assert', text, context, true);
@@ -1951,7 +2008,7 @@ class Playwright extends Helper {
    * ```
    * 
    * @param {string} text which is not present.
-   * @param {CodeceptJS.LocatorOrString} [context] (optional) element located by CSS|XPath|strict locator in which to perfrom search.
+   * @param {string | object} [context] (optional) element located by CSS|XPath|strict locator in which to perfrom search.
    * 
    *
    *
@@ -2041,7 +2098,7 @@ class Playwright extends Helper {
    * I.seeNumberOfElements('#submitBtn', 1);
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {string | object} locator element located by CSS|XPath|strict locator.
    * @param {number} num number of elements.
    * 
    *
@@ -2060,7 +2117,7 @@ class Playwright extends Helper {
    * I.seeNumberOfVisibleElements('.buttons', 3);
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {string | object} locator element located by CSS|XPath|strict locator.
    * @param {number} num number of elements.
    * 
    *
@@ -2224,7 +2281,7 @@ class Playwright extends Helper {
    * ```
    * If multiple elements found returns first element.
    * 
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {string | object} locator element located by CSS|XPath|strict locator.
    * @returns {Promise<string>} attribute value
    * 
    *
@@ -2245,7 +2302,7 @@ class Playwright extends Helper {
    * let pins = await I.grabTextFromAll('#pin li');
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {string | object} locator element located by CSS|XPath|strict locator.
    * @returns {Promise<string[]>} attribute value
    * 
    *
@@ -2268,7 +2325,7 @@ class Playwright extends Helper {
    * ```js
    * let email = await I.grabValueFrom('input[name=email]');
    * ```
-   * @param {CodeceptJS.LocatorOrString} locator field located by label|name|CSS|XPath|strict locator.
+   * @param {string | object} locator field located by label|name|CSS|XPath|strict locator.
    * @returns {Promise<string>} attribute value
    * 
    */
@@ -2286,7 +2343,7 @@ class Playwright extends Helper {
    * ```js
    * let inputs = await I.grabValueFromAll('//form/input');
    * ```
-   * @param {CodeceptJS.LocatorOrString} locator field located by label|name|CSS|XPath|strict locator.
+   * @param {string | object} locator field located by label|name|CSS|XPath|strict locator.
    * @returns {Promise<string[]>} attribute value
    * 
    */
@@ -2305,7 +2362,7 @@ class Playwright extends Helper {
    * let postHTML = await I.grabHTMLFrom('#post');
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} element located by CSS|XPath|strict locator.
+   * @param {string | object} element located by CSS|XPath|strict locator.
    * @returns {Promise<string>} HTML code for an element
    * 
    */
@@ -2324,7 +2381,7 @@ class Playwright extends Helper {
    * let postHTMLs = await I.grabHTMLFromAll('.post');
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} element located by CSS|XPath|strict locator.
+   * @param {string | object} element located by CSS|XPath|strict locator.
    * @returns {Promise<string[]>} HTML code for an element
    * 
    */
@@ -2343,7 +2400,7 @@ class Playwright extends Helper {
    * const value = await I.grabCssPropertyFrom('h3', 'font-weight');
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {string | object} locator element located by CSS|XPath|strict locator.
    * @param {string} cssProperty CSS property name.
    * @returns {Promise<string>} CSS value
    * 
@@ -2364,7 +2421,7 @@ class Playwright extends Helper {
    * const values = await I.grabCssPropertyFromAll('h3', 'font-weight');
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {string | object} locator element located by CSS|XPath|strict locator.
    * @param {string} cssProperty CSS property name.
    * @returns {Promise<string[]>} CSS value
    * 
@@ -2385,7 +2442,7 @@ class Playwright extends Helper {
    * I.seeCssPropertiesOnElements('h3', { 'font-weight': "bold"});
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
+   * @param {string | object} locator located by CSS|XPath|strict locator.
    * @param {object} cssProperties object with CSS properties and their values to check.
    *
    */
@@ -2430,7 +2487,7 @@ class Playwright extends Helper {
    * I.seeAttributesOnElements('//form', { method: "post"});
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
+   * @param {string | object} locator located by CSS|XPath|strict locator.
    * @param {object} attributes attributes and their values to check.
    *
    */
@@ -2468,7 +2525,7 @@ class Playwright extends Helper {
    * I.dragSlider('#slider', -70);
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator located by label|name|CSS|XPath|strict locator.
+   * @param {string | object} locator located by label|name|CSS|XPath|strict locator.
    * @param {number} offsetX position to drag.
    *
    */
@@ -2498,7 +2555,7 @@ class Playwright extends Helper {
    * ```js
    * let hint = await I.grabAttributeFrom('#tooltip', 'title');
    * ```
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {string | object} locator element located by CSS|XPath|strict locator.
    * @param {string} attr attribute name.
    * @returns {Promise<string>} attribute value
    * 
@@ -2518,7 +2575,7 @@ class Playwright extends Helper {
    * ```js
    * let hints = await I.grabAttributeFromAll('.tooltip', 'title');
    * ```
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {string | object} locator element located by CSS|XPath|strict locator.
    * @param {string} attr attribute name.
    * @returns {Promise<string[]>} attribute value
    * 
@@ -2545,7 +2602,7 @@ class Playwright extends Helper {
    * I.saveElementScreenshot(`#submit`,'debug.png');
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {string | object} locator element located by CSS|XPath|strict locator.
    * @param {string} fileName file name to save.
    * 
    *
@@ -2595,6 +2652,53 @@ class Playwright extends Helper {
     return this.page.screenshot({ path: outputFile, fullPage: fullPageOption, type: 'png' });
   }
 
+  /**
+   * Performs [api request](https://playwright.dev/docs/api/class-apirequestcontext#api-request-context-get) using
+   * the cookies from the current browser session.
+   *
+   * ```js
+   * const users = await I.makeApiRequest('GET', '/api/users', { params: { page: 1 }});
+   * users[0]
+   * I.makeApiRequest('PATCH', )
+   * ```
+   *
+   * > This is Playwright's built-in alternative to using REST helper's sendGet, sendPost, etc methods.
+   *
+   * @param {string} method HTTP method
+   * @param {string} url endpoint
+   * @param {object} options request options depending on method used
+   * @returns {Promise<object>} response
+   */
+  async makeApiRequest(method, url, options) {
+    method = method.toLowerCase();
+    const allowedMethods = ['get', 'post', 'patch', 'head', 'fetch', 'delete'];
+    if (!allowedMethods.includes(method)) {
+      throw new Error(`Method ${method} is not allowed, use the one from a list ${allowedMethods} or switch to using REST helper`);
+    }
+
+    if (url.startsWith('/')) { // local url
+      url = this.options.url + url;
+      this.debugSection('URL', url);
+    }
+
+    const response = await this.page.request[method](url, options);
+    this.debugSection('Status', response.status());
+    this.debugSection('Response', await response.text());
+
+    // hook to allow JSON response handle this
+    if (this.config.onResponse) {
+      const axiosResponse = {
+        data: await response.json(),
+        status: response.status(),
+        statusText: response.statusText(),
+        headers: response.headers(),
+      };
+      this.config.onResponse(axiosResponse);
+    }
+
+    return response;
+  }
+
   async _failed(test) {
     await this._withinEnd();
 
@@ -2652,7 +2756,7 @@ class Playwright extends Helper {
    * Waits for element to become enabled (by default waits for 1sec).
    * Element can be located by CSS or XPath.
    * 
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {string | object} locator element located by CSS|XPath|strict locator.
    * @param {number} [sec=1] (optional) time in seconds to wait, 1 by default.
    */
   async waitForEnabled(locator, sec) {
@@ -2685,7 +2789,7 @@ class Playwright extends Helper {
    * I.waitForValue('//input', "GoodValue");
    * ```
    * 
-   * @param {LocatorOrString} field input field.
+   * @param {string | object} field input field.
    * @param {string }value expected value.
    * @param {number} [sec=1] (optional, `1` by default) time in seconds to wait
    * 
@@ -2721,7 +2825,7 @@ class Playwright extends Helper {
    * I.waitNumberOfVisibleElements('a', 3);
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {string | object} locator element located by CSS|XPath|strict locator.
    * @param {number} num number of elements.
    * @param {number} [sec=1] (optional, `1` by default) time in seconds to wait
    *
@@ -2762,7 +2866,7 @@ class Playwright extends Helper {
    * I.waitForClickable('.btn.continue', 5); // wait for 5 secs
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {string | object} locator element located by CSS|XPath|strict locator.
    * @param {number} [sec] (optional, `1` by default) time in seconds to wait
    */
   async waitForClickable(locator, waitTimeout) {
@@ -2779,7 +2883,7 @@ class Playwright extends Helper {
    * I.waitForElement('.btn.continue', 5); // wait for 5 secs
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {string | object} locator element located by CSS|XPath|strict locator.
    * @param {number} [sec] (optional, `1` by default) time in seconds to wait
    *
    */
@@ -2802,7 +2906,7 @@ class Playwright extends Helper {
    * I.waitForVisible('#popup');
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {string | object} locator element located by CSS|XPath|strict locator.
    * @param {number} [sec=1] (optional, `1` by default) time in seconds to wait
    * 
    *
@@ -2826,7 +2930,7 @@ class Playwright extends Helper {
    * I.waitForInvisible('#popup');
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {string | object} locator element located by CSS|XPath|strict locator.
    * @param {number} [sec=1] (optional, `1` by default) time in seconds to wait
    */
   async waitForInvisible(locator, sec) {
@@ -2847,7 +2951,7 @@ class Playwright extends Helper {
    * I.waitToHide('#popup');
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {string | object} locator element located by CSS|XPath|strict locator.
    * @param {number} [sec=1] (optional, `1` by default) time in seconds to wait
    */
   async waitToHide(locator, sec) {
@@ -2936,7 +3040,7 @@ class Playwright extends Helper {
    * 
    * @param {string }text to wait for.
    * @param {number} [sec=1] (optional, `1` by default) time in seconds to wait
-   * @param {CodeceptJS.LocatorOrString} [context] (optional) element located by CSS|XPath|strict locator.
+   * @param {string | object} [context] (optional) element located by CSS|XPath|strict locator.
    */
   async waitForText(text, sec = null, context = null) {
     const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout;
@@ -3006,7 +3110,7 @@ class Playwright extends Helper {
    * I.switchTo(); // switch back to main page
    * ```
    * 
-   * @param {?CodeceptJS.LocatorOrString} [locator=null] (optional, `null` by default) element located by CSS|XPath|strict locator.
+   * @param {?string | object} [locator=null] (optional, `null` by default) element located by CSS|XPath|strict locator.
    */
   async switchTo(locator) {
     if (Number.isInteger(locator)) {
@@ -3111,7 +3215,7 @@ class Playwright extends Helper {
    * I.waitForDetached('#popup');
    * ```
    * 
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {string | object} locator element located by CSS|XPath|strict locator.
    * @param {number} [sec=1] (optional, `1` by default) time in seconds to wait
    */
   async waitForDetached(locator, sec) {
@@ -3181,7 +3285,7 @@ class Playwright extends Helper {
    * const width = await I.grabElementBoundingRect('h3', 'width');
    * // width == 527
    * ```
-   * @param {LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {string | object} locator element located by CSS|XPath|strict locator.
    * @param {string=} elementSize x, y, width or height of the given element.
    * @returns {Promise<DOMRect>|Promise<number>} Element bounding rectangle
    * 
@@ -3368,8 +3472,7 @@ async function findCheckable(locator, context) {
 async function proceedIsChecked(assertType, option) {
   let els = await findCheckable.call(this, option);
   assertElementExists(els, option, 'Checkable');
-  els = await Promise.all(els.map(el => el.getProperty('checked')));
-  els = await Promise.all(els.map(el => el.jsonValue()));
+  els = await Promise.all(els.map(el => el.isChecked()));
   const selected = els.reduce((prev, cur) => prev || cur);
   return truth(`checkable ${option}`, 'to be checked')[assertType](selected);
 }
@@ -3397,36 +3500,6 @@ async function findFields(locator) {
   return this._locate({ css: locator });
 }
 
-async function proceedDragAndDrop(sourceLocator, destinationLocator) {
-  // modern drag and drop in Playwright
-  if (this.page.dragAndDrop) {
-    const source = new Locator(sourceLocator);
-    const dest = new Locator(destinationLocator);
-    if (source.isBasic() && dest.isBasic()) {
-      return this.page.dragAndDrop(source.simplify(), dest.simplify());
-    }
-  }
-
-  const src = await this._locate(sourceLocator);
-  assertElementExists(src, sourceLocator, 'Source Element');
-
-  const dst = await this._locate(destinationLocator);
-  assertElementExists(dst, destinationLocator, 'Destination Element');
-
-  // Note: Using clickablePoint private api becaues the .BoundingBox does not take into account iframe offsets!
-  const dragSource = await clickablePoint(src[0]);
-  const dragDestination = await clickablePoint(dst[0]);
-
-  // Drag start point
-  await this.page.mouse.move(dragSource.x, dragSource.y, { steps: 5 });
-  await this.page.mouse.down();
-
-  // Drag destination
-  await this.page.mouse.move(dragDestination.x, dragDestination.y, { steps: 5 });
-  await this.page.mouse.up();
-  await this._waitForAction();
-}
-
 async function proceedSeeInField(assertType, field, value) {
   const els = await findFields.call(this, field);
   assertElementExists(els, field, 'Field');
@@ -3453,14 +3526,15 @@ async function proceedSeeInField(assertType, field, value) {
   };
 
   if (tag === 'SELECT') {
-    const selectedOptions = await el.$$('option:checked');
-    // locate option by values and check them
-    if (value === '') {
-      return proceedMultiple(selectedOptions);
+    if (await el.getProperty('multiple')) {
+      const selectedOptions = await el.$$('option:checked');
+      if (!selectedOptions.length) return null;
+
+      const options = await filterFieldsByValue(selectedOptions, value, true);
+      return proceedMultiple(options);
     }
 
-    const options = await filterFieldsByValue(selectedOptions, value, true);
-    return proceedMultiple(options);
+    return el.inputValue();
   }
 
   if (tag === 'INPUT') {
@@ -3476,7 +3550,8 @@ async function proceedSeeInField(assertType, field, value) {
     }
     return proceedMultiple(els[0]);
   }
-  const fieldVal = await el.getProperty('value').then(el => el.jsonValue());
+
+  const fieldVal = await el.inputValue();
   return stringIncludes(`fields by ${field}`)[assertType](value, fieldVal);
 }
 
@@ -3507,10 +3582,10 @@ async function filterFieldsBySelectionState(elements, state) {
 }
 
 async function elementSelected(element) {
-  const type = await element.getProperty('type').then(el => el.jsonValue());
+  const type = await element.getProperty('type').then(el => !!el && el.jsonValue());
 
   if (type === 'checkbox' || type === 'radio') {
-    return element.getProperty('checked').then(el => el.jsonValue());
+    return element.isChecked();
   }
   return element.getProperty('selected').then(el => el.jsonValue());
 }
@@ -3558,12 +3633,18 @@ async function targetCreatedHandler(page) {
       });
   });
   page.on('console', (msg) => {
-    this.debugSection(`Browser:${ucfirst(msg.type())}`, (msg.text && msg.text() || msg._text || '') + msg.args().join(' '));
+    if (!consoleLogStore.includes(msg) && this.options.ignoreLog && !this.options.ignoreLog.includes(msg.type())) {
+      this.debugSection(`Browser:${ucfirst(msg.type())}`, (msg.text && msg.text() || msg._text || '') + msg.args().join(' '));
+    }
     consoleLogStore.add(msg);
   });
 
   if (this.options.windowSize && this.options.windowSize.indexOf('x') > 0 && this._getType() === 'Browser') {
-    await page.setViewportSize(parseWindowSize(this.options.windowSize));
+    try {
+      await page.setViewportSize(parseWindowSize(this.options.windowSize));
+    } catch (err) {
+      // target can be already closed, ignoring...
+    }
   }
 }
 
@@ -3653,3 +3734,37 @@ async function clickablePoint(el) {
   } = rect;
   return { x: x + width / 2, y: y + height / 2 };
 }
+
+async function refreshContextSession() {
+  // close other sessions
+  try {
+    const contexts = await this.browser.contexts();
+    contexts.shift();
+
+    await Promise.all(contexts.map(c => c.close()));
+  } catch (e) {
+    console.log(e);
+  }
+
+  if (this.page) {
+    const existingPages = await this.browserContext.pages();
+    await this._setPage(existingPages[0]);
+  }
+
+  if (this.options.keepBrowserState) return;
+
+  if (!this.options.keepCookies) {
+    this.debugSection('Session', 'cleaning cookies and localStorage');
+    await this.clearCookie();
+  }
+  const currentUrl = await this.grabCurrentUrl();
+
+  if (currentUrl.startsWith('http')) {
+    await this.executeScript('localStorage.clear();').catch((err) => {
+      if (!(err.message.indexOf("Storage is disabled inside 'data:' URLs.") > -1)) throw err;
+    });
+    await this.executeScript('sessionStorage.clear();').catch((err) => {
+      if (!(err.message.indexOf("Storage is disabled inside 'data:' URLs.") > -1)) throw err;
+    });
+  }
+}