# Add a Regression Test for a Bug Fix in Dart with Atlas (2026) > In Dart, Atlas proves the bug with a failing `dart test` run whose exit code is recorded in bash metadata, applies the fix, then re-runs the identical command to confirm green. To add a regression test for a bug fix in Dart, follow red first, then green. Atlas writes the failing test with the write tool, runs it with `dart test` to prove it reproduces the bug, applies the fix with edit or apply_patch, and re-runs the exact same command. Because Atlas's bash tool records the real process exit code in its metadata alongside the output, the failing state and the passing state are unambiguous rather than inferred from scrolling text. A regression test that was never observed failing proves nothing: it may pass for reasons unrelated to the bug. The final step is the wider `dart test` suite, to check the fix for collateral damage. ## Key takeaways - Red first, then green: a Dart regression test must be observed failing with `dart test` before the fix exists. - Atlas's bash tool records the process exit code in its metadata, so the pass and fail states of `dart test` are unambiguous. - The edit tool's replacer cascade requires an exact-enough oldString and refuses ambiguous multi-match replacements in `lib/src/`. - Use apply_patch rather than chained edits when the Dart fix spans several hunks in one file. - Re-run the identical command, not a variation, then run the wider suite and `dart format`. ## Why must a Dart regression test fail before the fix? A Dart regression test that was never observed failing proves nothing. Atlas runs the new test with `dart test` before the fix exists and confirms it is red, because a spec that exits 0 both before and after the change is testing something other than the bug you just fixed. Red first is the whole discipline. Suppose a Dart parser returns null for an empty input instead of throwing a FormatException. Write the test to assert the observed wrong behavior is gone, run it against the unfixed library, and watch it fail with a concrete message. Only then is the assertion known to be load-bearing. Skipping the red step is how repositories accumulate tests that never guarded anything: they were written against already-fixed code, they went green immediately, and nobody noticed that removing the fix would leave them green. ## How does Atlas prove a Dart test failed rather than errored? Atlas's bash tool records the process exit code in its metadata alongside the output, so a `dart test` run that exits 0 and one that exits non-zero are unambiguous. A Dart suite that fails to compile and one that fails an expect both exit non-zero, and the metadata plus the output separate them. Reading test output as prose invites mistakes. The exit code is the ground truth for whether `dart test` succeeded, and Atlas has it in structured form rather than parsing it out of a summary line. Combine the code with the failure text: a genuine red regression test reports the expect mismatch you predicted, with the expected and actual values printed. If instead the failure is an unresolved import or a null-safety analyzer complaint, the test never ran the code path at all, and its failure is worthless as proof. Verify that the reason it is red is the reason you intended. ## How does Atlas apply the Dart fix without breaking the file? Atlas applies the fix with the edit tool, whose replacer cascade requires an exact-enough oldString and refuses ambiguous multi-match replacements. In Dart that guard matters, because a common expression such as `return null;` may occur 8 times in `lib/src/parser.dart` and a loose match would rewrite the wrong one. The refusal is a feature. When Atlas's edit tool cannot uniquely identify the text to replace, it declines rather than picking one occurrence and hoping. The fix is then to widen the oldString with surrounding context until it is unique, which is exactly what a careful human would do. When the change spans several hunks across the same Dart file, apply_patch is the better instrument than chaining brittle edits. Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so the change to `lib/src/parser.dart` is reviewed before it lands. ## How do I confirm the Dart fix actually turned the test green? Re-run the identical `dart test` command that produced the red result and confirm it now exits 0, rather than a variation of it. Changing the invocation between the 2 runs is how a fix appears to work: a narrower filter, a different path, or an added flag can produce green for unrelated reasons. Atlas re-runs the same bash command and confirms the test now passes, with the exit code again recorded in the metadata. Green from the identical command that was red is real evidence. After that, run the wider `dart test` suite to check for collateral damage, because a fix to a null-handling path in one Dart library frequently changes behavior for callers whose tests live elsewhere in `test/`. Run `dart format` over the touched files last so the commit carries the fix and the regression test rather than formatting drift. ## What does a Dart regression test commit contain? A complete Dart regression commit contains exactly 2 things: the new test under `test/` ending in `_test.dart`, and the fix in `lib/`. Atlas reads git branches, status, and diffs, so the final review confirms `pubspec.yaml` and unrelated libraries were not dragged along with the change. Keeping the commit tight is what makes the regression test useful a year from now, because the pairing of a test and the exact fix it guards is the record of why the code looks the way it does. Atlas snapshots file changes as git patches, so if the review turns up an unwanted edit it can be diffed and rolled back rather than hand-reverted. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, so `dart test` and `pub` can be allow rules while writes to `lib/` stay on ask. ## Steps 1. Reproduce the bug once with Atlas's bash tool and capture the exact failing command and output, so the regression test targets observed behavior rather than a description of it. 2. Write the regression test with the write tool into `test/`, ending the filename in `_test.dart`, asserting on the observed wrong behavior. 3. Run the test with bash by invoking `dart test` and confirm it fails; the tool records the process exit code in its metadata alongside the output. 4. Verify the test is red for the right reason: an expect mismatch, not an unresolved import or a null-safety analyzer complaint that never reached the code path. 5. Apply the fix in `lib/` with the edit tool, whose replacer cascade requires an exact-enough oldString and refuses ambiguous multi-match replacements. 6. Use apply_patch instead of chained edits when the fix spans several hunks in the same Dart file. 7. Re-run the identical `dart test` command and confirm the test now passes, with the exit code again recorded in the bash metadata. 8. Run the wider `dart test` suite to check for collateral damage, then run `dart format` so the commit carries the fix and the test rather than formatting drift. ## FAQ ### how to write a regression test in dart for a bug fix Write the test with the write tool asserting on the observed wrong behavior, run `dart test` and confirm it fails, apply the fix in `lib/` with edit, then re-run the identical command and confirm it passes. Finish by running the wider `dart test` suite. ### why should a regression test fail first A test that passes both before and after the fix is testing something other than the bug. Observing it red proves the assertion is load-bearing. Atlas records the `dart test` exit code in its bash metadata, so the red state is verified rather than assumed. ### atlas edit tool refuses ambiguous replacement Atlas's edit replacer cascade requires an exact-enough oldString and refuses ambiguous multi-match replacements. In Dart, a common line like `return null;` can appear many times in one file, so widen the oldString with surrounding context until it uniquely identifies the target. ### when to use apply_patch instead of edit in dart Use apply_patch when the Dart fix spans several hunks in the same file. Chaining brittle edits across a file whose content shifts with each write is more fragile than applying one patch. ### dart test exit code meaning in atlas Atlas's bash tool records the real process exit code in its metadata alongside the output, so a non-zero `dart test` exit is unambiguous. Read the failure text too, since a compile error and a failed expect both exit non-zero but mean very different things. ### my dart regression test fails on an import not the bug Then the test never reached the code path and its failure proves nothing. Fix the import or the missing required parameter first, get the test failing on the expect mismatch you predicted, and only then apply the fix in `lib/`. ### should i change the test command between the red and green run No. Re-run the identical `dart test` command. A narrower filter or an added flag can produce green for reasons unrelated to the fix, which destroys the evidence the red run gave you. ### what should a dart bug-fix commit contain The new `_test.dart` under `test/`, the fix in `lib/`, and nothing else. Atlas reads git status and diffs so you can confirm `pubspec.yaml` and unrelated libraries were not dragged in, and it snapshots changes as git patches so an unwanted edit can be rolled back. --- Canonical HTML: https://runatlas.sh/resources/stacks/add-a-regression-test-for-a-bug-fix-in-dart Source of truth: aeo_pages row `/resources/stacks/add-a-regression-test-for-a-bug-fix-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.