device is globally available in every test file, it enables control over the current attached device (currently only simulators are supported).
Holds the environment-unique ID of the device - namely, the adb ID on Android (e.g. emulator-5554) and the Mac-global simulator UDID on iOS, as used by simctl (e.g. AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE).
The value will be undefined until the device is properly prepared (i.e. in detox.init()).
Holds a descriptive name of the device. Example: emulator-5554 (Pixel_API_26)
The value will be undefined until the device is properly prepared (i.e. in detox.init()).
Access the launch-arguments predefined by the user in preliminary, static scopes such as the Detox configuration file and command-line arguments. This access allows, through dedicated methods, for both value-querying and modification:
// Modify some of the predefined arguments:
device.appLaunchArgs.modify({
mockServerPort: 1234,
});
// Retrieve the arguments:
device.appLaunchArgs.get(); // ==> { mockServerPort: 1234 }
// Reset (i.e. remove all arguments):
device.appLaunchArgs.reset();This is the most flexible way of editing the launch arguments. Refer to the launch arguments guide for complete details.
device.selectApp(name)device.launchApp()device.terminateApp()device.sendToHome()device.reloadReactNative()device.installApp()device.uninstallApp()device.openURL(url)device.sendUserNotification(params)device.sendUserActivity(params)iOS Onlydevice.setOrientation(orientation)device.setLocation(lat, lon)iOS Onlydevice.enableSynchronization()device.disableSynchronization()device.setURLBlacklist([urls])device.resetContentAndSettings()iOS Onlydevice.getPlatform()device.takeScreenshot([name])device.shake()iOS Onlydevice.setBiometricEnrollment(bool)iOS Onlydevice.matchFace()iOS Onlydevice.unmatchFace()iOS Onlydevice.matchFinger()iOS Onlydevice.unmatchFinger()iOS Onlydevice.clearKeychain()iOS Onlydevice.setStatusBar()iOS Onlydevice.resetStatusBar()iOS Onlydevice.reverseTcpPort()Android Onlydevice.unreverseTcpPort()Android Onlydevice.pressBack()Android Onlydevice.getUIDevice()Android Only
Use only for advanced multi-app configs when you need to switch between your apps
within the same test scenario. Refer to the APIRef.Configuration.md
to discover how to define multiple apps with different names.
await device.selectApp('myAppName');As a side effect (due to the current architectural limitation) running device.selectApp terminates the previous
app that had been running before.
Launch the app defined in the current configuration.
params—object, containing one of more of the following keys and values:
Terminate the app and launch it again.
If set to false, the device will try to resume the app (e.g. bring from foreground to background). If the app isn't running, it will launch a new instance nonetheless. Default is false.
await device.launchApp({newInstance: true});Grants or denies runtime permissions to your application. This will cause the app to terminate before permissions are applied.
await device.launchApp({permissions: {calendar: 'YES'}});Detox uses AppleSimUtils 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.
Launches the app with the specified URL to test your app's deep link handling mechanism.
await device.launchApp({url});
await device.launchApp({url, newInstance: true}); // Launch a new instance of the app
await device.launchApp({url, newInstance: false}); // Reuse existing instanceRead more here. Go back to subsection 1 to read about the full effect of the newInstance argument.
Launches with the specified user notification.
await device.launchApp({userNotification});
await device.launchApp({userNotification, newInstance: true}); // Launch a new instance of the app
await device.launchApp({userNotification, newInstance: false}); // Reuse existing instanceRead more here. Go back to subsection 1 to read about the full effect of the newInstance argument.
Launches the app with the specified user activity.
await device.launchApp({userActivity: activity});
await device.launchApp({userActivity: activity, newInstance: true}); //Launch a new instance of the app
await device.launchApp({userActivity: activity, newInstance: false}); //Reuse existing instanceRead more in here. Go back to subsection 1 to read about the full effect of the newInstance argument.
Before launching the application, it is uninstalled and then reinstalled.
A flag that enables relaunching into a fresh installation of the app (it will uninstall and install the binary. Default is false.
await device.launchApp({delete: true});Launches the app on the device with on-site, user-specified launch arguments:
await device.launchApp({
launchArgs: {
arg1: 1,
arg2: "2",
}
});This is the most explicit and straightforward way of setting launch arguments. Refer to the launch arguments guide for a complete overview on app launch arguments.
Disables touch indicators on iOS. Default is false.
await device.launchApp({disableTouchIndicators: true});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. detoxEnableSynchronization—Initialize Detox with synchronization enabled or disabled at app launch
Launches the app with the synchronization mechanism enabled or disabled. Useful if the app cannot be synchronized during the launch process. Synchronization can later be enabled using device.enableSynchronization().
await device.launchApp({
newInstance: true,
launchArgs: { detoxEnableSynchronization: 0 }
}); Launches the app with a 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"\\)' },
}); Deprecated: Use device.launchApp(params) instead. The method calls launchApp({newInstance: true}) for backwards compatibility.
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');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 stuffCheck out Detox's own test suite
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.
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');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.uninstallApp('other.bundle.id');Mock opening the app from URL. sourceApp is an optional iOS-only parameter to specify source application bundle id.
Read more in Mocking Open with URL section. Check out Detox's own test suite
Mock handling of a user notification previously received in the system, while the app is already running.
Read more in Mocking User Notifications section. Check out Detox's own test suite
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
Takes "portrait" or "landscape" and rotates the device to the given orientation.
Note: Setting device orientation is only supported for iPhone devices, or for apps declared as requiring full screen on iPad. For all other cases, the current test will be failed.
Check out Detox's own test suite.
Note:
setLocationis dependent on fbsimctl which is now deprecated. Iffbsimctlis 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);Enable (restore) synchronization (idle/busy monitoring) with the app - namely, resume waiting for the app to go idle before moving forward in the test execution. Enabled by default. This gets reset on every new instance of the app.
await device.enableSynchronization();Temporarily disable synchronization (idle/busy monitoring) with the app - namely, stop waiting for the app to go idle before moving forward in the test execution (rather, resort to applying unrecommended sleep()'s in your test code...). This gets reset on every new instance of the app.
await device.disableSynchronization();Exclude syncrhonization with respect to network activity (i.e. don't wait for network to go idle before moving forward in the test execution) according to specific endpoints, denoted as URL reg-exp's. To disable endpoints at initialization, pass in the black-list as an app-launch argument named detoxURLBlacklistRegex (as explained here).
await device.setURLBlacklist(['.*127.0.0.1.*', '.*my.ignored.endpoint.*']);Resets the Simulator to clean state (like the Simulator > Reset Content and Settings... menu item), especially removing previously set permissions.
await device.resetContentAndSettings();Returns the current device, ios or android.
if (device.getPlatform() === 'ios') {
await expect(loopSwitch).toHaveValue('1');
}Takes a screenshot of the device. For full details on taking screenshots with Detox, refer to the screen-shots guide.
Simulate shake
Toggles device enrollment in biometric auth (TouchID or FaceID).
await device.setBiometricEnrollment(true);
// or
await device.setBiometricEnrollment(false);Simulates the success of a face match via FaceID
Simulates the failure of face match via FaceID
Simulates the success of a finger match via TouchID
Simulates the failure of a finger match via TouchID
Clears the device keychain
Override simulator's status bar. Available options:
{
time: "12:34"
// Set the date or time to a fixed value.
// If the string is a valid ISO date string it will also set the date on relevant devices.
dataNetwork: "wifi"
// If specified must be one of 'wifi', '3g', '4g', 'lte', 'lte-a', or 'lte+'.
wifiMode: "failed"
// If specified must be one of 'searching', 'failed', or 'active'.
wifiBars: "2"
// If specified must be 0-3.
cellularMode: "searching"
// If specified must be one of 'notSupported', 'searching', 'failed', or 'active'.
cellularBars: "3"
// If specified must be 0-4.
batteryState: "charging"
// If specified must be one of 'charging', 'charged', or 'discharging'.
batteryLevel: "50"
// If specified must be 0-100.
}
Resets any override in simulator's status bar.
Reverse a TCP port from the device (guest) back to the host-computer, as typically done with the adb reverse command. The end result would be that all network requests going from the device to the specified port will be forwarded to the computer.
Clear a reversed TCP-port (e.g. previously set using device.reverseTcpPort()).
Simulate press back button.
await device.pressBack();Exposes UiAutomator's UiDevice API. 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.