qa-testing-ios

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

QA Testing (iOS)

iOS QA测试

Use

xcodebuild

+ Xcode Simulator (

simctl

) to build, run, and stabilize iOS tests.

Primary docs: XCTest, Swift Testing, simctl, Xcode testing

使用

xcodebuild

+ Xcode Simulator (

simctl

) 来构建、运行并稳定iOS测试。

主要文档：XCTest、Swift Testing、simctl、Xcode测试

Inputs to Confirm

需要确认的输入项

Xcode entrypoint:
```
-workspace
```
or
```
-project
```
```
-scheme
```
(and optional
```
-testPlan
```
)
Destination(s): simulator name + iOS runtime (or
```
OS=latest
```
), and whether real devices are required
UI-test hooks: launch arguments/env toggles (stubs, demo data, auth bypass, disable animations)
Artifact needs:
```
xcresult
```
, coverage, screenshots/video, logs

Xcode入口：
```
-workspace
```
或
```
-project
```
```
-scheme
```
（可选
```
-testPlan
```
）
测试目标：模拟器名称 + iOS运行时（或
```
OS=latest
```
），以及是否需要真机
UI测试钩子：启动参数/环境变量开关（桩数据、演示数据、跳过认证、禁用动画）
产物需求：
```
xcresult
```
、测试覆盖率、截图/录屏、日志

Quick Commands

快速命令

Task	Command
List schemes	`xcodebuild -list -workspace MyApp.xcworkspace`
List simulators	`xcrun simctl list devices`
List devices (USB)	`xcrun xctrace list devices`
Boot simulator	`xcrun simctl boot "iPhone 15 Pro"`
Wait for boot	`xcrun simctl bootstatus booted -b`
Build app	`xcodebuild build -scheme MyApp -sdk iphonesimulator`
Install app	`xcrun simctl install booted app.app`
Run tests	`xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15 Pro,OS=latest' -resultBundlePath TestResults.xcresult`
Run tests (device)	`xcodebuild test -scheme MyApp -destination 'platform=iOS,id=<UDID>' -resultBundlePath TestResults.xcresult`
Reset simulators	`xcrun simctl shutdown all && xcrun simctl erase all`
Take screenshot	`xcrun simctl io booted screenshot screenshot.png`
Record video	`xcrun simctl io booted recordVideo recording.mov`

任务	命令
列出Scheme	`xcodebuild -list -workspace MyApp.xcworkspace`
列出模拟器	`xcrun simctl list devices`
列出USB连接设备	`xcrun xctrace list devices`
启动模拟器	`xcrun simctl boot "iPhone 15 Pro"`
等待模拟器启动完成	`xcrun simctl bootstatus booted -b`
构建应用	`xcodebuild build -scheme MyApp -sdk iphonesimulator`
安装应用	`xcrun simctl install booted app.app`
运行测试	`xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15 Pro,OS=latest' -resultBundlePath TestResults.xcresult`
在真机上运行测试	`xcodebuild test -scheme MyApp -destination 'platform=iOS,id=<UDID>' -resultBundlePath TestResults.xcresult`
重置模拟器	`xcrun simctl shutdown all && xcrun simctl erase all`
截图	`xcrun simctl io booted screenshot screenshot.png`
录屏	`xcrun simctl io booted recordVideo recording.mov`

Workflow

工作流程

Resolve build inputs (
```
workspace/project
```
,
```
scheme
```
,
```
testPlan
```
, destinations).
Make simulator state repeatable: shutdown/erase as needed, boot, and wait for boot.
Run tests with artifacts enabled (
```
-resultBundlePath
```
); parallelize and retry only when appropriate.
Triage failures from the
```
xcresult
```
bundle; confirm flakes with repetition; quarantine with an owner and reproduction steps.

确定构建输入项（
```
workspace/project
```
、
```
scheme
```
、
```
testPlan
```
、测试目标）。
确保模拟器状态可重复：按需关闭/重置模拟器，启动并等待启动完成。
启用产物输出（
```
-resultBundlePath
```
）运行测试；仅在合适时启用并行测试和重试。
从
```
xcresult
```
包中排查失败用例；通过重复执行确认是否为不稳定测试；标记问题并分配责任人，同时附上复现步骤。

xcodebuild Patterns

Xcodebuild使用模式

Select tests to reproduce:

-only-testing:TargetTests/ClassName/testMethod

and

-skip-testing:TargetTests/FlakyClass

Prefer test plans for large suites:
```
-testPlan <plan>
```
(keeps device/config/runs consistent).

Enable parallel testing when suites are isolation-safe:

-parallel-testing-enabled YES

-maximum-parallel-testing-workers N

Always write a result bundle in automation:
```
-resultBundlePath TestResults.xcresult
```
.

For reruns, split build and test:

xcodebuild build-for-testing ...

then

xcodebuild test-without-building ...

Inspect results locally:

open TestResults.xcresult

xcrun xcresulttool get --path TestResults.xcresult --format json

选择特定测试进行复现：

-only-testing:TargetTests/ClassName/testMethod

和

-skip-testing:TargetTests/FlakyClass

。

大型测试套件优先使用测试计划：
```
-testPlan <plan>
```
（确保设备/配置/执行保持一致）。

当测试套件支持隔离时，启用并行测试：

-parallel-testing-enabled YES

（+

-maximum-parallel-testing-workers N

）。

自动化测试中始终生成结果包：
```
-resultBundlePath TestResults.xcresult
```
。

重跑测试时，拆分构建和测试步骤：

xcodebuild build-for-testing ...

然后

xcodebuild test-without-building ...

。

本地查看测试结果：

open TestResults.xcresult

或

xcrun xcresulttool get --path TestResults.xcresult --format json

。

Flake Triage (Repetition and Retry)

不稳定测试排查（重复执行与重试）

Prefer repetition to prove flake rate before adding retries.
Use targeted reruns before suite-wide retries.

Common patterns (flags vary by Xcode version):

Retry failing tests once in CI:

-retry-tests-on-failure -test-iterations 2

Measure flakiness until first failure:

-test-iterations 50 -test-repetition-mode until-failure

Run a single test repeatedly:

-only-testing:TargetTests/ClassName/testMethod -test-iterations 20

在添加重试逻辑前，优先通过重复执行确认不稳定率。
优先针对特定测试重跑，而非全套件重试。

常见配置（参数随Xcode版本变化）：

CI中失败测试重试一次：

-retry-tests-on-failure -test-iterations 2

重复执行直到首次失败以测量不稳定率：

-test-iterations 50 -test-repetition-mode until-failure

重复执行单个测试：

-only-testing:TargetTests/ClassName/testMethod -test-iterations 20

Testing Layers

测试层级

Layer	Framework	Scope
Unit	XCTest / Swift Testing	Business logic (fast)
Snapshot	XCTest + snapshot libs	View rendering
Integration	XCTest	Persistence, networking
UI	XCUITest	Critical user journeys

测试层级	框架	测试范围
单元测试	XCTest / Swift Testing	业务逻辑（执行快速）
快照测试	XCTest + 快照库	视图渲染效果
集成测试	XCTest	持久化、网络交互
UI测试	XCUITest	核心用户流程

Device Matrix

设备矩阵策略

Default: simulators for PR gates; real devices for release
Cover: one small phone, one large phone, iPad if supported
Add OS versions only for multiple major release support

默认：PR校验使用模拟器；发布阶段使用真机
覆盖范围：一台小屏手机、一台大屏手机，若支持则包含iPad
仅在需要支持多个主要版本时，添加对应OS版本测试

Flake Control

不稳定测试控制

Use these defaults unless the project requires otherwise:

Disable or reduce animations in UI-test builds.
Fix locale/timezone (via launch arguments or app-level configuration).
Stub network at the boundary (avoid real third-party calls in UI tests).
Reset app state between tests (fresh install, deep-link reset, or explicit teardown).
Prefer state-based waits (
```
waitForExistence
```
, expectations) over sleeps.
Pre-grant/reset permissions where possible (simulators):
```
xcrun simctl privacy booted grant ...
```
.

除非项目有特殊需求，否则默认遵循以下规则：

在UI测试构建中禁用或减少动画。
固定区域设置/时区（通过启动参数或应用级配置）。
在边界层Stub网络请求（UI测试中避免真实第三方调用）。
测试间重置应用状态（重新安装、通过Deep Link重置，或显式清理）。
优先使用基于状态的等待（
```
waitForExistence
```
、预期断言）而非休眠。
尽可能提前授予/重置权限（模拟器）：
```
xcrun simctl privacy booted grant ...
```
。

CI Integration (GitHub Actions)

CI集成（GitHub Actions）

yaml

name: iOS CI
on: [push, pull_request]
jobs:
  test:
    runs-on: macos-15
    steps:
      - uses: actions/checkout@v4
      - uses: maxim-lobanov/setup-xcode@v1
        with:
          xcode-version: "16.0"
      - run: |
          set -euo pipefail
          xcodebuild test \
            -scheme MyApp \
            -sdk iphonesimulator \
            -destination 'platform=iOS Simulator,name=iPhone 15 Pro,OS=latest' \
            -resultBundlePath TestResults.xcresult
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: test-results
          path: TestResults.xcresult