feat(config): default app permissions (iOS)

Author: noomorph

detox/index.d.ts

@@ -184,6 +184,7 @@ declare global {
             bundleId?: string;
             build?: string;
             launchArgs?: Record<string, any>;
+            permissions?: DevicePermissions;
         }
 
         interface DetoxAndroidAppConfig {
@@ -201,6 +202,7 @@ declare global {
             build?: string;
             testBinaryPath?: string;
             launchArgs?: Record<string, any>;
+            permissions?: DevicePermissions;
         }
 
         type DetoxBuiltInDeviceConfig =

detox/src/configuration/composeAppsConfig.js

@@ -68,6 +68,7 @@ function composeAppsConfigFromPlain(opts) {
         bundleId: localConfig.bundleId,
         build: localConfig.build,
         launchArgs: localConfig.launchArgs,
+        permissions: localConfig.permissions,
       };
       break;
     default:

detox/src/configuration/composeAppsConfig.test.js

@@ -56,6 +56,9 @@ describe('composeAppsConfig', () => {
         binaryPath: 'path/to/app',
         bundleId: 'com.example.app',
         build: 'echo OK',
+        permissions: {
+          calendar: 'YES',
+        },
         launchArgs: {
           hello: 'world',
         }
@@ -65,6 +68,18 @@ describe('composeAppsConfig', () => {
     it.each([
       ['ios.none', 'ios.app'],
       ['ios.simulator', 'ios.app'],
+    ])('should infer type and app properties for %j', (deviceType, appType) => {
+      deviceConfig.type = deviceType;
+      expect(compose()).toEqual({
+        default: {
+          ...localConfig,
+          type: appType,
+          device: undefined,
+        },
+      });
+    });
+
+    it.each([
       ['android.attached', 'android.apk'],
       ['android.emulator', 'android.apk'],
       ['android.genycloud', 'android.apk'],
@@ -75,6 +90,7 @@ describe('composeAppsConfig', () => {
           ...localConfig,
           type: appType,
           device: undefined,
+          permissions: undefined,
         },
       });
     });

detox/src/devices/runtime/RuntimeDevice.js

@@ -1,3 +1,5 @@
+const _ = require('lodash');
+
 const DetoxRuntimeError = require('../../errors/DetoxRuntimeError');
 const debug = require('../../utils/debug'); // debug utils, leave here even if unused
 const { traceCall } = require('../../utils/trace');
@@ -56,6 +58,7 @@ class RuntimeDevice {
     this._emitter = eventEmitter;
     this._errorComposer = runtimeErrorComposer;
 
+    /** @type {Detox.DetoxAppConfig | null} */
     this._currentApp = null;
     this._currentAppLaunchArgs = new LaunchArgsEditor();
     this._processes = {};
@@ -189,9 +192,13 @@ class RuntimeDevice {
   }
 
   async installApp(binaryPath, testBinaryPath) {
-    await traceCall('appInstall', () => {
+    await traceCall('appInstall', async () => {
+      /** @type {*} */
       const currentApp = binaryPath ? { binaryPath, testBinaryPath } : this._getCurrentApp();
-      return this.deviceDriver.installApp(currentApp.binaryPath, currentApp.testBinaryPath);
+      await this.deviceDriver.installApp(currentApp.binaryPath, currentApp.testBinaryPath);
+      if (!_.isEmpty(currentApp.permissions)) {
+        await this.deviceDriver.setPermissions(currentApp.bundleId, currentApp.permissions);
+      }
     });
   }
 

detox/src/devices/runtime/RuntimeDevice.test.js

@@ -687,9 +687,35 @@ describe('Device', () => {
       expect(driverMock.driver.installApp).toHaveBeenCalledWith('newAppPath', device._deviceConfig.testBinaryPath);
     });
 
+    it(`with a custom app permissions should setPermissions after installing`, async () => {
+      const device = await aValidDevice({
+        appsConfig: {
+          default: {
+            permissions: {
+              calendar: 'NO',
+              camera: 'YES',
+            },
+          },
+        },
+      });
+
+      driverMock.driver.setPermissions.mockRejectedValue(new Error('Should be called last!'));
+      driverMock.driver.installApp.mockImplementation(() => {
+        driverMock.driver.setPermissions.mockReset();
+      });
+
+      await device.installApp();
+      expect(driverMock.driver.setPermissions).toHaveBeenCalledWith('test.bundle', {
+        calendar: 'NO',
+        camera: 'YES',
+      });
+    });
+
     it(`with no args should use the default path given in configuration`, async () => {
       const device = await aValidDevice();
       await device.installApp();
+
+      expect(driverMock.driver.setPermissions).not.toHaveBeenCalled();
       expect(driverMock.driver.installApp).toHaveBeenCalledWith(device._currentApp.binaryPath, device._currentApp.testBinaryPath);
     });
   });

detox/test/e2e/detox.config.js

@@ -16,6 +16,13 @@ const launchArgs = {
   micro: 'soft',
 };
 
+const defaultPermissions = {
+  calendar: 'YES',
+  notifications: 'YES',
+  camera: 'YES',
+  photos: 'YES',
+};
+
 /** @type {Detox.DetoxConfig} */
 const config = {
   testRunner: 'nyc jest',
@@ -57,13 +64,15 @@ const config = {
       binaryPath: 'ios/build/Build/Products/Debug-iphonesimulator/example.app',
       build: 'set -o pipefail && xcodebuild -workspace ios/example.xcworkspace -UseNewBuildSystem=YES -scheme example_ci -configuration Debug -sdk iphonesimulator -derivedDataPath ios/build -quiet',
       bundleId: 'com.wix.detox-example',
+      permissions: defaultPermissions,
     },
 
     'ios.release': {
       type: 'ios.app',
       name: 'example',
       binaryPath: 'ios/build/Build/Products/Release-iphonesimulator/example.app',
       build: 'set -o pipefail && export CODE_SIGNING_REQUIRED=NO && export RCT_NO_LAUNCH_PACKAGER=true && xcodebuild -workspace ios/example.xcworkspace -UseNewBuildSystem=YES -scheme example_ci -configuration Release -sdk iphonesimulator -derivedDataPath ios/build -quiet',
+      permissions: defaultPermissions,
     },
 
     'android.debug': {

docs/APIRef.Configuration.md

@@ -202,7 +202,11 @@ The format of Detox config allows you to define inside it multiple app configs i
     "ios.debug": {
       "type": "ios.app",
       "binaryPath": "ios/build/Build/Products/Debug-iphonesimulator/example.app",
-      "build": "xcodebuild -project ios/example.xcodeproj -scheme example -configuration Debug -sdk iphonesimulator -derivedDataPath ios/build"
+      "build": "xcodebuild -project ios/example.xcodeproj -scheme example -configuration Debug -sdk iphonesimulator -derivedDataPath ios/build",
+      "permissions": {
+        /** @see {Detox.DevicePermissions} */
+        notifications: 'YES',
+      },
     },
     "android.release": {
       "type": "android.apk",
@@ -218,14 +222,15 @@ The format of Detox config allows you to define inside it multiple app configs i
 
 An app config can have the following params:
 
-| Configuration Params | Details                                                                                                                                                                                                             |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `type`               | Mandatory property to discern app types: `ios.app`, `android.apk`.                                                                                                                                                  |
-| `name`               | Use only when working with multiple apps within the same configuration. See an example below.                                                                                                                       |
-| `binaryPath`         | Relative path to the ipa/app/apk due to be tested (make sure you build the app in a project relative path)                                                                                                          |
-| `build`              | **\[optional]** Build command (normally an `xcodebuild` command you use to build your app), which can be called later using Detox CLI tool as a convenience.                                                        |
-| `testBinaryPath`     | (optional, Android only): relative path to the test app (apk)                                                                                                                                                       |
-| `launchArgs`         | **\[optional]** An object specifying arguments (key-values pairs) to pass through into the app, upon launching on the device. For more info, refer to the dedicated [launch-arguments guide](APIRef.LaunchArgs.md). |
+| Configuration Params | Details                                                                                                                                                                                                               |
+|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `type`               | Mandatory property to discern app types: `ios.app`, `android.apk`.                                                                                                                                                    |
+| `name`               | Use only when working with multiple apps within the same configuration. See an example below.                                                                                                                         |
+| `build`              | **\[optional]** Build command (normally an `xcodebuild` command you use to build your app), which can be called later using Detox CLI tool as a convenience.                                                          |
+| `binaryPath`         | Relative path to the ipa/app/apk due to be tested (make sure you build the app in a project relative path)                                                                                                            |
+| `testBinaryPath`     | **\[optional, Android only]**: relative path to the test app (apk)                                                                                                                                                    |
+| `launchArgs`         | **\[optional]** An object specifying arguments (key-values pairs) to pass through into the app, upon launching on the device. For more info, refer to the dedicated [launch-arguments guide](APIRef.LaunchArgs.md).   |
+| `permissions`        | **\[optional, iOS only]** An object specifying default [runtime permissions](APIRef.DeviceObjectAPI.md#permissions-ios-only) to give before launching the app.                                                        |
 
 To work with multiple apps within the same configuration you should be giving each app its name, e.g.:
 

docs/APIRef.DeviceObjectAPI.md

@@ -137,6 +137,8 @@ await device.launchApp({permissions: {calendar: 'YES'}});
 
 Detox uses [AppleSimUtils](https://github.com/wix/AppleSimulatorUtils) to implement this functionality for iOS simulators. Read about the different types of permissions and how to set them in AppleSimUtils' documentation and by checking out Detox’s [own test suite](https://github.com/wix/Detox/tree/a9a09246c05733f6b91cfcc0dba05a4714abca92/detox/test/e2e/13.permissions.test.js).
 
+As a reference, you can also use this [table of possible permissions](#permissions-ios-only).
+
 ##### 3. `url`—Launching with URL
 
 Launches the app with the specified URL to test your app’s deep link handling mechanism.
@@ -528,3 +530,32 @@ Exposes [`UiAutomator`’s `UiDevice` API](https://developer.android.com/referen
 **This is not a part of the official Detox API**, it may break and change whenever an update to `UiDevice` or `UiAutomator` Gradle dependencies (`androidx.test.uiautomator:uiautomator`) is introduced.
 
 [`UiDevice`’s autogenerated code](https://github.com/wix/Detox/tree/a9a09246c05733f6b91cfcc0dba05a4714abca92/detox/src/android/espressoapi/UIDevice.js)
+
+### Permissions (iOS only)
+
+When you are [configuring the apps](APIRef.Configuration.md#apps-configurations) list in your
+Detox config file or [launching the app](#2-permissionsset-runtime-permissions-ios-only),
+you can give certain permissions beforehand to it to avoid this inconvenient modal:
+
+![iOS permissions modal](img/ios-permissions.png)
+
+So, here is the exhaustive permissions list that Detox currently supports for iOS:
+
+| Permission    | Values                                                  |
+|---------------|---------------------------------------------------------|
+| calendar      | `'YES' | 'NO' | 'unset'`                      |
+| camera        | `'YES' | 'NO' | 'unset'`                      |
+| contacts      | `'YES' | 'NO' | 'unset'`                      |
+| faceid        | `'YES' | 'NO' | 'unset'`                      |
+| health        | `'YES' | 'NO' | 'unset'`                      |
+| homekit       | `'YES' | 'NO' | 'unset'`                      |
+| location      | `'always' | 'inuse' | 'never' | 'unset'` |
+| medialibrary  | `'YES' | 'NO' | 'unset'`                      |
+| microphone    | `'YES' | 'NO' | 'unset'`                      |
+| motion        | `'YES' | 'NO' | 'unset'`                      |
+| notification  | `'YES' | 'NO' | 'unset'`                      |
+| photos        | `'YES' | 'NO' | 'unset'`                      |
+| reminders     | `'YES' | 'NO' | 'unset'`                      |
+| siri          | `'YES' | 'NO' | 'unset'`                      |
+| speech        | `'YES' | 'NO' | 'unset'`                      |
+| userTracking  | `'YES' | 'NO' | 'unset'`                      |