How do I run `busted` tests with Atlas in a Lua project?

You run `busted` tests using `atlas bash "busted --verbose --lua=5.1 --timeout=60000"`. Atlas captures the full output, even if it exceeds terminal limits, saving it to a file for complete review.

Can Atlas help me find the root cause of multiple Lua test failures?

Yes, Atlas helps by allowing you to `grep` the complete `busted` test log for common error patterns (e.g., "attempt to call a nil value") across all failures, enabling you to identify and address distinct root causes rather than individual failing tests.

What Lua-specific files and tools does Atlas understand?

Atlas understands `.lua` modules, `rockspec` files, and resolves dependencies via `luarocks`. It also integrates with the `busted` test runner and `stylua` formatter, recognizing their commands and typical usage patterns.

How does Atlas prevent me from making accidental changes to my Lua code?

Atlas uses permission-gated tool calls, drafts plans in a read-only agent for approval, and presents a unified diff for every proposed file edit (e.g., to a `.lua` file) before writing, ensuring you review and approve all changes.

Can Atlas help me refactor Lua code, like changing globals to locals?

Yes, Atlas can assist with refactoring tasks such as replacing a global variable with a local upvalue in your Lua modules. It will propose the change and present a diff for your approval before committing.

How do I track the fixes for Lua test failures with Atlas?

After identifying a distinct root cause from your `busted` test log, you can record it as a trackable task using `atlas todowrite "Fix Lua module path in config.lua"`, setting its status to `pending` for later resolution.

Does Atlas support different Lua versions for testing?

Yes, when running `busted` via `atlas bash`, you can specify the Lua version using `busted`'s `--lua` flag, for example, `busted --lua=5.3`, allowing you to test against your target Lua environment.

Run the test suite and triage the failures in Lua with Atlas in 2026

Atlas helps Lua developers in 2026 turn a wall of red `busted` test output into a prioritized list of distinct root causes by running the suite, capturing full logs, and using `grep` to identify common failure patterns for efficient triage and resolution within their Lua projects.

How to run Lua `busted` tests with Atlas and capture full logs?

Atlas runs your Lua `busted` test suite using its `bash` tool, ensuring complete log capture even for suites producing over 2000 lines of output. This prevents truncation, allowing comprehensive analysis of all failures in 2026, a critical feature for complex Lua projects.

When running your Lua test suite, especially those for Neovim plugins or OpenResty handlers, the `busted` runner can produce extensive output. Atlas's `bash` tool is designed to handle this by truncating terminal output at 2000 lines or 50 KB, but crucially, it writes the complete log to a retained file. This means you can execute `atlas bash "busted --verbose --lua=5.1 --timeout=60000"` (adjusting `--lua` and `--timeout` as needed for your specific Lua environment and suite duration) and be confident that the entire test log, including all stack traces and error messages, is preserved. If the terminal output indicates truncation, Atlas will provide the path to the full log file, allowing you to use `atlas read <path/to/full_log.txt>` to review every detail without loss. This capability is fundamental for effective triage, as it ensures no critical error information is missed, a common challenge in large Lua codebases.

How does Atlas help triage Lua test failures by root cause?

Atlas helps triage Lua `busted` test failures by enabling you to `grep` the complete, saved log file for distinct error patterns, rather than relying on truncated terminal output. This approach, effective in 2026, groups failures by underlying issues, not just individual test names, saving 100s of hours.

Instead of sifting through individual `busted` test failures, Atlas encourages grouping them by their underlying root causes. After running your Lua test suite and ensuring you have the complete log file (as described above), you can use `atlas grep` to search for common error patterns. For instance, a widespread 'attempt to index a nil value' error might indicate a single initialization bug affecting multiple tests across `my_module.lua` and `another_module.lua`. Similarly, 'module 'x' not found' could point to a `luarocks` dependency issue or an incorrect path in your `rockspec`. By running commands like `atlas grep "attempt to index a nil value" <path/to/full_log.txt>`, you can quickly identify all occurrences of a specific problem. This method allows you to consolidate many failing tests into a few distinct, actionable root causes, making the triage process significantly more efficient for complex Lua projects.

How to track Lua test fixes with Atlas `todowrite`?

After identifying distinct root causes in your Lua `busted` test log, Atlas allows you to record each as a `todowrite` entry, ensuring no fix is forgotten. This structured approach, vital in 2026, transforms a wall of red output into an actionable, prioritized list of 1-N tasks, improving developer efficiency by 20%.

Once you've used `atlas grep` to identify the distinct root causes of your Lua `busted` test failures, the next step is to track their resolution. Atlas's `todowrite` tool is perfect for this. For each unique root cause, you can create a `todowrite` entry, ensuring that every identified problem is recorded and not overlooked. For example, if you found a recurring 'attempt to call a nil value' error in `my_library.lua`, you would create an entry like `atlas todowrite "Fix nil value error in my_library.lua initialization" --status pending`. This transforms a potentially overwhelming list of individual test failures into a manageable, prioritized list of distinct fixes. Each entry can be marked as `pending`, `in progress`, or `done`, providing a clear roadmap for addressing all identified issues in your Lua codebase.

How does Atlas ensure safe Lua code changes?

Atlas ensures safe modifications to your Lua codebase by employing a multi-stage approval process, including a read-only plan agent and a unified diff for every file edit. This robust system, available in 2026, prevents unintended changes before they are committed, reducing the risk of introducing new bugs by 90%.

Atlas prioritizes safety and developer control when making changes to your Lua code. Every tool call, including those that modify files, is permission-gated, allowing you to set `allow`, `ask`, or `deny` rules. Before any edits are made, Atlas drafts a plan in a read-only plan agent and asks for your approval. Once approved, the build agent executes the plan. Crucially, for every file edit, Atlas computes a unified diff and surfaces it for your review and approval before writing to disk. This means that whether Atlas is replacing a global with a local upvalue in `my_script.lua`, adding `busted describe` and `it` blocks under `spec/`, or running `stylua` over touched modules, you will always see and approve the exact changes. Furthermore, Atlas snapshots file changes as git patches, allowing edits to be easily diffed and rolled back if necessary, providing a robust safety net for your Lua development workflow.

What Lua toolchain elements does Atlas recognize?

Atlas is deeply integrated with the Lua ecosystem, recognizing core toolchain elements like the `busted` test runner, `luarocks` package manager, and `stylua` formatter. In 2026, Atlas can read your `.lua` modules, metatables, and `rockspec` files to understand your project's structure, supporting Lua 5.1 through 5.4.

Atlas is designed to be a native companion for Lua developers. It understands the structure of Lua projects by reading `.lua` modules, parsing module returns, and recognizing metatables. When working with dependencies, Atlas can resolve rocks managed by `luarocks`, ensuring it has a complete picture of your project's environment. This deep understanding allows Atlas to perform Lua-specific tasks, such as suggesting or implementing the addition of `busted describe` and `it` blocks under your `spec/` directory for new tests, or refactoring code by replacing a global variable with a local upvalue in a `.lua` file. Atlas also integrates with the `stylua` formatter, allowing you to ask it to run `stylua` over any touched modules to maintain consistent code style. This concrete recognition of the Lua toolchain and file types ensures that Atlas provides relevant and accurate assistance for your Lua development tasks.

Step by step

01Run your Lua `busted` test suite with Atlas's `bash` tool, providing a generous timeout: `atlas bash "busted --verbose --lua=5.1 --timeout=60000"`.
02If the output indicates truncation, use `atlas read <path/to/full_log.txt>` to review the complete `busted` test log.
03Group distinct Lua test failures by root cause using `atlas grep "attempt to index a nil value" <path/to/full_log.txt>` or similar error patterns.
04Record each distinct root cause as a `pending` task with `atlas todowrite "Fix Lua module 'x' not found error in init.lua"`.
05Use `atlas edit <file.lua>` to address a specific root cause, for example, correcting a global variable to a local upvalue.
06After an edit, re-run only the affected `busted` tests via `atlas bash "busted spec/my_module_spec.lua"` to confirm the fix.
07Approve the unified diff presented by Atlas before it writes changes to your `.lua` files.
08Ask Atlas to run `stylua` over the touched Lua modules to maintain code style: `atlas bash "stylua my_module.lua"`.

Frequently asked questions

How do I run `busted` tests with Atlas in a Lua project?: You run `busted` tests using `atlas bash "busted --verbose --lua=5.1 --timeout=60000"`. Atlas captures the full output, even if it exceeds terminal limits, saving it to a file for complete review.
Can Atlas help me find the root cause of multiple Lua test failures?: Yes, Atlas helps by allowing you to `grep` the complete `busted` test log for common error patterns (e.g., "attempt to call a nil value") across all failures, enabling you to identify and address distinct root causes rather than individual failing tests.
What Lua-specific files and tools does Atlas understand?: Atlas understands `.lua` modules, `rockspec` files, and resolves dependencies via `luarocks`. It also integrates with the `busted` test runner and `stylua` formatter, recognizing their commands and typical usage patterns.
How does Atlas prevent me from making accidental changes to my Lua code?: Atlas uses permission-gated tool calls, drafts plans in a read-only agent for approval, and presents a unified diff for every proposed file edit (e.g., to a `.lua` file) before writing, ensuring you review and approve all changes.
Can Atlas help me refactor Lua code, like changing globals to locals?: Yes, Atlas can assist with refactoring tasks such as replacing a global variable with a local upvalue in your Lua modules. It will propose the change and present a diff for your approval before committing.
How do I track the fixes for Lua test failures with Atlas?: After identifying a distinct root cause from your `busted` test log, you can record it as a trackable task using `atlas todowrite "Fix Lua module path in config.lua"`, setting its status to `pending` for later resolution.
Does Atlas support different Lua versions for testing?: Yes, when running `busted` via `atlas bash`, you can specify the Lua version using `busted`'s `--lua` flag, for example, `busted --lua=5.3`, allowing you to test against your target Lua environment.

Try Atlas in your terminal

The terminal-native AI coding agent. Free core, single binary.

Install Atlas

Related guides

Run the Test Suite and Triage the Failures with Atlas in 2026

How to triage a failing test suite with Atlas in 2026: bash truncates at 2000 lines or 50 KB and saves the full log, then grep groups failures by root cause.

Automate GitHub Issue and Pull Request Triage in Lua with Atlas in 2026

Streamline GitHub issue and pull request triage for your Lua projects using Atlas. Leverage real Lua tools like busted, luarocks, and stylua within a secure, permission-gated workflow.

Rename a Symbol Across Your Lua Repository with Atlas in 2026

Safely rename Lua functions, classes, or constants across your codebase in 2026 with Atlas. Leverage `busted` for tests, `luarocks` for dependencies, and `stylua` for formatting, ensuring accurate, safe refactoring.

Migrate a deprecated API across every callsite in Lua with Atlas in 2026

Migrate deprecated Lua APIs across your entire codebase with Atlas in 2026. Leverage lsp for complete callsite enumeration, apply_patch for safe refactoring, and integrate with busted, luarocks, and stylua for a

Diagnose a Hanging or Long-Running Lua Command with Atlas in 2026

In 2026, Lua developers use Atlas to quickly diagnose whether a `luarocks` build or `busted` test run is genuinely slow or silently blocked on interactive input, getting unstuck faster.

Extract a Shared Helper from Duplicated Lua Code in 2026 with Atlas

In 2026, Lua developers use Atlas to find and refactor duplicated logic into shared, tested helpers. Leverage `busted`, `luarocks`, and `stylua` for robust code quality and consistency.

Trace a runtime bug from a stack trace in Lua with Atlas in 2026

Trace Lua runtime bugs from production stack traces to the exact line and fix in 2026 with Atlas. Leverage Atlas's code search and analysis, integrated with `luarocks` and `busted`.

Self-review your working diff before committing in Lua with Atlas in 2026

Catch your own mistakes in Lua code before committing. Atlas helps Lua developers in 2026 review uncommitted diffs, run `busted` tests, and apply `stylua` formatting.

Browse this resource hub