iOS Workflow

Activated automatically when the Platform Detection Engine identifies an iOS/Swift project. Never activate this manually in non-iOS projects.

Phase 1: Toolchain verification

When iOS is detected, check and report tool availability:

🍎 iOS project detected. Checking toolchain...

✅ swift        — found (Swift 6.0.3)
✅ xcodebuild   — found (Xcode 16.2)
✅ swiftlint    — found (0.57.0)
✅ XcodeBuildMCP — found (~/.claude/skills/xcodebuildmcp/SKILL.md)
⚠️ xcbeautify  — not found (optional: brew install xcbeautify)

iOS toolchain ready.

Checks to perform:

• swift --version

  → report Swift version

• xcodebuild -version

  → report Xcode version

• command -v swiftlint && swiftlint version

  → report version or "not found"

• ls ~/.claude/skills/xcodebuildmcp/SKILL.md 2>/dev/null

  → XcodeBuildMCP presence

• command -v xcbeautify

  → optional, just report

None of these checks are blockers — missing tools generate warnings, not errors.

Phase 2: Test Framework Detection

Determine whether the project uses Swift Testing or XCTest:

# Count test files using each framework
swift_testing_count=$(grep -r "import Testing" . --include="*.swift" -l 2>/dev/null | wc -l)
xctest_count=$(grep -r "import XCTest" . --include="*.swift" -l 2>/dev/null | wc -l)

• swift_testing_count > 0

  AND

  xctest_count == 0

  → use Swift Testing

• xctest_count > 0

  AND

  swift_testing_count == 0

  → use XCTest (legacy)
• Both present → use Swift Testing for new tests, keep existing XCTest tests
• None found → default to Swift Testing (modern standard)

Report to user:

🧪 Test framework: Swift Testing (@Test, @Suite, #expect)

or:

🧪 Test framework: XCTest (existing project uses XCTest — maintaining consistency)

Phase 3: iOS Test Pipeline

Execute in this exact order:

Step 1 — Unit tests (swift test or xcodebuild)

# Option A: Swift Package Manager project
swift test --parallel

# Option B: Xcode project/workspace (if .xcodeproj/.xcworkspace found)
xcodebuild test \
  -scheme {detected_scheme} \
  -destination 'platform=iOS Simulator,name=iPhone 16' \
  -resultBundlePath .claude/feature-state/{slug}/test-results.xcresult \
  | xcbeautify 2>/dev/null || cat

Detect which to use: if

Package.swift

exists without

.xcodeproj

→ use

swift test

.

Step 2 — SwiftLint (files modified by this feature only)

Run SwiftLint only on modified files — not the whole project:

# Get files modified since the feature branch started
modified_files=$(git diff --name-only HEAD~1 -- "*.swift" 2>/dev/null)

# Run swiftlint on those files only (if swiftlint is available)
if command -v swiftlint > /dev/null 2>&1 && [ -n "$modified_files" ]; then
  swiftlint lint $modified_files --reporter json > .claude/feature-state/{slug}/swiftlint.json
  swiftlint lint $modified_files  # human-readable output
fi

If swiftlint not found: skip with

⚠️ swiftlint not found — skipping lint

.

Step 3 — XcodeBuildMCP build + simulator (optional, non-blocking)

Only if

capabilities.xcodebuildmcp_available == true

in platform-context.json:

1. /xcodebuildmcp discover_projs
   → find .xcodeproj or .xcworkspace

2. /xcodebuildmcp session_set_defaults
   → configure scheme, destination, configuration

3. /xcodebuildmcp build_run_sim
   → build + launch on iOS Simulator
   → capture build output and simulator status

Result reporting:

✅ App running on iPhone 16 Simulator (iOS 18.3)

or:

⚠️ Simulator build failed: [error summary] — tests passed, continuing to commit

XcodeBuildMCP failure is non-blocking. Unit tests passing is sufficient for the workflow.

Swift Testing patterns for iOS

When generating new tests (Test Only mode or per-task test generation), always use Swift Testing — never XCTest — unless the project exclusively uses XCTest.

Required imports and structure

import Testing
@testable import {ModuleName}

@Suite("ViewModel or UseCase Name")
struct PersonalTrainerViewModelTests {

    @Test("describe the behavior, not the method name")
    func loadsTrainerOnAppear() async throws {
        // Arrange
        let viewModel = PersonalTrainerViewModel(
            discoverTrainersUseCase: MockDiscoverTrainersUseCase(),
            featureFlagChecker: MockFeatureFlagChecker(enabled: true)
        )

        // Act
        await viewModel.onAppear()

        // Assert
        #expect(viewModel.isFeatureEnabled == true)
        #expect(viewModel.currentTrainer != nil)
    }

    @Test("does not load trainer when feature flag is disabled")
    func doesNotLoadWhenDisabled() async {
        let viewModel = PersonalTrainerViewModel(
            featureFlagChecker: MockFeatureFlagChecker(enabled: false)
        )
        await viewModel.onAppear()
        #expect(viewModel.currentTrainer == nil)
    }

    // Parameterized test
    @Test("requestConnection returns true for valid trainer IDs",
          arguments: ["trainer-alpha", "trainer-beta", "trainer-gamma"])
    func requestConnectionSucceeds(trainerId: String) async {
        let viewModel = PersonalTrainerViewModel(
            connectTrainerUseCase: MockConnectTrainerUseCase(shouldSucceed: true)
        )
        let result = await viewModel.requestConnection(trainerId: trainerId)
        #expect(result == true)
    }
}

Rules for iOS tests

• Use

  @Suite

  to group related tests (one suite per ViewModel/UseCase/Repository)
• Use

  @Test("behavior description")

  — describe what it does, not the method
• Use

  #expect(condition)

  for assertions — never

  XCTAssert

• Use

  #require(value)

  to unwrap optionals that must exist
• Use

  throws

  for tests that can throw,

  async throws

  for async tests
• Use

  arguments:

  for data-driven tests (replaces XCTest

  parametrize

  )
• Use

  .tags()

  trait for categorization:

  @Test("...", .tags(.unit, .viewModel))

• Never use

  XCTest

  ,

  XCTAssert*

  , or

  class FooTests: XCTestCase

File structure for iOS tests

Follow the existing project convention. If no convention exists, use:

{ProjectName}/
└── {ProjectName}Tests/
    ├── Domain/
    │   └── UseCases/
    │       └── {UseCase}Tests.swift     ← one file per use case
    ├── Data/
    │   ├── Repositories/
    │   │   └── {Repository}Tests.swift
    │   └── Services/
    │       └── {Service}Tests.swift
    └── Presentation/
        └── Features/
            └── {Feature}/
                └── {Feature}ViewModelTests.swift

Test file naming

• One test file per production file:

  PersonalTrainerViewModel.swift

  →

  PersonalTrainerViewModelTests.swift

• Place in mirror directory under

  {ProjectName}Tests/

Test Only mode — iOS

When

--mode test-only

is invoked on an iOS project:

1. Detect test framework (Swift Testing vs XCTest)
2. Find Swift files without corresponding test files:

   find . -name "*.swift" \
     ! -name "*Tests.swift" \
     ! -name "*Mock*" \
     ! -path "*/Tests/*" \
     -type f 2>/dev/null
   

3. For each file without tests, check if it's testable (ViewModels, UseCases, Repositories, Services)
4. Present to user:

   Found 3 files without test coverage:
   - Presentation/Features/PersonalTrainer/PersonalTrainerViewModel.swift
   - Domain/UseCases/ConnectTrainerUseCase.swift
   - Data/Repositories/TrainerRepository.swift
   
   Generate Swift Testing tests for these files? [yes/no/select]
   

5. Generate tests following Swift Testing patterns above
6. Run

   swift test --parallel

7. If XcodeBuildMCP available: optionally run build on simulator
8. Report coverage delta

Configuration in platform-context.json

The iOS entry in

platform-context.json

includes:

{
  "type": "ios",
  "test_framework": "swift-testing",
  "capabilities": {
    "swiftlint_available": true,
    "xcodebuildmcp_available": true,
    "swift_testing_available": true
  }
}

This configuration is ignored completely on non-iOS projects.