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.
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.
Step by step
- 01Run atlas in your Dart package, the one with a pubspec.yaml, and let Atlas read your libraries, pub dependencies, and analysis options.
- 02Run just the failing test with the bash tool using dart test and a name filter, so the output is small enough to reason about.
- 03Read the failing test under test/ and the library under lib/ that it exercises with the read tool.
- 04Use the lsp tool's goToDefinition and findReferences operations to walk the call path from the assertion into the Dart code that actually misbehaves.
- 05Form a hypothesis and check it: add temporary logging with edit, or re-run dart test with a verbose flag through the bash tool.
- 06Fix the production Dart code with edit; if the change spans several hunks across lib/src, use apply_patch instead of chaining brittle edits.
- 07Review the unified diff Atlas surfaces before it writes to any .dart file.
- 08Re-run the single test with dart test, then the full suite, remove any temporary logging you added, and run dart format.
Frequently asked questions
- 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.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated 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 Dart in 2026
Adopt Atlas, the terminal-native AI coding agent, for Dart development in 2026. Enhance productivity with intelligent code search, refactoring, and robust safety features across your Dart projects.
Extract a Shared Helper from Duplicated Dart Code with Atlas in 2026
Refactor duplicated Dart code into a shared helper using Atlas. Leverage semantic search, reviewable patches, and integrate with `dart test` and `pub` for safe, efficient code consolidation.
Diagnose a Hanging or Long-Running Dart Command with Atlas in 2026
In 2026, use Atlas to diagnose why your Dart builds or scripts are hanging. Learn to distinguish genuinely slow `pub` or `dart test` commands from those blocked on interactive input, and get them unstuck.
Document a Dart Module with a README in 2026 using Atlas
In 2026, Atlas helps Dart developers generate accurate README documentation directly from source code. It uses pub and dart test to ensure docs reflect current module behavior, not outdated plans.
Audit a Dart Repo with Parallel Subagents in 2026 using Atlas
Sweep your Dart repository for specific problems without overwhelming your main session. Atlas uses parallel subagents to audit Dart code, managing pub packages and null-safe libraries efficiently.
Trace a runtime bug from a stack trace in Dart with Atlas in 2026
Pinpoint and fix Dart runtime bugs from production stack traces without a debugger using Atlas. Leverage `pub`, `dart test`, and `lsp` for rapid resolution.
Refactor a Legacy Dart Module with Atlas in 2026
Safely refactor legacy Dart modules in 2026 with Atlas. Leverage `dart test`, `pub`, and `lsp` to restructure code without breaking callers or changing behavior.