| name | swiftui-tester |
| description | Swift Testing and XCTest patterns for SwiftUI apps. Use when authoring, refactoring, or debugging tests. Triggers on "test", "#expect", "#require", "XCTest", "unit test", "integration test", "@Test", "@Suite", "withKnownIssue". |
| model | inherit |
SwiftUI Testing Best Practices
Modern testing patterns using Swift Testing (Xcode 16+, Swift 6+) and XCTest. Focused on unit testing business logic, integration testing SwiftUI data flow, and UI testing.
Specialized Agents
| Agent | Role | Focus |
|---|
| swiftui-tester-pro | Test Expert | Swift Testing, XCTest, Mocking, Async Testing, Migration. |
When to Use
Reference these guidelines when:
- Writing new unit tests using Swift Testing (
@Test, #expect, #require)
- Migrating legacy XCTest suites to Swift Testing
- Writing UI tests with XCTest
- Testing Swift Concurrency (async tests, actor isolation, confirmations)
- Mocking dependencies using Dependency Injection in tests
- Testing SwiftData models and predicates
- Using parameterized tests, test traits,
withKnownIssue, and attachments
- Debugging failing tests or flaky UI tests
Step 1: Check Test Surface and Tooling
- Use Swift Testing for new unit and integration tests when the project is on Xcode 16+ / Swift 6+.
- Keep XCTest for UI tests and any legacy areas where the target or tooling still requires it.
- If the project mixes both frameworks, keep file boundaries explicit and avoid casual cross-imports.
Core Directives
MUST DO
- Swift Testing: Use Swift Testing for all new unit and integration tests (Xcode 16+, Swift 6+).
- Suites: Use
struct for test suites — enables parallel execution and no shared state by default.
- Lifecycle: Use
init() for struct-suite setup. Switch to a final class suite only when reference semantics or deinit cleanup is genuinely needed.
- Assertions: Use
#expect for general assertions; #require when a failure should stop the test immediately.
- Async: Mark tests
async and await all async calls.
- Actor Isolation: Mark UI-facing or main-thread-bound tests
@MainActor instead of relying on implicit thread affinity.
- Data: Use in-memory
ModelContainer for testing SwiftData models.
- UI Testing: Use XCTest for UI tests — Swift Testing does not support
XCUIApplication.
- Known Issues: Use
withKnownIssue() to mark expected failures with tracking context.
- Test Behavior: Write tests that test behavior (what the code does), not implementation (how it does it).
- Error Paths: Cover error paths and edge cases, not just the happy path.
- Determinism: Prefer injected clocks, stubbed dependencies, and explicit launch arguments over timing assumptions.
MUST NOT DO
- Legacy Assertions: Do NOT use
XCTAssert in Swift Testing suites.
- Shared State: Do NOT use global variables or static state in test suites.
- Blocking: Never use
Thread.sleep; use confirmation for async events or await Task.yield() for cooperative scheduling.
- UI Tests in Swift Testing: Do NOT attempt to use Swift Testing for
XCUIApplication interactions.
- Implementation Testing: Do NOT test internal implementation details — test observable behavior.
- Mixed Frameworks: Do NOT mix
import XCTest and import Testing in the same file (unless bridging intentionally).
- Order Dependency: Do NOT assume tests run in declaration order — Swift Testing runs in parallel by default.
- Main-Thread Assumptions: Do NOT rely on background tests implicitly mutating UI-bound state; isolate them with
@MainActor.
Category Index — When to Load Which Reference
Rule Index
1. Swift Testing (test-) — CRITICAL
test-struct-suites · test-expect-vs-require · test-parameterized · test-async-confirmation · test-known-issue · test-no-sleep · test-no-shared-state · test-behavior-names · test-serialized-scope · test-mainactor-isolation
2. Persistence Testing (test-data-) — HIGH
test-swiftdata-inmemory · test-predicate-validation
3. UI Testing (ui-test-) — HIGH
ui-test-accessibility-identifiers · ui-test-page-objects · ui-test-no-sleep · ui-test-xctest-only
Validation Checklist
