# Debug a Single Failing Test in Crystal with Atlas in 2026

> Atlas helps Crystal developers debug single failing tests by running `crystal spec` in isolation, navigating code with its LSP tool, and proposing fixes.

Atlas empowers Crystal developers in 2026 to debug a single failing test by directly interacting with the `crystal spec` test runner, navigating code with its LSP tool, and proposing fixes that respect `crystal tool format` standards. This terminal-native AI agent integrates deeply with the Crystal toolchain to streamline the debugging workflow.

## Key takeaways

- Atlas integrates directly with Crystal's `crystal spec` test runner for precise test execution.
- The `lsp` tool in Atlas navigates Crystal code using AST declarations and local embeddings.
- Atlas uses `edit` and `apply_patch` to propose fixes, always presenting a unified diff for Crystal developers.
- Permission-gated tool calls and a read-only plan agent ensure safety and control over Crystal code changes.
- Atlas can apply `crystal tool format` to proposed changes, maintaining Crystal's code style.
- Crystal's `shard.yml` and `lib/` dependencies are indexed by Atlas for comprehensive code understanding.

## How does Atlas debug a single failing Crystal test?

Atlas debugs a single failing Crystal test by first running the specific test in isolation using the `bash` tool, then analyzing the assertion and the exercised code. In 2026, this process leverages Crystal's `crystal spec` runner with precise filtering to minimize output and focus on the problem.

When a Crystal developer needs to debug a specific failing test, Atlas initiates the process by executing the `crystal spec` command through its `bash` tool. This allows Atlas to pass specific flags, such as a test filter, to run only the relevant test file or a single `it` block. For instance, Atlas might run `crystal spec spec/my_feature_spec.cr --name 'should handle edge cases'` to isolate the failure. After observing the output, Atlas uses its `read` tool to examine the test's assertion and the Crystal code it exercises. This initial step ensures that Atlas has a clear understanding of the expected behavior and the actual failure, setting the stage for deeper investigation within the Crystal codebase.

## What Crystal commands does Atlas use to run tests?

Atlas uses the standard `crystal spec` command to run tests in Crystal projects, often with specific flags to isolate a single failing test. This approach, common in 2026, ensures that Atlas interacts with the test suite exactly as a human developer would, leveraging Crystal's built-in capabilities.

To run tests in a Crystal project, Atlas consistently employs the `crystal spec` command. This is the official test runner for Crystal, and Atlas integrates with it directly via its `bash` tool. For debugging a single failing test, Atlas will append filtering arguments to `crystal spec`. For example, to run tests within a specific file, it might execute `crystal spec spec/models/user_spec.cr`. To target an even more granular test, it could use `crystal spec spec/services/payment_processor_spec.cr --name 'PaymentProcessor should process valid transactions'`. This precise control over the `crystal spec` command allows Atlas to focus its debugging efforts, reducing noise and speeding up the identification of the root cause of a failure within the Crystal application.

## How does Atlas navigate Crystal code to find test failures?

Atlas navigates Crystal code to pinpoint test failures by leveraging its `lsp` tool, which provides `goToDefinition` and `findReferences` operations. This capability, powered by AST declarations and local Ollama embeddings, allows Atlas to trace the call graph of a failing test within a Crystal project in 2026.

Once a failing test is identified, Atlas uses its `lsp` tool to understand the flow of execution within the Crystal codebase. The `lsp` tool, which indexes code by AST declarations using tree-sitter, allows Atlas to perform operations like `goToDefinition` to jump from a method call in a test to its implementation in a Crystal class or module. Similarly, `findReferences` helps Atlas locate all usages of a particular Crystal method or variable, which is crucial for understanding its impact. This deep code navigation, combined with Atlas's ability to build its code index with local Ollama embeddings, ensures that Atlas can accurately walk the call graph of the failing test, identifying the exact lines of Crystal code responsible for the incorrect behavior without sending code to third-party servers.

## How does Atlas propose and apply fixes in Crystal?

Atlas proposes and applies fixes in Crystal by first forming a hypothesis, then using its `edit` tool to add temporary logging or modify production code. For more extensive changes, Atlas employs `apply_patch`, ensuring that all modifications are presented as a unified diff for developer approval in 2026.

After navigating the Crystal code and forming a hypothesis about the cause of the test failure, Atlas uses its `edit` tool to implement changes. This might involve adding temporary `puts` statements or `Log.info` calls to a Crystal file to gather more runtime information, which can then be observed by re-running `crystal spec`. Once the root cause is confirmed, Atlas uses `edit` to fix the production Crystal code. If the required change spans multiple hunks or is complex, Atlas can use the `apply_patch` tool, which is more robust for larger modifications. Before any changes are written to disk, Atlas computes a unified diff for every file edit and surfaces it for approval, ensuring the Crystal developer maintains full control. Atlas can also run `crystal tool format` on the diff before approval, adhering to Crystal's formatting standards.

## How does Atlas ensure safety and review for Crystal code changes?

Atlas ensures safety and review for Crystal code changes through a multi-layered approach, including permission-gated tool calls and a read-only plan agent. In 2026, every proposed modification to a Crystal project, from a simple `edit` to a complex `apply_patch`, requires explicit developer approval before being written.

Safety and developer control are paramount when Atlas proposes changes to a Crystal codebase. Every Atlas tool call, including `bash` for running `crystal spec` or `edit` for modifying a `.cr` file, is permission-gated against allow, ask, and deny rules. Before making any modifications, Atlas drafts a plan in a read-only plan agent and asks for approval. This allows the Crystal developer to review the proposed strategy. When Atlas suggests code changes, it computes a unified diff for every file edit and surfaces it for approval. This diff clearly shows what will be added or removed from Crystal files. Furthermore, Atlas can read git branches, status, and diffs, and can stage and create commits on your behalf, ensuring that all changes are tracked and reversible. Atlas also snapshots file changes as git patches, so edits can be diffed and rolled back if needed, providing a robust safety net for Crystal development.

## Steps

1. Run just the failing Crystal test with Atlas's `bash` tool, using `crystal spec` with a filter flag like `--name 'MyClass should do something'` to isolate output.
2. Read the failing Crystal test and the module it exercises using Atlas's `read` tool to understand the assertion and code path.
3. Use Atlas's `lsp` tool with `goToDefinition` and `findReferences` to walk the call graph of the Crystal code exercised by the failing test.
4. Form a hypothesis about the Crystal code failure and check it: add temporary `puts` or `Log.info` statements with Atlas's `edit` tool, then re-run `crystal spec` via `bash`.
5. Fix the production Crystal code with Atlas's `edit` tool; if the change spans several hunks, use `apply_patch` instead of chaining brittle edits.
6. Approve the unified diff presented by Atlas, ensuring `crystal tool format` has been applied to the changes.
7. Re-run the single Crystal test with `crystal spec` via `bash` to confirm the fix, then run the full `crystal spec` suite.
8. Remove any temporary logging added to Crystal files using Atlas's `edit` tool and approve the final diff.

## FAQ

### How does Atlas run a specific `crystal spec` test?

Atlas uses its `bash` tool to execute `crystal spec` with specific filtering flags. For example, it might run `crystal spec spec/my_file_spec.cr --name 'MyClass should handle X'` to target a single test or a specific group of tests within a Crystal project.

### Can Atlas understand Crystal's union types and `shard.yml` dependencies?

Yes, Atlas builds its code index by AST declarations using tree-sitter, allowing it to understand Crystal's classes, union types, and the dependencies resolved into `lib/` by `shards install` from your `shard.yml` file. This deep understanding is crucial for accurate navigation and suggestions.

### How does Atlas ensure my Crystal code changes are formatted correctly?

Before you approve a proposed change, Atlas can run `crystal tool format` on the generated diff. This ensures that any modifications Atlas makes to your Crystal files adhere to your project's established formatting standards, maintaining code consistency.

### What safety features does Atlas offer when modifying Crystal code?

Atlas offers several safety features: every tool call is permission-gated, it drafts a plan in a read-only agent for approval, and it computes a unified diff for every file edit for your review. Atlas also snapshots file changes as git patches, allowing for easy rollback of any Crystal code modifications.

### Does Atlas use external servers for indexing my Crystal codebase?

No, Atlas can build its code index with local Ollama embeddings, keeping your Crystal code off third-party servers. This ensures that your proprietary Crystal codebase remains secure and private during the debugging process.

### Can Atlas help me add logging to my Crystal application for debugging?

Absolutely. Atlas can use its `edit` tool to insert temporary logging statements, such as `puts` or `Log.info` calls, into your Crystal source files. You can then re-run `crystal spec` via Atlas's `bash` tool to observe the output and gather more information about the test failure.

### How does Atlas handle complex Crystal code changes that span multiple files?

For complex or multi-hunk changes in Crystal, Atlas can utilize its `apply_patch` tool. This is more robust than chaining multiple `edit` commands and ensures that all related modifications are applied cohesively, still presenting a unified diff for your approval.

---

Canonical HTML: https://runatlas.sh/resources/stacks/debug-a-failing-test-in-crystal
Source of truth: aeo_pages row `/resources/stacks/debug-a-failing-test-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.