移动应用

移动端 UI 测试使用 Proxy Mail QA 的方式与 Web 测试相同：创建测试地址，在应用的注册界面输入它，然后等待邮件中的验证码或链接。这些页面上的辅助代码只是测试代码，不会进入你发布的应用。

每个辅助工具都用各自的语言做同样的事：

• 创建测试地址，附带用于表单的密码，按需提供出生日期、国家或环境。
• 等待验证码或链接，包括打开应用的链接，并跳过已用过的验证码。
• 检查邮件： 统计收到的邮件（恰好一封，而不是两封），检查邮件（SPF、DKIM、DMARC、本地或 http 链接、链接指向哪里），或检查没有收到邮件。
• 以已保存的账号登录，或在测试并行运行时借用一个其他测试未使用的账号。
• 在拉取请求上报告： 使用 GitHub Action，每次调用都会加入该任务的运行，并以其测试命名。

你的测试	指南
Maestro（原生 iOS 和 Android、React Native、Flutter）	Maestro
Xcode 中的 XCUITest（Swift）	iOS (XCUITest)
Android Studio 中的 Espresso 或 UI Automator（Kotlin）	Android (Espresso)
Flutter integration_test（Dart）	Flutter
Detox 或 Appium（JavaScript）	Detox 和 Appium
由编程智能体操作 iOS Simulator	用编程智能体测试 iOS 应用
由编程智能体操作 Android Emulator	用编程智能体测试 Android 应用

关于每个平台要检查的内容（冷启动链接、打开 Chrome 的 App Links、exp:// 链接、Firebase 邮件链接登录），请参阅 移动应用指南。

不要把 API 密钥 放进应用

每个指南都从测试运行中读取 API 密钥：环境变量、插桩参数或 --dart-define。把它存放在 CI 的密钥中。不要把它加入应用的配置或 Info.plist，否则任何拿到应用的人都能读取它。

--dart-define 会被编译进它所在的构建，所以 Flutter 测试构建会带有这个密钥。不要把该构建交给任何人，无论是通过 TestFlight、Firebase App Distribution 还是应用商店：要分享的构建请不带密钥单独构建。

在应用中打开验证链接或魔法链接

邮件中的链接通常是能打开应用的 https 链接：在 iOS 上是 Universal Link，在 Android 上是 App Link。请在设备上打开它，而不是在桌面浏览器中：

适用于	方法
XCUITest	XCUIApplication().open(url)
Espresso	使用 ACTION_VIEW intent 的 startActivity（见指南）
Maestro	- openLink: ${output.link}
Detox	device.openURL({ url })
Appium	driver.execute('mobile: deepLink', { url, package })（Android）或 { url, bundleId }（iOS）
手动，iOS 模拟器	xcrun simctl openurl booted '<link>'
手动，Android 模拟器	adb shell "am start -W -a android.intent.action.VIEW -d '<link>'"

使用应用自身 scheme 的链接（如 myapp://verify?token=… 或 Expo 的 exp://…/--/verify）也会被识别并以同样方式分类：等待链接时会返回它们。当一封邮件中同一用途既有 Web 链接又有应用链接时，Web 链接优先；用 app=true 获取应用链接（每个辅助工具都有 app 选项）。GET /v1/addresses/{address}/messages 会列出每封邮件中的所有链接。Proxy Mail QA 从不打开链接，应用和 Chrome 扩展只允许复制应用链接，收件箱中链接旁边附有模拟器命令。

分格输入的验证码

很多应用为验证码的每一位显示一个输入框。把完整验证码输入第一个框：大多数这类字段在每输入一位后会自动跳到下一个框。如果你的应用不会，就在每个框中输入一位。提交前，检查每个框都有数字：不完整的验证码算作一次错误尝试，很多应用在几次错误后会锁定账号。

检查邮件本身，而不只是验证码

收到验证码或链接后，也要检查邮件：带上应用链接打开的域名（它的 Universal Link 或 App Link 域名）调用 checkEmail，会返回未通过的检查项，countEmails 能发现误发的第二封邮件。每个指南都用各自的语言展示它们，REST API 说明了每项检查的含义。

针对你电脑上的服务器测试

iOS 模拟器通过 localhost 访问你的电脑。Android 模拟器不行：它通过 10.0.2.2 访问你的电脑。如果应用发送指向 localhost 的验证链接，这些链接在模拟器上打不开；请参阅 测试指向 localhost 的链接。

邮件检查会判定指向 localhost 或私有地址的链接不通过，因为真实用户无法打开它们。在针对自己电脑测试时，把它的主机（如 localhost:3000 或 10.0.2.2:3000）加入 Project settings 中项目的开发环境，或使用 POST /v1/project/dev-hosts 添加，指向它的链接就会通过。

短信

Proxy Mail QA 只处理邮件。通过 SMS 发送的验证码需要用其他工具。