codeceptjs 3.5.1 → 3.5.3

package/docs/installation.md

@@ -59,7 +59,7 @@ For WebDriver installation Selenium Server is required 👇
 
 ## WebDriver
 
-WebDriver based helpers like WebDriver, Protractor, Selenium WebDriver will require [Selenium Server](https://codecept.io/helpers/WebDriver/#selenium-installation) installed. They will also require ChromeDriver or GeckoDriver to run corresponding browsers.
+WebDriver based helpers like WebDriver will require [Selenium Server](https://codecept.io/helpers/WebDriver/#selenium-installation) installed. They will also require ChromeDriver or GeckoDriver to run corresponding browsers.
 
 We recommend to install them manually or use NPM packages:
 

package/docs/mobile.md

@@ -123,9 +123,7 @@ Select [Appium helper](https://codecept.io/helpers/Appium/) when asked.
 ```sh
 ? What helpers do you want to use?
  ◯ WebDriver
- ◯ Protractor
  ◯ Puppeteer
- ◯ Nightmare
 ❯◉ Appium
  ◯ REST
 ```

package/docs/plugins.md

@@ -1152,8 +1152,6 @@ plugins: {
 }
 ```
 
-Please note, this service can be used with Protractor helper as well!
-
 #### Sauce Service
 
 Install `@wdio/sauce-service` package, as [described here][19].

package/docs/quickstart.md

@@ -31,7 +31,6 @@ TestCafe provides cross-browser support without Selenium. TestCafe tests are fas
 ---
 
 * [Mobile Testing with Appium »](/mobile)
-* [Testing with Protractor »](/angular)
 
 :::
 

package/docs/testcafe.md

@@ -5,7 +5,7 @@ title: Testing with TestCafe
 
 # Testing with TestCafe
 
-[TestCafe](https://devexpress.github.io/testcafe/) is another alternative engine for driving browsers. It is driven by unique technology which provides fast and simple cross browser testing for desktop and mobile browsers. Unlike WebDriver or Puppeteer, TestCafe doesn't control a browser at all. It is not a browser itself, like [Nightmare](/nightmare) or Cypress. **TestCafe core is a proxy server** that runs behind the scene, and transforms all HTML and JS to include code that is needed for test automation.
+[TestCafe](https://devexpress.github.io/testcafe/) is another alternative engine for driving browsers. It is driven by unique technology which provides fast and simple cross browser testing for desktop and mobile browsers. Unlike WebDriver or Puppeteer, TestCafe doesn't control a browser at all. It is not a browser itself, like Cypress. **TestCafe core is a proxy server** that runs behind the scene, and transforms all HTML and JS to include code that is needed for test automation.
 
 ![Testcafe](/img/testcafe.png)
 

package/docs/webdriver.md

@@ -21,8 +21,6 @@ Let's clarify the terms:
 
 We use [webdriverio](https://webdriver.io) library to run tests over WebDriver.
 
-> Popular tool [Protractor](/angular) also uses WebDriver for running end 2 end tests.
-
 To proceed you need to have [CodeceptJS installed](/quickstart#using-selenium-webdriver) and `WebDriver` helper selected.
 
 Selenium WebDriver may be complicated from start, as it requires following tools to be installed and started.

package/lib/command/init.js

@@ -20,7 +20,7 @@ const defaultConfig = {
   include: {},
 };
 
-const helpers = ['Playwright', 'WebDriver', 'Puppeteer', 'REST', 'GraphQL', 'Appium', 'TestCafe', 'Nightmare'];
+const helpers = ['Playwright', 'WebDriver', 'Puppeteer', 'REST', 'GraphQL', 'Appium', 'TestCafe'];
 const translations = Object.keys(require('../../translations'));
 
 const noTranslation = 'English (no localization)';

package/lib/helper/OpenAI.js

@@ -25,7 +25,9 @@ class OpenAI extends Helper {
       chunkSize: 80000,
     };
     this.options = { ...this.options, ...config };
+  }
 
+  _beforeSuite() {
     const helpers = Container.helpers();
 
     for (const helperName of standardActingHelpers) {
@@ -37,16 +39,16 @@ class OpenAI extends Helper {
   }
 
   /**
- * Asks the OpenAI GPT language model a question based on the provided prompt within the context of the current page's HTML.
- *
- * ```js
- * I.askGptOnPage('what does this page do?');
- * ```
- *
- * @async
- * @param {string} prompt - The question or prompt to ask the GPT model.
- * @returns {Promise<string>} - A Promise that resolves to the generated responses from the GPT model, joined by newlines.
- */
+   * Asks the OpenAI GPT language model a question based on the provided prompt within the context of the current page's HTML.
+   *
+   * ```js
+   * I.askGptOnPage('what does this page do?');
+   * ```
+   *
+   * @async
+   * @param {string} prompt - The question or prompt to ask the GPT model.
+   * @returns {Promise<string>} - A Promise that resolves to the generated responses from the GPT model, joined by newlines.
+   */
   async askGptOnPage(prompt) {
     const html = await this.helper.grabSource();
 
@@ -120,3 +122,5 @@ class OpenAI extends Helper {
     return response;
   }
 }
+
+module.exports = OpenAI;

package/lib/helper/Playwright.js

@@ -3,6 +3,7 @@ const fs = require('fs');
 
 const Helper = require('@codeceptjs/helper');
 const { v4: uuidv4 } = require('uuid');
+const assert = require('assert');
 const Locator = require('../locator');
 const store = require('../store');
 const recorder = require('../recorder');
@@ -311,6 +312,11 @@ class Playwright extends Helper {
     this.electronSessions = [];
     this.storageState = null;
 
+    // for network stuff
+    this.requests = [];
+    this.recording = false;
+    this.recordedAtLeastOnce = false;
+
     // override defaults with config
     this._setConfig(config);
   }
@@ -1560,7 +1566,7 @@ class Playwright extends Helper {
    */
   async clearField(locator, options = {}) {
     let result;
-    const isNewClearMethodPresent = typeof this.page.locator().clear === 'function';
+    const isNewClearMethodPresent = false; // not works, disabled for now. Prev: typeof this.page.locator().clear === 'function';
 
     if (isNewClearMethodPresent) {
       const els = await findFields.call(this, locator);
@@ -2655,6 +2661,330 @@ class Playwright extends Helper {
   async stopMockingRoute(url, handler) {
     return this.browserContext.unroute(...arguments);
   }
+
+  /**
+   * Starts recording of network traffic.
+   * This also resets recorded network requests.
+   *
+   * ```js
+   * I.startRecordingTraffic();
+   * ```
+   *
+   * @return {Promise<void>}
+   */
+  async startRecordingTraffic() {
+    this.flushNetworkTraffics();
+    this.recording = true;
+    this.recordedAtLeastOnce = true;
+
+    this.page.on('requestfinished', async (request) => {
+      const information = {
+        url: request.url(),
+        method: request.method(),
+        requestHeaders: request.headers(),
+        requestPostData: request.postData(),
+      };
+
+      this.debugSection('REQUEST: ', JSON.stringify(information));
+
+      information.requestPostData = JSON.parse(information.requestPostData);
+      this.requests.push(information);
+      return this._waitForAction();
+    });
+  }
+
+  /**
+  *  Grab the recording network traffics
+  *
+  * @return { Array<any> }
+  *
+  */
+  grabRecordedNetworkTraffics() {
+    if (!this.recording || !this.recordedAtLeastOnce) {
+      throw new Error('Failure in test automation. You use "I.grabRecordedNetworkTraffics", but "I.startRecordingTraffic" was never called before.');
+    }
+    return this.requests;
+  }
+
+  /**
+   * Blocks traffic for URL.
+   *
+   * Examples:
+   *
+   * ```js
+   * I.blockTraffic('http://example.com/css/style.css');
+   * I.blockTraffic('http://example.com/css/*.css');
+   * I.blockTraffic('http://example.com/**');
+   * I.blockTraffic(/\.css$/);
+   * ```
+   *
+   * @param url URL to block . URL can contain * for wildcards. Example: https://www.example.com** to block all traffic for that domain. Regexp are also supported.
+   */
+  async blockTraffic(url) {
+    this.page.route(url, (route) => {
+      route
+        .abort()
+        // Sometimes it happens that browser has been closed in the meantime. It is ok to ignore error then.
+        .catch((e) => {});
+    });
+    return this._waitForAction();
+  }
+
+  /**
+   * Mocks traffic for URL(s).
+   * This is a powerful feature to manipulate network traffic. Can be used e.g. to stabilize your tests, speed up your tests or as a last resort to make some test scenarios even possible.
+   *
+   * Examples:
+   *
+   * ```js
+   * I.mockTraffic('/api/users/1', '{ id: 1, name: 'John Doe' }');
+   * I.mockTraffic('/api/users/*', JSON.stringify({ id: 1, name: 'John Doe' }));
+   * I.mockTraffic([/^https://api.example.com/v1/, 'https://api.example.com/v2/**'], 'Internal Server Error', 'text/html');
+   * ```
+   *
+   * @param urls string|Array These are the URL(s) to mock, e.g. "/fooapi/*" or "['/fooapi_1/*', '/barapi_2/*']". Regular expressions are also supported.
+   * @param responseString string The string to return in fake response's body.
+   * @param contentType Content type of fake response. If not specified default value 'application/json' is used.
+   */
+  async mockTraffic(urls, responseString, contentType = 'application/json') {
+    // Required to mock cross-domain requests
+    const headers = { 'access-control-allow-origin': '*' };
+
+    if (typeof urls === 'string') {
+      urls = [urls];
+    }
+
+    urls.forEach((url) => {
+      this.page.route(url, (route) => {
+        if (this.page.isClosed()) {
+          // Sometimes it happens that browser has been closed in the meantime.
+          // In this case we just don't fulfill to prevent error in test scenario.
+          return;
+        }
+        route.fulfill({
+          contentType,
+          headers,
+          body: responseString,
+        });
+      });
+    });
+    return this._waitForAction();
+  }
+
+  /**
+   * Resets all recorded network requests.
+   */
+  flushNetworkTraffics() {
+    this.requests = [];
+  }
+
+  /**
+   * Stops recording of network traffic. Recorded traffic is not flashed.
+   *
+   * ```js
+   * I.stopRecordingTraffic();
+   * ```
+   */
+  stopRecordingTraffic() {
+    this.page.removeAllListeners('request');
+    this.recording = false;
+  }
+
+  /**
+   * Verifies that a certain request is part of network traffic.
+   *
+   * ```js
+   * // checking the request url contains certain query strings
+   * I.amOnPage('https://openai.com/blog/chatgpt');
+   * I.startRecordingTraffic();
+   * await I.seeTraffic({
+   *    name: 'sentry event',
+   *    url: 'https://images.openai.com/blob/cf717bdb-0c8c-428a-b82b-3c3add87a600',
+   *    parameters: {
+   *       width: '1919',
+   *       height: '1138',
+   *     },
+   * });
+   * ```
+   *
+   * ```js
+   * // checking the request url contains certain post data
+   * I.amOnPage('https://openai.com/blog/chatgpt');
+   * I.startRecordingTraffic();
+   * await I.seeTraffic({
+   *    name: 'event',
+   *    url: 'https://cloudflareinsights.com/cdn-cgi/rum',
+   *    requestPostData: {
+   *       st: 2,
+   *     },
+   * });
+   * ```
+   *
+   * @param {Object} opts - options when checking the traffic network.
+   * @param {string} opts.name A name of that request. Can be any value. Only relevant to have a more meaningful error message in case of fail.
+   * @param {string} opts.url Expected URL of request in network traffic
+   * @param {Object} [opts.parameters] Expected parameters of that request in network traffic
+   * @param {Object} [opts.requestPostData] Expected that request contains post data in network traffic
+   * @param {number} [opts.timeout] Timeout to wait for request in seconds. Default is 10 seconds.
+   * @return { Promise<*> }
+   */
+  async seeTraffic({
+    name, url, parameters, requestPostData, timeout = 10,
+  }) {
+    if (!name) {
+      throw new Error('Missing required key "name" in object given to "I.seeTraffic".');
+    }
+
+    if (!url) {
+      throw new Error('Missing required key "url" in object given to "I.seeTraffic".');
+    }
+
+    if (!this.recording || !this.recordedAtLeastOnce) {
+      throw new Error('Failure in test automation. You use "I.seeInTraffic", but "I.startRecordingTraffic" was never called before.');
+    }
+
+    for (let i = 0; i <= timeout * 2; i++) {
+      const found = this._isInTraffic(url, parameters);
+      if (found) {
+        return true;
+      }
+      await new Promise((done) => setTimeout(done, 1000));
+    }
+
+    // check request post data
+    if (requestPostData && this._isInTraffic(url)) {
+      const advancedTestResults = createAdvancedTestResults(url, requestPostData, this.requests);
+
+      assert.equal(advancedTestResults, true, `Traffic named "${name}" found correct URL ${url}, BUT the post data did not match:\n ${advancedTestResults}`);
+    } else if (parameters && this._isInTraffic(url)) {
+      const advancedTestResults = createAdvancedTestResults(url, parameters, this.requests);
+
+      assert.fail(
+        `Traffic named "${name}" found correct URL ${url}, BUT the query parameters did not match:\n`
+        + `${advancedTestResults}`,
+      );
+    } else {
+      assert.fail(
+        `Traffic named "${name}" not found in recorded traffic within ${timeout} seconds.\n`
+        + `Expected url: ${url}.\n`
+        + `Recorded traffic:\n${this._getTrafficDump()}`,
+      );
+    }
+  }
+
+  /**
+   * Returns full URL of request matching parameter "urlMatch".
+   *
+   * @param {string|RegExp} urlMatch Expected URL of request in network traffic. Can be a string or a regular expression.
+   *
+   * Examples:
+   *
+   * ```js
+   * I.grabTrafficUrl('https://api.example.com/session');
+   * I.grabTrafficUrl(/session.*start/);
+   * ```
+   *
+   * @return {Promise<*>}
+   */
+  grabTrafficUrl(urlMatch) {
+    if (!this.recordedAtLeastOnce) {
+      throw new Error('Failure in test automation. You use "I.grabTrafficUrl", but "I.startRecordingTraffic" was never called before.');
+    }
+
+    for (const i in this.requests) {
+      // eslint-disable-next-line no-prototype-builtins
+      if (this.requests.hasOwnProperty(i)) {
+        const request = this.requests[i];
+
+        if (request.url && request.url.match(new RegExp(urlMatch))) {
+          return request.url;
+        }
+      }
+    }
+
+    assert.fail(`Method "getTrafficUrl" failed: No request found in traffic that matches ${urlMatch}`);
+  }
+
+  /**
+   * Verifies that a certain request is not part of network traffic.
+   *
+   * Examples:
+   *
+   * ```js
+   * I.dontSeeTraffic({ name: 'Unexpected API Call', url: 'https://api.example.com' });
+   * I.dontSeeTraffic({ name: 'Unexpected API Call of "user" endpoint', url: /api.example.com.*user/ });
+   * ```
+   *
+   * @param {Object} opts - options when checking the traffic network.
+   * @param {string} opts.name A name of that request. Can be any value. Only relevant to have a more meaningful error message in case of fail.
+   * @param {string|RegExp} opts.url Expected URL of request in network traffic. Can be a string or a regular expression.
+   *
+   */
+  dontSeeTraffic({ name, url }) {
+    if (!this.recordedAtLeastOnce) {
+      throw new Error('Failure in test automation. You use "I.dontSeeTraffic", but "I.startRecordingTraffic" was never called before.');
+    }
+
+    if (!name) {
+      throw new Error('Missing required key "name" in object given to "I.dontSeeTraffic".');
+    }
+
+    if (!url) {
+      throw new Error('Missing required key "url" in object given to "I.dontSeeTraffic".');
+    }
+
+    if (this._isInTraffic(url)) {
+      assert.fail(`Traffic with name "${name}" (URL: "${url}') found, but was not expected to be found.`);
+    }
+  }
+
+  /**
+   * Checks if URL with parameters is part of network traffic. Returns true or false. Internal method for this helper.
+   *
+   * @param url URL to look for.
+   * @param [parameters] Parameters that this URL needs to contain
+   * @return {boolean} Whether or not URL with parameters is part of network traffic.
+   * @private
+   */
+  _isInTraffic(url, parameters) {
+    let isInTraffic = false;
+    this.requests.forEach((request) => {
+      if (isInTraffic) {
+        return; // We already found traffic. Continue with next request
+      }
+
+      if (!request.url.match(new RegExp(url))) {
+        return; // url not found in this request. continue with next request
+      }
+
+      // URL has matched. Now we check the parameters
+
+      if (parameters) {
+        const advancedReport = allParameterValuePairsMatchExtreme(extractQueryObjects(request.url), parameters);
+        if (advancedReport === true) {
+          isInTraffic = true;
+        }
+      } else {
+        isInTraffic = true;
+      }
+    });
+
+    return isInTraffic;
+  }
+
+  /**
+   * Returns all URLs of all network requests recorded so far during execution of test scenario.
+   *
+   * @return {string} List of URLs recorded as a string, seperaeted by new lines after each URL
+   * @private
+   */
+  _getTrafficDump() {
+    let dumpedTraffic = '';
+    this.requests.forEach((request) => {
+      dumpedTraffic += `${request.method} - ${request.url}\n`;
+    });
+    return dumpedTraffic;
+  }
 }
 
 module.exports = Playwright;
@@ -3152,3 +3482,134 @@ function highlightActiveElement(element, context) {
 
   highlightElement(element, context);
 }
+
+const createAdvancedTestResults = (url, dataToCheck, requests) => {
+  // Creates advanced test results for a network traffic check.
+  // Advanced test results only applies when expected parameters are set
+  if (!dataToCheck) return '';
+
+  let urlFound = false;
+  let advancedResults;
+  requests.forEach((request) => {
+    // url not found in this request. continue with next request
+    if (urlFound || !request.url.match(new RegExp(url))) return;
+    urlFound = true;
+
+    // Url found. Now we create advanced test report for that URL and show which parameters failed
+    if (!request.requestPostData) {
+      advancedResults = allParameterValuePairsMatchExtreme(extractQueryObjects(request.url), dataToCheck);
+    } else if (request.requestPostData) {
+      advancedResults = allRequestPostDataValuePairsMatchExtreme(request.requestPostData, dataToCheck);
+    }
+  });
+  return advancedResults;
+};
+
+const extractQueryObjects = (queryString) => {
+  // Converts a string of GET parameters into an array of parameter objects. Each parameter object contains the properties "name" and "value".
+  if (queryString.indexOf('?') === -1) {
+    return [];
+  }
+  const queryObjects = [];
+
+  const queryPart = queryString.split('?')[1];
+
+  const queryParameters = queryPart.split('&');
+
+  queryParameters.forEach((queryParameter) => {
+    const keyValue = queryParameter.split('=');
+    const queryObject = {};
+    // eslint-disable-next-line prefer-destructuring
+    queryObject.name = keyValue[0];
+    queryObject.value = decodeURIComponent(keyValue[1]);
+    queryObjects.push(queryObject);
+  });
+
+  return queryObjects;
+};
+
+const allParameterValuePairsMatchExtreme = (queryStringObject, advancedExpectedParameterValuePairs) => {
+  // More advanced check if all request parameters match with the expectations
+  let littleReport = '\nQuery parameters:\n';
+  let success = true;
+
+  for (const expectedKey in advancedExpectedParameterValuePairs) {
+    if (!Object.prototype.hasOwnProperty.call(advancedExpectedParameterValuePairs, expectedKey)) {
+      continue;
+    }
+    let parameterFound = false;
+    const expectedValue = advancedExpectedParameterValuePairs[expectedKey];
+
+    for (const queryParameter of queryStringObject) {
+      if (queryParameter.name === expectedKey) {
+        parameterFound = true;
+        if (expectedValue === undefined) {
+          littleReport += `   ${expectedKey.padStart(10, ' ')}\n`;
+        } else if (typeof expectedValue === 'object' && expectedValue.base64) {
+          const decodedActualValue = Buffer.from(queryParameter.value, 'base64').toString('utf8');
+          if (decodedActualValue === expectedValue.base64) {
+            littleReport += `   ${expectedKey.padStart(10, ' ')} = base64(${expectedValue.base64})\n`;
+          } else {
+            littleReport += ` ✖ ${expectedKey.padStart(10, ' ')} = base64(${expectedValue.base64})     -> actual value: "base64(${decodedActualValue})"\n`;
+            success = false;
+          }
+        } else if (queryParameter.value === expectedValue) {
+          littleReport += `   ${expectedKey.padStart(10, ' ')} = ${expectedValue}\n`;
+        } else {
+          littleReport += ` ✖ ${expectedKey.padStart(10, ' ')} = ${expectedValue}      -> actual value: "${queryParameter.value}"\n`;
+          success = false;
+        }
+      }
+    }
+
+    if (parameterFound === false) {
+      littleReport += ` ✖ ${expectedKey.padStart(10, ' ')}${expectedValue ? ` = ${JSON.stringify(expectedValue)}` : ''}      -> parameter not found in request\n`;
+      success = false;
+    }
+  }
+
+  return success ? true : littleReport;
+};
+
+const allRequestPostDataValuePairsMatchExtreme = (RequestPostDataObject, advancedExpectedRequestPostValuePairs) => {
+  // More advanced check if all request post data match with the expectations
+  let littleReport = '\nRequest Post Data:\n';
+  let success = true;
+
+  for (const expectedKey in advancedExpectedRequestPostValuePairs) {
+    if (!Object.prototype.hasOwnProperty.call(advancedExpectedRequestPostValuePairs, expectedKey)) {
+      continue;
+    }
+    let keyFound = false;
+    const expectedValue = advancedExpectedRequestPostValuePairs[expectedKey];
+
+    for (const [key, value] of Object.entries(RequestPostDataObject)) {
+      if (key === expectedKey) {
+        keyFound = true;
+        if (expectedValue === undefined) {
+          littleReport += `   ${expectedKey.padStart(10, ' ')}\n`;
+        } else if (typeof expectedValue === 'object' && expectedValue.base64) {
+          const decodedActualValue = Buffer.from(value, 'base64').toString('utf8');
+          if (decodedActualValue === expectedValue.base64) {
+            littleReport += `   ${expectedKey.padStart(10, ' ')} = base64(${expectedValue.base64})\n`;
+          } else {
+            littleReport += ` ✖ ${expectedKey.padStart(10, ' ')} = base64(${expectedValue.base64})     -> actual value: "base64(${decodedActualValue})"\n`;
+            success = false;
+          }
+        } else if (value === expectedValue) {
+          littleReport += `   ${expectedKey.padStart(10, ' ')} = ${expectedValue}\n`;
+        } else {
+          littleReport += ` ✖ ${expectedKey.padStart(10, ' ')} = ${expectedValue}      -> actual value: "${value}"\n`;
+          success = false;
+        }
+      }
+    }
+
+    if (keyFound === false) {
+      littleReport += ` ✖ ${expectedKey.padStart(10, ' ')}${expectedValue ? ` = ${JSON.stringify(expectedValue)}` : ''}      -> key not found in request\n`;
+      success = false;
+    }
+  }
+
+  return success ? true : littleReport;
+};

package/lib/plugin/standardActingHelpers.js

@@ -4,8 +4,6 @@ const standardActingHelpers = [
   'Puppeteer',
   'Appium',
   'TestCafe',
-  'Protractor',
-  'Nightmare',
 ];
 
 module.exports = standardActingHelpers;

package/lib/plugin/wdio.js

@@ -51,7 +51,6 @@ let restartsSession;
  * }
  * ```
  *
- * Please note, this service can be used with Protractor helper as well!
  *
  * #### Sauce Service
  *

package/lib/recorder.js

@@ -94,7 +94,8 @@ module.exports = {
     oldPromises = [];
     tasks = [];
     this.session.running = false;
-    this.retries = [];
+    // reset this retries makes the retryFailedStep plugin won't work if there is Before/BeforeSuit block due to retries is undefined on Scenario
+    // this.retries = [];
   },
 
   /**