Atlas helps Godot developers in 2026 add real unit tests to untested modules by leveraging GUT (Godot Unit Test) for execution, gdformat (gdtoolkit) for formatting, and Godot Asset Library (gd-plug) for package management, ensuring new tests match existing repository conventions.
How does Atlas find untested Godot code and existing test patterns?
Atlas identifies untested Godot code by reading .gd scripts and enumerating exported symbols using the lsp tool's documentSymbol operation. It then greps for existing test files, like those under test/, to copy the repository's framework, import style, and naming conventions, ensuring new tests integrate direct. This process ensures 100% of public functions are considered for testing.
Atlas begins by thoroughly understanding your Godot project. It uses its `read` tool to ingest the target Godot module's `.gd` script. Following this, Atlas employs the `lsp` tool's `documentSymbol` operation to precisely enumerate all exported symbols within that script. This ensures that every public function and property is identified as a candidate for testing, leaving no part of the module's public API unexamined. To maintain consistency with your existing codebase, Atlas then uses the `grep` tool to search for existing test files. Typically, these are found within a `test/` directory. By analyzing these existing files, Atlas learns your repository's specific `GUT (Godot Unit Test)` framework setup, preferred import styles, and established naming conventions. This crucial step allows Atlas to generate new test files that direct integrate into your project's established testing ecosystem, rather than introducing foreign patterns.
How does Atlas write new unit tests for Godot modules?
Atlas writes new unit test specifications for Godot modules using its write tool, which drafts the test file based on the identified conventions and module symbols. Before any changes land on disk, Atlas presents a unified diff for review, allowing developers to approve or modify the proposed GUT (Godot Unit Test) scripts. This ensures precise control over the 100% new test code.
Once Atlas has a clear understanding of the module under test and the repository's testing conventions, it proceeds to draft the new unit test file. The `write` tool is central to this process. Atlas generates a new `.gd` script, typically placed under the `test/` directory, that adheres to the `GUT (Godot Unit Test)` framework. This script includes test cases for the previously enumerated public symbols, following the learned naming and import conventions. A critical safety feature of Atlas is its permission-gated workflow: before any generated code is written to disk, Atlas computes a unified diff. This diff is presented to the developer for explicit approval. This allows you to review every proposed change, ensuring the new `GUT` test code meets your expectations and accurately reflects the desired test coverage for your Godot module. You retain full control over what gets written to your project.
How does Atlas run and iterate on Godot unit tests?
Atlas runs Godot unit tests using the bash tool, executing godot --headless -s addons/gut/gut_cmdln.gd to run GUT (Godot Unit Test) suites headlessly. If the output exceeds 2000 lines or 50 KB, Atlas truncates it in the terminal but saves the full log to a file for detailed review. Developers then iterate with the edit tool until all tests pass.
The true value of a test lies in its execution. Atlas uses its `bash` tool to run the newly created `GUT (Godot Unit Test)` suite. For Godot projects, this means executing the command `godot --headless -s addons/gut/gut_cmdln.gd`. This command runs the `GUT` test runner in a headless environment, meaning the Godot editor does not need to be open, making the testing process efficient and automatable. Atlas captures the output of this command, displaying it in the terminal. If the test output is extensive, exceeding 2000 lines or 50 KB, Atlas intelligently truncates the terminal display to maintain readability while saving the complete log to a file for comprehensive review. After reviewing the test failures, developers can use the Atlas `edit` tool to modify the test code or the module under test. For larger modules or complex test suites, the `todowrite` tool can be employed to manage progress, breaking down the iteration process into manageable steps until the entire suite is green.
How does Atlas ensure safety and review for Godot test changes?
Atlas ensures safety and review for Godot test changes by presenting a unified diff for every file edit before writing to disk, requiring explicit approval. It also reads git branches, status, and diffs, allowing it to stage and create commits on your behalf. This process provides 100% transparency and control over all modifications.
Safety and developer control are paramount in Atlas's workflow. Every single file edit proposed by Atlas, whether it's writing a new `GUT (Godot Unit Test)` script or modifying an existing `.gd` file, is first presented as a unified diff. This diff must be explicitly approved by the developer before any changes are written to disk. This permission-gated approach ensures that you always have the final say on modifications to your Godot project. Beyond individual file edits, Atlas deeply integrates with `git`. It can read your current `git` branch, status, and existing diffs. Once the test suite is passing and you are satisfied with the changes, Atlas can stage the modified `.gd` scripts and even create commits on your behalf, streamlining the version control process. Furthermore, Atlas can run `gdformat (gdtoolkit)` over the touched scripts, ensuring that all new and modified Godot code adheres to your project's established formatting standards before committing.
What is the setup for Atlas to test Godot projects?
To set up Atlas for Godot testing, run Atlas in a project with a project.godot file at its root. Allow Atlas to read your .gd scripts, understand node paths like $Node or get_node, and recognize autoload singletons from project settings. This initial setup ensures Atlas has a complete understanding of your Godot project's structure and dependencies, enabling it to generate accurate tests for 100% of your public API.
Getting Atlas ready to work with your Godot project is straightforward. You simply need to run Atlas from the root directory of your Godot project, ensuring that the `project.godot` file is present. This file is crucial as it defines your project's structure and settings. Atlas is designed to understand the intricacies of Godot development. It will read your `.gd` scripts, parsing them to comprehend the logic. Crucially, Atlas also understands how Godot's scene structure works, recognizing node paths accessed via the `$` shorthand or the `get_node` method. It also processes the `project.godot` settings to identify and understand any `autoload` singletons you have configured. This comprehensive understanding of your Godot project's code, scene structure, and global resources allows Atlas to generate highly relevant and accurate `GUT (Godot Unit Test)` scripts that correctly interact with your game's components.
Step by step
- 01Run Atlas in your Godot project root, ensuring a `project.godot` file is present.
- 02Ask Atlas to `read` your target Godot module's `.gd` script and use the `lsp` tool's `documentSymbol` operation to enumerate its exported symbols.
- 03Instruct Atlas to `grep` for an existing test file, typically under `test/`, to identify the repository's `GUT (Godot Unit Test)` framework, import style, and naming conventions.
- 04Use the Atlas `write` tool to draft the new `GUT (Godot Unit Test)` spec file, reviewing the unified diff before it's written to disk.
- 05Execute the new test suite with the Atlas `bash` tool, running `godot --headless -s addons/gut/gut_cmdln.gd` to observe failures.
- 06Iterate on the test code using the Atlas `edit` tool until the `GUT (Godot Unit Test)` suite passes, utilizing `todowrite` for larger modules.
- 07Let Atlas run `gdformat (gdtoolkit)` over the touched `.gd` scripts to ensure consistent formatting.
- 08Review the final diffs and allow Atlas to stage and commit the changes to your `git` repository.
Frequently asked questions
- How does Atlas find functions to test in Godot?
- Atlas uses the `lsp` tool's `documentSymbol` operation to enumerate all exported symbols from your Godot `.gd` scripts, ensuring no public function is missed for testing.
- Can Atlas run Godot tests without opening the editor?
- Yes, Atlas uses the `bash` tool to run `GUT (Godot Unit Test)` suites headlessly with the command `godot --headless -s addons/gut/gut_cmdln.gd`.
- How does Atlas ensure new Godot tests match my project's style?
- Atlas `grep`s your existing Godot test files to learn and replicate your repository's `GUT (Godot Unit Test)` framework, import style, and naming conventions.
- What Godot formatting tool does Atlas use?
- Atlas integrates with `gdformat (gdtoolkit)` to automatically format touched Godot `.gd` scripts, ensuring consistent code style across your project.
- How does Atlas handle large Godot modules during testing?
- For large Godot modules, Atlas can use the `todowrite` tool to manage progress, breaking down the testing task into manageable steps.
- Is it safe to let Atlas modify my Godot code?
- Yes, Atlas provides a unified diff for every file edit and requires explicit approval before writing any changes to your Godot `.gd` scripts or `project.godot` file.
- Does Atlas understand Godot's scene structure?
- Atlas reads your `.gd` scripts, understands node paths accessed via `$` or `get_node`, and recognizes `autoload` singletons from your `project.godot` settings, comprehending scene structure.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Write Unit Tests for Untested Code with Atlas in 2026
How to write unit tests for untested code with Atlas in 2026: the lsp tool enumerates exported symbols, grep copies repo conventions, and bash actually runs the suite.
Atlas for Godot: Terminal-Native AI Coding for GDScript and the Node Tree in 2026
Atlas is a terminal-native AI coding agent for Godot in 2026, working across GDScript, the node tree, and signals, where scene structure is half the program.
Research a third-party API before integrating it in Godot with Atlas in 2026
Streamline third-party API integration in Godot with Atlas in 2026. Use Atlas to research API documentation, fetch details, and generate Godot-native code, ensuring compatibility with your `project.godot` and `gdformat`
Run Atlas Headless in CI for Godot Projects in 2026
Automate Atlas sessions in your Godot CI/CD pipelines. Get machine-readable output for GDScript, node trees, and signals, integrating with GUT and gdformat.
Refactor a Legacy Godot Module with Atlas in 2026
Streamline legacy Godot modules in 2026 using Atlas, the terminal-native AI coding agent. Safely restructure GDScript, node paths, and signals without breaking existing callers, leveraging GUT (Godot Unit Test) and
Document a module with a README in Godot with Atlas in 2026
In 2026, Atlas helps Godot developers create accurate READMEs for modules by analyzing live GDScript code, node paths, and signals. Ensure your documentation reflects what your Godot project actually does today.
Rename a symbol across the repo in Godot with Atlas in 2026
Rename functions, classes, and constants across your Godot project with Atlas in 2026. Use `lsp`, `grep`, and `edit` for precise, safe refactoring, catching all references, even those `grep` alone misses.
Self-review your working diff before committing in Godot with Atlas in 2026
Catch your own mistakes in Godot's uncommitted diffs before they reach review or CI. Atlas helps Godot developers self-review GDScript, node trees, and signals, ensuring clean code quality.