320 lines
11 KiB
Markdown
320 lines
11 KiB
Markdown
---
|
|
id: APIRef.DeviceObjectAPI
|
|
title: 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()`](#devicelaunchappparams)
|
|
- [`device.relaunchApp()` **Deprecated**](#devicerelaunchappparams)
|
|
- [`device.terminateApp()`](#deviceterminateapp)
|
|
- [`device.sendToHome()`](#devicesendtohome)
|
|
- [`device.reloadReactNative()`](#devicereloadreactnative)
|
|
- [`device.installApp()`](#deviceinstallapp)
|
|
- [`device.uninstallApp()`](#deviceuninstallapp)
|
|
- [`device.openURL(url)`](#deviceopenurlurl-sourceappoptional)
|
|
- [`device.sendUserNotification(params)`](#devicesendusernotificationparams)
|
|
- [`device.sendUserActivity(params)`](#devicesenduseractivityparams)
|
|
- [`device.setOrientation(orientation)`](#devicesetorientationorientation)
|
|
- [`device.setLocation(lat, lon)`](#devicesetlocationlat-lon)
|
|
- [`device.setURLBlacklist([urls])`](#deviceseturlblacklisturls)
|
|
- [`device.enableSynchronization()`](#deviceenablesynchronization)
|
|
- [`device.disableSynchronization()`](#devicedisablesynchronization)
|
|
- [`device.resetContentAndSettings()`](#deviceresetcontentandsettings)
|
|
- [`device.getPlatform()`](#devicegetplatform)
|
|
- [`device.pressBack()` **Android Only**](#devicepressback-android-only)
|
|
- [`device.shake()` **iOS Only**](#deviceshake-ios-only)
|
|
|
|
### `device.launchApp(params)`
|
|
Launch the app defined in the current [`configuration`](APIRef.Configuration.md).
|
|
|
|
**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`
|
|
|
|
```js
|
|
await device.launchApp({newInstance: true});
|
|
```
|
|
|
|
##### 2. Set runtime permissions
|
|
Grant or deny runtime permissions for your application.
|
|
|
|
```js
|
|
await device.launchApp({permissions: {calendar: 'YES'}});
|
|
```
|
|
Detox uses [AppleSimUtils](https://github.com/wix/AppleSimulatorUtils) 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](../detox/test/e2e/13.permissions.test.js)
|
|
|
|
##### 3. Launch from URL
|
|
Mock opening the app from URL to test your app's deep link handling mechanism.
|
|
|
|
```js
|
|
await device.launchApp({url: url});
|
|
```
|
|
###### Mock opening from a URL when app is not running
|
|
```js
|
|
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
|
|
|
|
```js
|
|
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](APIRef.MockingOpenFromURL.md) section.
|
|
|
|
##### 4. Launch with user notifications
|
|
|
|
```js
|
|
await device.launchApp({userNotification: notification});
|
|
```
|
|
|
|
###### Mock receiving a notifications when app is not running
|
|
```js
|
|
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
|
|
|
|
```js
|
|
await device.launchApp({userNotification: notification, newInstance: false});
|
|
```
|
|
This will launch the app from background and handle the notification.
|
|
|
|
Read more in [Mocking User Notifications](APIRef.MockingUserNotifications.md) section.
|
|
|
|
##### 5. Launch with user activity
|
|
|
|
```js
|
|
await device.launchApp({userActivity: activity});
|
|
```
|
|
|
|
###### Mock receiving an activity when app is not running
|
|
```js
|
|
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
|
|
|
|
```js
|
|
await device.launchApp({userActivity: activity, newInstance: false});
|
|
```
|
|
This will launch the app from background and handle the activity.
|
|
|
|
Read more in [Mocking User Activity](APIRef.MockingUserActivity.md) 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`.
|
|
|
|
```js
|
|
await device.launchApp({delete: true});
|
|
```
|
|
|
|
##### 7. Additional launch arguments
|
|
Detox can start the app with additional launch arguments
|
|
|
|
```js
|
|
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.
|
|
|
|
```js
|
|
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](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPInternational/LanguageandLocaleIDs/LanguageandLocaleIDs.html).
|
|
|
|
```js
|
|
await device.launchApp({
|
|
languageAndLocale: {
|
|
language: "es-MX",
|
|
locale: "es-MX"
|
|
}
|
|
});
|
|
```
|
|
|
|
With this API, you can run sets of e2e tests per language. For example:
|
|
```js
|
|
['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.
|
|
|
|
```js
|
|
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.<Br>
|
|
Kill and relaunch the app defined in the current [`configuration`](APIRef.Configuration.md).
|
|
|
|
### `device.terminateApp()`
|
|
By default, `terminateApp()` with no params will terminate the app file defined in the current [`configuration`](APIRef.Configuration.md).
|
|
|
|
To terminate another app, specify its bundle id
|
|
|
|
```js
|
|
await device.terminateApp('other.bundle.id');
|
|
```
|
|
|
|
### `device.sendToHome()`
|
|
Send application to background by bringing `com.apple.springboard` to the foreground.<br>
|
|
Combining `sendToHome()` with `launchApp({newInstance: false})` will simulate app coming back from background.<br>
|
|
Check out Detox's [own test suite](../detox/test/e2e/06.device.test.js)
|
|
|
|
```js
|
|
await device.sendToHome();
|
|
await device.launchApp({newInstance: false});
|
|
// app returned from background, do stuff
|
|
```
|
|
Check out Detox's [own test suite](../detox/test/e2e/06.device.test.js)
|
|
|
|
### `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.
|
|
|
|
<i>**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.</i>
|
|
|
|
### `device.installApp()`
|
|
By default, `installApp()` with no params will install the app file defined in the current [`configuration`](APIRef.Configuration.md).
|
|
|
|
To install another app, specify its path
|
|
|
|
```js
|
|
await device.installApp('path/to/other/app');
|
|
```
|
|
|
|
### `device.uninstallApp()`
|
|
By default, `uninstallApp()` with no params will uninstall the app defined in the current [`configuration`](APIRef.Configuration.md).
|
|
|
|
To uninstall another app, specify its bundle id
|
|
|
|
```js
|
|
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.<br>
|
|
Read more in [Mocking Open From URL](APIRef.MockingOpenFromURL.md) section.<br>
|
|
Check out Detox's [own test suite](../detox/test/e2e/15.urls.test.js)
|
|
|
|
### `device.sendUserNotification(params)`
|
|
Mock handling of received user notification when app is in foreground.<br>
|
|
Read more in [Mocking User Notifications](APIRef.MockingUserNotifications.md) section.<br>
|
|
Check out Detox's [own test suite](../detox/test/e2e/11.user-notifications.test.js)
|
|
|
|
### `device.sendUserActivity(params)`
|
|
Mock handling of received user activity when app is in foreground.<br>
|
|
Read more in [Mocking User Activity](APIRef.MockingUserActivity.md) section.<br>
|
|
Check out Detox's [own test suite](../detox/test/e2e/18.user-activities.test.js)
|
|
|
|
### `device.setOrientation(orientation)`
|
|
Takes `"portrait"` or `"landscape"` and rotates the device to the given orientation.
|
|
Currently only available in the iOS Simulator.<br>
|
|
Check out Detox's [own test suite](../detox/test/e2e/06.device-orientation.test.js)
|
|
|
|
### `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.
|
|
```js
|
|
await device.setLocation(32.0853, 34.7818);
|
|
```
|
|
|
|
### `device.setURLBlacklist([urls])`
|
|
|
|
Disable [EarlGrey's network synchronization mechanism](https://github.com/google/EarlGrey/blob/master/docs/api.md#network) 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](#10-initialize-the-url-blacklist-at-device-launch).
|
|
|
|
```js
|
|
await device.setURLBlacklist(['.*127.0.0.1.*']);
|
|
```
|
|
|
|
```js
|
|
await device.setURLBlacklist(['.*my.ignored.endpoint.*']);
|
|
```
|
|
|
|
### `device.enableSynchronization()`
|
|
Enable [EarlGrey's synchronization mechanism](https://github.com/google/EarlGrey/blob/master/docs/api.md#synchronization
|
|
) (enabled by default). **This is being reset on every new instance of the app.**
|
|
```js
|
|
await device.enableSynchronization();
|
|
```
|
|
|
|
|
|
### `device.disableSynchronization()`
|
|
Disable [EarlGrey's synchronization mechanism](https://github.com/google/EarlGrey/blob/master/docs/api.md#synchronization
|
|
) (enabled by default) **This is being reset on every new instance of the app.**
|
|
|
|
```js
|
|
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.
|
|
|
|
```js
|
|
await device.resetContentAndSettings();
|
|
```
|
|
|
|
### `device.getPlatform()`
|
|
Returns the current device, `ios` or `android`.
|
|
|
|
```js
|
|
if (device.getPlatform() === 'ios') {
|
|
await expect(loopSwitch).toHaveValue('1');
|
|
}
|
|
```
|
|
|
|
### `device.pressBack()` **Android Only**
|
|
Simulate press back button.
|
|
|
|
```js
|
|
await device.pressBack();
|
|
```
|
|
|
|
### `device.shake()` **iOS Only**
|
|
Simulate shake
|