Testing Guide

The v2.2.0 boilerplate ships with roughly 598 tests that all run in a single pass through Boilerplate.xctestplan. One xcodebuild test against the SwiftAIBoilerplatePro scheme exercises every package test target plus the app’s unit and UI suites.

Complete testing strategy in your project: TestingStrategy.md

Test Suite Overview

Boilerplate.xctestplan wires up 14 test targets: the 12 package test targets and the app’s two targets.

12 package test targets

CoreTests, TestSupportTests, NetworkingTests, StorageTests, AuthTests, DesignSystemTests, FeatureChatTests, FeatureRatingTests, FeatureSettingsTests, PaymentsTests, LocalizationTests, AITests

App test suites

SwiftAIBoilerplateProTests (unit + integration) and SwiftAIBoilerplateProUITests (end-to-end XCUITest flows)

TestSupport is the v2.2 test-infrastructure package (it exposes URLProtocolStub for network stubbing). It is not one of the 11 reusable product packages — it exists only to support the test targets.

Total: ~598 tests, one test-plan run.

Run Tests

Xcode
Command Line

# Run the whole test plan
⌘ + U

# Run a single test — click the diamond next to the test function
# Run a test class — click the diamond next to the class name

# Whole workspace via the test plan
xcodebuild test \
  -scheme SwiftAIBoilerplatePro \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro,OS=26.2'

# Convenience wrapper with a coverage report
./scripts/run-tests.sh --coverage --open

# A single package (runs `swift test` inside Packages/<name>)
./scripts/run-tests.sh --package Core --coverage

The repo targets the iPhone 17 Pro, OS=26.2 simulator (the destination CI uses). scripts/run-tests.sh itself drives the app test target on iPhone 16, OS=18.6 to exercise the pre-iOS-26 SAIGlass Material fallback — pass any installed destination by editing the script’s DESTINATION if your simulators differ.

Coverage

Coverage is measured with xccov, not asserted per module. scripts/run-tests.sh --coverage writes coverage-report.txt and an HTML report, and warns (does not fail) if overall app coverage drops below its local COVERAGE_THRESHOLD of 85%. CI enforces a separate product-coverage floor of 25% (MINIMUM_COVERAGE in .github/workflows/ci.yml). It computes coverage over product targets only — test targets and vendored dependencies (SnapshotTesting, InlineSnapshotTesting, OneSignal) are excluded so they don’t deflate the number.

Writing Tests

The packages use XCTest with protocol-based fakes. The patterns below mirror the suites that ship in the repo.

Unit Test Example

ChatViewModel is constructed with conversationID, a MessageRepository, and an LLMClient. You set inputText and call send(). Tests inject FakeMessageRepository and FakeLLMClient (from FeatureChatTests).

@MainActor
final class ChatViewModelTests: XCTestCase {
    func testSendAppendsUserMessage() async {
        // Arrange
        let fakeRepo = FakeMessageRepository()
        let fakeLLM = FakeLLMClient(chunks: ["Hello", " ", "world"])
        let viewModel = ChatViewModel(
            conversationID: UUID(),
            messageRepository: fakeRepo,
            llmClient: fakeLLM
        )

        // Act
        viewModel.inputText = "Hello, AI!"
        await viewModel.send()

        // Assert — the user message landed and the input cleared
        let userMessages = viewModel.messages.filter { $0.role == .user }
        XCTAssertEqual(userMessages.count, 1)
        XCTAssertEqual(viewModel.inputText, "")
    }
}

Integration Test Example

CompositionRootTests wires the real CompositionRoot with test configs and asserts the dependency graph is built.

@MainActor
final class CompositionRootTests: XCTestCase {
    func testGraphIsWired() throws {
        let authConfig = AuthConfig(
            supabaseURL: try XCTUnwrap(URL(string: "https://test.supabase.co")),
            supabaseAnonKey: "test_anon_key"
        )
        let paymentsConfig = PaymentsConfig(
            apiKey: "test_api_key",
            entitlementID: "test_entitlement"
        )

        let composition = try CompositionRoot(
            authConfig: authConfig,
            paymentsConfig: paymentsConfig
        )

        XCTAssertNotNil(composition.httpClient)
        XCTAssertNotNil(composition.sessionManager)
        XCTAssertNotNil(composition.makeChatViewModel(conversationID: UUID()))
    }
}

UI Test Example

UI tests set UI_TESTING=1 in the launch environment so the app skips the first-launch onboarding/permission prompts that would otherwise block automation. They drive the app by its real accessibility labels.

func testChatFlow() throws {
    let app = XCUIApplication()
    app.launchEnvironment["UI_TESTING"] = "1"
    app.launch()

    app.buttons["Debug: Mock Sign In"].tap()
    app.tabBars.buttons["Chat"].tap()
    app.buttons["New Chat"].firstMatch.tap()

    let input = app.textFields["Type a message..."]
    input.tap()
    input.typeText("Hello, test message")
    app.buttons["Send"].tap()

    XCTAssertTrue(app.staticTexts["Hello, test message"].waitForExistence(timeout: 5))
}

CI/CD Integration

.github/workflows/ci.yml runs on every push to main/develop and on pull requests targeting those branches. Its jobs:

Build & Test (iOS 26.2) — builds and runs the full test plan on iPhone 17 Pro / iOS 26.2 with coverage, then enforces the 25% product-coverage floor.
Build & Test (iOS 18.6 fallback path) — test-ios18-fallback rebuilds and runs the suite on iPhone 16 Pro / iOS 18.6 to prove the SAIGlass Material fallback still compiles and passes on pre-iOS-26 simulators. No coverage gate — it catches fallback-path regressions only.
Template Manifest — validates template.manifest.json via scripts/validate-template-manifest.sh.
Secret Scan — Gitleaks over the full history.
SwiftLint — swiftlint lint --strict.

Coverage Reports

The iOS 26.2 job posts a coverage summary as a PR comment.
.github/workflows/coverage-report.yml runs weekly (Mondays 09:00 UTC) and on demand, producing a detailed report and opening a GitHub issue if any module falls below the 25% threshold.
scripts/run-tests.sh --coverage --open generates a local HTML breakdown.

Test Organization

Boilerplate.xctestplan
├── App targets
│   ├── SwiftAIBoilerplateProTests      # unit + integration (CompositionRoot, proxy, paywall)
│   └── SwiftAIBoilerplateProUITests    # XCUITest end-to-end flows (auth, chat, settings)
│
└── Package test targets (12)
    ├── CoreTests
    ├── TestSupportTests
    ├── NetworkingTests
    ├── StorageTests
    ├── AuthTests
    ├── DesignSystemTests
    ├── FeatureChatTests
    ├── FeatureRatingTests
    ├── FeatureSettingsTests
    ├── PaymentsTests
    ├── LocalizationTests
    └── AITests

Best Practices

What to Test

Do test:

✅ ViewModels (business logic)
✅ Repositories (data access)
✅ Clients (external services)
✅ Error scenarios
✅ Edge cases

Don’t test:

❌ SwiftUI Views (snapshot instead)
❌ Third-party libraries
❌ Framework code

Test Structure

Use Arrange-Act-Assert pattern
One assertion per test (when possible)
Clear test names (testSendMessage_WhenOffline_ShowsError)
Mock external dependencies
Test in isolation

Mock Guidelines

Protocol-based mocking
Track call counts
Configurable behavior
Avoid over-mocking
Use real objects when simple

Coverage Measurement

# Generate the local HTML report and open it
./scripts/run-tests.sh --coverage --open

# Coverage for one package only
./scripts/run-tests.sh --package Core --coverage

The local report warns below 85% app coverage; CI gates only the 25% product-coverage floor described under CI/CD Integration.

View Complete Guide

View Complete Testing Guide

Complete guide with examples, patterns, and best practices

Troubleshooting

Tests fail on CI but pass locally

Match the CI destination: iPhone 17 Pro, OS=26.2
Confirm Xcode 26.2+ (CI selects Xcode 26.2)
Clear derived data, then rebuild
Look for timing-sensitive async tests

Coverage lower than expected

Run with --coverage
Add tests for untested branches and error scenarios
Make sure async code is actually awaited in the test

UI tests flaky or stuck on first launch

Set app.launchEnvironment["UI_TESTING"] = "1" so the app skips the first-launch onboarding/permission alert that blocks automation
Use waitForExistence(timeout:) instead of bare exists
Drive elements by their accessibility labels (e.g. "Send", "Type a message...")
Avoid asserting mid-animation

Getting Started

Setup Guides

Core Modules

Feature Modules

Migration

Reference

Before You Submit

Test Suite Overview

12 package test targets

App test suites

Run Tests

Coverage

Writing Tests

Unit Test Example

Integration Test Example

UI Test Example

CI/CD Integration

Coverage Reports

Test Organization

Best Practices

Coverage Measurement

View Complete Guide

View Complete Testing Guide

Troubleshooting

​Test Suite Overview

12 package test targets

App test suites

​Run Tests

​Coverage

​Writing Tests

​Unit Test Example

​Integration Test Example

​UI Test Example

​CI/CD Integration

​Coverage Reports

​Test Organization

​Best Practices

​Coverage Measurement

​View Complete Guide

View Complete Testing Guide

​Troubleshooting

Test Suite Overview

Run Tests

Coverage

Writing Tests

Unit Test Example

Integration Test Example

UI Test Example

CI/CD Integration

Coverage Reports

Test Organization

Best Practices

Coverage Measurement

View Complete Guide

Troubleshooting