codeceptjs 3.4.1 → 3.5.1-2.beta.7

package/lib/helper/Appium.js

@@ -17,8 +17,12 @@ const supportedPlatform = {
   iOS: 'iOS',
 };
 
+const vendorPrefix = {
+  appium: 'appium',
+};
+
 /**
- *  Appium helper extends [Webriver](http://codecept.io/helpers/WebDriver/) helper.
+ *  Appium helper extends [Webdriver](http://codecept.io/helpers/WebDriver/) helper.
  *  It supports all browser methods and also includes special methods for mobile apps testing.
  *  You can use this helper to test Web on desktop and mobile devices and mobile apps.
  *
@@ -27,7 +31,7 @@ const supportedPlatform = {
  * Appium is an open source test automation framework for use with native, hybrid and mobile web apps that implements the WebDriver protocol.
  * It allows you to run Selenium tests on mobile devices and also test native, hybrid and mobile web apps.
  *
- * Download and install [Appium](http://appium.io/)
+ * Download and install [Appium](https://appium.io/docs/en/2.1/)
  *
  * ```sh
  * npm install -g appium
@@ -39,6 +43,7 @@ const supportedPlatform = {
  *
  * This helper should be configured in codecept.conf.ts or codecept.conf.js
  *
+ * * `appiumV2`: set this to true if you want to run tests with AppiumV2. See more how to setup [here](https://codecept.io/mobile/#setting-up)
  * * `app`: Application path. Local path or remote URL to an .ipa or .apk file, or a .zip containing one of these. Alias to desiredCapabilities.appPackage
  * * `host`: (default: 'localhost') Appium host
  * * `port`: (default: '4723') Appium port
@@ -112,11 +117,48 @@ const supportedPlatform = {
  * }
  * ```
  *
- * Additional configuration params can be used from <https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/caps.md>
+ * Example Android App using AppiumV2 on BrowserStack:
+ *
+ * ```js
+ * {
+ * helpers: {
+ *   Appium: {
+ *         appiumV2: true,
+ *         host: "hub-cloud.browserstack.com",
+ *         port: 4444,
+ *         user: process.env.BROWSERSTACK_USER,
+ *         key: process.env.BROWSERSTACK_KEY,
+ *         app: `bs://c700ce60cf1gjhgjh3ae8ed9770ghjg5a55b8e022f13c5827cg`,
+ *         browser: '',
+ *         desiredCapabilities: {
+ *             'appPackage': data.packageName,
+ *             'deviceName': process.env.DEVICE || 'Google Pixel 3',
+ *             'platformName': process.env.PLATFORM || 'android',
+ *             'platformVersion': process.env.OS_VERSION || '10.0',
+ *             'automationName': process.env.ENGINE || 'UIAutomator2',
+ *             'newCommandTimeout': 300000,
+ *             'androidDeviceReadyTimeout': 300000,
+ *             'androidInstallTimeout': 90000,
+ *             'appWaitDuration': 300000,
+ *             'autoGrantPermissions': true,
+ *             'gpsEnabled': true,
+ *             'isHeadless': false,
+ *             'noReset': false,
+ *             'noSign': true,
+ *             'bstack:options' : {
+ *                 "appiumVersion" : "2.0.1",
+ *             },
+ *         }
+ *   }
+ * }
+ * }
+ * ```
+ *
+ * Additional configuration params can be used from <https://github.com/appium/appium/blob/master/packages/appium/docs/en/guides/caps.md>
  *
  * ## Access From Helpers
  *
- * Receive a Appium client from a custom helper by accessing `browser` property:
+ * Receive Appium client from a custom helper by accessing `browser` property:
  *
  * ```js
  * let browser = this.helpers['Appium'].browser
@@ -135,9 +177,17 @@ class Appium extends Webdriver {
     super(config);
 
     this.isRunning = false;
+    if (config.appiumV2 === true) {
+      this.appiumV2 = true;
+    }
     this.axios = axios.create();
 
     webdriverio = require('webdriverio');
+    if (!config.appiumV2) {
+      console.log('The Appium core team does not maintain Appium 1.x anymore since the 1st of January 2022. Please migrating to Appium 2.x by adding appiumV2: true to your config.');
+      console.log('More info: https://bit.ly/appium-v2-migration');
+      console.log('This Appium 1.x support will be removed in next major release.');
+    }
   }
 
   _validateConfig(config) {
@@ -181,14 +231,22 @@ class Appium extends Webdriver {
 
     config.baseUrl = config.url || config.baseUrl;
     if (config.desiredCapabilities && Object.keys(config.desiredCapabilities).length) {
-      config.capabilities = config.desiredCapabilities;
+      config.capabilities = this.appiumV2 === true ? this._convertAppiumV2Caps(config.desiredCapabilities) : config.desiredCapabilities;
+    }
+
+    if (this.appiumV2) {
+      config.capabilities[`${vendorPrefix.appium}:deviceName`] = config[`${vendorPrefix.appium}:device`] || config.capabilities[`${vendorPrefix.appium}:deviceName`];
+      config.capabilities[`${vendorPrefix.appium}:browserName`] = config[`${vendorPrefix.appium}:browser`] || config.capabilities[`${vendorPrefix.appium}:browserName`];
+      config.capabilities[`${vendorPrefix.appium}:app`] = config[`${vendorPrefix.appium}:app`] || config.capabilities[`${vendorPrefix.appium}:app`];
+      config.capabilities[`${vendorPrefix.appium}:tunnelIdentifier`] = config[`${vendorPrefix.appium}:tunnelIdentifier`] || config.capabilities[`${vendorPrefix.appium}:tunnelIdentifier`]; // Adding the code to connect to sauce labs via sauce tunnel
+    } else {
+      config.capabilities.deviceName = config.device || config.capabilities.deviceName;
+      config.capabilities.browserName = config.browser || config.capabilities.browserName;
+      config.capabilities.app = config.app || config.capabilities.app;
+      config.capabilities.tunnelIdentifier = config.tunnelIdentifier || config.capabilities.tunnelIdentifier; // Adding the code to connect to sauce labs via sauce tunnel
     }
 
-    config.capabilities.deviceName = config.device || config.capabilities.deviceName;
-    config.capabilities.browserName = config.browser || config.capabilities.browserName;
-    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.waitForTimeoutInSeconds = config.waitForTimeout / 1000; // convert to seconds
 
     // [CodeceptJS compatible] transform host to hostname
@@ -203,6 +261,10 @@ class Appium extends Webdriver {
     }
 
     this.platform = null;
+    if (config.capabilities[`${vendorPrefix.appium}:platformName`]) {
+      this.platform = config.capabilities[`${vendorPrefix.appium}:platformName`].toLowerCase();
+    }
+
     if (config.capabilities.platformName) {
       this.platform = config.capabilities.platformName.toLowerCase();
     }
@@ -210,6 +272,22 @@ class Appium extends Webdriver {
     return config;
   }
 
+  _convertAppiumV2Caps(capabilities) {
+    const _convertedCaps = {};
+    for (const [key, value] of Object.entries(capabilities)) {
+      if (!key.startsWith(vendorPrefix.appium)) {
+        if (key !== 'platformName' && key !== 'bstack:options') {
+          _convertedCaps[`${vendorPrefix.appium}:${key}`] = value;
+        } else {
+          _convertedCaps[`${key}`] = value;
+        }
+      } else {
+        _convertedCaps[`${key}`] = value;
+      }
+    }
+    return _convertedCaps;
+  }
+
   static _config() {
     return [{
       name: 'app',
@@ -229,6 +307,11 @@ class Appium extends Webdriver {
   }
 
   async _startBrowser() {
+    if (this.appiumV2 === true) {
+      this.options.capabilities = this._convertAppiumV2Caps(this.options.capabilities);
+      this.options.desiredCapabilities = this._convertAppiumV2Caps(this.options.desiredCapabilities);
+    }
+
     try {
       if (this.options.multiremote) {
         this.browser = await webdriverio.multiremote(this.options.multiremote);
@@ -285,7 +368,7 @@ class Appium extends Webdriver {
       if (context.web) return this.switchToWeb(context.web);
       if (context.webview) return this.switchToWeb(context.webview);
     }
-    return this._switchToContext(context);
+    return this.switchToContext(context);
   }
 
   _withinEnd() {
@@ -340,8 +423,8 @@ class Appium extends Webdriver {
   async runOnIOS(caps, fn) {
     if (this.platform !== 'ios') return;
     recorder.session.start('iOS-only actions');
-    this._runWithCaps(caps, fn);
-    recorder.add('restore from iOS session', () => recorder.session.restore());
+    await this._runWithCaps(caps, fn);
+    await recorder.add('restore from iOS session', () => recorder.session.restore());
     return recorder.promise();
   }
 
@@ -382,8 +465,8 @@ class Appium extends Webdriver {
   async runOnAndroid(caps, fn) {
     if (this.platform !== 'android') return;
     recorder.session.start('Android-only actions');
-    this._runWithCaps(caps, fn);
-    recorder.add('restore from Android session', () => recorder.session.restore());
+    await this._runWithCaps(caps, fn);
+    await recorder.add('restore from Android session', () => recorder.session.restore());
     return recorder.promise();
   }
 
@@ -445,6 +528,7 @@ class Appium extends Webdriver {
    */
   async checkIfAppIsInstalled(bundleId) {
     onlyForApps.call(this, supportedPlatform.android);
+
     return this.browser.isAppInstalled(bundleId);
   }
 
@@ -481,7 +565,7 @@ class Appium extends Webdriver {
   async seeAppIsNotInstalled(bundleId) {
     onlyForApps.call(this, supportedPlatform.android);
     const res = await this.browser.isAppInstalled(bundleId);
-    return truth(`app ${bundleId}`, 'to be installed').negate(res);
+    return truth(`app ${bundleId}`, 'not to be installed').negate(res);
   }
 
   /**
@@ -750,7 +834,7 @@ class Appium extends Webdriver {
    *
    * @param {*} context the context to switch to
    */
-  async _switchToContext(context) {
+  async switchToContext(context) {
     return this.browser.switchContext(context);
   }
 
@@ -774,11 +858,11 @@ class Appium extends Webdriver {
     this.isWeb = true;
     this.defaultContext = 'body';
 
-    if (context) return this._switchToContext(context);
+    if (context) return this.switchToContext(context);
     const contexts = await this.grabAllContexts();
     this.debugSection('Contexts', contexts.toString());
     for (const idx in contexts) {
-      if (contexts[idx].match(/^WEBVIEW/)) return this._switchToContext(contexts[idx]);
+      if (contexts[idx].match(/^WEBVIEW/)) return this.switchToContext(contexts[idx]);
     }
 
     throw new Error('No WEBVIEW could be guessed, please specify one in params');
@@ -801,8 +885,8 @@ class Appium extends Webdriver {
     this.isWeb = false;
     this.defaultContext = '//*';
 
-    if (context) return this._switchToContext(context);
-    return this._switchToContext('NATIVE_APP');
+    if (context) return this.switchToContext(context);
+    return this.switchToContext('NATIVE_APP');
   }
 
   /**
@@ -837,11 +921,12 @@ class Appium extends Webdriver {
    * I.setNetworkConnection(4) // airplane mode off, wifi off, data on
    * I.setNetworkConnection(6) // airplane mode off, wifi on, data on
    * ```
-   * See corresponding [webdriverio reference](http://webdriver.io/api/mobile/setNetworkConnection.html).
-   *
-   * @return {Promise<{}>}
+   * See corresponding [webdriverio reference](https://webdriver.io/docs/api/chromium/#setnetworkconnection).
    *
    * Appium: support only Android
+   *
+   * @param {number} value The network connection mode bitmask
+   * @return {Promise<number>}
    */
   async setNetworkConnection(value) {
     onlyForApps.call(this, supportedPlatform.android);
@@ -1339,10 +1424,10 @@ class Appium extends Webdriver {
    *
    * @return {Promise<void>}
    *
-   * Appium: support only iOS
+   * Appium: support both Android and iOS
    */
   async closeApp() {
-    onlyForApps.call(this, 'iOS');
+    onlyForApps.call(this);
     return this.browser.closeApp();
   }
 
@@ -1395,8 +1480,9 @@ class Appium extends Webdriver {
    *
    */
   async dontSeeInField(field, value) {
-    if (this.isWeb) return super.dontSeeInField(field, value);
-    return super.dontSeeInField(parseLocator.call(this, field), value);
+    const _value = (typeof value === 'boolean') ? value : value.toString();
+    if (this.isWeb) return super.dontSeeInField(field, _value);
+    return super.dontSeeInField(parseLocator.call(this, field), _value);
   }
 
   /**
@@ -1527,8 +1613,9 @@ class Appium extends Webdriver {
    *
    */
   async seeInField(field, value) {
-    if (this.isWeb) return super.seeInField(field, value);
-    return super.seeInField(parseLocator.call(this, field), value);
+    const _value = (typeof value === 'boolean') ? value : value.toString();
+    if (this.isWeb) return super.seeInField(field, _value);
+    return super.seeInField(parseLocator.call(this, field), _value);
   }
 
   /**