Testing & TDD Skills
Test-driven development workflows and testing infrastructure for Apple platform apps. Works with both new and existing codebases.
When This Skill Activates
Use this skill when the user:
- Wants to do TDD (test-driven development) with AI-generated code
- Needs to add tests before refactoring existing code
- Wants to fix a bug using the red-green-refactor cycle
- Needs test infrastructure (factories, mocks, contracts)
- Asks about snapshot/visual regression testing
- Wants to ensure AI-generated code is correct via tests
- Wants deterministic gates around agent-written code (architecture invariants, coverage floors, mutation audits)
Available Skills
For Existing Codebases
characterization-test-generator/ Capture current behavior of existing code before refactoring. Generates tests that document what code actually does (not what it should do), giving you a safety net for AI-assisted refactoring.
tdd-bug-fix/ Reproduce-first bug fix workflow. Write a failing test that demonstrates the bug, then fix it. Ensures the bug never regresses — critical when AI generates fixes.
tdd-refactor-guard/ Pre-refactor safety checklist. Verifies test coverage exists before allowing AI to touch existing code. Prevents the "refactor without a safety net" problem.
For New Code
tdd-feature/ Red-green-refactor scaffold for new features. Generates the failing test first, then guides implementation to make it pass, then refactors. The core TDD workflow.
test-contract/ Protocol/interface test suites. Define the contract (e.g., "any DataStore must handle empty state, single item, 100 items, and errors"), and it generates a test suite any implementation must pass.
Infrastructure
snapshot-test-setup/ SwiftUI visual regression testing using swift-snapshot-testing. Generates snapshot test boilerplate, configuration, and CI integration.
test-data-factory/ Test fixture factories for your models. Makes writing tests faster by eliminating boilerplate data setup. Supports Builder pattern and static factory methods.
integration-test-scaffold/ Cross-module test harness with mock servers, in-memory stores, and test configuration. For testing networking + persistence + business logic together.
flow-walkthrough/ Drive each user flow in the Simulator (XCUITest + per-step screenshots), audit the navigation graph for dead-ends, and run a human discoverability check.
Deterministic Gates
fitness-functions/ Architecture fitness functions — tests that enforce a project's hard rules (module import boundaries, offline guarantees, count/copy contracts) from inside its own test target. Turns prose constraints into exit codes.
coverage-ratchet/ Coverage floor that only rises: a committed baseline the app target's line coverage may never drop below, gated by a generated xccov script. Includes an advisory CRAP report (complexity × uncovered).
mutation-testing/ EXPERIMENTAL, advisory-only muter setup scoped to engine targets — surviving mutants reveal covered-but-unasserted code. Never a merge gate; includes the manual deliberate-break fallback.
Keep Tests Fast
Agent-written tests get slow in the same few ways, and every phase runs the
suite more often, so slow tests cost time on every build. SwiftShip's
/apple:verify times the suite each phase and warns when it gets more than
25% slower or a single test takes over 10 s. Write tests so it never has to:
- One test with a list of inputs, not copies. Five near-identical
tests are five setups. Use
@Test(arguments:):@Test(arguments: ["", " ", "\n"]) func rejectsBlankTitle(_ title: String) throws { #expect(throws: NoteError.blankTitle) { try Note(title: title) } } - Fakes for the network, the clock and storage. No real
URLSessioncalls: inject a protocol, or aURLProtocolstub. No real waiting: pass a clock or a date provider instead of waiting for time to pass. SwiftData: an in-memoryModelConfiguration(isStoredInMemoryOnly: true). - No
sleep, no fixed waits.Task.sleep,sleep()and longXCTWaitertimeouts make every run pay the worst case. Await the result, or wait on the specific element (waitForExistence(timeout:)returns as soon as it appears). - UI tests launch the app once per class, not per test, when the
tests don't need a fresh state: launch in
setUponly when needed, or reset state through a launch argument instead of a relaunch. Test logic in unit tests, not through the UI; keep UI tests for flows. - Unit tests touch no disk, network or Simulator. If a unit test needs
one of those, it's an integration test (
integration-test-scaffold/); keep it in its own target or test plan so the fast suite stays fast.
A test over 10 s is a bug in the test, not a fact of life: find which of the five it breaks.
How to Use
- Identify whether user is working on new code or existing code
- Read the relevant skill's SKILL.md for detailed workflow
- Detect project context (testing framework, architecture, existing tests)
- Generate tests following the skill's workflow
- Verify tests compile and run
Relationship to test-generator
The generators/test-generator/ skill generates test boilerplate (unit, integration, UI tests). These testing skills are complementary — they focus on workflows and methodology (TDD cycle, characterization testing, contracts) rather than just test file generation.
Cross-reference:
- Use
test-generatorfor "add tests to this class" - Use
testing/tdd-featurefor "I want to TDD this new feature" - Use
testing/characterization-test-generatorfor "I need to safely refactor this" - Use
testing/tdd-bug-fixfor "fix this bug and make sure it never comes back"