device is globally available in every test file, it enables control over the current attached device (currently only simulators are supported).
device.launchApp()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()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
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()).
Launch the app defined in the current configuration.
Options:
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});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
Mock opening the app from URL to test your app's deep link handling mechanism.
await device.launchApp({url: url});await device.launchApp({url: url, newInstance: true});This will launch a new instance of the app and handle the deep link.
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.
Currently only supported on iOS!
await device.launchApp({userNotification: notification});await device.launchApp({userNotification: notification, newInstance: true});This will launch a new instance of the app and handle the notification.
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.
Currently only supported on iOS!
await device.launchApp({userActivity: activity});await device.launchApp({userActivity: activity, newInstance: true});This will launch a new instance of the app and handle the activity.
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.
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});Detox can start the app with additional launch arguments
await device.launchApp({launchArgs: {arg1: 1, arg2: "2"}});- On iOS, the added
launchArgswill be passed through the launch command to the device and be accessible via[[NSProcessInfo processInfo] arguments] - On Android, the
launchArgswill be set as a bundle-extra into the activity's intent. It will therefore be accessible on the native side via the current activity as:currentActivity.getIntent().getBundleExtra("launchArgs").
Note that there are numerous ways to forward the arguments onto the javascript side of the app, but that is essentially out of Detox' scope. Nevertheless here are some references:
- Supported out of the box if you're using React Native Navigation.
- On Android, you can use
ReactNativeDelegate.getLaunchOptions(), as described here. - For iOS, you may find this this post on stack overflow useful.
Disable touch indicators on iOS.
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', () => {
})
});
});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"\\)' },
}); Deprecated Use device.launchApp(params) instead. This method is now calling launchApp({newInstance: true}) for backwards compatibility.
Kill and relaunch the app defined in the current configuration.
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 parameter to specify source application bundle id.
Read more in Mocking Open From URL section.
Check out Detox's own test suite
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
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.
Currently only available in the iOS Simulator.
Check out Detox's own test suite
Note:
setLocationis dependent onfbsimctl. 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);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.*']);Enable EarlGrey's synchronization mechanism (enabled by default). This is being reset on every new instance of the app.
await device.enableSynchronization();Disable EarlGrey's synchronization mechanism (enabled by default) This is being reset on every new instance of the app.
await device.disableSynchronization();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 on the device and schedules putting it to the artifacts folder upon completion of the current test.
Returns a temporary path to the screenshot.
NOTE: The returned path is guaranteed to be valid only during the test execution. Later on, the screenshot will be moved to the artifacts location.
Consider the example below:
describe('Menu items', () => {
it('should have Logout', async () => {
// ...
const screenshotPath = await device.takeScreenshot('tap on menu');
// ...
});
});In this example:
- If
--take-screenshots noneis set, the screenshot will be taken, but it won't be saved to<artifacts-location>after the test ends. - If
--take-screenshots failingis set, and the test passes, the screenshot won't be saved to<artifacts-location>after the test ends. - In the other modes (
manualandall), if the test passes, the screenshot will be put to<artifacts-location>/✓ Menu items should have Logout/tap on menu.png. - In the other modes (
manualandall), if the test fails, the screenshot will be put to<artifacts-location>/✗ Menu items should have Logout/tap on menu.png.
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 (https://developer.android.com/reference/android/support/test/uiautomator/UiDevice) 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.