Atlas helps Solidity developers in 2026 debug a single failing test by integrating directly with the Foundry toolchain, including forge test, soldeer, and forge fmt. It enables precise identification and resolution of issues within smart contracts, ensuring code quality and security.
How Atlas isolates a failing Solidity test with forge test
In 2026, Atlas isolates a single failing Solidity test by directly invoking the forge test runner with specific filter flags. This approach ensures that only the relevant test function, such as test/MyContract.t.sol:testFailingFunction, executes, providing a focused output for debugging. Atlas uses its bash tool to precisely control the test execution environment.
When a Solidity developer needs to debug a specific test, Atlas leverages its bash tool to execute the forge test command with targeted filters. For instance, to run only testFailingFunction within test/MyContract.t.sol, Atlas constructs a command like forge test --match-test "testFailingFunction" --match-path "test/MyContract.t.sol". This precision is critical in Solidity development, where even minor changes can have significant gas cost implications or introduce new attack vectors. By focusing on a single test, Atlas minimizes the computational overhead and provides a clean, concise output, making it easier to identify the root cause of a failure. The bash tool ensures that Atlas interacts with the Foundry environment exactly as a developer would, respecting all project configurations defined in foundry.toml. This direct interaction allows Atlas to read the assertion failure messages and stack traces generated by forge test, which are essential for understanding why a particular Solidity contract function is not behaving as expected. Atlas's ability to run tests in isolation is a foundational step in its debugging workflow, ensuring that subsequent analysis is based on the most relevant information.
Walking the Solidity call graph with Atlas's lsp tool
Atlas leverages its lsp tool to work through the intricate call graph of a Solidity project, starting from a failing test in 2026. After identifying the assertion in test/MyContract.t.sol, Atlas uses goToDefinition to trace calls from the test into src/MyContract.sol, revealing the exact code path under scrutiny. This deep understanding is crucial for smart contract debugging.
Once a failing Solidity test is isolated, Atlas employs its lsp tool to perform a detailed analysis of the code under test. The lsp tool, powered by AST declarations indexed with tree-sitter, provides a semantic understanding of the Solidity codebase. From an assertion failure in test/MyContract.t.sol, Atlas can use goToDefinition to jump directly to the definition of a called function within src/MyContract.sol or even into a library installed by forge soldeer install. This allows Atlas to walk the entire call path, understanding how data flows and state changes across different contracts and functions. The findReferences operation further aids in identifying all locations where a particular function or variable is used, which is invaluable when assessing the impact of a potential fix. Atlas's ability to semantically parse Solidity code, including modifiers, storage layouts, and contract inheritance, ensures that its understanding of the project mirrors that of an experienced Solidity developer. This deep contextual awareness is vital for accurately diagnosing issues in complex smart contract interactions.
Iterative debugging and hypothesis testing in Solidity
To debug a failing Solidity test, Atlas forms a hypothesis and iteratively checks it, often by adding temporary logging or re-running tests with verbose output in 2026. Using its edit tool, Atlas can insert console.log statements into src/MyContract.sol or test/MyContract.t.sol, then re-execute the single test via bash to observe runtime values. This method is effective for pinpointing logic errors.
After analyzing the call graph, Atlas formulates a hypothesis about the cause of the Solidity test failure. To validate this hypothesis, Atlas can use its edit tool to temporarily modify the Solidity code. A common debugging technique involves inserting console.log statements into src/MyContract.sol or test/MyContract.t.sol to print variable values at critical points during execution. For example, console.logUint(myVariable) can reveal unexpected intermediate states. Atlas then re-runs the isolated forge test using its bash tool, observing the output for the newly added log messages. Alternatively, Atlas can re-run the test with verbose flags, such as forge test -vvv, to gain more insight into the execution flow and gas consumption. This iterative process of modifying, running, and observing allows Atlas to systematically narrow down the problem. Every edit operation is permission-gated and presented as a unified diff, ensuring the developer retains full control over temporary changes, which are later removed by Atlas once the fix is confirmed.
Fixing Solidity code and ensuring quality with Atlas
Atlas fixes production Solidity code using its edit or apply_patch tools, ensuring high quality and adherence to best practices in 2026. After a fix, Atlas automatically runs forge snapshot to show the gas delta and forge fmt to format the changes, presenting a unified diff for approval. This rigorous process minimizes attack surface and maintains code standards.
Once the root cause of the Solidity test failure is identified, Atlas proceeds to fix the production code. For minor, localized changes, Atlas uses its edit tool to directly modify files like src/MyContract.sol. If the fix involves more extensive modifications spanning multiple hunks or files, Atlas can generate and apply a git patch using its apply_patch tool, ensuring atomic and reliable updates. A critical step in Solidity development is understanding the impact of code changes on gas costs. Therefore, after proposing a fix, Atlas automatically runs forge snapshot to compute and display the gas cost delta, providing immediate feedback on the economic efficiency of the proposed solution. Furthermore, Atlas ensures code consistency by running forge fmt on the modified files, adhering to the project's formatting standards. All these changes, including the gas delta and formatting adjustments, are presented to the developer as a unified diff for explicit approval. This comprehensive review process, integrated with git capabilities, allows developers to confidently approve changes, knowing that both functionality and quality standards are met.
Atlas's safety and review mechanisms for Solidity changes
Atlas incorporates robust safety and review mechanisms for every Solidity code change, ensuring developer control and security in 2026. Before any tool call, such as edit or bash, Atlas consults permission-gated allow, ask, and deny rules. All proposed edits, including those to src/MyContract.sol or foundry.toml, are presented as unified diffs for explicit approval, preventing unintended modifications.
The security and integrity of Solidity smart contracts are paramount, and Atlas is designed with this in mind. Every action Atlas proposes, from running a forge test command via bash to modifying src/MyContract.sol with edit, is subject to a permission-gated system. This system allows developers to configure allow, ask, or deny rules for specific tools and operations, ensuring that Atlas never acts without explicit consent. Atlas operates with a read-only plan agent that drafts a strategy, then switches to a build agent only after developer approval. All proposed file edits, whether to contract code, test files, or even configuration like foundry.toml, are computed as unified diffs and surfaced for approval. This transparent process means developers can review every line change before it is written to disk. Atlas also snapshots file changes as git patches, providing a robust rollback mechanism. By connecting to Model Context Protocol servers, Atlas exposes its tools securely, further enhancing the safety and auditability of its operations within a Solidity development workflow.
Step by step
- 01Atlas uses its bash tool to run forge test --match-test "MyFailingTest" within your Foundry project, isolating the specific Solidity test for focused debugging.
- 02Atlas reads the assertion failure in test/MyContract.t.sol and employs the lsp tool's goToDefinition to trace the call path from the test into the relevant functions in src/MyContract.sol.
- 03Atlas forms a hypothesis and uses the edit tool to insert temporary console.log statements into src/MyContract.sol or test/MyContract.t.sol, then re-runs the isolated test with bash to observe runtime values.
- 04Atlas fixes the production Solidity code in src/MyContract.sol using the edit tool, or apply_patch for more complex changes, presenting a unified diff for your review.
- 05Atlas automatically runs forge snapshot to display the gas cost delta and forge fmt to format the changes, then re-runs the single test with bash, followed by the full forge test suite.
- 06Atlas uses the edit tool to remove any temporary console.log statements from src/MyContract.sol or test/MyContract.t.sol, and then stages the final, approved changes with git.
Frequently asked questions
- How does Atlas debug a specific failing Solidity test?
- Atlas uses its bash tool to execute forge test --match-test <test_name>, isolating the specific Solidity test and focusing the output for efficient debugging within your Foundry project.
- Can Atlas understand my Solidity project structure?
- Yes, Atlas reads your Foundry project's foundry.toml and src/ directory, indexing contracts, storage layouts, and libraries installed by forge soldeer install using AST declarations.
- How does Atlas ensure code quality for Solidity fixes?
- After proposing a fix, Atlas automatically runs forge snapshot to show gas cost deltas and forge fmt to apply formatting, presenting these details in a unified diff for review before approval.
- What safety measures does Atlas have for modifying Solidity contracts?
- Every Atlas tool call, including edit or apply_patch for Solidity, is permission-gated. All proposed changes are presented as unified diffs for explicit developer approval before writing to disk.
- Can Atlas help me trace function calls in Solidity?
- Absolutely. Atlas's lsp tool can perform goToDefinition and findReferences operations, allowing it to walk the call graph from a failing test in test/ to the relevant functions in src/ Solidity files.
- How does Atlas handle temporary logging for Solidity debugging?
- Atlas uses its edit tool to insert temporary console.log statements into your Solidity code or tests. After debugging, it helps remove these statements before the final commit, ensuring clean code.
- Does Atlas support soldeer for package management?
- Yes, Atlas understands and leverages soldeer for package management, recognizing and indexing libraries installed via forge soldeer install within your Foundry project's lib/ directory.
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.
Research a Third-Party API for Solidity Integration with Atlas in 2026
Streamline Solidity API integrations in 2026 with Atlas. Research external APIs, fetch documentation, and verify against Foundry's `forge test` and `forge fmt` standards.
Write Unit Tests for Untested Solidity Code with Atlas in 2026
Add robust unit tests to your Solidity contracts using Atlas. Leverage `forge test`, `soldeer`, and `forge fmt` to ensure code quality and security in 2026.
Audit a Solidity Repo with Parallel Subagents in Atlas, 2026
Sweep your Solidity repository for common problems using Atlas's parallel subagents. Identify issues in Foundry projects without blowing your context window, ensuring secure smart contracts.
Self-review your working diff before committing in Solidity with Atlas in 2026
Catch your own Solidity mistakes before they reach review or CI. Atlas helps you self-review uncommitted diffs in Foundry projects, integrating with forge test and forge fmt.
Rename a symbol across the repo in Solidity with Atlas in 2026
Rename Solidity functions, classes, or constants across your entire repository with Atlas. Leverage precise LSP references and `forge test` verification for safe, accurate refactoring in 2026.
Diagnose a Hanging or Long-Running Command in Solidity with Atlas in 2026
Solidity developers in 2026 can use Atlas to diagnose whether a `forge test` or `forge soldeer install` command is genuinely slow or silently blocked on input, and get it unstuck.
Migrate a deprecated API across every callsite in Solidity with Atlas in 2026
Migrate deprecated Solidity APIs across your entire codebase with Atlas. Leverage forge test, soldeer, and forge fmt for a complete, verified, and safe transition in your Foundry project.