codeceptjs 3.2.0 → 3.3.0-beta.1

package/docs/build/Playwright.js

@@ -14,12 +14,12 @@ const {
   ucfirst,
   fileExists,
   chunkArray,
-  toCamelCase,
   convertCssPropertiesToCamelCase,
   screenshotOutputFolder,
   getNormalizedKeyAttributeValue,
   isModifierKey,
   clearString,
+  requireWithFallback,
 } = require('../utils');
 const {
   isColorProperty,
@@ -39,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');
 
 /**
@@ -50,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
@@ -63,17 +72,21 @@ 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/master/docs/api.md#pagewaitfornavigationoptions).
+ * * `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.
@@ -84,6 +97,7 @@ const { createValueEngine, createDisabledEngine } = require('./extras/Playwright
  * * `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).
  *
  * #### Video Recording Customization
  *
@@ -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,10 +314,16 @@ class Playwright extends Helper {
 
   _setConfig(config) {
     this.options = this._validateConfig(config);
+    setRestartStrategy(this.options);
     this.playwrightOptions = {
       headless: !this.options.show,
       ...this._getOptionsForBrowser(config),
     };
+
+    if (this.options.channel && this.options.browser === 'chromium') {
+      this.playwrightOptions.channel = this.options.channel;
+    }
+
     if (this.options.video) {
       this.options.recordVideo = { size: parseWindowSize(this.options.windowSize) };
     }
@@ -329,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'];
     }
   }
 
@@ -348,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();
     }
@@ -365,7 +388,8 @@ class Playwright extends Helper {
         return err.message.includes('context');
       },
     });
-    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;
@@ -387,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;
@@ -415,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();
     }
@@ -437,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() {
@@ -500,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/master/docs/api.md#class-page), [`context`](https://github.com/microsoft/playwright/blob/master/docs/api.md#class-context) [`browser`](https://github.com/microsoft/playwright/blob/master/docs/api.md#class-browser) } 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);
@@ -584,7 +613,14 @@ 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!');
+      await page.close();
+    });
     this.context = await this.page;
     this.contextLocator = null;
     if (this.options.browser === 'chrome') {
@@ -680,7 +716,6 @@ class Playwright extends Helper {
     this._setPage(null);
     this.context = null;
     popupStore.clear();
-
     await this.browser.close();
   }
 
@@ -828,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.
    * 
@@ -851,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);
   }
 
   /**
@@ -913,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.
    */
@@ -1163,7 +1210,7 @@ class Playwright extends Helper {
    * I.openNewTab();
    * ```
    *
-   * You can pass in [page options](https://github.com/microsoft/playwright/blob/master/docs/api.md#browsernewpageoptions) to emulate device on this page
+   * You can pass in [page options](https://github.com/microsoft/playwright/blob/main/docs/api.md#browsernewpageoptions) to emulate device on this page
    *
    * ```js
    * // enable mobile
@@ -1201,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) {
@@ -1217,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) {
@@ -1233,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) {
@@ -1248,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);
@@ -1308,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);
   }
 
   /**
@@ -1353,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) {
@@ -1372,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.
    * 
    *
    *
@@ -1394,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.
    * 
    *
    *
@@ -1415,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();
   }
 
   /**
@@ -1440,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();
   }
 
   /**
@@ -1463,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) {
@@ -1479,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) {
@@ -1660,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.
    * 
    *
    */
@@ -1688,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) {
@@ -1702,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.
    *
    *
@@ -1725,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.
    * 
    */
@@ -1742,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) {
@@ -1759,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.
    *
    */
@@ -1794,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.
    * 
    */
@@ -1835,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
    *
    */
@@ -1908,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.
    *
    *
    */
@@ -1924,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);
@@ -1940,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.
    * 
    *
    *
@@ -2030,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.
    * 
    *
@@ -2049,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.
    * 
    *
@@ -2151,7 +2219,7 @@ class Playwright extends Helper {
    */
   async clearCookie() {
     // Playwright currently doesn't support to delete a certain cookie
-    // https://github.com/microsoft/playwright/blob/master/docs/api.md#class-browsercontext
+    // https://github.com/microsoft/playwright/blob/main/docs/api.md#class-browsercontext
     if (!this.browserContext) return;
     return this.browserContext.clearCookies();
   }
@@ -2213,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
    * 
    *
@@ -2234,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
    * 
    *
@@ -2257,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
    * 
    */
@@ -2275,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
    * 
    */
@@ -2294,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
    * 
    */
@@ -2313,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
    * 
    */
@@ -2332,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
    * 
@@ -2353,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
    * 
@@ -2374,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.
    *
    */
@@ -2419,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.
    *
    */
@@ -2457,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.
    *
    */
@@ -2487,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
    * 
@@ -2507,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
    * 
@@ -2534,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.
    * 
    *
@@ -2584,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();
 
@@ -2596,7 +2711,7 @@ class Playwright extends Helper {
     }
 
     if (this.options.trace) {
-      const path = `${global.output_dir}/trace/${clearString(test.title).slice(0, 255)}.zip`;
+      const path = `${`${global.output_dir}/trace/${clearString(test.title)}`.slice(0, 251)}.zip`;
       await this.browserContext.tracing.stop({ path });
       test.artifacts.trace = path;
     }
@@ -2641,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) {
@@ -2674,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
    * 
@@ -2710,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
    *
@@ -2751,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) {
@@ -2768,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
    *
    */
@@ -2791,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
    * 
    *
@@ -2815,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) {
@@ -2836,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) {
@@ -2925,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;
@@ -2995,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)) {
@@ -3100,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) {
@@ -3170,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
    * 
@@ -3357,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);
 }
@@ -3386,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');
@@ -3442,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') {
@@ -3465,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);
 }
 
@@ -3496,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());
 }
@@ -3547,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...
+    }
   }
 }
 
@@ -3642,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;
+    });
+  }
+}