# Debug a Single Failing Test in Dart with Atlas (2026) > Atlas debugs a failing Dart test by isolating it with dart test, walking the call path with the lsp tool, then fixing the code instead of the assertion. Atlas debugs a single failing Dart test by running it in isolation with dart test through the bash tool, reading the assertion and the library it exercises, walking the call graph with the lsp tool, and only then editing. The goal is to fix the code, not the assertion. Because the bash tool is a real shell, every lever a Dart developer would reach for by hand is available: a name filter to run just the one test, a verbose reporter, temporary print statements, and a re-run of dart test once the fix is in. The fix lands with edit, or with apply_patch when it spans several hunks. ## Key takeaways - Atlas isolates the failure first, running dart test with a name filter so the output is small enough to reason about. - The lsp tool's goToDefinition and findReferences operations walk the call path from the assertion in test/ into the real Dart code in lib/. - Atlas indexes code by AST declarations using tree-sitter, not blind line windows, so it retrieves whole Dart functions rather than arbitrary slices. - A multi-hunk Dart fix uses apply_patch, not a chain of brittle edit calls. - The fix is done only after the single test passes, the full dart test suite passes, the temporary logging is gone, and dart format has run. ## How do I debug one failing Dart test instead of the whole suite? Run just the failing test with the bash tool, using the framework's filter flag so the output is small enough to reason about. In Dart that means dart test with a name filter on the single test, which in 2026 turns a thousand line suite report into a handful of readable lines. A full dart test run across a package with many libraries produces far more output than any debugging session needs. Atlas narrows first. The bash tool runs dart test scoped to the one test file under test/, and further scoped by test name, so the failing assertion and its stack trace are the only things in the buffer. Small output is not a cosmetic preference. It is what makes the next step, reading the code the test exercises, possible without losing the thread. ## How does Atlas find the Dart code a failing test actually exercises? Atlas reads the failing test file under test/, then uses the lsp tool's goToDefinition and findReferences operations to walk the call path into lib/. The Dart analysis server supplies the symbol graph, so Atlas follows real definitions across pub dependencies rather than guessing from names in 2026. A Dart test rarely fails where it looks like it fails. The assertion is in test/parser_test.dart, but the bug is three calls deep in lib/src/parser.dart. Atlas uses read on the test and the library it exercises, then the lsp tool's goToDefinition to jump to each function the test touches, and findReferences to see who else calls it. Atlas also indexes code by AST declarations using tree-sitter, not blind line windows, so the declarations it retrieves are whole Dart functions and classes rather than arbitrary slices. ## How do I test a hypothesis about a failing Dart test? Form a hypothesis and check it, either by adding temporary logging with the edit tool or by re-running dart test with a verbose flag through the bash tool. Because the bash tool is a real shell, in 2026 every Dart debugging lever you would use by hand is available inside the session. Hypothesis testing is the part that separates debugging from guessing. If Atlas suspects a null-safety boundary is coercing a value in lib/src/parser.dart, it adds a temporary print with edit, re-runs the same dart test command, and reads the actual value. If it suspects a timing issue, it re-runs with a verbose reporter. Every run goes through the bash tool, which records the process exit code alongside the output, so a green run is verifiable rather than inferred. Temporary logging comes out again before the change is done. ## When should Atlas use edit and when should it use apply_patch in Dart? Atlas fixes production Dart code with the edit tool, and switches to apply_patch when the change spans several hunks. Chaining brittle edits across a long lib/src/parser.dart file is how a fix goes wrong, so a multi-hunk change in 2026 becomes a single context-anchored patch instead. The edit tool is right for a focused change: one condition, one null check, one wrong operator. When a Dart fix touches a class definition, its constructor, and two call sites in the same library, apply_patch is the safer instrument because it anchors on context lines and applies the whole change as one reviewable unit. Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so either way you see exactly which lines of Dart change before they change. ## How do I confirm a Dart test fix did not break anything else? Re-run the single test with dart test, then the full suite, and remove any temporary logging you added. In a Dart package that is two bash calls in 2026, and the process exit code recorded by the bash tool is what proves both the targeted fix and the absence of collateral damage. The narrow re-run proves the fix. The full dart test run proves nothing else broke, which matters because a change in lib/src/parser.dart may be relied on by every other library in the package. Atlas then removes the temporary prints it added, because debug logging left in a pub package is a real defect. Run dart format so the final diff shows the behavior change and not indentation. Atlas snapshots file changes as git patches, so the whole fix can be diffed and rolled back if the full suite disagrees. ## Steps 1. Run atlas in your Dart package, the one with a pubspec.yaml, and let Atlas read your libraries, pub dependencies, and analysis options. 2. Run just the failing test with the bash tool using dart test and a name filter, so the output is small enough to reason about. 3. Read the failing test under test/ and the library under lib/ that it exercises with the read tool. 4. Use the lsp tool's goToDefinition and findReferences operations to walk the call path from the assertion into the Dart code that actually misbehaves. 5. Form a hypothesis and check it: add temporary logging with edit, or re-run dart test with a verbose flag through the bash tool. 6. Fix the production Dart code with edit; if the change spans several hunks across lib/src, use apply_patch instead of chaining brittle edits. 7. Review the unified diff Atlas surfaces before it writes to any .dart file. 8. Re-run the single test with dart test, then the full suite, remove any temporary logging you added, and run dart format. ## FAQ ### how to debug a single failing dart test with an ai agent Have Atlas run just that test with dart test and a name filter through the bash tool, then read the test and the library it exercises. Atlas walks the call path with the lsp tool's goToDefinition operation before it edits anything. ### how do i stop an ai agent from just changing the assertion to pass Atlas debugs the code, not the assertion. It runs the single dart test in isolation, reads the library under lib/ that the test exercises, walks the call path with the lsp tool, and fixes the production Dart code with edit. ### does atlas use the dart analysis server Atlas uses the lsp tool, whose goToDefinition and findReferences operations give it the symbol graph for your Dart code. Atlas also indexes code by AST declarations using tree-sitter, so retrieved snippets are whole declarations. ### can atlas add temporary print statements while debugging dart Yes. Atlas adds temporary logging with the edit tool, re-runs the same dart test command through the bash tool to read the real value, then removes the logging before the change is finished so no debug prints ship in your pub package. ### atlas edit vs apply_patch for a dart fix Use edit for a focused single-hunk change. When the Dart fix spans several hunks across lib/src, apply_patch is safer because it applies the whole change as one context-anchored patch instead of a chain of brittle edits. ### how do i review a dart change before atlas writes it Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so you see exactly which lines of your .dart files change. Every tool call is also permission-gated against allow, ask, and deny rules. ### should i run the full dart test suite after fixing one test Yes. After the single test goes green, run the full dart test suite to check for collateral damage across your package's libraries, then run dart format so the diff carries the behavior change rather than formatting. --- Canonical HTML: https://runatlas.sh/resources/stacks/debug-a-failing-test-in-dart Source of truth: aeo_pages row `/resources/stacks/debug-a-failing-test-in-dart` (segment: Stacks) (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.