codeceptjs 3.0.3 → 3.0.7

package/docs/build/Playwright.js

@@ -35,9 +35,10 @@ let defaultSelectorEnginesInitialized = false;
 
 const popupStore = new Popup();
 const consoleLogStore = new Console();
-const availableBrowsers = ['chromium', 'webkit', 'firefox'];
+const availableBrowsers = ['chromium', 'webkit', 'firefox', 'electron'];
 
 const { createValueEngine, createDisabledEngine } = require('./extras/PlaywrightPropEngine');
+
 /**
  * Uses [Playwright](https://github.com/microsoft/playwright) library to run tests inside:
  *
@@ -58,7 +59,7 @@ const { createValueEngine, createDisabledEngine } = require('./extras/Playwright
  * 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`. Default: chromium.
+ * * `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.
  * * `disableScreenshots`: (optional, default: false)  - don't save screenshot on failure.
@@ -77,6 +78,7 @@ const { createValueEngine, createDisabledEngine } = require('./extras/Playwright
  * * `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["Playwright"]._startBrowser()`.
  * * `chromium`: (optional) pass additional chromium options
+ * * `electron`: (optional) pass additional electron options
  *
  * #### Example #1: Wait for 0 network connections.
  *
@@ -121,7 +123,7 @@ const { createValueEngine, createDisabledEngine } = require('./extras/Playwright
  * }
  * ```
  *
- * #### Example #4: Connect to remote browser by specifying [websocket endpoint](https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target)
+ * #### Example #4: Connect to remote browser by specifying [websocket endpoint](https://playwright.dev/docs/api/class-browsertype#browsertypeconnectparams)
  *
  * ```js
  * {
@@ -129,7 +131,7 @@ const { createValueEngine, createDisabledEngine } = require('./extras/Playwright
  *      Playwright: {
  *        url: "http://localhost",
  *        chromium: {
- *          browserWSEndpoint: "ws://localhost:9222/devtools/browser/c5aa6160-b5bc-4d53-bb49-6ecb36cd2e0a"
+ *          browserWSEndpoint: { wsEndpoint: 'ws://localhost:9222/devtools/browser/c5aa6160-b5bc-4d53-bb49-6ecb36cd2e0a' }
  *        }
  *      }
  *    }
@@ -147,6 +149,7 @@ const { createValueEngine, createDisabledEngine } = require('./extras/Playwright
  *      url: "http://localhost",
  *      show: true // headless mode not supported for extensions
  *      chromium: {
+ *        userDataDir: '/tmp/playwright-tmp', // necessary to launch the browser in normal mode instead of incognito,
  *        args: [
  *           `--disable-extensions-except=${pathToExtension}`,
  *           `--load-extension=${pathToExtension}`
@@ -206,6 +209,8 @@ class Playwright extends Helper {
     this.isAuthenticated = false;
     this.sessionPages = {};
     this.activeSessionName = '';
+    this.isElectron = false;
+    this.electronSessions = [];
 
     // override defaults with config
     this._setConfig(config);
@@ -257,6 +262,8 @@ class Playwright extends Helper {
       ...this._getOptionsForBrowser(config),
     };
     this.isRemoteBrowser = !!this.playwrightOptions.browserWSEndpoint;
+    this.isElectron = this.options.browser === 'electron';
+    this.userDataDir = this.playwrightOptions.userDataDir;
     popupStore.defaultAction = this.options.defaultPopupAction;
   }
 
@@ -268,7 +275,7 @@ class Playwright extends Helper {
       },
       {
         name: 'browser',
-        message: 'Browser in which testing will be performed. Possible options: chromium, firefox or webkit',
+        message: 'Browser in which testing will be performed. Possible options: chromium, firefox, webkit or electron',
         default: 'chromium',
       },
     ];
@@ -320,11 +327,21 @@ class Playwright extends Helper {
   async _after() {
     if (!this.isRunning) return;
 
+    if (this.isElectron) {
+      this.browser.close();
+      this.electronSessions.forEach(session => session.close());
+      return;
+    }
+
     // close other sessions
-    const contexts = await this.browser.contexts();
-    contexts.shift();
+    try {
+      const contexts = await this.browser.contexts();
+      contexts.shift();
 
-    await Promise.all(contexts.map(c => c.close()));
+      await Promise.all(contexts.map(c => c.close()));
+    } catch (e) {
+      console.log(e);
+    }
 
     if (this.options.restart) {
       this.isRunning = false;
@@ -371,12 +388,22 @@ class Playwright extends Helper {
         this.debugSection('New Context', config ? JSON.stringify(config) : 'opened');
         this.activeSessionName = sessionName;
 
-        const bc = await this.browser.newContext(config);
-        const page = await bc.newPage();
+        let browserContext;
+        let page;
+        if (this.isElectron) {
+          const browser = await playwright._electron.launch(this.playwrightOptions);
+          this.electronSessions.push(browser);
+          browserContext = browser.context();
+          page = await browser.firstWindow();
+        } else {
+          browserContext = await this.browser.newContext(config);
+          page = await browserContext.newPage();
+        }
+
         targetCreatedHandler.call(this, page);
         this._setPage(page);
         // Create a new page inside context.
-        return bc;
+        return browserContext;
       },
       stop: async () => {
         // is closed by _after
@@ -496,6 +523,7 @@ class Playwright extends Helper {
     if (!page) return;
     page.setDefaultNavigationTimeout(this.options.getPageTimeout);
     this.context = await this.page;
+    this.contextLocator = null;
     if (this.config.browser === 'chrome') {
       await page.bringToFront();
     }
@@ -554,15 +582,19 @@ class Playwright extends Helper {
   }
 
   async _startBrowser() {
-    if (this.isRemoteBrowser) {
+    if (this.isElectron) {
+      this.browser = await playwright._electron.launch(this.playwrightOptions);
+    } else if (this.isRemoteBrowser) {
       try {
-        this.browser = await playwright[this.options.browser].connect(this.playwrightOptions);
+        this.browser = await playwright[this.options.browser].connect(this.playwrightOptions.browserWSEndpoint);
       } catch (err) {
         if (err.toString().indexOf('ECONNREFUSED')) {
           throw new RemoteBrowserConnectionRefused(err);
         }
         throw err;
       }
+    } else if (this.userDataDir) {
+      this.browser = await playwright[this.options.browser].launchPersistentContext(this.userDataDir, this.playwrightOptions);
     } else {
       this.browser = await playwright[this.options.browser].launch(this.playwrightOptions);
     }
@@ -571,11 +603,22 @@ class Playwright extends Helper {
     this.browser.on('targetchanged', (target) => {
       this.debugSection('Url', target.url());
     });
-    this.browserContext = await this.browser.newContext({ ignoreHTTPSErrors: this.options.ignoreHTTPSErrors, acceptDownloads: true, ...this.options.emulate });// Adding the HTTPSError ignore in the context so that we can ignore those errors
 
-    const existingPages = await this.browserContext.pages();
+    if (this.isElectron) {
+      this.browserContext = this.browser.context();
+    } else if (this.userDataDir) {
+      this.browserContext = this.browser;
+    } else {
+      this.browserContext = await this.browser.newContext({ ignoreHTTPSErrors: this.options.ignoreHTTPSErrors, acceptDownloads: true, ...this.options.emulate });// Adding the HTTPSError ignore in the context so that we can ignore those errors
+    }
 
-    const mainPage = existingPages[0] || await this.browserContext.newPage();
+    let mainPage;
+    if (this.isElectron) {
+      mainPage = await this.browser.firstWindow();
+    } else {
+      const existingPages = await this.browserContext.pages();
+      mainPage = existingPages[0] || await this.browserContext.newPage();
+    }
     targetCreatedHandler.call(this, mainPage);
 
     await this._setPage(mainPage);
@@ -584,6 +627,10 @@ class Playwright extends Helper {
     this.isRunning = true;
   }
 
+  _getType() {
+    return this.browser._type;
+  }
+
   async _stopBrowser() {
     this.withinLocator = null;
     this._setPage(null);
@@ -618,6 +665,7 @@ class Playwright extends Helper {
     const els = await this._locate(locator);
     assertElementExists(els, locator);
     this.context = els[0];
+    this.contextLocator = locator;
 
     this.withinLocator = new Locator(locator);
   }
@@ -625,6 +673,7 @@ class Playwright extends Helper {
   async _withinEnd() {
     this.withinLocator = null;
     this.context = await this.page;
+    this.contextLocator = null;
   }
 
   _extractDataFromPerformanceTiming(timing, ...dataNames) {
@@ -651,6 +700,9 @@ class Playwright extends Helper {
    * @param {string} url url path or global url.
    */
   async amOnPage(url) {
+    if (this.isElectron) {
+      throw new Error('Cannot open pages inside an Electron container');
+    }
     if (!(/^\w+\:\/\//.test(url))) {
       url = this.options.url + url;
     }
@@ -878,11 +930,14 @@ class Playwright extends Helper {
   }
 
   /**
-   * Checks that title is equal to provided one.
-   *
-   * ```js
-   * I.seeTitleEquals('Test title.');
-   * ```
+   *  Checks that title is equal to provided one.
+   * 
+   *  ```js
+   *  I.seeTitleEquals('Test title.');
+   *  ```
+   * 
+   *  @param {string} text value to check.
+   * 
    */
   async seeTitleEquals(text) {
     const title = await this.page.title();
@@ -981,6 +1036,9 @@ class Playwright extends Helper {
    * @param {number} [num=1]
    */
   async switchToNextTab(num = 1) {
+    if (this.isElectron) {
+      throw new Error('Cannot switch tabs inside an Electron container');
+    }
     const pages = await this.browserContext.pages();
 
     const index = pages.indexOf(this.page);
@@ -1004,6 +1062,9 @@ class Playwright extends Helper {
    * @param {number} [num=1]
    */
   async switchToPreviousTab(num = 1) {
+    if (this.isElectron) {
+      throw new Error('Cannot switch tabs inside an Electron container');
+    }
     const pages = await this.browserContext.pages();
     const index = pages.indexOf(this.page);
     this.withinLocator = null;
@@ -1025,6 +1086,9 @@ class Playwright extends Helper {
    * ```
    */
   async closeCurrentTab() {
+    if (this.isElectron) {
+      throw new Error('Cannot close current tab inside an Electron container');
+    }
     const oldPage = this.page;
     await this.switchToPreviousTab();
     await oldPage.close();
@@ -1063,6 +1127,9 @@ class Playwright extends Helper {
    * ```
    */
   async openNewTab(options) {
+    if (this.isElectron) {
+      throw new Error('Cannot open new tabs inside an Electron container');
+    }
     await this._setPage(await this.browserContext.newPage(options));
     return this._waitForAction();
   }
@@ -1217,14 +1284,34 @@ class Playwright extends Helper {
   }
 
   /**
-   *
-   * Force clicks an element without waiting for it to become visible and not animating.
-   *
+   * Perform an emulated click on a link or a button, given by a locator.
+   * Unlike normal click instead of sending native event, emulates a click with JavaScript.
+   * This works on hidden, animated or inactive elements as well.
+   * 
+   * If a fuzzy locator is given, the page will be searched for a button, link, or image matching the locator string.
+   * For buttons, the "value" attribute, "name" attribute, and inner text are searched. For links, the link text is searched.
+   * For images, the "alt" attribute and inner text of any parent links are searched.
+   * 
+   * The second parameter is a context (CSS or XPath locator) to narrow the search.
+   * 
    * ```js
-   * I.forceClick('#hiddenButton');
-   * I.forceClick('Click me', '#hidden');
+   * // simple link
+   * I.forceClick('Logout');
+   * // button of form
+   * I.forceClick('Submit');
+   * // CSS button
+   * I.forceClick('#form input[type=submit]');
+   * // XPath
+   * I.forceClick('//form/*[@type=submit]');
+   * // link in context
+   * I.forceClick('Logout', '#nav');
+   * // using strict locator
+   * 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.
+   * 
    */
   async forceClick(locator, context = null) {
     return proceedClick.call(this, locator, context, { force: true });
@@ -1530,7 +1617,7 @@ class Playwright extends Helper {
    * I.fillField({css: 'form#login input[name=username]'}, 'John');
    * ```
    * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
-   * @param {string} value text value to fill.
+   * @param {CodeceptJS.StringOrSecret} value text value to fill.
    * 
    *
    */
@@ -2043,6 +2130,10 @@ class Playwright extends Helper {
    * I.executeScript(([x, y]) => x + y, [x, y]);
    * ```
    * If a function returns a Promise it will wait for its resolution.
+   *
+   * @param {string|function} fn function to be executed in browser context.
+   * @param {any} [arg] optional argument to pass to the function
+   * @return {Promise<any>}
    */
   async executeScript(fn, arg) {
     let context = this.page;
@@ -2052,6 +2143,22 @@ class Playwright extends Helper {
     return context.evaluate.apply(context, [fn, arg]);
   }
 
+  /**
+   * Grab Locator if called within Context
+   *
+   * @param {*} locator
+   */
+  _contextLocator(locator) {
+    locator = buildLocatorString(new Locator(locator, 'css'));
+
+    if (this.contextLocator) {
+      const contextLocator = buildLocatorString(new Locator(this.contextLocator, 'css'));
+      locator = `${contextLocator} >> ${locator}`;
+    }
+
+    return locator;
+  }
+
   /**
    * Retrieves a text from an element located by CSS or XPath and returns it to test.
    * Resumes test execution, so **should be used inside async with `await`** operator.
@@ -2067,10 +2174,11 @@ class Playwright extends Helper {
    *
    */
   async grabTextFrom(locator) {
-    const texts = await this.grabTextFromAll(locator);
-    assertElementExists(texts, locator);
-    this.debugSection('Text', texts[0]);
-    return texts[0];
+    locator = this._contextLocator(locator);
+    const text = await this.page.textContent(locator);
+    assertElementExists(text, locator);
+    this.debugSection('Text', text);
+    return text;
   }
 
   /**
@@ -2209,8 +2317,7 @@ class Playwright extends Helper {
   async grabCssPropertyFromAll(locator, cssProperty) {
     const els = await this._locate(locator);
     this.debug(`Matched ${els.length} elements`);
-    const res = await Promise.all(els.map(el => el.$eval('xpath=.', el => JSON.parse(JSON.stringify(getComputedStyle(el))), el)));
-    const cssValues = res.map(props => props[toCamelCase(cssProperty)]);
+    const cssValues = await Promise.all(els.map(el => el.$eval('xpath=.', (el, cssProperty) => getComputedStyle(el).getPropertyValue(cssProperty), cssProperty)));
 
     return cssValues;
   }
@@ -2824,6 +2931,7 @@ class Playwright extends Helper {
 
       if (locator >= 0 && locator < childFrames.length) {
         this.context = childFrames[locator];
+        this.contextLocator = locator;
       } else {
         throw new Error('Element #invalidIframeSelector was not found by text|CSS|XPath');
       }
@@ -2831,6 +2939,7 @@ class Playwright extends Helper {
     }
     if (!locator) {
       this.context = this.page;
+      this.contextLocator = null;
       return;
     }
 
@@ -2841,8 +2950,10 @@ class Playwright extends Helper {
 
     if (contentFrame) {
       this.context = contentFrame;
+      this.contextLocator = null;
     } else {
       this.context = els[0];
+      this.contextLocator = locator;
     }
   }
 
@@ -2882,7 +2993,7 @@ class Playwright extends Helper {
   /**
    * Waits for navigation to finish. By default takes configured `waitForNavigation` option.
    *
-   * See [Pupeteer's reference](https://github.com/microsoft/Playwright/blob/master/docs/api.md#pagewaitfornavigationoptions)
+   * See [Playwright's reference](https://playwright.dev/docs/api/class-page?_highlight=waitfornavi#pagewaitfornavigationoptions)
    *
    * @param {*} opts
    */
@@ -3031,6 +3142,19 @@ async function findElements(matcher, locator) {
   return matcher.$$(buildLocatorString(locator));
 }
 
+async function getVisibleElements(elements) {
+  const visibleElements = [];
+  for (const element of elements) {
+    if (await element.isVisible()) {
+      visibleElements.push(element);
+    }
+  }
+  if (visibleElements.length === 0) {
+    return elements;
+  }
+  return visibleElements;
+}
+
 async function proceedClick(locator, context = null, options = {}) {
   let matcher = await this._getContext();
   if (context) {
@@ -3050,7 +3174,8 @@ async function proceedClick(locator, context = null, options = {}) {
   if (options.force) {
     await els[0].dispatchEvent('click');
   } else {
-    await els[0].click(options);
+    const element = els.length > 1 ? (await getVisibleElements(els))[0] : els[0];
+    await element.click(options);
   }
   const promises = [];
   if (options.waitForNavigation) {
@@ -3308,11 +3433,13 @@ async function targetCreatedHandler(page) {
           // we are inside iframe?
           const frameEl = await this.context.frameElement();
           this.context = await frameEl.contentFrame();
+          this.contextLocator = null;
           return;
         }
         // if context element was in iframe - keep it
         // if (await this.context.ownerFrame()) return;
         this.context = page;
+        this.contextLocator = null;
       });
   });
   page.on('console', (msg) => {
@@ -3323,7 +3450,7 @@ async function targetCreatedHandler(page) {
   if (this.options.userAgent) {
     await page.setUserAgent(this.options.userAgent);
   }
-  if (this.options.windowSize && this.options.windowSize.indexOf('x') > 0) {
+  if (this.options.windowSize && this.options.windowSize.indexOf('x') > 0 && this._getType() === 'Browser') {
     const dimensions = this.options.windowSize.split('x');
     const width = parseInt(dimensions[0], 10);
     const height = parseInt(dimensions[1], 10);

package/docs/build/Protractor.js

@@ -723,7 +723,7 @@ class Protractor extends Helper {
    * I.fillField({css: 'form#login input[name=username]'}, 'John');
    * ```
    * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
-   * @param {string} value text value to fill.
+   * @param {CodeceptJS.StringOrSecret} value text value to fill.
    * 
    */
   async fillField(field, value) {

package/docs/build/Puppeteer.js

@@ -1593,7 +1593,7 @@ class Puppeteer extends Helper {
    * I.fillField({css: 'form#login input[name=username]'}, 'John');
    * ```
    * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
-   * @param {string} value text value to fill.
+   * @param {CodeceptJS.StringOrSecret} value text value to fill.
    * 
    * {{ react }}
    */

package/docs/build/REST.js

@@ -1,4 +1,5 @@
 const axios = require('axios').default;
+const Secret = require('../secret');
 
 const Helper = require('../helper');
 
@@ -58,7 +59,8 @@ class REST extends Helper {
 
     this.options = { ...this.options, ...config };
     this.headers = { ...this.options.defaultHeaders };
-    axios.defaults.headers = this.options.defaultHeaders;
+    this.axios = axios.create();
+    this.axios.defaults.headers = this.options.defaultHeaders;
   }
 
   static _checkRequirements() {
@@ -75,12 +77,18 @@ class REST extends Helper {
    * @param {*} request
    */
   async _executeRequest(request) {
-    axios.defaults.timeout = request.timeout || this.options.timeout;
+    const _debugRequest = { ...request };
+    this.axios.defaults.timeout = request.timeout || this.options.timeout;
 
     if (this.headers && this.headers.auth) {
       request.auth = this.headers.auth;
     }
 
+    if (request.data instanceof Secret) {
+      _debugRequest.data = '*****';
+      request.data = typeof request.data === 'object' ? { ...request.data.toString() } : request.data.toString();
+    }
+
     if ((typeof request.data) === 'string') {
       if (!request.headers || !request.headers['Content-Type']) {
         request.headers = { ...request.headers, ...{ 'Content-Type': 'application/x-www-form-urlencoded' } };
@@ -91,11 +99,11 @@ class REST extends Helper {
       await this.config.onRequest(request);
     }
 
-    this.debugSection('Request', JSON.stringify(request));
+    this.debugSection('Request', JSON.stringify(_debugRequest));
 
     let response;
     try {
-      response = await axios(request);
+      response = await this.axios(request);
     } catch (err) {
       if (!err.response) throw err;
       this.debugSection('Response', `Response error. Status code: ${err.response.status}`);
@@ -149,6 +157,10 @@ class REST extends Helper {
    *
    * ```js
    * I.sendPostRequest('/api/users.json', { "email": "user@user.com" });
+   *
+   * // To mask the payload in logs
+   * I.sendPostRequest('/api/users.json', secret({ "email": "user@user.com" }));
+   *
    * ```
    *
    * @param {*} url
@@ -176,6 +188,10 @@ class REST extends Helper {
    *
    * ```js
    * I.sendPatchRequest('/api/users.json', { "email": "user@user.com" });
+   *
+   * // To mask the payload in logs
+   * I.sendPatchRequest('/api/users.json', secret({ "email": "user@user.com" }));
+   *
    * ```
    *
    * @param {string} url
@@ -203,6 +219,10 @@ class REST extends Helper {
    *
    * ```js
    * I.sendPutRequest('/api/users.json', { "email": "user@user.com" });
+   *
+   * // To mask the payload in logs
+   * I.sendPutRequest('/api/users.json', secret({ "email": "user@user.com" }));
+   *
    * ```
    *
    * @param {string} url

package/docs/build/TestCafe.js

@@ -440,7 +440,7 @@ class TestCafe extends Helper {
    * I.fillField({css: 'form#login input[name=username]'}, 'John');
    * ```
    * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
-   * @param {string} value text value to fill.
+   * @param {CodeceptJS.StringOrSecret} value text value to fill.
    * 
    */
   async fillField(field, value) {