QA Testing (iOS) Skill | Agent Skills

QA Testing (iOS)

Use xcodebuild + Xcode Simulator (simctl) to build, run, and stabilize iOS tests.

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

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

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 |

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.

xcodebuild Patterns

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 or 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

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 |

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

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 ....

CI Integration (GitHub Actions)

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

Do / Avoid

Do

Make UI tests independent and idempotent
Use test data builders and dedicated test accounts
Collect xcresult bundles on failure
Use accessibilityIdentifier, not labels

Avoid

Relying on test ordering or global state
UI tests requiring real network
Thread.sleep() for synchronization
Accepting AI-proposed selectors without validation

Resources

| Resource | Purpose | |----------|---------| | references/swift-testing.md | Swift Testing framework | | references/simulator-commands.md | Complete simctl reference | | references/xctest-patterns.md | XCTest/XCUITest patterns | | references/xcuitest-patterns.md | XCUITest UI testing patterns | | references/snapshot-testing-ios.md | Visual snapshot testing | | references/ios-ci-optimization.md | CI pipeline optimization |

Templates

| Template | Purpose | |----------|---------| | assets/template-ios-ui-test-stability-checklist.md | Stability checklist |

Related Skills

| Skill | Purpose | |-------|---------| | software-mobile | iOS development | | qa-testing-strategy | Test strategy | | qa-testing-mobile | Cross-platform mobile |

Fact-Checking

Use web search/web fetch to verify current external facts, versions, pricing, deadlines, regulations, or platform behavior before final answers.
Prefer primary sources; report source links and dates for volatile information.
If web access is unavailable, state the limitation and mark guidance as unverified.

Agent Skills: QA Testing (iOS)

Install this agent skill to your local

Skill Files