codeceptjs 3.5.13-beta.1 → 3.5.13-beta.3

package/docs/webapi/startRecordingTraffic.mustache

@@ -0,0 +1,8 @@
+Starts recording the network traffics.
+This also resets recorded network requests.
+
+```js
+I.startRecordingTraffic();
+```
+
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/stopRecordingTraffic.mustache

@@ -0,0 +1,5 @@
+Stops recording of network traffic. Recorded traffic is not flashed.
+
+```js
+I.stopRecordingTraffic();
+```

package/docs/webapi/switchTo.mustache

@@ -0,0 +1,9 @@
+Switches frame or in case of null locator reverts to parent.
+
+```js
+I.switchTo('iframe'); // switch to first iframe
+I.switchTo(); // switch back to main page
+```
+
+@param {?CodeceptJS.LocatorOrString} [locator=null] (optional, `null` by default) element located by CSS|XPath|strict locator.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/switchToNextTab.mustache

@@ -0,0 +1,10 @@
+Switch focus to a particular tab by its number. It waits tabs loading and then switch tab.
+
+```js
+I.switchToNextTab();
+I.switchToNextTab(2);
+```
+
+@param {number} [num] (optional) number of tabs to switch forward, default: 1.
+@param {number | null} [sec] (optional) time in seconds to wait.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/switchToPreviousTab.mustache

@@ -0,0 +1,10 @@
+Switch focus to a particular tab by its number. It waits tabs loading and then switch tab.
+
+```js
+I.switchToPreviousTab();
+I.switchToPreviousTab(2);
+```
+
+@param {number} [num] (optional) number of tabs to switch backward, default: 1.
+@param {number?} [sec] (optional) time in seconds to wait.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/type.mustache

@@ -0,0 +1,21 @@
+Types out the given text into an active field.
+To slow down typing use a second parameter, to set interval between key presses.
+_Note:_ Should be used when [`fillField`](#fillfield) is not an option.
+
+```js
+// passing in a string
+I.type('Type this out.');
+
+// typing values with a 100ms interval
+I.type('4141555311111111', 100);
+
+// passing in an array
+I.type(['T', 'E', 'X', 'T']);
+
+// passing a secret
+I.type(secret('123456'));
+```
+
+@param {string|string[]} key or array of keys to type.
+@param {?number} [delay=null] (optional) delay in ms between key presses
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/uncheckOption.mustache

@@ -0,0 +1,13 @@
+Unselects a checkbox or radio button.
+Element is located by label or name or CSS or XPath.
+
+The second parameter is a context (CSS or XPath locator) to narrow the search.
+
+```js
+I.uncheckOption('#agree');
+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.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/wait.mustache

@@ -0,0 +1,8 @@
+Pauses execution for a number of seconds.
+
+```js
+I.wait(2); // wait 2 secs
+```
+
+@param {number} sec number of second to wait.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/waitForClickable.mustache

@@ -0,0 +1,11 @@
+Waits for element to be clickable (by default waits for 1sec).
+Element can be located by CSS or XPath.
+
+```js
+I.waitForClickable('.btn.continue');
+I.waitForClickable('.btn.continue', 5); // wait for 5 secs
+```
+
+@param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+@param {number} [sec] (optional, `1` by default) time in seconds to wait
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/waitForCookie.mustache

@@ -0,0 +1,9 @@
+Waits for the specified cookie in the cookies.
+
+```js
+I.waitForCookie("token");
+```
+
+@param {string} name expected cookie name.
+@param {number} [sec=3] (optional, `3` by default) time in seconds to wait
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/waitForDetached.mustache

@@ -0,0 +1,10 @@
+Waits for an element to become not attached to the DOM on a page (by default waits for 1sec).
+Element can be located by CSS or XPath.
+
+```js
+I.waitForDetached('#popup');
+```
+
+@param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+@param {number} [sec=1] (optional, `1` by default) time in seconds to wait
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/waitForElement.mustache

@@ -0,0 +1,11 @@
+Waits for element to be present on page (by default waits for 1sec).
+Element can be located by CSS or XPath.
+
+```js
+I.waitForElement('.btn.continue');
+I.waitForElement('.btn.continue', 5); // wait for 5 secs
+```
+
+@param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+@param {number} [sec] (optional, `1` by default) time in seconds to wait
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/waitForEnabled.mustache

@@ -0,0 +1,6 @@
+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 {number} [sec=1] (optional) time in seconds to wait, 1 by default.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/waitForFunction.mustache

@@ -0,0 +1,17 @@
+Waits for a function to return true (waits for 1 sec by default).
+Running in browser context.
+
+```js
+I.waitForFunction(fn[, [args[, timeout]])
+```
+
+```js
+I.waitForFunction(() => window.requests == 0);
+I.waitForFunction(() => window.requests == 0, 5); // waits for 5 sec
+I.waitForFunction((count) => window.requests == count, [3], 5) // pass args and wait for 5 sec
+```
+
+@param {string|function} fn to be executed in browser context.
+@param {any[]|number} [argsOrSec] (optional, `1` by default) arguments for function or seconds.
+@param {number} [sec] (optional, `1` by default) time in seconds to wait
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/waitForInvisible.mustache

@@ -0,0 +1,10 @@
+Waits for an element to be removed or become invisible on a page (by default waits for 1sec).
+Element can be located by CSS or XPath.
+
+```js
+I.waitForInvisible('#popup');
+```
+
+@param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+@param {number} [sec=1] (optional, `1` by default) time in seconds to wait
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/waitForNumberOfTabs.mustache

@@ -0,0 +1,9 @@
+Waits for number of tabs.
+
+```js
+I.waitForNumberOfTabs(2);
+```
+
+@param {number} expectedTabs expecting the number of tabs.
+@param {number} sec number of secs to wait.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/waitForText.mustache

@@ -0,0 +1,13 @@
+Waits for a text to appear (by default waits for 1sec).
+Element can be located by CSS or XPath.
+Narrow down search results by providing context.
+
+```js
+I.waitForText('Thank you, form has been submitted');
+I.waitForText('Thank you, form has been submitted', 5, '#modal');
+```
+
+@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.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/waitForValue.mustache

@@ -0,0 +1,10 @@
+Waits for the specified value to be in value attribute.
+
+```js
+I.waitForValue('//input', "GoodValue");
+```
+
+@param {LocatorOrString} field input field.
+@param {string }value expected value.
+@param {number} [sec=1] (optional, `1` by default) time in seconds to wait
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/waitForVisible.mustache

@@ -0,0 +1,10 @@
+Waits for an element to become visible on a page (by default waits for 1sec).
+Element can be located by CSS or XPath.
+
+```js
+I.waitForVisible('#popup');
+```
+
+@param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+@param {number} [sec=1] (optional, `1` by default) time in seconds to wait
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/waitInUrl.mustache

@@ -0,0 +1,9 @@
+Waiting for the part of the URL to match the expected. Useful for SPA to understand that page was changed.
+
+```js
+I.waitInUrl('/info', 2);
+```
+
+@param {string} urlPart value to check.
+@param {number} [sec=1] (optional, `1` by default) time in seconds to wait
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/waitNumberOfVisibleElements.mustache

@@ -0,0 +1,10 @@
+Waits for a specified number of elements on the page.
+
+```js
+I.waitNumberOfVisibleElements('a', 3);
+```
+
+@param {CodeceptJS.LocatorOrString} 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
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/waitToHide.mustache

@@ -0,0 +1,10 @@
+Waits for an element to hide (by default waits for 1sec).
+Element can be located by CSS or XPath.
+
+```js
+I.waitToHide('#popup');
+```
+
+@param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+@param {number} [sec=1] (optional, `1` by default) time in seconds to wait
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/waitUrlEquals.mustache

@@ -0,0 +1,10 @@
+Waits for the entire URL to match the expected
+
+```js
+I.waitUrlEquals('/info', 2);
+I.waitUrlEquals('http://127.0.0.1:8000/info');
+```
+
+@param {string} urlPart value to check.
+@param {number} [sec=1] (optional, `1` by default) time in seconds to wait
+@returns {void} automatically synchronized promise through #recorder

package/lib/helper/Playwright.js

@@ -51,6 +51,7 @@ const { createValueEngine, createDisabledEngine } = require('./extras/Playwright
 const {
   seeElementError, dontSeeElementError, dontSeeElementInDOMError, seeElementInDOMError,
 } = require('./errors/ElementAssertion');
+const { createAdvancedTestResults, allParameterValuePairsMatchExtreme, extractQueryObjects } = require('./networkTraffics/utils');
 const { log } = require('../output');
 
 const pathSeparator = path.sep;
@@ -2976,14 +2977,8 @@ class Playwright extends Helper {
   }
 
   /**
-   * Starts recording the network traffics.
-   * This also resets recorded network requests.
+   * {{> flushNetworkTraffics }}
    *
-   * ```js
-   * I.startRecordingTraffic();
-   * ```
-   *
-   * @return {void}
    */
   startRecordingTraffic() {
     this.flushNetworkTraffics();
@@ -3010,18 +3005,8 @@ class Playwright extends Helper {
   }
 
   /**
-  *  Grab the recording network traffics
-  *
-  * ```js
-  * const traffics = await I.grabRecordedNetworkTraffics();
-  * expect(traffics[0].url).to.equal('https://reqres.in/api/comments/1');
-  * expect(traffics[0].response.status).to.equal(200);
-  * expect(traffics[0].response.body).to.contain({ name: 'this was mocked' });
-  * ```
-  *
-  * @return { Promise<Array<any>> }
-  *
-  */
+   * {{> grabRecordedNetworkTraffics }}
+   */
   async grabRecordedNetworkTraffics() {
     if (!this.recording || !this.recordedAtLeastOnce) {
       throw new Error('Failure in test automation. You use "I.grabRecordedNetworkTraffics", but "I.startRecordingTraffic" was never called before.');
@@ -3129,18 +3114,14 @@ class Playwright extends Helper {
   }
 
   /**
-   * Resets all recorded network requests.
+   * {{> flushNetworkTraffics }}
    */
   flushNetworkTraffics() {
     this.requests = [];
   }
 
   /**
-   * Stops recording of network traffic. Recorded traffic is not flashed.
-   *
-   * ```js
-   * I.stopRecordingTraffic();
-   * ```
+   * {{> stopRecordingTraffic }}
    */
   stopRecordingTraffic() {
     this.page.removeAllListeners('request');
@@ -3148,42 +3129,7 @@ class Playwright extends Helper {
   }
 
   /**
-   * 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<*> }
+   * {{> seeTraffic }}
    */
   async seeTraffic({
     name, url, parameters, requestPostData, timeout = 10,
@@ -3265,18 +3211,7 @@ class Playwright extends Helper {
   }
 
   /**
-   * 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 }}
    *
    */
   dontSeeTraffic({ name, url }) {
@@ -3988,134 +3923,3 @@ async function highlightActiveElement(element) {
     });
   }
 }
-
-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;
-};