Detox/docs/APIRef.DeviceObjectAPI.md

id, title

id	title
APIRef.DeviceObjectAPI	The `device` Object

device is globally available in every test file, it enables control over the current attached device (currently only simulators are supported).

Methods

• device.launchApp()
• device.relaunchApp() Deprecated
• device.terminateApp()
• device.sendToHome()
• device.reloadReactNative()
• device.installApp()
• device.uninstallApp()
• device.openURL(url)
• device.sendUserNotification(params)
• device.sendUserActivity(params)
• device.setOrientation(orientation)
• device.setLocation(lat, lon)
• device.setURLBlacklist([urls])
• device.enableSynchronization()
• device.disableSynchronization()
• device.resetContentAndSettings()
• device.getPlatform()
• device.pressBack() Android Only
• device.shake() iOS Only

device.launchApp(params)

Launch the app defined in the current configuration.

Options:

1. Restart the app

Terminate the app and launch it again. If set to false, the simulator will try to bring app from background, if the app isn't running, it will launch a new instance. default is false

await device.launchApp({newInstance: true});

2. Set runtime permissions

Grant or deny runtime permissions for your application.

await device.launchApp({permissions: {calendar: 'YES'}});

Detox uses AppleSimUtils on iOS to support this functionality. Read about the different types of permissions and how to set them in AppleSimUtils' Readme. Check out Detox's own test suite

3. Launch from URL

Mock opening the app from URL to test your app's deep link handling mechanism.

await device.launchApp({url: url});

Mock opening from a URL when app is not running

await device.launchApp({url: url, newInstance: true});

This will launch a new instance of the app and handle the deep link.

Mock opening from a URL when app is in background

await device.launchApp({url: url, newInstance: false});

This will launch the app from background and handle the deep link.

Read more in Mocking Open From URL section.

4. Launch with user notifications

await device.launchApp({userNotification: notification});

Mock receiving a notifications when app is not running

await device.launchApp({userNotification: notification, newInstance: true});

This will launch a new instance of the app and handle the notification.

Mock receiving a notifications when app is in background

await device.launchApp({userNotification: notification, newInstance: false});

This will launch the app from background and handle the notification.

Read more in Mocking User Notifications section.

5. Launch with user activity

await device.launchApp({userActivity: activity});

Mock receiving an activity when app is not running

await device.launchApp({userActivity: activity, newInstance: true});

This will launch a new instance of the app and handle the activity.

Mock receiving an activity when app is in background

await device.launchApp({userActivity: activity, newInstance: false});

This will launch the app from background and handle the activity.

Read more in Mocking User Activity section.

6. Launch into a fresh installation

A flag that enables relaunching into a fresh installation of the app (it will uninstall and install the binary again), default is false.

await device.launchApp({delete: true});

7. Additional launch arguments

Detox can start the app with additional launch arguments

await device.launchApp({launchArgs: {arg1: 1, arg2: "2"}});

The added launchArgs will be passed through the launch command to the device and be accessible via [[NSProcessInfo processInfo] arguments]

8. Disable touch indicators (iOS only)

Disable touch indicators on iOS.

await device.launchApp({disableTouchIndicators: true});

9. Launch with a specific language (iOS only)

Launch the app with a specific system language

Information about accepted values can be found here.

await device.launchApp({
  languageAndLocale: {
    language: "es-MX",
    locale: "es-MX"
  }
});

With this API, you can run sets of e2e tests per language. For example:

['es-MX', 'fr-FR', 'pt-BR'].forEach(locale => {
  describe(`Test suite in ${locale}`, () => {

    beforeAll(async () => {
      await device.launchApp({
        newInstance: true,
        languageAndLocale: {
          language: locale,
          locale
        }
      });
    });


    it('Test A', () => {
      
    })

    it('Test B', () => {
      
    })

  });
});

10. Initialize the URL blacklist at device launch

Launch the app with an URL blacklist to disable network synchronization on certain endpoints. Useful if the app makes frequent network calls to blacklisted endpoints upon startup.

await device.launchApp({
  newInstance: true,
  launchArgs: { detoxURLBlacklistRegex: ' \\("http://192.168.1.253:19001/onchange","https://e.crashlytics.com/spi/v2/events"\\)' },
}); 

device.relaunchApp(params)

Deprecated Use device.launchApp(params) instead. This method is now calling launchApp({newInstance: true}) for backwards compatibility, it will be removed in Detox 6.X.X.
Kill and relaunch the app defined in the current configuration.

device.terminateApp()

By default, terminateApp() with no params will terminate the app file defined in the current configuration.

To terminate another app, specify its bundle id

await device.terminateApp('other.bundle.id');

device.sendToHome()

Send application to background by bringing com.apple.springboard to the foreground.
Combining sendToHome() with launchApp({newInstance: false}) will simulate app coming back from background.
Check out Detox's own test suite

await device.sendToHome();
await device.launchApp({newInstance: false});
// app returned from background, do stuff

Check out Detox's own test suite

device.reloadReactNative()

If this is a React Native app, reload the React Native JS bundle. This action is much faster than device.launchApp(), and can be used if you just need to reset your React Native logic.

Note: This functionality does not work without faults. Under certain conditions, the system may not behave as expected and/or even crash. In these cases, use device.launchApp() to launch the app cleanly instead of only reloading the JS bundle.

device.installApp()

By default, installApp() with no params will install the app file defined in the current configuration.

To install another app, specify its path

await device.installApp('path/to/other/app');

device.uninstallApp()

By default, uninstallApp() with no params will uninstall the app defined in the current configuration.

To uninstall another app, specify its bundle id

await device.installApp('other.bundle.id');

device.openURL({url, sourceApp[optional]})

Mock opening the app from URL. sourceApp is an optional parameter to specify source application bundle id.
Read more in Mocking Open From URL section.
Check out Detox's own test suite

device.sendUserNotification(params)

Mock handling of received user notification when app is in foreground.
Read more in Mocking User Notifications section.
Check out Detox's own test suite

device.sendUserActivity(params)

Mock handling of received user activity when app is in foreground.
Read more in Mocking User Activity section.
Check out Detox's own test suite

device.setOrientation(orientation)

Takes "portrait" or "landscape" and rotates the device to the given orientation. Currently only available in the iOS Simulator.
Check out Detox's own test suite

device.setLocation(lat, lon)

Note: setLocation is dependent on fbsimctl. if fbsimctl is not installed, the command will fail, asking for it to be installed. Sets the simulator location to the given latitude and longitude.

await device.setLocation(32.0853, 34.7818);

device.setURLBlacklist([urls])

Disable EarlGrey's network synchronization mechanism on preferred endpoints. Useful if you want to on skip over synchronizing on certain URLs. To disable endpoints at initialization, pass in the blacklist at device launch.

await device.setURLBlacklist(['.*127.0.0.1.*']);

await device.setURLBlacklist(['.*my.ignored.endpoint.*']);

device.enableSynchronization()

Enable EarlGrey's synchronization mechanism (enabled by default). This is being reset on every new instance of the app.

await device.enableSynchronization();

device.disableSynchronization()

Disable EarlGrey's synchronization mechanism (enabled by default) This is being reset on every new instance of the app.

await device.disableSynchronization();

device.resetContentAndSettings()

Resets the Simulator to clean state (like the Simulator > Reset Content and Settings... menu item), especially removing previously set permissions.

await device.resetContentAndSettings();

device.getPlatform()

Returns the current device, ios or android.

if (device.getPlatform() === 'ios') {
  await expect(loopSwitch).toHaveValue('1');
}

device.pressBack() Android Only

Simulate press back button.

await device.pressBack();

device.shake() iOS Only

Simulate shake