IOS E2e Scaffold

ios-e2e-scaffold

Manual-invocation skill that bootstraps XCUITest infrastructure for iOS SwiftUI projects. Mirrors macos-e2e-scaffold's deterministic Read+Grep heuristic; differs only where iOS differs.

Phase 0 — Self-check

Before any other action, run three refuse-conditions. Any failure → return early with explicit message; no files modified.

iOS-discriminating signal — REQUIRED

WindowGroup is cross-platform (shared with macOS) and does NOT identify iOS on its own. Detect iOS via the FIRST that matches:

1. SPM: Package.swift contains .iOS( in a platforms: clause (and the target is an app, not a library).
2. xcodegen: project.yml/xcodegen.yml target has platform: iOS.
3. plain .xcodeproj: project.pbxproj contains SDKROOT = iphoneos or SUPPORTED_PLATFORMS = "?iphoneos for the app target's build config.
4. Corroborating (necessary-not-sufficient): grep -rl 'import UIKit' --include='*.swift' present AND macOS-only scenes absent (MenuBarExtra(, Settings {, Window().

Multiplatform targets (.iOS( AND .macOS( in Package.swift, or SUPPORTED_PLATFORMS lists both iphoneos and macosx): Phase 0 passes (iOS is among the platforms) and emits a note — "Multiplatform target detected; scaffolding iOS-Simulator tests. Run /macos-e2e-scaffold separately for the macOS surface." Treat iphoneos/.iOS( presence as sufficient; do not refuse just because macOS is also supported. Set TARGET_DIR = <App>iOSUITests (see below) so the iOS and macOS UI-test targets coexist — /macos-e2e-scaffold uses <App>macOSUITests in the same situation, each scaffold's "already scaffolded" glob ignores the sibling's suffixed directory, and without the suffix the two would collide on the same directory and the same xcodegen.yml/project.pbxproj target.

TARGET_DIR convention

Set once in Phase 0 and used everywhere below (Step 10 file naming, the xcodegen/Xcode UI-test target name, and the runner's -only-testing: argument):

• Single-platform iOS target → TARGET_DIR = <App>UITests
• Multiplatform target → TARGET_DIR = <App>iOSUITests

Always emit Phase 0 result on success:

## /ios-e2e-scaffold Phase 0
✅ Swift project detected (<project>.xcodeproj | Package.swift)
✅ iOS SwiftUI app (iOS signal: <SDKROOT=iphoneos | .iOS( | platform: iOS>; scene <Type> in <File.swift>:<line>)
✅ No existing UI test target

Project type: <xcodegen-managed | SPM-based | plain .xcodeproj>
Scheme: <SchemeName>
Source root: <path>
Total .swift files in source root: <N>
[Multiplatform note, if applicable — TARGET_DIR = <App>iOSUITests]

Proceeding with audit + scaffold.

What this skill does

1. Audits the project: walks the SwiftUI Scene tree, ranks views by interactive-control density, identifies top 5.
2. Suggests accessibility identifiers for each control in top 5 views; applies them after user batch-confirmation.
3. Generates ranked TIER-1/2/3 test stubs with XCTFail("not implemented") placeholders, an identifier-convention doc, and a Claude-readable xcresult runner script targeting the iOS Simulator.

What this skill is NOT

• Not a review skill. Does not analyse spec/plan/PRD artefacts. Use /pitfall-verification (will-it-work?), /quality-review (will-it-feel-premium?), or /ios-native-review (is-it-iOS-native?) for those.
• Not a code-quality reviewer. Does not check view-code idioms (use Antoine van der Lee's swiftui-expert-skill) or unit-test idioms (use swift-testing-expert).
• Not macOS-aware. Use /macos-e2e-scaffold.
• Not AppKit/UIKit-aware. SwiftUI only. For AppKit use /appkit-e2e-scaffold (deferred).
• Not snapshot-aware. Use /swiftui-snapshot-scaffold (deferred).
• Not auto-invoked. Manual /ios-e2e-scaffold only — same model as setup-routing. Normally reached via /e2e-route.

Heuristic process (deterministic, Read+Grep based)

Step 1: Detect project type

1. If xcodegen.yml or project.yml exists → xcodegen-managed
2. Else if Package.swift contains .executableTarget(name: → SPM-based
3. Else if *.xcodeproj exists → plain .xcodeproj

Step 2: Detect scheme name

• xcodegen: read name: field at root of xcodegen.yml/project.yml
• SPM: read name: from Package(name: ...)
• plain .xcodeproj: parse *.xcodeproj/xcshareddata/xcschemes/*.xcscheme filenames; fallback to project directory name

Step 3: Find source root

• xcodegen: read targets.<schemename>.sources.path from yml
• SPM: Sources/<TargetName>/
• plain .xcodeproj: parse project.pbxproj for main app target's source group path = ; fallback to <schemename>/

Step 4: Walk Scene tree

1. Grep source root for iOS root patterns:

   grep -rn -E 'WindowGroup|TabView\s*[({]|NavigationStack|NavigationSplitView' --include='*.swift'
   

2. For each Scene file, grep its body for iOS destination patterns: NavigationLink(destination:, NavigationLink(, .navigationDestination(, .sheet(isPresented:, .sheet(item:, .fullScreenCover(isPresented:, .fullScreenCover(item:, .popover(
3. Recursively follow destinations to build view-graph (max depth: 5; cycle detection via view-name set)
4. For each view in graph, count interactive controls using word-boundary patterns:
   • \bButton\b\s*[({]
   • \bToggle\b\s*\(
   • \bTextField\b\s*\(
   • \bPicker\b\s*\(
   • \bNavigationLink\b\s*\(
   • \bStepper\b\s*\(
   • \bSlider\b\s*\(
   • \bDatePicker\b\s*\(
   • \bMenu\b\s*[({]

Step 5: Rank views

Sort views by (reference_count + interactive_control_count) descending. Tie-breaker: alphabetical by source-file name, then by line number. Top 5 receive identifier suggestions.

Step 6: Detect TIER mappings

• TIER-1 #1 (Smoke): always (app launches, root scene appears).
• TIER-1 #2 (Happy-path): pick top-ranked view's primary button. Heuristic: Button containing await OR action calling a method named generate*/create*/save*/run*/start*. Fallback if no Button matches: pick the first Button in the top-ranked view (by line number); mark the generated stub with comment // HEURISTIC: generic fallback — no save/create/await action matched. Verify this is the right primary action.
• TIER-1 #3 (Error-recovery): pick first view (alphabetical by source-file name, then by line number — deterministic) containing .alert(, errorMessage, failure, or error: Error
• TIER-2 (Modal): only if .sheet(isPresented:, .sheet(item:, .fullScreenCover(, or .popover( found in walked tree → ModalAndSheetTests.swift
• TIER-2 (Tab-navigation): only if TabView found → TabNavigationTests.swift (assert tab switch changes selected content)
• TIER-3 (Push-navigation): only if (NavigationStack OR NavigationSplitView) present AND (any NavigationLink( OR .navigationDestination( present) → PushNavigationTests.swift (list → detail push/pop). NOTE: a single NavigationLink(value:) + .navigationDestination( is the modern master-detail idiom — do NOT require two links, or you miss the primary drill-down flow.
• TIER-3 (Gestures/rotation): only if .swipeActions(, .refreshable, or orientation usage (.onRotate, UIDevice.*orientation, @Environment(\.verticalSizeClass)) found → GestureAndRotationTests.swift

Step 7: Generate identifier suggestions

For each control in top 5 views:

• Skip controls that already have .accessibilityIdentifier(...) set — scan from the control declaration to the end of its modifier chain (balance braces/parens from the control's opening; cap at 25 lines as a safety bound). A 5-line window is too shallow: a Button with a long trailing action: closure can carry its .accessibilityIdentifier(...) 15+ lines down, and missing it makes the skill inject a second, different ID → an "Ambiguous Match" XCUITest failure at runtime. Already-identified controls are listed under "Already identified (preserved)" but not re-suggested.
• Skip controls inside #Preview { ... } blocks or PreviewProvider (static var previews:) conformances — track brace-depth from #Preview or static var previews declarations; exclude when depth > 0.
• Construct ID as <ViewName>_<ControlType>_<Purpose>
• Purpose extracted from button label, action method name, or property name (in priority order)
• snake_case all parts; _ separator
• Examples: PlanListView_Button_GeneratePlan, SettingsView_Toggle_EnableTelemetry, ChatView_TextField_PromptInput

Step 8: Emit suggestions table for user confirmation

Present batch table in markdown:

| File:line | Current code | Suggested identifier |
|---|---|---|
| PlanListView.swift:34 | Button("Generate") { ... } | PlanListView_Button_GeneratePlan |
| ... | ... | ... |

Ask: "Apply all N suggestions? [a]ll / [c]herry-pick / [s]kip"

If [c]herry-pick: follow up with one question per suggestion: "Apply suggestion k of N? [y/n]". Accumulate accepted set; apply only that subset in Step 9.

If [s]kip: skip Step 9 entirely; test files in Step 10 still generated, with placeholder identifier comments showing what user must fill in manually.

Step 9: Apply identifiers

Use Edit tool, one identifier per Edit call. On uniqueness conflict (same ID would land on two distinct controls): skip both; flag for manual review in report.

Step 10: Generate test files

Per TIER, write one .swift file with XCTFail("not implemented — fyll inn assertion") placeholder + TODO-comment pointing to source-file:line + suggested assertions in comments.

File naming (all paths use the Phase 0 TARGET_DIR — <App>UITests single-platform, <App>iOSUITests multiplatform):

• <TARGET_DIR>/SmokeTest.swift (TIER-1 #1)
• <TARGET_DIR>/HappyPathTests.swift (TIER-1 #2)
• <TARGET_DIR>/ErrorRecoveryTests.swift (TIER-1 #3)
• <TARGET_DIR>/ModalAndSheetTests.swift (TIER-2 modal, if any)
• <TARGET_DIR>/TabNavigationTests.swift (TIER-2 tab, if any)
• <TARGET_DIR>/PushNavigationTests.swift (TIER-3 push, if any)
• <TARGET_DIR>/GestureAndRotationTests.swift (TIER-3 gesture/rotation, if any)

Step 11: Generate runner script

Write scripts/run-uitests.sh per template in §Runner-script-template (substitute <APP> with detected scheme name and <TARGET_DIR> with the Phase 0 TARGET_DIR). Make executable: chmod +x scripts/run-uitests.sh.

Step 12: Generate identifier convention doc

Write docs/accessibility-identifiers.md with the convention, examples, rationale, and a table listing all applied identifiers with their source-file:line.

Step 13: Emit final report

Per Output-format section below.

TIER rubric

TIER-1 is non-negotiable. Even on a project where heuristics return weak matches, three test files appear. Smoke validates app launches. Happy-path and Error-recovery may need user-tuning but provide a starting structure.

TIER-2 and TIER-3 conditional. Skipped silently if pattern not detected. Report says e.g. "TIER-2 tab-navigation: not generated (no TabView found)".

Identifier convention

Format: <ViewName>_<ControlType>_<Purpose>

• snake_case all parts
• _ separator (consistent grep-by-view: PlanListView_ matches all PlanListView-controls)
• Stable across label-text changes (refactor-safe)

Examples:

• PlanListView_Button_GeneratePlan
• SettingsView_Toggle_EnableTelemetry
• ChatView_TextField_PromptInput
• DetailView_NavigationLink_OpenSettings

Identical to the macos-e2e-scaffold convention, so /e2e-route can point at one consistent convention for both platforms.

Convention doc: docs/accessibility-identifiers.md (auto-generated by skill, includes table of all applied identifiers + rationale).

Output format

After Phase 0 emission and identifier-application, the final report (single message at end of skill execution):

## /ios-e2e-scaffold report — <ProjectName>

### Phase 0
✅ Swift project (<project-type>)
✅ iOS SwiftUI app (<N> Scenes detected, iOS signal: <signal>)
✅ No existing UI test target

### Project context
- Scheme: <SchemeName>
- Source root: <path>
- Top 5 views by control density: <View1>, <View2>, <View3>, <View4>, <View5>

### Identifier suggestions (<N> total)
✅ Applied (<N>): <Id1>, <Id2>, ...
⏭️  Skipped on uniqueness conflict (<M>): <Id-X> (collides with <Id-Y> — review manually)
ℹ️  Already identified (preserved <K>): <Id-existing-1>, ...
🚫 Excluded from Preview blocks (<L>)

### Test stubs generated (<S>)
**TIER-1 (3 — must implement)**
- `SmokeTest.swift` :: testTIER1_AppLaunches
- `HappyPathTests.swift` :: testTIER1_<HappyPathName>
- `ErrorRecoveryTests.swift` :: testTIER1_<ErrorPathName>

**TIER-2 (<n> — should implement if applicable)**
- `ModalAndSheetTests.swift` :: testTIER2_<...> (if `.sheet`/`.fullScreenCover`/`.popover` detected)
- `TabNavigationTests.swift` :: testTIER2_<...> (if `TabView` detected)

**TIER-3 (<n> — patterns not detected | generated)**
- Push-navigation: <generated | not generated (no NavigationStack / <2 NavigationLink)>
- Gestures/rotation: <generated | not generated (no swipe/refresh/orientation usage)>

### Runner script
- `scripts/run-uitests.sh` — `xcodebuild test -only-testing:<TARGET_DIR>` against `platform=iOS Simulator`, parses xcresult to Claude-readable JSON (Xcode 16+ format; falls back to plaintext on older Xcode)

### Convention doc
- `docs/accessibility-identifiers.md` — `<ViewName>_<ControlType>_<Purpose>`, snake_case, examples, full identifier table

### Project-type integration
<branch-specific instructions per Project-type-specific-behavior section>

### Next steps
1. <project-type-specific build step>
2. `./scripts/run-uitests.sh` — all <S> TIER stubs will fail with `XCTFail("not implemented")`. That's expected — fill in assertions per stub.
3. Re-invoke /ios-e2e-scaffold if you add new top-level views or controls. Skill detects existing UI test target and refuses overwrite (extend manually).

Project-type-specific behavior

xcodegen-managed

Modify xcodegen.yml (or project.yml) to add new target:

targets:
  <TARGET_DIR>:
    type: bundle.ui-testing
    platform: iOS
    sources:
      - <TARGET_DIR>
    dependencies:
      - target: <App>

Skill writes the diff. User runs xcodegen generate to regenerate .xcodeproj. Report says: "Run xcodegen generate before opening Xcode."

SPM-based

SwiftPM does NOT support UI Test bundles natively (only .testTarget for unit tests). UI Tests require .xcodeproj.

Skill detects this case:

• Generate test files in Tests/<TARGET_DIR>/ directory
• Print warning: "SPM doesn't support UI Test bundles. Generated files exist but require .xcodeproj. Recommend: switch to xcodegen-managed project, or add .xcodeproj manually."
• Refuse to attempt project-modification

This is an honest limitation, not a skill failure. (Note: SPM-only is still a valid input — the skill proceeds and generates files; it does not refuse in Phase 0.)

Runner for SPM-only: do NOT emit the normal Step 11 runner — without an .xcodeproj there is no scheme, so xcodebuild test -scheme "$SCHEME" fails at scheme resolution, not at test execution. Instead write a stub scripts/run-uitests.sh that is honest about the precondition:

#!/usr/bin/env bash
# Auto-generated by /ios-e2e-scaffold (SPM-only project).
echo "SPM-only project: no .xcodeproj → no scheme for 'xcodebuild test'." >&2
echo "Convert to an xcodegen-managed project or add an .xcodeproj, then re-run /ios-e2e-scaffold." >&2
exit 1

So a CI consumer that follows /e2e-route's "Next action: ./scripts/run-uitests.sh" fails fast with a clear reason instead of an opaque scheme-resolution error.

plain .xcodeproj (no xcodegen)

Skill cannot reliably modify project.pbxproj programmatically (one wrong line corrupts the project).

• Generate files in <TARGET_DIR>/ directory
• Emit step-by-step manual instructions:

  1. Open <App>.xcodeproj in Xcode
  2. File > New > Target > iOS > UI Testing Bundle
  3. Name: <TARGET_DIR>  ← MUST equal the Phase 0 TARGET_DIR EXACTLY. The generated
     scripts/run-uitests.sh hardcodes `-only-testing:"${UITEST_TARGET}"` with this
     name baked in; if you accept a different Xcode-suggested name the runner
     reports "no tests / target not found". (Alternatively, edit the runner to read
     the real target from `xcodebuild -list -json`.)
  4. Drag generated .swift files into target
  5. Set Target to be Tested: <App>
  6. Build target once to verify
  

• Report says: "Generated files exist; manual Xcode steps required for target setup. Name the UI-test target exactly <TARGET_DIR> to match the runner."

Failure modes

Skill never silently corrupts project files. All modifications confirmed; uniqueness conflicts skip; .xcodeproj is never directly edited.

Relationship to other skills

ios-e2e-scaffold creates test infrastructure rather than reviewing artefacts. This warrants the manual-only invocation pattern (no auto-trigger) — skill should run with full user awareness, not as a pipeline step. It is normally reached via /e2e-route.

Runner script template

scripts/run-uitests.sh:

#!/usr/bin/env bash
# Auto-generated by /ios-e2e-scaffold v1.0.0
# Runs iOS UI tests and emits Claude-readable JSON summary.
# Requires Xcode 16+ for JSON xcresulttool format; falls back to plaintext on older.
# Exit codes: 0 = tests passed, 2 = setup error (no simulator runtime), any other
# non-zero = a failed test run. That status is xcodebuild's own, passed through
# unchanged, so it is typically 65 — NOT 1. Check `-ne 0`, never `-eq 1`.

set -uo pipefail

SCHEME="<APP>"
UITEST_TARGET="<TARGET_DIR>"   # <App>UITests, or <App>iOSUITests on multiplatform
RESULT_BUNDLE="$(mktemp -d)/uitests.xcresult"

# Pick a simulator by UDID. Never hardcode a model name: Xcode ships a rolling set
# and drops old ones, and a stale name fails as "Unable to find a device matching
# the provided destination specifier" — which reads as a broken project rather than
# a dead device name. Targeting by id= is also exact, so it cannot match "iPhone 15
# Pro" when you meant "iPhone 15", and it does not miss "iPhone SE".
UDID="$(xcrun simctl list devices available | grep 'iPhone' | grep -oiE '[0-9A-F]{8}-([0-9A-F]{4}-){3}[0-9A-F]{12}' | head -1)"
if [ -z "$UDID" ]; then
  echo "No iPhone simulator available. Install a runtime: Xcode > Settings > Components." >&2
  exit 2
fi
DEST="platform=iOS Simulator,id=${UDID}"
echo "(using iPhone simulator ${UDID})"

# Run the tests. Capture xcodebuild's OWN exit status via PIPESTATUS — piping into
# `tail` would otherwise mask a non-zero status (tail returns 0), making a failing
# committed-regression run look green in CI.
xcodebuild test \
  -scheme "$SCHEME" \
  -destination "$DEST" \
  -only-testing:"${UITEST_TARGET}" \
  -resultBundlePath "$RESULT_BUNDLE" \
  -quiet 2>&1 | tail -50
TEST_STATUS=${PIPESTATUS[0]}

# Parse xcresult to JSON summary (Xcode 16+); fall back to plaintext on older Xcode.
xcrun xcresulttool get test-results summary --path "$RESULT_BUNDLE" --format json 2>/dev/null \
  | jq '{total: .totalTestCount, passed: .passedTests, failed: .failedTests, results: [((.testFailures // [])[]) | {test: .testIdentifier, file: .sourceCodeContext.location.filePath, line: .sourceCodeContext.location.lineNumber, message: .failureText}]}' 2>/dev/null \
  || { echo "(Xcode 16+ JSON format unavailable — falling back to plaintext)"; \
       xcrun xcresulttool get --path "$RESULT_BUNDLE" 2>/dev/null | tail -100 || true; }
# NOTE: `.testFailures` is null/absent on an all-green run; `(.testFailures // [])`
# guards `null | .[]` so passing runs still emit clean JSON instead of falling back.

# Exit with the REAL test status so CI / committed-regression runs fail when tests fail.
# Deliberately NOT normalised to 1: xcodebuild's own code distinguishes a test failure
# (65) from a build failure (also non-zero, different code), and flattening them would
# throw that away. Callers must test for non-zero.
exit "$TEST_STATUS"