# Debug a Single Failing Test with Atlas in 2026 > Atlas debugs a failing test by running it in isolation with bash, walking the call graph with the lsp tool, and only then editing the production code. You find why one specific test fails and fix the code rather than the assertion by running the failing test in isolation with Atlas's bash tool, using the framework's filter flag so the output is small enough to reason about. Atlas then reads the test and the module it exercises, walks the call path with the lsp tool's goToDefinition and findReferences operations, and only then edits. Because bash is a real shell, the same debugging levers you would use by hand, extra logging, a focused test filter, a verbose flag, are all available. ## Key takeaways - Run the failing test in isolation with bash and the framework's filter flag, so the output is small enough to reason about. - Walk the call path with the lsp tool's goToDefinition and findReferences operations rather than guessing from the stack. - Because Atlas's bash tool is a real shell, extra logging, a focused test filter, and a verbose flag are all available. - Fix the code, not the assertion. Changing the expected value to match broken behavior destroys the evidence. - Use apply_patch when a fix spans several hunks instead of chaining brittle edit calls. - Re-run the single test, then the full suite, and remove every temporary log line you added. ## How do I debug one failing test without reading the whole suite output? Atlas debugs a single failing test by running just that test with the bash tool, using the framework's filter flag so the output is small enough to reason about. Isolating 1 test instead of running the whole suite turns a wall of output into a single assertion, a single stack, and a single hypothesis to check. Debugging a failing test starts with reducing the search space. Atlas runs the one test in isolation through the bash tool, passing whatever filter flag the repository's test framework provides. The result is a small, readable failure: the assertion that fired, the values it compared, and the stack that produced them. From there the read tool opens both the test and the module it exercises, so the assertion and the implementation are in context together. The rule that shapes the whole workflow is that the goal is to fix the code, not the assertion, and reading both sides is what keeps that honest. ## How do I trace why a test fails through the call graph? Atlas traces a failing test through the call graph with 2 lsp tool operations. goToDefinition follows the failing test into the implementation it actually runs, and findReferences enumerates every other caller of that implementation, which is how you tell a broken function apart from a caller passing it the wrong input. A failing assertion tells you where the wrong value surfaced, not where it was produced. The Atlas lsp tool closes that distance. goToDefinition takes you from the call in the test into the function that actually runs, and then from that function into the next one down. findReferences goes the other way and enumerates the callers, which matters because if other callers of the same function are passing their tests, the defect is more likely in the arguments than in the function. Atlas walks the graph with the language server rather than by pattern-matching text. ## How do I add temporary logging to debug a test in Atlas? Atlas adds temporary logging with the edit tool, or re-runs with a verbose flag through bash. Because the Atlas bash tool is a real shell, all 3 of the levers you would reach for by hand, extra logging, a focused test filter, and a verbose flag, are available inside the agent loop. Forming a hypothesis is not enough; the hypothesis has to be checked. Atlas checks it the way a developer would. If the question is what value reached the function, the edit tool inserts a temporary log line and bash re-runs the isolated test. If the question is what the framework itself was doing, bash re-runs with the verbose flag. There is nothing special or restricted about these commands, because bash is a real shell. Every edit that inserts logging is still a permission-gated tool call and still arrives as a unified diff, so temporary instrumentation is visible, not sneaked in. ## Should I fix a failing test or the code it tests? Atlas fixes the production code with the edit tool, not the assertion. Changing an assertion to match broken behavior deletes the only evidence the bug existed, so the Atlas debugging workflow in 2026 reads the test and the module together and treats a failing assertion as a report, not a nuisance. The tempting shortcut when a test fails is to adjust the expected value until the test passes. Atlas is built to resist that. The workflow reads the test and the module it exercises, walks the call path with the lsp tool, and locates the defect in the production code, which is what the edit tool then changes. When the correct fix spans several hunks rather than one contiguous region, apply_patch is used instead of chaining brittle edits, because a multi-hunk fix applied as a sequence of independent edits is fragile against a file that shifts under it. ## Where does the human approve while Atlas debugs a test? While Atlas debugs a failing test, the human approves the bash commands and the diffs. Every Atlas tool call is permission-gated against 3 rule types, allow, ask, and deny, before it runs, and Atlas computes a unified diff for every file edit and surfaces it for approval before writing. Debugging generates a lot of tool calls, and each one is gated. The bash runs that execute the isolated test pass the permission check, so a repository can auto-allow its test command while still prompting on anything else. Every change to a file, whether it is a temporary log line inserted with edit or the real fix applied with apply_patch, is surfaced as a unified diff you approve before it lands. Atlas also snapshots file changes as git patches so edits can be diffed and rolled back, which is exactly what you want when a debugging session has left instrumentation scattered around. ## What do I do after the failing test passes? After the failing test passes, Atlas re-runs the single test, then the full suite, and removes any temporary logging that was added. A fix verified only against the 1 test it targeted can easily break others, and instrumentation left behind in production code is a defect of its own. The Atlas debugging workflow does not end at green. The isolated test is re-run through bash to confirm the fix. The full suite is then run through bash to confirm the fix did not break anything else, which is the step that catches a change to a shared function that satisfied one caller and broke three. Finally, every temporary log line added with edit during the investigation is removed, and the removal arrives as a diff like any other edit. What is left in the repository is a real fix and nothing else. ## Steps 1. Run just the failing test with the bash tool, using the framework's filter flag so the output is small enough to reason about. 2. Read the test and the module it exercises with the read tool, so the assertion and the implementation are in context together. 3. Walk the call path with the lsp tool's goToDefinition operation to reach the code the test actually runs. 4. Run the lsp tool's findReferences operation on the suspect function to see its other callers, which tells you whether the function or the caller is wrong. 5. Form a hypothesis and check it: add temporary logging with the edit tool, or re-run with a verbose flag through bash. Because bash is a real shell, both levers are available. 6. Fix the production code with the edit tool, not the assertion. If the change spans several hunks, use apply_patch instead of chaining brittle edits. 7. Approve the change at the diff. Atlas computes a unified diff for every file edit and surfaces it for approval before writing. 8. Re-run the single test, then the full suite, and remove any temporary logging you added. ## FAQ ### how to debug a single failing test with an AI agent Run it in isolation. Atlas uses the bash tool with the framework's filter flag so only that test runs, reads the test and the module it exercises, walks the call path with the lsp tool, and then fixes the production code with edit. ### why does my AI coding agent change the test instead of fixing the bug Weaker workflows adjust the assertion until it passes. The Atlas debugging workflow explicitly fixes the code, not the assertion, by reading the test alongside the module and tracing the defect with the lsp tool before any edit is made. ### how do I add debug logging with an AI agent and remove it later Atlas adds temporary logging with the edit tool, re-runs the isolated test with bash, and removes the logging as the final step of the workflow. Every insertion and removal arrives as a unified diff you approve. ### how do I know if the function is broken or the caller is wrong Run the lsp tool's findReferences operation on the suspect function. If the other callers pass their tests, the defect is more likely in the arguments the failing path supplies than in the function itself. ### can I run a test with a verbose flag through an AI agent Yes. Atlas's bash tool is a real shell, so a verbose flag, a focused test filter, or any other debugging lever you would use by hand is available. Every bash call is still permission-gated before it runs. ### edit or apply_patch for a debugging fix in Atlas Use edit for a single contiguous change and apply_patch when the fix spans several hunks. Chaining brittle edit calls across a shifting file is the failure mode apply_patch exists to avoid. ### what should I run after fixing a failing test Re-run the single test with bash to confirm the fix, then run the full suite to catch collateral damage, then remove any temporary logging. A fix verified only against its own test can still break other callers. --- Canonical HTML: https://runatlas.sh/resources/workflows/debug-a-failing-test Source of truth: aeo_pages row `/resources/workflows/debug-a-failing-test` (segment: Workflows) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.