Detox device API 完全指南:掌控移动端 E2E 测试中的设备生命周期
Detox device API 完全指南:掌控移动端 E2E 测试中的设备生命周期
device 是 Detox 中控制当前所连接设备的核心全局对象,覆盖应用启动/终止、权限授予、URL 深度链接、用户通知、同步开关、系统手势与传感器模拟等数十项操作。本文以 Detox 20.x 的 device API 参考为骨架,结合仓库源码(如 RuntimeDevice.js、AndroidDriver.js、SimulatorDriver.js)深入讲解每个属性与方法的语义、平台差异与底层实现,帮助读者写出稳定、可维护的端到端测试。
device 对象:全局可用性与导入方式
在默认配置下,device 对象在每个测试文件中全局可用。若在行为配置(behavior config)中设置了 exposeGlobals: false,全局对象将被关闭,此时需要显式从 Detox 包中导入:
const { device } = require('detox');
它提供对当前所连接设备(当前附加的模拟器/真机)的控制能力。从源码结构看,device 本质上是对 RuntimeDevice 类的封装——该类在构造时将所有设备方法统一挂载并附加了调用追踪(traceMethods)与堆栈截断(wrapWithStackTraceCutter)能力,见 RuntimeDevice.js。这意味着你在测试日志中能看到每个设备调用的耗时与轨迹,便于排查慢操作。
Public Properties(公开属性)
device.id
保存设备在环境中的唯一 ID:
- Android:
adb设备 ID,例如emulator-5554; - iOS:Mac 级唯一的模拟器 UDID,即
simctl使用的 ID,例如AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE。
该值在设备被正确 prepared(即调用 detox.init() 之后)之前为 undefined。其底层实现取自设备驱动:get id() { return this.deviceDriver.getExternalId(); }(RuntimeDevice.js)。
device.name
保存设备的描述性名称,例如 emulator-5554 (Pixel_API_26)。同样,在 detox.init() 之前为 undefined。底层对应 get name() { return this.deviceDriver.getDeviceName(); },iOS 侧名称由驱动拼接为 `${udid} (${type})` 的形式(见 SimulatorDriver.js)。
device.appLaunchArgs
用于访问用户在静态作用域(如 Detox 配置文件 与 命令行参数)中预定义的启动参数,并支持查询与修改:
// 修改部分预定义参数:
device.appLaunchArgs.modify({
mockServerPort: 1234,
});
// 读取参数:
device.appLaunchArgs.get(); // ==> { mockServerPort: 1234 }
// 重置(移除所有参数):
device.appLaunchArgs.reset();
在多应用环境中,你可能希望让参数值在 device.selectApp(name) 调用之间保持:
device.appLaunchArgs.modify({ transientArg: 'value' });
device.appLaunchArgs.shared.modify({
permanentMockServerPort: 1234,
};
device.appLaunchArgs.get(); // ==> { permanentMockServerPort: 1234, transientArg: 'value' }
device.appLaunchArgs.shared.get(); // ==> { permanentMockServerPort: 1234 }
await device.selectApp('anotherApp');
device.appLaunchArgs.get(); // ==> { permanentMockServerPort: 1234 }
device.appLaunchArgs.reset();
device.appLaunchArgs.get(); // ==> { permanentMockServerPort: 1234 }
device.appLaunchArgs.shared.reset();
device.appLaunchArgs.get(); // ==> {}
这是编辑启动参数最灵活的方式。完整细节参考 启动参数指南。
源码级原理:appLaunchArgs 由 LaunchArgsEditor 实现,内部维护两个作用域——_local(瞬时/随应用切换而重置)与 _shared(永久/跨应用保留),get() 通过 lodash 的 merge 将两者合并返回深拷贝(LaunchArgsEditor.js)。其对应的单元测试 LaunchArgsEditor.test.js 验证了"local 与 shared 合并""默认只重置瞬时值""每次返回深拷贝"等行为。另外,在 RuntimeDevice.selectApp() 中,每次切换应用都会先 reset() 再 modify(currentApp.launchArgs)(RuntimeDevice.js),这就是瞬时参数随应用切换被清空的原因。
多应用切换:device.selectApp(name)
仅用于高级多应用配置场景:在同一测试用例内切换不同的应用。如何定义多个不同 name 的应用,参见配置文档。
await device.selectApp('myAppName');
由于当前架构限制,调用 device.selectApp 会终止之前正在运行的应用(源码中 selectApp 在切换前调用 terminateApp(),见 RuntimeDevice.js),这是一个需要注意的副作用。同时它会重置当前应用的 launch-args 编辑器并重新加载新应用的静态启动参数。
核心方法:device.launchApp(params)
启动当前配置中定义的应用。params 为对象,可包含以下 13 组键值,下面逐一详解。
1. newInstance — 启动应用新实例
终止应用后重新启动。若设为 false,设备会尝试恢复应用(例如从后台回到前台);若应用未运行,仍会启动新实例。默认值为 false。
await device.launchApp({newInstance: true});
源码中 newInstance 的默认逻辑是"进程尚未注册则视为需要新实例":params.newInstance !== undefined ? params.newInstance : this._processes<a href="https://link.gitcode.com/i/d41b08b64bfa53a318a602950c5e2630" target="_blank">bundleId] == null([RuntimeDevice.js),_processes 表在 terminateApp 时被清空。
2. permissions — 设置运行时权限(仅 iOS)
向应用授予或拒绝运行时权限,应用会在权限生效前被终止。
await device.launchApp({permissions: {calendar: 'YES'}});
该功能在 iOS 模拟器上依赖 AppleSimUtils 与 xcrun simctl,请确保两者均为最新版本。支持的权限及取值如下:
| 权限 | 可选值 | 说明 |
|---|---|---|
| location | always / inuse / never / unset | inuse - 仅应用在前台时提供定位 |
| contacts | YES / NO / unset / limited | limited - 授予联系人受限访问 |
| photos | YES / NO / unset / limited | limited - 授予照片受限访问 |
| calendar | YES / NO / unset | |
| camera | YES / NO / unset | |
| medialibrary | YES / NO / unset | |
| microphone | YES / NO / unset | |
| motion | YES / NO / unset | |
| reminders | YES / NO / unset | |
| siri | YES / NO / unset | |
| notifications | YES / NO / unset | 依赖 AppleSimUtils;simctl 不支持 |
| health | YES / NO / unset | 依赖 AppleSimUtils;simctl 不支持 |
| homekit | YES / NO / unset | 依赖 AppleSimUtils;simctl 不支持 |
| speech | YES / NO / unset | 依赖 AppleSimUtils;simctl 不支持 |
| faceid | YES / NO / unset | 依赖 AppleSimUtils;simctl 不支持 |
| userTracking | YES / NO / unset | 依赖 AppleSimUtils;simctl 不支持 |
可参考 Detox 自带的权限测试套件 detox/test/e2e/13.permissions.test.js 获取使用示例。源码层面,该参数在 RuntimeDevice.js 中被透传给 deviceDriver.setPermissions(bundleId, params.permissions),iOS 侧最终调用 applesimutils.setPermissions(SimulatorDriver.js)。
3. url — 通过 URL 启动
以指定 URL 启动应用,用于测试深度链接(deep link)处理机制。
await device.launchApp({url});
await device.launchApp({url, newInstance: true}); // 启动应用新实例
await device.launchApp({url, newInstance: false}); // 复用已有实例
更多细节参见 Mocking Open with URL。newInstance 参数的完整效果见上文第 1 小节。源码中 url 会被写入 detoxURLOverride 启动参数;Android 侧通过 startActivityFromUrl(url) 拉起 Activity(AndroidDriver.js)。
4. userNotification — 携带用户通知启动
以指定的用户通知启动应用。
await device.launchApp({userNotification});
await device.launchApp({userNotification, newInstance: true}); // 启动应用新实例
await device.launchApp({userNotification, newInstance: false}); // 复用已有实例
更多细节参见 Mocking User Notifications。源码实现中,通知载荷会被写入临时 JSON 文件,并通过 detoxUserNotificationDataURL 启动参数传递给应用(RuntimeDevice.js);Android 侧会把载荷文件先推送到设备再启动通知 Activity(AndroidDriver.js)。
5. userActivity — 携带用户 Activity 启动(仅 iOS)
以指定的用户 activity 启动应用。
await device.launchApp({userActivity: activity});
await device.launchApp({userActivity: activity, newInstance: true}); // 启动应用新实例
await device.launchApp({userActivity: activity, newInstance: false}); // 复用已有实例
更多细节参见 Mocking User Activity。
6. resetAppState — 启动前重置应用状态
重置应用状态,且不必执行完整的卸载/重装周期:
- Android:使用
pm clear清除应用数据,通常比重装更快; - iOS:通过卸载并重装应用来恢复干净状态。
await device.launchApp({resetAppState: true});
源码中该分支会先 terminateApp(bundleId) 再调用 resetAppState(bundleId)(RuntimeDevice.js)。
7. delete — 删除并重装应用
先卸载再重装后启动。比 resetAppState 慢,但能保证应用及其全部数据是全新安装。
await device.launchApp({delete: true});
源码对应分支:terminateApp → uninstallApp() → installApp()(RuntimeDevice.js)。
8. launchArgs — 附加进程启动参数
以测试现场指定的启动参数启动应用:
await device.launchApp({
launchArgs: {
arg1: 1,
arg2: "2",
}
});
这是设置启动参数最直接、最明确的方式。完整的启动参数概览参见 启动参数指南。源码中 params.launchArgs 会与 appLaunchArgs 编辑器中的既有参数合并({...this._currentAppLaunchArgs.get(), ...params.launchArgs},见 RuntimeDevice.js),且与 detoxServer、detoxSessionId 等会话参数一并注入(_prepareLaunchArgs,RuntimeDevice.js)。
9. disableTouchIndicators — 禁用触控指示器(仅 iOS)
禁用 iOS 上的触控指示器。默认值为 false。
await device.launchApp({disableTouchIndicators: true});
10. languageAndLocale — 以指定语言/地区启动(仅 iOS)
以指定的系统语言启动应用,可接受的取值规范参考 Apple 的 Language and Locale IDs 文档。
await device.launchApp({
languageAndLocale: {
language: "es-MX",
locale: "es-MX"
}
});
利用此 API,可以按语言批量运行 E2E 测试,例如:
describe.each([
['es-MX'], ['fr-FR'], ['pt-BR'],
])(`Test suite (locale: %s)`, (locale) => {
beforeAll(async () => {
await device.launchApp({
newInstance: true,
languageAndLocale: {
language: locale,
locale
}
});
});
test('some description', async () => {
// …
});
});
Detox 自带的测试 detox/test/e2e/06.device.test.js 也验证了通过该参数启动后应用内可读取到正确的语言与地区。
11. detoxEnableSynchronization — 启动时初始化同步开关
以同步机制启用或禁用状态启动应用。若应用在启动过程中无法被同步,该参数非常有用;之后可通过 device.enableSynchronization() 重新启用同步。
await device.launchApp({
newInstance: true,
launchArgs: { detoxEnableSynchronization: 0 }
});
12. detoxURLBlacklistRegex — 启动时初始化 URL 黑名单
以 URL 黑名单启动应用,用于禁用对某些端点的网络同步。若应用启动时频繁访问黑名单端点,此参数很有用。
注意:由于正则表达式的复杂性与互操作性考虑,实现对该 URL 字符串的格式相当敏感,请尽量遵循下面的示例格式:
await device.launchApp({
newInstance: true,
launchArgs: { detoxURLBlacklistRegex: '\\("^http://192\.168\.1\.253:\\d{4}/.*","https://e\.crashlytics\.com/spi/v2/events"\\)' },
});
13. detoxDisableWebKitSecurity — 禁用 WebKit 安全(仅 iOS)
禁用 iOS 上的 WebKit 安全。默认值为 false。适用于测试加载 CORS 保护内容的 iframe 的 WebView。
:::caution 重要提示 禁用 WebKit 安全后,部分页面可能无法正常加载(例如符合 PCI DSS 的页面);对安全策略严格的页面可能引发加载错误。 :::
await device.launchApp({
launchArgs: { detoxDisableWebKitSecurity: true }
});
生命周期控制:终止、安装与卸载
device.terminateApp()
默认不带参数时,终止当前配置中定义的应用。若要终止其他应用,可传入其 bundle id:
await device.terminateApp('other.bundle.id');
device.reloadReactNative()
如果是 React Native 应用,重新加载 RN 的 JS bundle。这比 device.launchApp() 快得多,适合只需重置 React Native 逻辑的场景。
注意: 该功能并非万无一失。某些条件下系统可能表现异常甚至崩溃。此时应改用
device.launchApp()干净地启动应用,而不要仅重载 JS bundle。
device.installApp()
默认不带参数时,安装当前配置中定义的应用。若要安装其他应用,传入其路径:
await device.installApp('path/to/other/app');
值得注意的是,若应用配置中声明了 reversePorts(端口反向转发列表),installApp 后会自动逐一执行 reverseTcpPort(port)(RuntimeDevice.js)。
device.uninstallApp()
默认不带参数时,卸载当前配置中定义的应用。若要卸载其他应用,传入其 bundle id:
await device.uninstallApp('other.bundle.id');
注意: 对于应用状态重置场景,建议使用 device.resetAppState(),它比"卸载再安装"更高效。
模拟外部事件:URL、通知与用户 Activity
device.openURL({url, sourceApp[可选]})
模拟从 URL 打开应用。sourceApp 是可选参数(仅 iOS),用于指定来源应用的 bundle id。
await device.openURL({ url: 'myapp://...' });
源码要求必须传入包含 url 键的对象,否则抛出 DetoxRuntimeError(RuntimeDevice.js)。更多细节参见 Mocking Open with URL,相关测试见 detox/test/e2e/15.urls.test.js。
device.sendUserNotification(params)
在应用已在运行时,模拟系统收到用户通知并交由应用处理。更多细节参见 Mocking User Notifications,相关测试见 detox/test/e2e/11.user-notifications.test.js。
device.sendUserActivity(params)(仅 iOS)
在应用处于前台时,模拟收到用户 activity。更多细节参见 Mocking User Activity,相关测试见 detox/test/e2e/18.user-activities.test.js。
源码层面,这两个方法都走 _sendPayload(key, params):先创建载荷文件,再通过 deliverPayload 投递给运行中的应用(RuntimeDevice.js)。
系统级交互:方向、位置、按键与端口
device.setOrientation(orientation)
接受 "portrait" 或 "landscape",将设备旋转到指定方向。
注意: 方向设置仅支持 iPhone 设备,或声明为需要全屏(full screen)的 iPad 应用;其他情况当前测试将失败。
Android 侧通过 Espresso 的 changeOrientation 调用实现,映射为 landscape: 1, portrait: 0(AndroidDriver.js)。相关测试见 detox/test/e2e/06.device-orientation.test.js。
device.setLocation(lat, lon)
将模拟器/真机位置设置为给定的经纬度。
iOS 上
setLocation依赖xcrun simctl,建议使用其最新版本。Android 上
setLocation同时支持 Android Emulator(随 Android 开发工具提供)与 Genymotion,且应用 manifest 中必须声明相应权限。
await device.setLocation(32.0853, 34.7818);
device.pressBack()(仅 Android)
模拟按下返回键。
await device.pressBack();
Android 驱动中通过 uiDevice.pressBack() 实现(AndroidDriver.js)。
device.reverseTcpPort()(仅 Android)
将 TCP 端口从设备(guest)反向转发到宿主机,等同于 adb reverse 的效果——设备发往该端口的网络请求将被转发到宿主机。
device.unreverseTcpPort()(仅 Android)
清除之前设置的反向 TCP 端口(例如通过 device.reverseTcpPort() 设置的)。
Android 侧分别映射为 adb.reverse 与 adb.reverseRemove(AndroidDriver.js)。
device.shake()(仅 iOS)
模拟摇一摇。
device.getPlatform()
返回当前设备平台:ios 或 android。
if (device.getPlatform() === 'ios') {
await expect(loopSwitch).toHaveValue('1');
}
Android 驱动返回 'android'(AndroidDriver.js),iOS 驱动同理返回 'ios'。
任意坐标手势:tap 与 longPress
device.tap(point, shouldIgnoreStatusBar)
在设备屏幕的任意坐标上执行一次点击。
tap 参数
point— 元素坐标系中的坐标(默认值:{x: 100, y: 100},平台:Android 与 iOS);shouldIgnoreStatusBar— 是否从状态栏下方开始测量坐标(默认值:true,平台:Android)。
tap 示例
await device.tap();
await device.tap({ x: 100, y: 150 }, false);
await device.tap({ x: 100, y: 150 });
await device.tap(false);
device.longPress(point, duration, shouldIgnoreStatusBar)
在设备屏幕的任意坐标上执行长按,可按需自定义按压时长。
longPress 参数
point— 元素坐标系中的坐标(默认值:{x: 100, y: 100},平台:Android 与 iOS);duration— 自定义按压时长(毫秒)。默认值:Android 为标准长按时长,iOS 为 1000 毫秒(平台:Android 与 iOS);shouldIgnoreStatusBar— 是否从状态栏下方开始测量坐标(默认值:true,平台:Android)。
longPress 示例
await device.longPress();
await device.longPress({ x: 100, y: 150 }, 2000, false);
await device.longPress({ x: 100, y: 150 }, 2000);
await device.longPress(2000, false);
await device.longPress({ x: 100, y: 150 }, false);
await device.longPress({ x: 100, y: 150 });
await device.longPress(2000);
await device.longPress(false);
上述重载形式之所以可行,是因为 longPress 的三个参数均为可选,且由 mapDeviceLongPressArguments 统一做类型推断与断言(数字视为 duration、布尔值视为 shouldIgnoreStatusBar、对象视为 point),参数非法时会抛出带详细提示的 DetoxRuntimeError,见 mapDeviceLongPressArguments.js。
同步控制:禁用、恢复与 URL 黑名单
device.disableSynchronization()
临时禁用与应用的同步(idle/busy 监控),即不再等待应用空闲就继续执行测试。
此 API 适用于应用某区域允许持续保持部分 busy(例如存在无限循环的屏幕动画)时仍需在其中做断言的情况。但使用它通常意味着测试代码中会引入 sleep(),这并不被推荐,且永远无法做到 100% 稳定。因此经验法则是:同步禁用模式下的测试代码应精简到最低限度。
注意:同步默认启用,并且在每次启动应用新实例时都会重新启用。
await device.disableSynchronization();
device.enableSynchronization()
在之前调用 device.disableSynchronization() 之后,重新启用与应用的同步(idle/busy 监控),即恢复"等待应用空闲再继续执行"的行为。
:warning: 注意:该调用会立即恢复同步,其返回的 Promise 只有在应用再次变为空闲时才 resolve。也就是说,必须在你导航回"安全区域"(应用最终能够重新变空闲的地方)之后再调用它,否则 Promise 将一直挂起(直到保护性超时触发)。
await device.enableSynchronization();
Android 侧两者分别映射为 Espresso 的 setSynchronization(true/false) 调用(AndroidDriver.js)。
device.setURLBlacklist([urls])
根据特定端点(以 URL 正则表达式表示)排除与网络活动相关的同步(即不等待网络空闲再继续执行)。若要在初始化时禁用端点,可将黑名单作为名为 detoxURLBlacklistRegex 的应用启动参数传入(见上文 launchApp 第 12 小节)。
await device.setURLBlacklist(['.*127.0.0.1.*', '.*my.ignored.endpoint.*']);
源码中该列表会先经 normalizeURLBlacklist 规范化再下发到设备驱动(RuntimeDevice.js)。
状态与数据重置
device.resetAppState([...bundleIds])
通过清除应用数据、恢复到干净状态来重置应用状态。
- Android:使用
pm clear命令清除应用数据,在不卸载的情况下将应用重置为初始安装状态; - iOS:Detox 使用"卸载并重装"的 fallback 方案达到干净状态。
// 重置当前应用状态
await device.resetAppState();
// 重置指定应用状态
await device.resetAppState('com.example.app');
// 重置多个应用
await device.resetAppState('com.app1', 'com.app2');
源码中,不带参数时默认重置当前应用,多个 bundle id 会依次处理;Android 侧执行 adb.clearAppData 并随后重新授予所有权限(AndroidDriver.js)。
device.resetContentAndSettings()(仅 iOS)
将模拟器重置为干净状态(类似模拟器菜单中的 Reset Content and Settings...),尤其会移除此前设置的权限。
await device.resetContentAndSettings();
源码实现会先关闭模拟器、执行重置、再重新启动并触发相应事件(SimulatorDriver.js)。
device.clearKeychain()(仅 iOS)
清除设备钥匙串(Keychain)。
截屏与视图层级
device.takeScreenshot([name])
对设备进行截图。完整截图指南参见 taking-screenshots 指南。注意源码要求必须提供非空名称,否则抛出"empty name"错误(RuntimeDevice.js)。
device.captureViewHierarchy([name])(仅 iOS)
将当前打开应用的视图层级快照(*.viewhierarchy 文件)保存到临时目录,并在当前测试完成后将其归档到 artifacts 目录。该文件可在 Xcode 12.0 及以上版本中打开。
name 参数可选,默认值为 capture。
test('Capture view hierarchy', async () => {
const temporaryArtifactPath = await device.captureViewHierarchy('myElements');
// 临时路径在测试完成前有效。
// 之后 artifact 会被移动,例如:
// * 成功时:<artifacts-location>/✓ Capture view hierarchy/myElements.viewhierarchy
// * 失败时:<artifacts-location>/✗ Capture view hierarchy/myElements.viewhierarchy
});
device.generateViewHierarchyXml([shouldInjectTestIds])
生成当前打开应用的视图层级 XML,以字符串形式返回。shouldInjectTestIds 可选,默认 false;设为 true 时,Detox 会尝试为 XML 中每个未定义 testID 的元素注入该属性。
const viewHierarchyXml = await device.generateViewHierarchyXml();
Android 侧通过 DetoxApi.generateViewHierarchyXml 调用执行并返回结果字符串(AndroidDriver.js)。
生物识别与状态栏(iOS 专属)
device.setBiometricEnrollment(bool)(仅 iOS)
切换设备在生物认证(Touch ID 或 Face ID)中的注册状态。
await device.setBiometricEnrollment(true);
// 或
await device.setBiometricEnrollment(false);
device.matchFace()(仅 iOS)
模拟 Face ID 人脸匹配成功。
device.unmatchFace()(仅 iOS)
模拟 Face ID 人脸匹配失败。
device.matchFinger()(仅 iOS)
模拟 Touch ID 指纹匹配成功。
device.unmatchFinger()(仅 iOS)
模拟 Touch ID 指纹匹配失败。
源码中,注册状态被转为 'YES'/'NO' 后交给 AppleSimUtils;匹配/失配则分别映射到 matchBiometric/unmatchBiometric(SimulatorDriver.js)。
device.setStatusBar()(仅 iOS)
覆盖模拟器的状态栏,可用选项如下:
await device.setStatusBar({
time: "12:34",
// 将日期或时间设为固定值。
// 若字符串是合法的 ISO 日期字符串,还会在相关设备上同时设置日期。
dataNetwork: "wifi",
// 若指定,必须为 'hide', 'wifi', '3g', '4g', 'lte', 'lte-a', 'lte+', '5g', '5g+', '5g-uwb', 或 '5g-uc' 之一。
wifiMode: "failed",
// 若指定,必须为 'searching', 'failed', 或 'active' 之一。
wifiBars: "2",
// 若指定,必须为 0-3。
cellularMode: "searching",
// 若指定,必须为 'notSupported', 'searching', 'failed', 或 'active' 之一。
cellularBars: "3",
// 若指定,必须为 0-4。
operatorName: "A1",
// 设置蜂窝运营商名称。空字符串表示清空。
batteryState: "charging",
// 若指定,必须为 'charging', 'charged', 或 'discharging' 之一。
batteryLevel: "50",
// 若指定,必须为 0-100。
});
device.resetStatusBar()(仅 iOS)
重置模拟器状态栏上的任何覆盖设置。
Android 专属能力:device.getUiDevice()(仅 Android)
暴露 UiAutomator 的 UiDevice API。
const uiDevice = device.getUiDevice();
await uiDevice.pressRecentApps();
注意:该 API 不属于官方 Detox API 的一部分,当 UiDevice 或 UiAutomator 的 Gradle 依赖(androidx.test.uiautomator:uiautomator)更新时,它可能发生变动甚至被破坏。
从源码看,它由 UiDeviceProxy 通过 JavaScript Proxy 动态代理实现——UIDevice 中的每个方法都被包装为通过 InvocationManager 调用的异步调用(UiDeviceProxy.js),调用目标指向 androidx.test.uiautomator.UiDevice(见 UIDevice.js)。
结语:测试即文档
device API 几乎覆盖了移动端 E2E 测试中所有"设备级"操作:从启动参数注入、深度链接与通知模拟,到同步控制、系统手势、生物识别与状态栏覆盖。每一类操作都能在仓库中找到对应的驱动实现与端到端测试用例(如 06.device.test.js 中的 launchApp({newInstance: true}) + sendToHome() + launchApp() 组合用例),这为读者提供了"API 文档—源码实现—真实测试"三合一的验证闭环。建议在实际项目中使用本文 API 时,始终以当前仓库版本的 device API 文档 与类型声明(detox.d.ts)为准,并结合自家应用的启动路径与同步策略挑选最合适的组合。