Swift Test Writer Skill

Write repository-aware Swift tests that improve confidence in behavior, not just line coverage.

swift-test-writer-skill helps agents inspect the local suite first, match existing test conventions, choose high-value scenarios, and write stable tests using Swift Testing or XCTest based on the codebase they are working in.

Why This Skill Exists

Most AI-generated tests are syntactically correct but strategically weak. They often:

• chase line coverage instead of product risk
• overfit to implementation details
• ignore local testing conventions
• introduce unnecessary mocks and abstractions
• force a new framework into an established suite

This skill is built to do the opposite.

What It Helps With

• writing meaningful unit tests for Swift app and library code
• adding regression tests for bug fixes
• covering async workflows, state transitions, and failure paths
• following existing project conventions for Testing or XCTest
• reusing local fixtures, builders, fakes, and test helpers
• improving testability without over-engineering production code

What It Avoids

• shallow happy-path-only coverage
• line-by-line implementation mirroring
• protocol-for-everything test setups
• accidental framework migrations
• brittle assertions on private details
• sweeping architecture rewrites just to make tests possible

Best Fit

Use this skill when you want an agent to:

• add tests for a new Swift feature
• write regression coverage for a bug fix
• improve weak or noisy Swift tests
• choose between Swift Testing and XCTest based on existing usage
• review whether a code change is under-tested

Included Resources

• SKILL.md: Core workflow and scope boundaries
• references/test-discovery.md: How to inspect the local test suite first
• references/test-selection.md: How to choose high-value scenarios
• references/swift-testing.md: Modern Swift Testing guidance
• references/xctest-compat.md: XCTest and mixed-suite guidance
• references/test-doubles-and-fixtures.md: Mocks, fakes, fixtures, and testability
• references/test-quality-checklist.md: Final quality pass before finishing

Sample Prompts

Basic:

Use $swift-test-writer-skill to add tests for this Swift service and follow the existing test style in the repo.

Intermediate:

Use $swift-test-writer-skill to write regression tests for this bug fix. Prefer the repo's current framework, cover failure paths, and avoid implementation-coupled assertions.

Advanced:

Use $swift-test-writer-skill to review the surrounding test suite, identify the highest-risk untested behavior in this Swift module, add focused tests in the local style, and only make minimal production refactors if they clearly improve testability.

Installation

Codex

1. Copy this folder into your Codex skills directory.
2. Keep the folder name as swift-test-writer-skill.
3. Invoke it explicitly with $swift-test-writer-skill, or rely on metadata-based triggering if your Codex setup supports automatic skill selection.

Typical location:

$CODEX_HOME/skills/swift-test-writer-skill

Claude

Claude does not use the same Codex skill format natively, but the content maps well to Claude-compatible workflows.

Recommended approach:

1. Copy SKILL.md into a project instruction, system prompt, or reusable prompt template.
2. Keep the references/ folder nearby so the agent can load the specific guide it needs.
3. Tell Claude to inspect local test files before generating tests and to follow the repository's current framework and conventions.

Suggested wrapper prompt:

Use the Swift Test Writer guidance in this repository. Inspect the local test suite first, match the existing Swift test framework and conventions, prioritize behavior and risk over raw coverage, and keep production refactors minimal.

Other Agents

For agents that support prompt packs, skills, slash commands, or reusable instruction folders:

1. Place this repository where the agent can read SKILL.md and references/.
2. Use SKILL.md as the primary instruction file.
3. Load only the relevant reference files for the current task to keep context small.
4. Invoke the skill name explicitly in your workflow if the agent does not support metadata-based activation.

This repository is intentionally plain Markdown so it can be adapted to most agent systems.

For Different Experience Levels

If you are new to testing:

• use the sample prompts directly
• let the skill choose behavior-focused tests from nearby code
• prefer adding tests around bug fixes and branching logic first

If you are experienced:

• use the references selectively
• bias the agent toward risk-based coverage decisions
• ask for review of weak assertions, flakiness, and over-mocking

If you maintain large Swift codebases:

• use the skill to standardize test review heuristics
• apply it during feature work and bug-fix follow-ups
• keep it paired with local framework conventions instead of forcing migration

GitHub Metadata

Suggested repository description:

Repo-aware Swift testing skill for AI agents. Writes behavior-focused Swift tests using Swift Testing or XCTest based on local codebase conventions.

Suggested topics:

swift swift-testing xctest testing ai-agent llm codex claude developer-tools prompt-engineering code-quality ios macos tdd

License

This project is released under the MIT License. See LICENSE.