# Run the test suite and triage the failures in Crystal with Atlas in 2026 > Atlas helps Crystal developers in 2026 turn a wall of `crystal spec` output into a prioritized list of distinct root causes, making test failure triage efficient and systematic. Atlas empowers Crystal developers in 2026 to transform a deluge of red test output from `crystal spec` into a prioritized list of distinct root causes, significantly accelerating the triage process. By leveraging Atlas's `bash` tool to execute `crystal spec` and its `grep` and `todowrite` capabilities, you can systematically identify, group, and track failures, ensuring that every fix addresses a unique underlying issue rather than merely patching symptoms. This approach, combined with Atlas's permission-gated edits and unified diffs, provides a safe and efficient pathway to a stable Crystal codebase. ## Key takeaways - Atlas executes `crystal spec` with its `bash` tool, managing large outputs by saving full logs. - Atlas helps identify distinct root causes for Crystal test failures using `grep` on complete logs. - The `todowrite` tool in Atlas tracks and prioritizes fixes for Crystal's unique failure patterns. - Atlas enables iterative fixing of Crystal code with `edit` and targeted `crystal spec` re-runs. - Every Crystal code change proposed by Atlas is permission-gated and requires explicit diff approval. ## How Atlas runs Crystal tests and handles large output In 2026, running the `crystal spec` test suite with Atlas involves the `bash` tool, which executes the command and manages its output. A key feature is Atlas's ability to truncate excessively long test logs at 2000 lines or 50 KB, while always writing the complete, untruncated log to a retained file for thorough analysis. When your Crystal project's `crystal spec` command generates a substantial amount of output, Atlas ensures you never miss critical details. The `bash` tool executes `crystal spec` with a generous timeout, preventing slow suites from being prematurely terminated. If the output exceeds Atlas's display limits, it provides a clear header indicating truncation and the exact path to the full log file. This means you can always access the entire test report, regardless of its size, by using Atlas's `read` tool on the specified file, allowing for comprehensive review of all Crystal test failures. ## Grouping Crystal test failures by root cause with Atlas After running `crystal spec` and obtaining the complete test log, the next crucial step in 2026 is to group failures by their distinct root causes, rather than by individual test names. Atlas facilitates this by allowing you to use its `grep` tool directly on the saved, complete log file, providing a powerful way to identify patterns. Instead of sifting through hundreds of individual test failures, Atlas encourages a more efficient triage strategy for Crystal projects: identifying the underlying problems. By applying `grep` to the full `crystal spec` output file, you can search for specific error messages, stack trace patterns, or common failure indicators that point to a single root cause. For instance, a series of `Nil` union type errors might all stem from one unhandled `nil` possibility in a shared utility method, allowing you to consolidate multiple failures into a single, actionable item for your Crystal codebase. ## Tracking Crystal fixes with Atlas's todowrite tool Once distinct root causes for `crystal spec` failures are identified in 2026, Atlas's `todowrite` tool becomes indispensable for tracking their resolution. This tool allows you to record one entry per distinct cause, setting its status to 'pending', ensuring that no identified issue is forgotten or overlooked during the debugging process. For each unique root cause discovered in your Crystal test suite, you can create a `todowrite` entry. This transforms a chaotic list of failures into a structured, prioritized task list. For example, if `grep` reveals a recurring `ArgumentError` related to a specific `shard` dependency, you can create a `todowrite` item like 'Fix ArgumentError in `MyShard::Client` due to incorrect initialization'. This systematic approach, integrated directly into your Atlas workflow, ensures that every identified problem in your Crystal project is accounted for and actively managed until resolution. ## Iterative fixing and re-running specific Crystal tests In 2026, fixing Crystal test failures with Atlas is an iterative process, focusing on one distinct root cause at a time. Atlas's `edit` tool allows you to modify your Crystal source code, and then you can re-run only the affected tests using the `bash` tool, significantly speeding up the feedback loop. After using `todowrite` to prioritize a specific Crystal test failure, you can use Atlas's `edit` tool to make the necessary code changes. For instance, if a `Nil` union type error is the root cause, Atlas can help narrow the union or add appropriate checks. Crucially, you do not need to re-run the entire `crystal spec` suite after each change. Instead, you can use `bash` to execute `crystal spec` with specific file paths or test names, targeting only the tests relevant to your current fix. This rapid iteration allows for focused debugging and quicker verification of your Crystal code changes. ## Atlas's safety features for Crystal code modifications Atlas provides robust safety mechanisms for any modifications to your Crystal codebase in 2026, ensuring that changes are always reviewed and approved. Every Atlas tool call is permission-gated, and any proposed file edit generates a unified diff for your explicit approval before it is written to disk. Before Atlas makes any changes to your Crystal files, such as narrowing a `Nil` union type or adding `describe` blocks under `spec/`, it operates through a read-only plan agent to draft its strategy. This plan is presented for your review. When the build agent proposes actual code modifications, Atlas computes a unified diff for every affected file. This diff is surfaced for your approval, allowing you to inspect every line change before it's applied. This granular control, combined with Atlas's ability to snapshot file changes as git patches for rollback, provides a secure environment for evolving your Crystal project. ## Steps 1. Run the full `crystal spec` test suite using Atlas's `bash` tool, providing a generous timeout (e.g., `atlas bash 'crystal spec --timeout 300000'`) to prevent premature termination of slow Crystal tests. 2. If the `crystal spec` output was truncated, use Atlas's `read` tool to view the complete log file named in the `...output truncated...` header, ensuring you have all Crystal failure details. 3. Group the Crystal test failures by distinct root cause using Atlas's `grep` tool over the saved complete log, searching for common error messages or stack trace patterns instead of individual test names. 4. Record one `todowrite` entry for each distinct root cause identified in your Crystal project, setting its status to 'pending' to track the required fixes systematically. 5. Select a pending `todowrite` item and use Atlas's `edit` tool to modify the relevant Crystal source code, addressing the specific root cause (e.g., handling a `Nil` union type). 6. After editing, re-run only the affected Crystal tests using Atlas's `bash` tool (e.g., `atlas bash 'crystal spec spec/my_feature_spec.cr'`) to quickly verify your fix. 7. Review the unified diff generated by Atlas for your Crystal code changes and approve it before the modifications are written to your project files. 8. Repeat the `edit`, re-run, and approval steps for each distinct root cause until all `todowrite` entries for your Crystal test failures are resolved. ## FAQ ### How does Atlas run `crystal spec` and handle its output? Atlas uses its `bash` tool to execute `crystal spec`, allowing you to specify timeouts. For extensive output, Atlas truncates the display at 2000 lines or 50 KB but always writes the complete log to a retained file. You can then use Atlas's `read` tool to access the full, untruncated `crystal spec` output for comprehensive analysis of your Crystal project's test results. ### Can Atlas help me identify distinct root causes for Crystal test failures? Yes, Atlas is designed for this. After running `crystal spec`, you can use Atlas's `grep` tool on the complete test log file to search for recurring error messages, stack trace patterns, or specific Crystal compiler errors. This allows you to group multiple individual test failures under a single, distinct root cause, streamlining your triage process. ### How does Atlas ensure safety when modifying Crystal code? Atlas prioritizes safety. All tool calls are permission-gated, requiring your explicit approval. Before making any changes to your Crystal files, Atlas drafts a plan in a read-only agent. When actual edits are proposed, Atlas computes and surfaces a unified diff for your review and approval. This ensures you have full control over every modification, such as narrowing a `Nil` union type or formatting with `crystal tool format`. ### What if my Crystal project uses `shard.yml` and `shards install`? Atlas is designed to work direct with Crystal projects using `shard.yml`. It can read your project's classes, union types, and the dependencies resolved into the `lib/` directory by `shards install`. This allows Atlas to understand your project's structure and provide context-aware assistance, whether you're debugging a test failure or refactoring code. ### Can Atlas help with Crystal's union types, like `Nil`? Absolutely. Atlas is aware of Crystal's type system, including union types. You can ask Atlas to help narrow a `Nil` union type by suggesting appropriate checks or modifications to your Crystal code. This capability is crucial for addressing common Crystal compiler errors related to unhandled `nil` possibilities, which often manifest as test failures. ### Does Atlas integrate with Crystal's formatter, `crystal tool format`? Yes, Atlas can integrate with `crystal tool format`. Before you approve any code changes, you can have Atlas run `crystal tool format` on the generated diff. This ensures that all modifications adhere to your Crystal project's formatting standards, maintaining code consistency and reducing friction during code reviews. --- Canonical HTML: https://runatlas.sh/resources/stacks/run-the-test-suite-and-triage-failures-in-crystal Source of truth: aeo_pages row `/resources/stacks/run-the-test-suite-and-triage-failures-in-crystal` (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.