---
id: CharlesWiltgen/Axiom/axiom-testing
version: "972e76be"
license: MIT
install: manual
updated: 2026-07-27
---

# axiom-testing — Axiom Testing guides you through writing and debugging tests across all iOS scenarios—from unit tests with Swift Testing to UI automation with XCUITest. Navigate async testing patterns, flaky test fixes, and test architecture decisions with clear decision trees and critical patterns for each testing domain.

Publisher: CharlesWiltgen · Stars: 1095 · Updated: 2026-07-27

Install (manual): `git clone https://github.com/CharlesWiltgen/Axiom`

## SKILL.md

# Testing

**You MUST use this skill for ANY testing-related question, including writing tests, debugging test failures, making tests faster, or choosing between testing approaches.**

<!-- AXIOM_AUDITOR_INLINE_BEGIN — auto-maintained by scripts/build-inlined-auditors.ts; do not hand-edit -->
> **Not on Claude Code?** Where this router says "Launch `some-auditor` agent", read that auditor's file in this suite and follow it inline — the same procedure, needing only file search and read.
>
> Available here: `skills/test-failure-analyzer.md`, `skills/testing-auditor.md`.
>
> Agents that need Bash — builds, tests, simulators, crash symbolication — stay Claude Code-only; there is no inline equivalent for those.
<!-- AXIOM_AUDITOR_INLINE_END -->

## Quick Reference

| Symptom / Task | Reference |
|----------------|-----------|
| Writing unit tests, Swift Testing (@Test, #expect) | See `skills/swift-testing.md` |
| Making tests run without simulator | See `skills/swift-testing.md` |
| Parameterized tests, tags, traits | See `skills/swift-testing.md` |
| Migrating from XCTest to Swift Testing | See `skills/swift-testing.md` |
| Warning-severity issues / cancelling a test — `Issue.record(severity:)`, `Test.cancel` (`OS27`) | See `skills/swift-testing.md` |
| Testing async/await functions | See `skills/testing-async.md` |
| confirmation for callbacks | See `skills/testing-async.md` |
| @MainActor tests, parallel execution | See `skills/testing-async.md` |
| Writing UI tests, XCUITest | See `skills/ui-testing.md` |
| Condition-based waiting patterns | See `skills/ui-testing.md` |
| Recording UI Automation (Xcode 26) | See `skills/ui-testing.md` |
| Network conditioning, multi-factor testing | See `skills/ui-testing.md` |
| Testing resizable apps: dimension matrix, RTL/pseudoloc launch args, live-resize passes | See `skills/ui-testing.md` |
| Test Face ID/Touch ID, orientation, or simulator state from CI — devicectl | See `skills/ui-testing.md` |
| XCUIElement queries, waiting strategies | See `skills/xctest-automation.md` |
| Accessibility identifiers, test plans | See `skills/xctest-automation.md` |
| CI/CD test execution | See `skills/xctest-automation.md` |
| Record/Replay/Review workflow (Xcode 26) | See `skills/ui-recording.md` |
| Test plan multi-configuration replay | See `skills/ui-recording.md` |
| Enhancing recorded tests for stability | See `skills/ui-recording.md` |
| Testing a generative AI feature — output isn't deterministic, so `#expect(result == expected)` doesn't hold (`OS27`) | See axiom-ai (`skills/foundation-models-evaluations.md`) for the discipline, then axiom-ai (`skills/foundation-models-evaluations-ref.md`) for the API |

## Decision Tree

```dot
digraph testing {
    start [label="Testing task" shape=ellipse];
    what [label="What kind of test?" shape=diamond];

    start -> what;
    what -> "skills/swift-testing.md" [label="unit tests,\nSwift Testing,\nfast tests"];
    what -> "skills/testing-async.md" [label="testing async code,\ncallbacks,\nconfirmation"];
    what -> "skills/ui-testing.md" [label="UI tests,\nflaky tests,\nrecording"];
    what -> "skills/xctest-automation.md" [label="XCUITest patterns,\nelement queries"];
    what -> "skills/ui-recording.md" [label="Xcode 26\nRecord/Replay/Review"];
    what -> "axiom-ai (skills/foundation-models-evaluations.md)" [label="generative AI feature\n(nondeterministic output)"];
}
```

1. Writing unit tests / Swift Testing? → `skills/swift-testing.md`
2. Testing async/await code? → `skills/testing-async.md`
3. Writing UI tests / XCUITest / flaky tests? → `skills/ui-testing.md`
4. XCUIElement queries, waiting, test plans, CI? → `skills/xctest-automation.md`
5. Record UI interactions (Xcode 26)? → `skills/ui-recording.md`
6. Flaky tests / race conditions (Swift Testing)? → test-failure-analyzer (Agent)
7. Tests crash / environment wrong? → See axiom-build (skills/xcode-debugging.md)
8. Run tests from CLI / parse results? → test-runner (Agent)
9. Fix failing tests automatically? → test-debugger (Agent)
10. Want test quality audit? → testing-auditor (Agent) or `/axiom:audit testing`
11. Automate without XCUITest / AXe CLI? → simulator-tester (Agent) + See axiom-xcode-mcp (skills/axe-ref.md)
12. Testing a Foundation Models / generative feature? → See axiom-ai (`skills/foundation-models-evaluations.md`) for the discipline (dataset design, guardrails vs optimization target, judge calibration), then axiom-ai (`skills/foundation-models-evaluations-ref.md`) for the API. The Evaluations framework (`OS27`) runs *inside* Swift Testing via the `.evaluates` trait — it doesn't replace it. A model isn't a pure function, so you score outputs against a dataset and gate on an aggregate metric instead of asserting on one exact string.

## Swift Testing vs XCTest Quick Guide

| Need | Use |
|------|-----|
| Unit tests (logic, models) | Swift Testing |
| UI tests (tap, swipe, assert screens) | XCUITest (XCTest) |
| Tests without simulator | Swift Testing + Package/Framework |
| Parameterized tests | Swift Testing |
| Performance measurements | XCTest (XCTMetric) |
| Objective-C tests | XCTest |

## Critical Patterns

**Swift Testing** (`skills/swift-testing.md`):
- @Test/@Suite macros, #expect/#require assertions
- Parameterized testing for eliminating repetitive tests
- Fast tests architecture: Package extraction, Host Application: None
- Reliable async testing with withMainSerialExecutor and TestClock
- Migration guide from XCTest (comparison table)
- XCTestCase + Swift 6.2 MainActor compatibility fix

**Async Testing** (`skills/testing-async.md`):
- confirmation for single/multiple callbacks
- expectedCount: 0 to verify something never happens
- @MainActor test isolation
- Timeout control with .timeLimit
- Parallel execution gotchas and .serialized

**UI Testing** (`skills/ui-testing.md`):
- Condition-based waiting (replaces sleep())
- Recording UI Automation (Xcode 26)
- Network conditioning for 3G/LTE testing
- Multi-factor testing (device size + network speed)
- Crash debugging from UI test failures

**XCUITest Automation** (`skills/xctest-automation.md`):
- Element identification with accessibilityIdentifier
- Waiting strategies (appear, disappear, hittable)
- Test plans for multi-configuration testing
- CI/CD integration with parallel execution

**UI Recording** (`skills/ui-recording.md`):
- Xcode 26 Record/Replay/Review workflow
- Enhancing recorded code for stability
- Query selection guidelines
- Test plan configuration for multi-language replay

## Automated Scanning

**Test quality audit** → Launch `testing-auditor` agent or `/axiom:audit testing` (maps test coverage shape against production code, detects flaky patterns and speed issues, identifies untested critical paths, scores overall test health)

**Flaky test analysis** → Launch `test-failure-analyzer` agent (scans for patterns causing intermittent failures in Swift Testing: missing confirmation, shared mutable state, missing @MainActor)

## Anti-Rationalization

| Thought | Reality |
|---------|---------|
| "Simple test question, I don't need the skill" | Proper patterns prevent test debt. `skills/swift-testing.md` has copy-paste solutions. |
| "I know XCTest well enough" | Swift Testing is significantly better for unit tests. Migration guide included. |
| "Tests are slow but it's fine" | Fast tests enable TDD. `skills/swift-testing.md` shows how to run without simulator. |
| "I'll fix the flaky test with a sleep()" | sleep() makes tests slower AND flakier. `skills/ui-testing.md` has condition-based waiting. |
| "I'll add tests later" | Tests written after implementation miss edge cases. |
| "I'll test the AI feature by asserting the model returns the right string" | A model isn't a pure function — that test fails on a synonym and passes on a fluent lie. Score a dataset and gate on an aggregate metric: axiom-ai (`skills/foundation-models-evaluations.md`). |
| "The AI output looked good when I tried it, so it's tested" | Trying a few prompts by hand measures nothing and catches no regression. That's the exact gap the Evaluations framework exists to close. |

## Example Invocations

User: "How do I write a unit test in Swift?"
→ Read: `skills/swift-testing.md`

User: "My UI tests are flaky in CI"
→ Check codebase: XCUIApplication/XCUIElement? → `skills/ui-testing.md`
→ Check codebase: @Test/#expect? → test-failure-analyzer (Agent)

User: "How do I test async code without flakiness?"
→ Read: `skills/testing-async.md`

User: "What's the Swift Testing equivalent of XCTestExpectation?"
→ Read: `skills/testing-async.md`

User: "I want my tests to run faster"
→ Read: `skills/swift-testing.md` (Strategy 1: Package extraction)

User: "Should I use Swift Testing or XCTest?"
→ Read: `skills/swift-testing.md` (Migration section) + this decision tree

User: "How do I record UI automation in Xcode 26?"
→ Read: `skills/ui-recording.md`

User: "Run my tests and show me what failed"
→ Invoke: test-runner (Agent)

User: "Audit my tests for quality issues"
→ Invoke: testing-auditor (Agent)


[View on SkillFed](https://skillfed.io/CharlesWiltgen/Axiom/axiom-testing) · [View on GitHub](https://github.com/CharlesWiltgen/Axiom)