chore: Deprecate calendarAccessAuthorized capability (#1465)

README.md

@@ -142,6 +142,7 @@ Capability | Description
 `browserName` | The name of the browser to run the test on. If this capability is provided then the driver will try to start the test in Web context mode (Native mode is applied by default). Read [Automating hybrid apps](https://appium.io/docs/en/writing-running-appium/web/hybrid/) for more details. Usually equals to `safari`.
 `appium:includeDeviceCapsToSessionInfo` | Whether to include screen information as the result of [Get Session Capabilities](http://appium.io/docs/en/commands/session/get/). It includes `pixelRatio`, `statBarHeight` and `viewportRect`, but it causes an extra API call to WDA which may increase the response time like [this issue](https://github.com/appium/appium/issues/15101). Defaults to `true`.
 `appium:resetLocationService` | Whether reset the location service in the session deletion on real device. Defaults to `false`.
+|`appium:customSSLCert`| Adds a root SSL certificate to IOS Simulators and real devices. Real devices only work if [py-ios-device](https://github.com/YueChen-C/py-ios-device) tool is available on the server machine. The certificate content must be provided in [PEM](https://knowledge.digicert.com/quovadis/ssl-certificates/ssl-general-topics/what-is-pem-format.html) format | e.g. ```-----BEGIN CERTIFICATE-----MIIFWjCCBEKg...-----END CERTIFICATE-----```|
 
 ### App
 
@@ -206,12 +207,11 @@ If a test is executed on a Simulator then UI locale is changed as well. You can
 
 |Capability|Description|Values|
 |----------|-----------|------|
-|`appium:orientation`|Start a test in a certain orientation|`LANDSCAPE` or `PORTRAIT`|
+|`appium:orientation`|Start a test session in a certain orientation. Note, that Simulator may ignore this capability if the simulated device itself does not support orientation change in its current state. For example, iPhones only allow orientation change to landscape if an app that declares landscape support in its manifest is running. Thus changing the orientation from portrait to something else being on home screen won't have any effect.|`LANDSCAPE` or `PORTRAIT`|
 |`appium:scaleFactor`|Simulator scale factor. This is useful to have if the default resolution of simulated device is greater than the actual display resolution. So you can scale the simulator to see the whole device screen without scrolling.|Acceptable values for simulators running Xcode SDK 8 and older are: `'1.0', '0.75', '0.5', '0.33' and '0.25'`, where '1.0' means 100% scale. For simulators running Xcode SDK 9 and above the value could be any valid positive float number. The capability must be of a string type.|
-|`appium:connectHardwareKeyboard`|Set this option to `true` in order to enable hardware keyboard in Simulator. The preference works only when Appium launches a simulator instance with this value. It is set to `false` by default, because this helps to workaround some XCTest bugs. `connectHardwareKeyboard: true` makes `forceSimulatorSoftwareKeyboardPresence: false` if no explicit value is set for `forceSimulatorSoftwareKeyboardPresence` capability since Appium 1.22.0. |`true` or `false`|
-|`appium:forceSimulatorSoftwareKeyboardPresence`|Set this option to `true` in order to turn software keyboard on and turn hardware keyboard off in Simulator since Appium 1.22.0. This option helps to avoid `Keyboard is not present` error. It is set to `true` by default. Appium respects preset simulator software/hardware keyboard preference when this value is `false`, so `connectHardwareKeyboard: false` and `forceSimulatorSoftwareKeyboardPresence: false` means for Appium to keep the current Simulator keyboard preferences. This option has priority over `connectHardwareKeyboard`. |`true` or `false`|
-|`appium:calendarAccessAuthorized`|Set this to `true` if you want to enable calendar access on IOS Simulator with given bundleId. Set to `false`, if you want to disable calendar access on IOS Simulator with given bundleId. If not set, the calendar authorization status will not be set.|e.g., `true`|
-|`appium:calendarFormat`|Calendar format to set for the iOS Simulator|e.g. `gregorian`|
+|`appium:connectHardwareKeyboard`|Set this option to `true` in order to enable hardware keyboard in Simulator. The preference works only when XCUITest driver launches a simulator instance with this value. It is set to `false` by default, because this helps to workaround some XCTest bugs. `connectHardwareKeyboard: true` makes `forceSimulatorSoftwareKeyboardPresence: false` if no explicit value is set for `forceSimulatorSoftwareKeyboardPresence` capability since Appium 1.22.0. |`true` or `false`|
+|`appium:forceSimulatorSoftwareKeyboardPresence`|Set this option to `true` in order to turn software keyboard on and turn hardware keyboard off in Simulator since Appium 1.22.0. This option helps to avoid `Keyboard is not present` error. It is set to `true` by default. XCUITest driver respects preset simulator software/hardware keyboard preference when this value is `false`, so `connectHardwareKeyboard: false` and `forceSimulatorSoftwareKeyboardPresence: false` means for XCUITest driver to keep the current Simulator keyboard preferences. This option has priority over `connectHardwareKeyboard`. |`true` or `false`|
+| **Deprecated** `appium:calendarAccessAuthorized`|This capability is obsolete. Please use `appium:permissions` one instead with the `calendar` key.|`true` or `false`|
 |`appium:isHeadless`|Set this capability to `true` if automated tests are running on Simulator and the device display is not needed to be visible. This only has an effect since Xcode9 and only for simulators. All running instances of Simulator UI are going to be automatically terminated if headless test is started. `false` is the default value.|e.g., `true`|
 |`appium:simulatorWindowCenter`|Allows to explicitly set the coordinates of Simulator window center for Xcode9+ SDK. This capability only has an effect if Simulator window has not been opened yet for the current session before it started.|e.g. `{-100.0,100.0}` or `{500,500}`, spaces are not allowed|
 |`appium:simulatorStartupTimeout`|Allows to change the default timeout for Simulator startup. By default this value is set to 120000ms (2 minutes), although the startup could take longer on a weak hardware or if other concurrent processes use much system resources during the boot up procedure.|e.g. `300000`|
@@ -226,9 +226,8 @@ If a test is executed on a Simulator then UI locale is changed as well. You can
 |`appium:iosSimulatorLogsPredicate`|Set the `--predicate` flag in the ios simulator logs|e.g.: `'process != "locationd" AND process != "DTServiceHub"' AND process != "mobileassetd"`|
 |`appium:simulatorPasteboardAutomaticSync`| Handle the `-PasteboardAutomaticSync` flag when simulator process launches. It could improve launching simulator performance not to sync pasteboard with the system when this value is `off`. `on` forces the flag enabled. `system` does not provide the flag to the launching command. `on`, `off`, or `system` is available. They are case insensitive. Defaults to `off` | e.g. `system` |
 |`appium:simulatorDevicesSetPath`| This capability allows to set an alternative path to the simulator devices set in case you have multiple sets deployed on your local system. Such feature could be useful if you, for example, would like to save disk space on the main system volume. | e.g. `/MyVolume/Devices` |
-|`appium:customSSLCert`| Adds a root SSL certificate to IOS Simulators and real devices. Real devices only work if [py-ios-device](https://github.com/YueChen-C/py-ios-device) tool is available on the server machine. The certificate content must be provided in [PEM](https://knowledge.digicert.com/quovadis/ssl-certificates/ssl-general-topics/what-is-pem-format.html) format | e.g. ```-----BEGIN CERTIFICATE-----MIIFWjCCBEKg...-----END CERTIFICATE-----```|
 |`appium:webkitResponseTimeout`| (Real device only) Set the time, in ms, to wait for a response from WebKit in a Safari session. Defaults to `5000` | e.g., `10000`|
-|`appium:safariGlobalPreferences`| (Simulator only) Allows changing of Mobile Safari's preferences at the session startup. Check the documentation on arguments of [mobile: updateSafariPreferences](#mobile-updatesafaripreferences) extension to get more details on the value type requirements. | { ShowTabBar: 0, WarnAboutFraudulentWebsites: 0 } |
+|`appium:safariGlobalPreferences`| Allows changing of Mobile Safari's preferences at the session startup. Check the documentation on arguments of [mobile: updateSafariPreferences](#mobile-updatesafaripreferences) extension to get more details on the value type requirements. | { ShowTabBar: 0, WarnAboutFraudulentWebsites: 0 } |
 
 ### Web Context
 

lib/driver.js

@@ -441,13 +441,24 @@ class XCUITestDriver extends BaseDriver {
         this.log.debug('Localization preferences have been updated');
       }
 
+      if (_.isBoolean(this.opts.reduceMotion)) {
+        this.log.info(`Setting reduceMotion to ${this.opts.reduceMotion}`);
+        await this.opts.device.setReduceMotion(this.opts.reduceMotion);
+      }
+
+      if (_.isBoolean(this.opts.reduceTransparency)) {
+        this.log.info(`Setting reduceTransparency to ${this.opts.reduceTransparency}`);
+        await this.opts.device.setReduceTransparency(this.opts.reduceTransparency);
+      }
+
       if (this.opts.launchWithIDB) {
         try {
           const idb = new IDB({udid});
           await idb.connect();
           this.opts.device.idb = idb;
         } catch (e) {
-          this.log.info(`idb will not be used for Simulator interaction. Original error: ${e.message}`);
+          this.log.debug(e.stack);
+          this.log.warn(`idb will not be used for Simulator interaction. Original error: ${e.message}`);
         }
       }
 
@@ -467,43 +478,30 @@ class XCUITestDriver extends BaseDriver {
     }
 
     // if we only have bundle identifier and no app, fail if it is not already installed
-    if (!this.opts.app && this.opts.bundleId && !this.isSafari()) {
-      if (!await this.opts.device.isAppInstalled(this.opts.bundleId)) {
-        this.log.errorAndThrow(`App with bundle identifier '${this.opts.bundleId}' unknown`);
-      }
+    if (!this.opts.app && this.opts.bundleId && !this.isSafari()
+        && !await this.opts.device.isAppInstalled(this.opts.bundleId)) {
+      this.log.errorAndThrow(`App with bundle identifier '${this.opts.bundleId}' unknown`);
     }
 
-    if (this.opts.permissions) {
-      if (this.isSimulator()) {
+    if (this.isSimulator()) {
+      if (this.opts.permissions) {
         this.log.debug('Setting the requested permissions before WDA is started');
         for (const [bundleId, permissionsMapping] of _.toPairs(JSON.parse(this.opts.permissions))) {
           await this.opts.device.setPermissions(bundleId, permissionsMapping);
         }
-      } else {
-        this.log.warn('Setting permissions is only supported on Simulator. ' +
-          'The "permissions" capability will be ignored.');
       }
-    }
 
-    if (this.isSimulator()) {
-      if (this.opts.calendarAccessAuthorized) {
-        await this.opts.device.enableCalendarAccess(this.opts.bundleId);
-      } else if (this.opts.calendarAccessAuthorized === false) {
-        await this.opts.device.disableCalendarAccess(this.opts.bundleId);
+      // TODO: Deprecate and remove this block together with calendarAccessAuthorized capability
+      if (_.isBoolean(this.opts.calendarAccessAuthorized)) {
+        this.log.warn(`The 'calendarAccessAuthorized' capability is deprecated and will be removed soon. ` +
+          `Consider using 'permissions' one instead with 'calendar' key`);
+        const methodName = `${this.opts.calendarAccessAuthorized ? 'enable' : 'disable' }CalendarAccess`;
+        await this.opts.device[methodName](this.opts.bundleId);
       }
     }
 
     await this.startWda(this.opts.sessionId, realDevice);
 
-    if (_.isBoolean(this.opts.reduceMotion)) {
-      await this.setReduceMotion(this.opts.reduceMotion);
-    }
-
-    if (_.isBoolean(this.opts.reduceTransparency) && this.isSimulator()) {
-      this.log.info(`Setting reduceTransparency to ${this.opts.reduceTransparency}`);
-      await this.opts.device.setReduceTransparency(this.opts.reduceTransparency);
-    }
-
     if (this.opts.orientation) {
       await this.setInitialOrientation(this.opts.orientation);
       this.logEvent('orientationSet');
@@ -1325,20 +1323,6 @@ class XCUITestDriver extends BaseDriver {
     }
   }
 
-  /**
-   * Set reduceMotion as 'isEnabled' only when the capabilities has 'reduceMotion'
-   * The call is ignored for real devices.
-   * @param {?boolean} isEnabled Wether enable reduceMotion
-   */
-  async setReduceMotion (isEnabled) {
-    if (this.isRealDevice() || !_.isBoolean(isEnabled)) {
-      return;
-    }
-
-    this.log.info(`Setting reduceMotion to ${isEnabled}`);
-    await this.updateSettings({reduceMotion: isEnabled});
-  }
-
   async setInitialOrientation (orientation) {
     const dstOrientation = _.toUpper(orientation);
     if (!SUPPORTED_ORIENATIONS.includes(dstOrientation)) {

lib/simulator-management.js

@@ -279,22 +279,22 @@ async function setLocalizationPrefs (sim, opts = {}) {
     locale,
     calendarFormat,
   } = opts;
-  const i10nConfig = {};
+  const l10nConfig = {};
   if (language) {
-    i10nConfig.language = {name: language};
+    l10nConfig.language = {name: language};
   }
   if (locale) {
-    i10nConfig.locale = {name: locale};
+    l10nConfig.locale = {name: locale};
     if (calendarFormat) {
-      i10nConfig.locale.calendar = calendarFormat;
+      l10nConfig.locale.calendar = calendarFormat;
     }
   }
-  if (_.isEmpty(i10nConfig)) {
+  if (_.isEmpty(l10nConfig)) {
     return false;
   }
 
-  log.debug(`About to update internationalization preferences: ${JSON.stringify(i10nConfig)}`);
-  await sim.configureLocalization(i10nConfig);
+  log.debug(`About to update localization preferences: ${JSON.stringify(l10nConfig)}`);
+  await sim.configureLocalization(l10nConfig);
   return true;
 }
 

test/unit/driver-specs.js

@@ -121,7 +121,6 @@ describe('driver commands', function () {
       sandbox.stub(driver, 'startSim').callsFake(_.noop);
       sandbox.stub(driver, 'startWdaSession').callsFake(_.noop);
       sandbox.stub(driver, 'startWda').callsFake(_.noop);
-      sandbox.stub(driver, 'setReduceMotion').callsFake(_.noop);
       sandbox.stub(driver, 'installAUT').callsFake(_.noop);
       sandbox.stub(driver, 'connectToRemoteDebugger').callsFake(_.noop);
       sandbox.stub(xcode, 'getMaxIOSSDK').callsFake(async () => '10.0'); // eslint-disable-line require-await