how to debug a single failing XCTest case with an AI agent

Have Atlas run only that case with XCTest via swift test and the framework's filter flag, read the case and the module under Sources/ it exercises, walk the call path with the lsp tool's goToDefinition and findReferences, then fix the production code with edit or apply_patch.

how do I stop an AI agent from just changing the Swift assertion to make a test pass

The goal is to find why the test fails and fix the code, not the assertion. Atlas walks from the failing XCTest case into the module under Sources/ with the lsp tool, so the change lands on the implementation that produced the wrong value rather than on the expectation.

why run only one Swift test instead of the whole suite while debugging

A full XCTest via swift test run rebuilds the Swift Package Manager package and prints hundreds of passing cases, which buries the one XCTAssertEqual you need to read. Atlas uses the framework's filter flag so the output is small enough to reason about.

how does Atlas find which Swift implementation actually ran

It uses the lsp tool's goToDefinition operation, which resolves through protocol witnesses and extensions. In Swift, the call site names the protocol requirement, not the body that executed, so the language server is what tells you which implementation was invoked.

when should I use apply_patch instead of edit in Atlas

Use edit for a one-place Swift fix, and apply_patch when the change spans several hunks, such as changing a func signature in Sources/ plus its callers plus the XCTest case that used the old shape. Chained edits drift as each one shifts the file.

does Atlas remove the debug logging it adds

It should, and the workflow calls for it explicitly: re-run the single XCTest case, run the full XCTest via swift test suite, then remove any temporary print statements added during debugging. Atlas reads git status and the diff, so the working diff can be checked before committing.

can Atlas undo a Swift fix that made things worse

Yes. Atlas snapshots file changes as git patches, so an edit or apply_patch against Sources/ can be diffed and rolled back rather than unpicked by hand. Every change is also surfaced as a unified diff for approval before it is written.

Debug a Single Failing Test in Swift with Atlas (2026)

To debug a single failing Swift test, Atlas runs that test in isolation first, using XCTest via swift test with the framework's filter flag so the output is small enough to reason about instead of a full Swift Package Manager suite scrolling past. Atlas then reads the failing XCTest case and the module under Sources/ that it exercises, and walks the call path with the lsp tool's goToDefinition and findReferences operations, so the fix targets the production code rather than the assertion. Because Atlas's bash tool is a real shell, the same debugging levers you would reach for by hand are available: temporary logging added with edit, a verbose flag, a re-run of just the one case. Multi-hunk fixes go through apply_patch instead of a chain of brittle edits, and the temporary logging comes back out before the full suite runs.

How does Atlas debug one failing Swift test in isolation?

Atlas runs just the failing XCTest case with the bash tool, using XCTest via swift test with the framework's filter flag so the output is small enough to reason about. 1 failing case in Tests/AppTests/BillingTests.swift produces a handful of lines instead of the thousands a full Swift Package Manager run emits.

Isolation is what makes the rest of the debugging session tractable. A single XCTest case that fails on an XCTAssertEqual gives you the expected value, the actual value, and the exact file and line, and none of that is buried under 700 passing cases. Atlas filters down to the one case, reads the failure, and starts from there. The bash tool is a real shell, so the invocation Atlas runs is the same one you would type, and its metadata carries the process exit code, so the failure state is recorded rather than inferred from output text. Every Atlas tool call is permission-gated against allow, ask, and deny rules first.

How does Atlas walk the Swift call path from the assertion to the bug?

Atlas reads the failing XCTest case and the module it exercises, then uses 2 lsp operations to walk the call path: goToDefinition and findReferences. In Swift, goToDefinition resolves through protocol witnesses and extensions, so the implementation actually invoked at runtime is the one Atlas ends up reading.

Swift makes the invoked implementation genuinely hard to eyeball. A protocol with a default implementation in an extension, a conforming struct that overrides only some requirements, a generic constrained by that protocol: reading the call site tells you the protocol requirement, not which body ran. goToDefinition through the language server resolves it. findReferences then answers the other half of the question, which other callers reach the same function, because a bug reachable from three places is not fixed by patching the path the one XCTest case happened to take. Atlas indexes code by AST declarations using tree-sitter, so each hop returns a whole Swift declaration.

How do you test a hypothesis about a failing Swift test?

Atlas forms 1 hypothesis at a time and then checks it, either by adding temporary logging with edit or by re-running the filtered XCTest case through bash with a verbose flag. Because bash is a real shell, the debugging levers available to Atlas are the same ones a Swift developer would reach for by hand.

The discipline here is one hypothesis at a time. Add a print inside the function under Sources/App/Billing.swift, re-run only the filtered XCTest case, read what the value actually was. If the value is wrong on the way in, the bug is upstream and the next hop is a findReferences on the caller. If the value is right on the way in and wrong on the way out, the bug is in the function. Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so even a temporary print statement is a change you see before it lands, which also means you know exactly what has to be removed later.

When should a Swift fix use apply_patch instead of edit?

Atlas fixes the Swift production code with edit when the change is 1 place, and uses apply_patch when the fix spans several hunks. Threading an optional through 3 functions in Sources/App/Billing.swift is a multi-hunk change, and chaining brittle edits against a file that shifts under each one is how a fix goes wrong.

apply_patch is the structural tool: it applies a set of hunks anchored on their surrounding Swift context rather than on line numbers, which is what you want once the first hunk has already changed the offsets of everything below it. The rule of thumb is scope. A one-line guard added to a single func is edit. Changing a function signature, updating its two callers, and adjusting the XCTest case that exercised the old shape is apply_patch. Either way Atlas snapshots file changes as git patches, so a fix that turned out to be wrong is diffed and rolled back rather than unpicked by hand across Sources/ and Tests/.

What does Atlas do after a failing Swift test goes green?

Atlas re-runs the single XCTest case, then the full XCTest via swift test suite, then removes any temporary logging it added. A fix that turns 1 Swift test green while breaking 2 others is not a fix, and the full Swift Package Manager run is the only thing that proves the difference.

The cleanup step is not optional. A print left inside Sources/App/Billing.swift ships to production and pollutes every log line, and Atlas added it deliberately, so Atlas removes it deliberately. Because Atlas reads git branches, status, and diffs, the working diff is available to check before committing: what should be in it is the production fix, and nothing else. Run swift-format on the touched files at the end so the commit is a behavior change rather than a behavior change mixed with reformatting, and let Swift Package Manager resolve any dependency the fix required in Package.swift.

How do you set up Atlas on a Swift package in 2026?

Run atlas in a Swift package with a Package.swift in 2026 and let Atlas read your targets, protocols, and dependencies. Atlas is a terminal-native TUI, so a debug loop of filter, read, hypothesize, re-run all happens in the same shell where you already run swift test.

The setup that pays off in a debugging session is permission shape: allow swift test and swift build under bash so the filtered re-runs never stall on approval, and leave edit and apply_patch on ask so every change to Sources/ is reviewed. Reading Package.swift is what lets Atlas know which target the failing XCTest case belongs to and which protocols that target declares, which is exactly the information goToDefinition needs to resolve a witness. Teams that cannot send source to a hosted model can build the code index with local Ollama embeddings, keeping the Swift package off third-party servers.

Step by step

01Run atlas in the Swift package that contains Package.swift, and let it read your targets, protocols, and dependencies.
02Run just the failing case with the bash tool as XCTest via swift test using the framework's filter flag, so the output is small enough to reason about rather than a full Swift Package Manager suite.
03Read the failing XCTest case and the module under Sources/ that it exercises, so the assertion and the implementation are both in context.
04Walk the call path with the lsp tool's goToDefinition and findReferences operations, which resolve Swift protocol witnesses and extensions to the implementation that actually ran.
05Form one hypothesis and check it: add temporary logging with edit, or re-run the filtered XCTest case through bash with a verbose flag.
06Fix the production code with edit when the change is local, and use apply_patch when the fix spans several hunks, so a chain of brittle edits does not drift against a shifting file.
07Re-run the single XCTest case, then the full XCTest via swift test suite, to prove the fix did not break another target.
08Remove every temporary print you added, check the working diff, and run swift-format on the touched files before committing.

Frequently asked questions

how to debug a single failing XCTest case with an AI agent: Have Atlas run only that case with XCTest via swift test and the framework's filter flag, read the case and the module under Sources/ it exercises, walk the call path with the lsp tool's goToDefinition and findReferences, then fix the production code with edit or apply_patch.
how do I stop an AI agent from just changing the Swift assertion to make a test pass: The goal is to find why the test fails and fix the code, not the assertion. Atlas walks from the failing XCTest case into the module under Sources/ with the lsp tool, so the change lands on the implementation that produced the wrong value rather than on the expectation.
why run only one Swift test instead of the whole suite while debugging: A full XCTest via swift test run rebuilds the Swift Package Manager package and prints hundreds of passing cases, which buries the one XCTAssertEqual you need to read. Atlas uses the framework's filter flag so the output is small enough to reason about.
how does Atlas find which Swift implementation actually ran: It uses the lsp tool's goToDefinition operation, which resolves through protocol witnesses and extensions. In Swift, the call site names the protocol requirement, not the body that executed, so the language server is what tells you which implementation was invoked.
when should I use apply_patch instead of edit in Atlas: Use edit for a one-place Swift fix, and apply_patch when the change spans several hunks, such as changing a func signature in Sources/ plus its callers plus the XCTest case that used the old shape. Chained edits drift as each one shifts the file.
does Atlas remove the debug logging it adds: It should, and the workflow calls for it explicitly: re-run the single XCTest case, run the full XCTest via swift test suite, then remove any temporary print statements added during debugging. Atlas reads git status and the diff, so the working diff can be checked before committing.
can Atlas undo a Swift fix that made things worse: Yes. Atlas snapshots file changes as git patches, so an edit or apply_patch against Sources/ can be diffed and rolled back rather than unpicked by hand. Every change is also surfaced as a unified diff for approval before it is written.

Try Atlas in your terminal

The terminal-native AI coding agent. Free core, single binary.

Install Atlas

Related guides

Debug a Single Failing Test with Atlas in 2026

How to debug one failing test with Atlas in 2026: run it in isolation with bash, walk the call graph with the lsp tool, and fix the code, not the assertion.

Atlas for Swift in 2026

Atlas for Swift in 2026 empowers developers with a terminal-native AI coding agent. Index code by AST, ensure privacy with local embeddings, and review changes with unified diffs.

Refactor a Legacy Module in Swift With Atlas (2026)

Restructure an old Swift module without breaking its callers. Atlas maps the public surface with the lsp tool, patches with apply_patch, and reruns swift test each hunk.

Diagnose a Hanging or Long-Running Command in Swift with Atlas (2026)

How Atlas diagnoses a hanging Swift build or script in 2026: read the shell_metadata block, tell a slow swift build from one blocked on stdin, and get unstuck.

Add a Regression Test for a Bug Fix in Swift with Atlas (2026)

Add a regression test for a bug fix in Swift with Atlas in 2026. Write a failing XCTest case, run swift test to prove it red, apply the fix, then re-run.

Automate GitHub Issue and Pull Request Triage in Swift with Atlas in 2026

Swift developers in 2026 can automate GitHub issue and pull request triage using Atlas, integrating with the Swift Package Manager toolchain for safe, trusted responses.

Onboard to an Unfamiliar Swift Codebase with Atlas (2026)

Learn an unfamiliar Swift package in 2026 without reading every file. Atlas queries the semantic index, maps Sources with glob, and delegates sweeps to a read-only explore subagent.

Audit a Swift Repo with Parallel Subagents in Atlas in 2026

Sweep large Swift repositories for code issues in 2026 using Atlas's parallel subagents. Leverage Swift Package Manager, XCTest, and swift-format without blowing your context window.

Browse this resource hub