Detox Expect API 完整指南:从元素匹配到状态断言的端到端实战
Detox Expect API 完整指南:从元素匹配到状态断言的端到端实战
Detox 的 Expect API 是移动端灰盒(gray box)端到端测试中的"断言层":它借助 Matchers 定位 UI 元素,再对元素的可见性、存在性、文本、标签、数值等状态进行校验。本文以 Detox 仓库中 APIRef.Expect.md 文档为骨架,结合 expectTwo.js 与 NativeExpect.js 的源码实现,系统讲解全部断言方法、not 取反、withTimeout 轮询等待机制,以及已废弃方法的迁移路径,帮助你写出稳定、可维护的 UI 断言代码。
Expect 在 Detox 中的定位
Detox 的测试 API 可以划分为三个彼此衔接的环节:
- 匹配(Matching):使用
by.id()、by.text()、by.label()等 Matchers 定位 UI 元素,参见 APIRef.Matchers.md; - 断言(Expectation):使用
expect(element(...)).toBeVisible()等断言验证元素处于预期状态,即本文主题; - 交互(Action):使用
tap()、typeText()、scroll()等模拟用户操作,参见 APIRef.ActionsOnElement.md。
从源码结构看,三者在 expectTwo.js 中由 Element、Expect、WaitFor 三个类分别承载,而 expect()、element()、waitFor() 三个工厂函数负责将它们串起来。所有断言最终都会序列化为一条 JSON 格式的 invocation(调用),通过 websocket 发送给运行在模拟器/真机上的测试驱动进程执行。
断言方法一览
Detox 的 Expect API 共提供 9 个正向断言方法、1 个取反修饰符和 1 个超时控制方法:
| 方法 | 作用 |
|---|---|
.toBeVisible() |
元素至少有 N% 区域可见于屏幕 |
.toExist() |
元素存在于当前 UI 层级树中 |
.toBeFocused() |
元素当前处于聚焦状态 |
.toHaveText(text) |
元素文本等于指定文本 |
.toHaveLabel(label) |
元素的无障碍标签(iOS)或内容描述(Android)匹配 |
.toHaveId(id) |
元素的无障碍标识符匹配 |
.toHaveValue(value) |
元素的无障碍数值匹配 |
.toHaveSliderPosition(position, tolerance) |
Slider 的归一化位置在容差范围内 |
.toHaveToggleValue(value) |
开关/复选框处于开启或关闭状态 |
.not |
对后续断言取反 |
.withTimeout(timeout) |
在指定毫秒内轮询等待断言满足 |
toBeVisible()
期望视图在屏幕上至少有 N% 的区域可见。可选参数 percent 为可见性阈值,取值范围 1~100 的整数;不传时默认 75%。
await expect(element(by.id('UniqueId203'))).toBeVisible();
await expect(element(by.id('UniqueId204'))).toBeVisible(35);
- 使用
not取反后,期望视图的可见面积小于 N%。 - 在 iOS 上,"可见"定义为视图本身或其某个子视图,位于该视图激活点(activation point)在屏幕上的最顶层。
- 参数校验在 expectTwo.js 中完成:
percent必须是 1~100 的安全整数,否则抛出percent must be an integer between 1 and 100错误;对应测试见 expectTwo.test.js 中"toBeVisible() should throw with bad args"用例。
toExist()
期望元素存在于 App 当前的 UI 层级树中,常用于校验动态加载的组件是否已挂载:
await expect(element(by.id('UniqueId205'))).toExist();
toBeFocused()
期望元素是当前聚焦元素,典型场景是校验输入框焦点:
await expect(element(by.id('textFieldId'))).toBeFocused();
toHaveText(text)
期望元素包含指定文本。在 React Native 中通常对应 <Text> 组件的文本内容:
await expect(element(by.id('UniqueId204'))).toHaveText('I contain some text');
在 expectTwo.js 的 toHaveText 实现中,参数既可以是字符串也可以是正则表达式(内部通过 isRegExp(text) 判断,并将正则标记随 invocation 一并下发,便于原生侧做正则匹配)。
toHaveLabel(label)
期望元素具有指定的无障碍标签:iOS 上为 accessibility label,Android 上为 content description。在 React Native 中对应 accessibilityLabel prop:
await expect(element(by.id('UniqueId204'))).toHaveLabel('Done');
平台差异注意:iOS 与 Android 对 accessibility label 的实现存在不一致——在 iOS 上,如果某个 View 没有显式定义
accessibilityLabel,它会默认使用其子 View 的 accessibilityLabel 拼接结果;而在 Android 上,同样的 View 将完全没有 accessibilityLabel。编写跨平台测试时需留意这一行为差异。
toHaveId(id)
期望元素具有指定的无障碍标识符。在 React Native 中对应 testID prop,在原生 iOS 中对应 accessibilityIdentifier:
await expect(element(by.text('I contain some text'))).toHaveId('UniqueId204');
toHaveValue(value)
期望元素具有指定的无障碍数值。在 React Native 中对应 accessibilityValue prop。典型场景如校验温度调节旋钮的数值:
await expect(element(by.id('UniqueId533'))).toHaveValue('0');
toHaveSliderPosition(normalizedPosition, tolerance)
期望 Slider 元素位于指定的归一化位置(取值范围 [0, 1]),第二个可选参数 tolerance 用于吸收 iOS 上的浮点舍入误差:
await expect(element(by.id('slider'))).toHaveSliderPosition(0.75);
await expect(element(by.id('slider'))).toHaveSliderPosition(0.3113, 0.00001);
从 expectTwo.js 源码看,tolerance 的默认值为 0;对应的 JSON 序列化测试见 expectTwo.test.js 中 toHaveSliderPosition 用例(期望的 invocation 结构包含 expectation: 'toHaveSliderPosition' 及其参数数组)。
toHaveToggleValue(value)
期望开关类元素(如 Switch、CheckBox)处于开/勾选或关/取消勾选状态。在 React Native 中对应 Switch 组件:
await expect(element(by.id('switch'))).toHaveToggleValue(true);
await expect(element(by.id('checkbox'))).toHaveToggleValue(false);
在 iOS 实现中,toHaveToggleValue 会先将参数强制转为数值(Number(value))再下发,与原生侧布尔表达保持一致。
not:断言取反
not 修饰符会对紧随其后的断言取反,语义与代码可读性均优于旧式 toBeNotXxx 系列方法:
await expect(element(by.id('UniqueId533'))).not.toBeVisible();
实现上,Expect 类的 not getter 会把 'not' 推入 this.modifiers 数组(expectTwo.js),最终随 invocation 的 modifiers 字段下发;Android 侧则由 NativeExpect 的 not getter 设置 _notCondition = true(NativeExpect.js)。被取反的断言在原生侧执行"反向匹配"语义——例如 not.toBeVisible() 期望可见面积小于阈值,而非简单地"消失"。
withTimeout():轮询等待
withTimeout(timeout) 会在指定时间(毫秒)内持续轮询,直到断言满足;若超时仍未满足,则断言失败:
await waitFor(element(by.id('UniqueId204'))).toBeVisible().withTimeout(2000);
关键点:
withTimeout只能与waitFor()搭配使用,不能直接接在expect()之后;- 从 detox.d.ts 的类型注释可见:每次
waitFor调用都必须通过withTimeout()设置超时,否则轮询不会执行任何操作; - expectTwo.js 中
WaitFor类通过InternalExpect先把断言构造成 invocation,再由waitForWithTimeout将timeout合并进 invocation 结构({ ...action, ...expectation, timeout })后一次性执行; WaitFor还支持whileElement(matcher).scroll(...)这种"反复执行滚动直到断言满足"的复合用法,是处理列表懒加载场景的利器。
waitFor 属于手动同步手段,仅应在 Detox 自动同步无法覆盖的少数场景(如等待长时间运行的动画)下使用,优先依赖 Detox 内建的应用空闲同步机制。
已废弃方法及迁移
以下三个旧式断言方法已标记为 Deprecated,新代码应改用 not 修饰符:
| 已废弃方法 | 替代写法 |
|---|---|
.toBeNotVisible() |
.not.toBeVisible() |
.toNotExist() |
.not.toExist() |
.toBeNotFocused() |
.not.toBeFocused() |
// 旧写法(已废弃)
await expect(element(by.id('UniqueId205'))).toBeNotVisible();
await expect(element(by.id('RandomJunk959'))).toNotExist();
await expect(element(by.id('textFieldId'))).toBeNotFocused();
// 新写法
await expect(element(by.id('UniqueId205'))).not.toBeVisible();
await expect(element(by.id('RandomJunk959'))).not.toExist();
await expect(element(by.id('textFieldId'))).not.toBeFocused();
在 expectTwo.js 中,旧方法实现上只是 this.not.toXxx() 的语法糖;detox.d.ts 类型定义同样为它们标注了 @deprecated 注释。另需注意:旧文档示例中 toBeNotFocused() 的用法示例存在笔误(示例写成了 toBeFocused()),实际应调用 toBeNotFocused()。
底层实现:断言如何被序列化并执行
理解断言底层机制有助于排查"断言不生效"类问题。以 iOS 侧 expectTwo.js 为例,一次断言经历以下链路:
expect(element)工厂函数校验入参必须是Element实例,然后返回Expect对象;- 调用
.toBeVisible()等方法后,createInvocation()将断言组装为 JSON 结构:
{
type: 'expectation',
predicate: this.element.matcher.predicate, // 元素匹配器谓词
atIndex: this.element.index, // 可选:元素索引
modifiers: ['not'], // 可选:取反标记
expectation: 'toBeVisible', // 断言名
params: [35] // 可选:断言参数
}
_executeInvocation()通过traceInvocationCall包装后调用invocationManager.execute(invocation),将 invocation 通过 websocket 下发至设备端执行;- 测试运行期间,每个断言都会附带一条 trace description,用于失败时的调用栈裁剪与日志输出(参见 invocationTraceDescriptions.js)。
Android 侧实现路径类似但更贴近 Espresso:NativeExpect.js 的每个方法都会构造一个对应的原生匹配器(如 VisibleMatcher、ExistsMatcher、TextMatcher、ToggleMatcher、SliderPositionMatcher、FocusMatcher),再交给 MatcherAssertionInteraction 执行,_notCondition 控制取反语义。两个平台的断言命名与参数约定保持一致,因此同一套测试代码通常可跨平台复用。
仓库中还提供了 expectTwo.test.js 与 AndroidExpect.test.js 等单元测试,覆盖了断言 JSON 结构、参数校验、not 组合、waitFor 超时等关键行为,是深入理解 Expect API 行为的权威参考。
实战建议
- 优先用
by.id()定位:toHaveId/toExist/toBeVisible组合最稳定,避免依赖文本布局变化; - 可见性阈值按需调整:元素被遮挡、部分滚动出屏幕时,可降低
toBeVisible阈值(如35)来容忍局部可见; - 列表加载用
waitFor+withTimeout:懒加载列表断言先waitFor(...).toExist().withTimeout(5000),必要时配合whileElement(...).scroll(); - 迁移旧 API:在代码库中全局替换
toBeNotVisible、toNotExist、toBeNotFocused为not写法,避免触发弃用警告。