codeceptjs 3.3.7-beta.1 → 3.3.7

package/docs/basics.md

@@ -23,14 +23,14 @@ The `I` object is an **actor**, an abstraction for a testing user. The `I` is a
 
 ## Architecture
 
-CodeceptJS bypasses execution commands to helpers. Depending on the helper enabled, your tests will be executed differently. If you need cross-browser support you should choose Selenium-based WebDriver or TestCafé. If you are interested in speed - you should use Chrome-based Puppeteer.
+CodeceptJS bypasses execution commands to helpers. Depending on the helper enabled, your tests will be executed differently.
 
 The following is a diagram of the CodeceptJS architecture:
 
 ![architecture](/img/architecture.png)
 
 All helpers share the same API, so it's easy to migrate tests from one backend to another.
-However, because of the difference in backends and their limitations, they are not guaranteed to be compatible with each other. For instance, you can't set request headers in WebDriver or Protractor, but you can do so in Puppeteer or Nightmare.
+However, because of the difference in backends and their limitations, they are not guaranteed to be compatible with each other. For instance, you can't set request headers in WebDriver but you can do so in Playwright or Puppeteer.
 
 **Pick one helper, as it defines how tests are executed.** If requirements change it's easy to migrate to another.
 
@@ -290,7 +290,6 @@ I.waitForElement('#agree_button', 30); // secs
 // clicks a button only when it is visible
 I.click('#agree_button');
 ```
-> ℹ See [helpers reference](/reference) for a complete list of all available commands for the helper you use.
 
 ## How It Works
 

package/docs/bdd.md

@@ -406,6 +406,39 @@ npx codeceptjs run --grep "@important"
 
 Tag should be placed before *Scenario:* or before *Feature:* keyword. In the last case all scenarios of that feature will be added to corresponding group.
 
+### Custom types
+
+If you need parameter text in more advanced way and you like using [Cucumber expressions](https://docs.cucumber.io/cucumber/cucumber-expressions/) better that regular expressions, use `DefineParameterType` function. You can extend Cucumber Expressions so they automatically convert output parameters to your own types or transforms the match from the regexp.
+
+```js
+DefineParameterType({
+  name: 'popup_type',
+  regexp: /critical|non-critical/,
+  transformer: (match) => {
+    return match === 'critical' ? '[class$="error"]' 
+    : '[class$="warning"]';
+  },
+};);
+
+Given('I see {popup_type} popup', (popup) => {
+  I.seeElement(popup);
+});
+```
+
+```gherkin
+  Scenario: Display error message if user doesn't have permissions
+    Given I on "Main" page without permissons
+    Then I see error popup
+```
+
+#### Parameters
+
+*  `name` **[string]** The name the parameter type will be recognised by in output parameters.
+*  `regexp` **([string] | [RegExp])** A regexp that will match the parameter. May include capture groups.
+*  `transformer` **[function]** A function or method that transforms the match from the regexp.
+*  `useForSnippets` **[boolean]** Defaults to `true`. That means this parameter type will be used to generate snippets for undefined steps. 
+*  `preferForRegexpMatch` **[boolean]** Defaults to `false`. Set to true if you have step definitions that use regular expressions, and you want this parameter type to take precedence over others during a match.
+
 ## Configuration
 
 * `gherkin`

package/docs/best.md

@@ -90,7 +90,7 @@ However, it's recommended to not overengineer and keep tests simple. If a test c
 
 ```js
 class CheckoutForm {
-  
+
   fillBillingInformation(data = {}) {
     // take data in a flexible format
     // iterate over fields to fill them all
@@ -99,7 +99,7 @@ class CheckoutForm {
     }
   }
 
-} 
+}
 module.exports = new CheckoutForm();
 module.exports.CheckoutForm = CheckoutForm; // for inheritance
 ```
@@ -108,7 +108,7 @@ module.exports.CheckoutForm = CheckoutForm; // for inheritance
 
 ```js
 class DropDownComponent {
-  
+
   selectFirstItem(locator) {
     I.click(locator);
     I.click('#dropdown-items li');
@@ -133,17 +133,17 @@ class DatePicker {
     I.click(locator);
     I.click('.currentDate', '.date-picker');
   }
-  
+
   selectInNextMonth(locator, date = '15') {
     I.click(locator);
     I.click('show next month', '.date-picker')
     I.click(date, '.date-picker')
   }
-  
+
 }
 
 
-module.exports = new DatePicker;
+module.exports = new DatePicker();
 module.exports.DatePicker = DatePicker; // for inheritance
 ```
 
@@ -187,7 +187,7 @@ include them like this:
 
 ```js
 // inside codecept conf file
-bootstrap: () => {  
+bootstrap: () => {
   codeceptjs.container.append({
     testUser: {
       email: 'test@test.com',
@@ -202,7 +202,7 @@ bootstrap: () => {
 ```js
 include: {
   // ...
-  testData: './config/testData' 
+  testData: './config/testData'
 
 }
 ```

package/docs/build/Appium.js

@@ -2,7 +2,7 @@ let webdriverio;
 let wdioV4;
 
 const fs = require('fs');
-const axios = require('axios');
+const axios = require('axios').default;
 
 const Webdriver = require('./WebDriver');
 const AssertionFailedError = require('../assert/error');
@@ -13,6 +13,10 @@ const ConnectionRefused = require('./errors/ConnectionRefused');
 
 const mobileRoot = '//*';
 const webRoot = 'body';
+const supportedPlatform = {
+  android: 'Android',
+  iOS: 'iOS',
+};
 
 /**
  *  Appium helper extends [Webriver](http://codecept.io/helpers/WebDriver/) helper.
@@ -131,6 +135,7 @@ class Appium extends Webdriver {
     super(config);
 
     this.isRunning = false;
+    this.axios = axios.create();
 
     webdriverio = require('webdriverio');
     (!webdriverio.VERSION || webdriverio.VERSION.indexOf('4') !== 0) ? wdioV4 = false : wdioV4 = true;
@@ -185,7 +190,7 @@ class Appium extends Webdriver {
     config.capabilities.app = config.app || config.capabilities.app;
     config.capabilities.platformName = config.platform || config.capabilities.platformName;
     config.capabilities.tunnelIdentifier = config.tunnelIdentifier || config.capabilities.tunnelIdentifier; // Adding the code to connect to sauce labs via sauce tunnel
-    config.waitForTimeout /= 1000; // convert to seconds
+    config.waitForTimeoutInSeconds = config.waitForTimeout / 1000; // convert to seconds
 
     // [CodeceptJS compatible] transform host to hostname
     config.hostname = config.host || config.hostname;
@@ -215,8 +220,8 @@ class Appium extends Webdriver {
       name: 'platform',
       message: 'Mobile Platform',
       type: 'list',
-      choices: ['iOS', 'Android'],
-      default: 'Android',
+      choices: ['iOS', supportedPlatform.android],
+      default: supportedPlatform.android,
     }, {
       name: 'device',
       message: 'Device to run tests on',
@@ -427,6 +432,23 @@ class Appium extends Webdriver {
     fn();
   }
 
+  /**
+   * Returns app installation status.
+   *
+   * ```js
+   * I.checkIfAppIsInstalled("com.example.android.apis");
+   * ```
+   *
+   * @param {string} bundleId String  ID of bundled app
+   * @return {Promise<boolean>}
+   *
+   * Appium: support only Android
+   */
+  async checkIfAppIsInstalled(bundleId) {
+    onlyForApps.call(this, supportedPlatform.android);
+    return this.browser.isAppInstalled(bundleId);
+  }
+
   /**
    * Check if an app is installed.
    *
@@ -440,7 +462,7 @@ class Appium extends Webdriver {
    * Appium: support only Android
    */
   async seeAppIsInstalled(bundleId) {
-    onlyForApps.call(this, 'Android');
+    onlyForApps.call(this, supportedPlatform.android);
     const res = await this.browser.isAppInstalled(bundleId);
     return truth(`app ${bundleId}`, 'to be installed').assert(res);
   }
@@ -458,7 +480,7 @@ class Appium extends Webdriver {
    * Appium: support only Android
    */
   async seeAppIsNotInstalled(bundleId) {
-    onlyForApps.call(this, 'Android');
+    onlyForApps.call(this, supportedPlatform.android);
     const res = await this.browser.isAppInstalled(bundleId);
     return truth(`app ${bundleId}`, 'to be installed').negate(res);
   }
@@ -475,7 +497,7 @@ class Appium extends Webdriver {
    * Appium: support only Android
    */
   async installApp(path) {
-    onlyForApps.call(this, 'Android');
+    onlyForApps.call(this, supportedPlatform.android);
     return this.browser.installApp(path);
   }
 
@@ -492,19 +514,35 @@ class Appium extends Webdriver {
    * @param {string} [bundleId] ID of bundle
    */
   async removeApp(appId, bundleId) {
-    onlyForApps.call(this, 'Android');
+    onlyForApps.call(this, supportedPlatform.android);
 
     if (wdioV4) {
       return this.browser.removeApp(bundleId);
     }
 
-    return axios({
+    return this.axios({
       method: 'post',
       url: `${this._buildAppiumEndpoint()}/session/${this.browser.sessionId}/appium/device/remove_app`,
       data: { appId, bundleId },
     });
   }
 
+  /**
+   * Reset the currently running app for current session.
+   *
+   * ```js
+   * I.resetApp();
+   * ```
+   *
+   */
+  async resetApp() {
+    onlyForApps.call(this);
+    return this.axios({
+      method: 'post',
+      url: `${this._buildAppiumEndpoint()}/session/${this.browser.sessionId}/appium/app/reset`,
+    });
+  }
+
   /**
    * Check current activity on an Android device.
    *
@@ -517,7 +555,7 @@ class Appium extends Webdriver {
    * Appium: support only Android
    */
   async seeCurrentActivityIs(currentActivity) {
-    onlyForApps.call(this, 'Android');
+    onlyForApps.call(this, supportedPlatform.android);
     const res = await this.browser.getCurrentActivity();
     return truth('current activity', `to be ${currentActivity}`).assert(res === currentActivity);
   }
@@ -534,7 +572,7 @@ class Appium extends Webdriver {
    * Appium: support only Android
    */
   async seeDeviceIsLocked() {
-    onlyForApps.call(this, 'Android');
+    onlyForApps.call(this, supportedPlatform.android);
     const res = await this.browser.isLocked();
     return truth('device', 'to be locked').assert(res);
   }
@@ -551,7 +589,7 @@ class Appium extends Webdriver {
    * Appium: support only Android
    */
   async seeDeviceIsUnlocked() {
-    onlyForApps.call(this, 'Android');
+    onlyForApps.call(this, supportedPlatform.android);
     const res = await this.browser.isLocked();
     return truth('device', 'to be locked').negate(res);
   }
@@ -579,7 +617,7 @@ class Appium extends Webdriver {
       currentOrientation = res;
     }
 
-    const res = await axios({
+    const res = await this.axios({
       method: 'get',
       url: `${this._buildAppiumEndpoint()}/session/${this.browser.sessionId}/orientation`,
     });
@@ -606,7 +644,7 @@ class Appium extends Webdriver {
       return this.browser.setOrientation(orientation);
     }
 
-    return axios({
+    return this.axios({
       method: 'post',
       url: `${this._buildAppiumEndpoint()}/session/${this.browser.sessionId}/orientation`,
       data: { orientation },
@@ -657,7 +695,7 @@ class Appium extends Webdriver {
    * Appium: support only Android
    */
   async grabCurrentActivity() {
-    onlyForApps.call(this, 'Android');
+    onlyForApps.call(this, supportedPlatform.android);
     return this.browser.getCurrentActivity();
   }
 
@@ -675,7 +713,7 @@ class Appium extends Webdriver {
    * Appium: support only Android
    */
   async grabNetworkConnection() {
-    onlyForApps.call(this, 'Android');
+    onlyForApps.call(this, supportedPlatform.android);
     const res = await this.browser.getNetworkConnection();
     return {
       value: res,
@@ -795,7 +833,7 @@ class Appium extends Webdriver {
    * @return {Promise<void>}
    */
   async startActivity(appPackage, appActivity) {
-    onlyForApps.call(this, 'Android');
+    onlyForApps.call(this, supportedPlatform.android);
     return this.browser.startActivity(appPackage, appActivity);
   }
 
@@ -820,7 +858,7 @@ class Appium extends Webdriver {
    * Appium: support only Android
    */
   async setNetworkConnection(value) {
-    onlyForApps.call(this, 'Android');
+    onlyForApps.call(this, supportedPlatform.android);
     return this.browser.setNetworkConnection(value);
   }
 
@@ -877,7 +915,7 @@ class Appium extends Webdriver {
    * Appium: support only Android
    */
   async sendDeviceKeyEvent(keyValue) {
-    onlyForApps.call(this, 'Android');
+    onlyForApps.call(this, supportedPlatform.android);
     if (wdioV4) {
       return this.browser.sendKeyEvent(keyValue);
     }
@@ -896,7 +934,7 @@ class Appium extends Webdriver {
    * Appium: support only Android
    */
   async openNotifications() {
-    onlyForApps.call(this, 'Android');
+    onlyForApps.call(this, supportedPlatform.android);
     return this.browser.openNotifications();
   }
 
@@ -965,7 +1003,7 @@ class Appium extends Webdriver {
     onlyForApps.call(this);
     const res = await this.browser.$(parseLocator.call(this, locator));
     // if (!res.length) throw new ElementNotFound(locator, 'was not found in UI');
-    return this.performSwipe(await res.getLocation(), { x: await res.getLocation().x + xoffset, y: await res.getLocation().y + yoffset });
+    return this.performSwipe(await res.getLocation(), { x: (await res.getLocation()).x + xoffset, y: (await res.getLocation()).y + yoffset });
   }
   /* eslint-enable */
 
@@ -1148,7 +1186,7 @@ class Appium extends Webdriver {
         direction = 'swipeRight';
         break;
     }
-    timeout = timeout || this.options.waitForTimeout;
+    timeout = timeout || this.options.waitForTimeoutInSeconds;
 
     const errorMsg = `element ("${searchableLocator}") still not visible after ${timeout}seconds`;
     const browser = this.browser;

package/docs/build/GraphQL.js

@@ -139,9 +139,9 @@ class GraphQL extends Helper {
    * ```
    *
    * @param {String} query
-   * @param {object} variables that may go along with the query
-   * @param {object} options are additional query options
-   * @param {object} headers
+   * @param {object} [variables] that may go along with the query
+   * @param {object} [options] are additional query options
+   * @param {object} [headers]
    * @return Promise<any>
    */
   async sendQuery(query, variables, options = {}, headers = {}) {
@@ -179,9 +179,9 @@ class GraphQL extends Helper {
    * ```
    *
    * @param {String} mutation
-   * @param {object} variables that may go along with the mutation
-   * @param {object} options are additional query options
-   * @param {object} headers
+   * @param {object} [variables] that may go along with the mutation
+   * @param {object} [options] are additional query options
+   * @param {object} [headers]
    * @return Promise<any>
    */
   async sendMutation(mutation, variables, options = {}, headers = {}) {

package/docs/build/Nightmare.js

@@ -128,7 +128,7 @@ class Nightmare extends Helper {
       this.evaluate_now((by, locator, contextEl) => {
         const res = window.codeceptjs.findAndStoreElement(by, locator, contextEl);
         if (res === null) {
-          throw new Error(`Element ${locator} couldn't be located by ${by}`);
+          throw new Error(`Element ${(new Locator(locator))} couldn't be located by ${by}`);
         }
         return res;
       }, done, by, value, contextEl);
@@ -708,7 +708,7 @@ class Nightmare extends Helper {
    */
   async seeNumberOfElements(locator, num) {
     const elements = await this._locate(locator);
-    return equals(`expected number of elements (${locator}) is ${num}, but found ${elements.length}`).assert(elements.length, num);
+    return equals(`expected number of elements (${(new Locator(locator))}) is ${num}, but found ${elements.length}`).assert(elements.length, num);
   }
 
   /**
@@ -726,7 +726,7 @@ class Nightmare extends Helper {
    */
   async seeNumberOfVisibleElements(locator, num) {
     const res = await this.grabNumberOfVisibleElements(locator);
-    return equals(`expected number of visible elements (${locator}) is ${num}, but found ${res}`).assert(res, num);
+    return equals(`expected number of visible elements (${(new Locator(locator))}) is ${num}, but found ${res}`).assert(res, num);
   }
 
   /**
@@ -1839,7 +1839,7 @@ class Nightmare extends Helper {
       height: Math.floor(rect.height),
     };
 
-    this.debug(`Screenshot of ${locator} element has been saved to ${outputFile}`);
+    this.debug(`Screenshot of ${(new Locator(locator))} element has been saved to ${outputFile}`);
     // take the screenshot
     await this.browser.screenshot(outputFile, button_clip);
   }