Building a Claude-Assisted iOS UI Testing Workflow

Use Claude as the authoring layer

The workflow begins with a compact input contract: the business state, visible requirement, permitted synthetic fields, forbidden content, safety stop, and evidence type. Claude uses that contract to draft a scenario matrix, propose fixture variants, identify gaps in the preconditions, and organize an expected-versus-observed report skeleton. This creates a consistent starting point without coupling the test design to a private application repository.

I review the generated structure as test code even when it is written in Markdown. The product contract supplies the expected behavior; QA confirms the oracle, negative conditions, and boundaries; ordinary execution tools interact with the simulator or device. OCR and accessibility data can support text checks, while visual properties and consequential flows retain dedicated review. Claude accelerates synthesis and consistency, but the workflow keeps approval and the final verdict explicit.

• Input: business state, observable requirement, safety boundary, and required evidence.
• Claude: draft scenario matrix, synthetic variants, missing-question list, and report structure.
• QA review: validate the contract, expected behavior, test oracle, and publishable scope.
• Execution: use simulator interaction, accessibility or OCR checks, screenshots, and focused UI automation.

Start from behavior, not production artifacts

Rare mobile states are expensive regression candidates because the UI may be simple while the precondition is difficult to reproduce. An overdue installment, unavailable limit, empty result, or blocked state can depend on several services and a precisely configured account. When preparation dominates execution, the suite needs a controllable state boundary.

The design starts from observable behavior and creates a purpose-built representation. Small synthetic JSON fixtures model representative states, a Markdown scenario defines expected observations, and a sample report keeps the result reviewable. Each artifact contains only the structure needed for the scenario.

• Represent each business state with the smallest deterministic fixture that preserves its behavior.
• Keep state setup independent from navigation and UI assertions.
• Define supported states, evidence types, and extension points in the README.

Make business state the first-class input

A long UI script can hide its real dependency. It may spend most of its steps navigating and waiting for an account to reach a condition that the test does not control. The project reverses that order: choose the business state, load the corresponding synthetic fixture, then describe the visible checks. Comparing AVAILABLE and OVERDUE for the same screen makes the intended difference explicit, reviewable, and ready for automation.

This separation keeps automation maintainable. The runner owns launch, proxy, or mock configuration; the scenario owns user-visible expectations; the fixture owns the deterministic response. A change in one layer does not require rewriting every other layer. Reviewers can validate the fixture against the supported contract instead of treating test data as opaque setup.

Separate text, visual, and interaction evidence

The scenario distinguishes checks that can be automated from observations that still require a different oracle. OCR or accessibility text can support assertions about a label in a defined region. It cannot prove spacing, icon shape, color contrast, animation, or enabled state. A screenshot is valuable evidence, but attaching an image is not the same as comparing it against an approved visual baseline.

The sample report therefore keeps expected and observed behavior separate and allows a qualified result when visual review remains open. This avoids an easy credibility failure: calling a run fully passed when only some of its assertions were executed. Later, stable regions could receive image comparison while subjective or frequently changing surfaces remain manual.

• Text layer: accessibility values or scoped recognition with an explicit confidence rule.
• Visual layer: stable screenshot regions and reviewed baselines where comparison is reliable.
• Interaction layer: element state and user actions through XCTest/XCUIAutomation in a demo app.

Protect scenarios and fixtures with CI

GitHub Actions validates JSON syntax, local Markdown links, and the expected semantics of the two synthetic fixture states. This keeps AI-assisted artifacts consistent before they are consumed by a separate iOS execution layer.

The execution layer extends that model with a demo target, simulator configuration, accessibility identifiers, launch arguments, screenshots, and XCUIAutomation assertions. Keeping artifact validation separate from device execution makes failures easier to classify and preserves a fast quality gate for scenario changes.

python scripts/validate_repository.py
python -m unittest discover -s tests -v

Extend the model into XCUIAutomation

The model extends naturally into a small demo application built around the same synthetic states. Stable accessibility identifiers give XCUIAutomation durable selectors, while launch configuration selects the fixture without relying on a live backend. Tests can attach screenshots on failure and preserve the expected-versus-observed report structure already documented.

The design separates business state, evidence, and execution. That foundation supports reliable CI checks today and a focused XCUIAutomation layer as the next increment.