How do I run a specific Perl test file with Atlas?

You can run a specific Perl test file like `t/my_module/01_failing_test.t` using the Atlas `bash` tool with `prove -lr t/my_module/01_failing_test.t`. For subtests, add `--test-args='--filter=my_subtest_name'` to focus the execution.

Can Atlas help me understand Perl module dependencies?

Yes, Atlas indexes Perl code by AST declarations using `tree-sitter`, allowing its `lsp` tool to accurately trace dependencies, `goToDefinition` for subs, and `findReferences` across `.pm` modules and CPAN distributions.

Does Atlas support `perltidy` for Perl code formatting?

Absolutely. Atlas automatically runs `perltidy` on any changed Perl files before committing, ensuring your code adheres to your `.perltidyrc` and maintaining consistent formatting across your project.

How does Atlas ensure I don't accidentally commit bad Perl code?

Atlas operates with a read-only plan agent and a build agent, requiring explicit permission for tool calls. It computes a unified diff for every file edit and surfaces it for your approval before writing, providing a critical review step.

Can Atlas debug Perl code that uses `cpanm` installed modules?

Yes, Atlas is designed to work within Perl distributions that use `cpanm`. It reads your packages and the modules pulled in by `cpanm`, allowing it to understand and navigate your entire Perl codebase effectively.

What if my Perl fix is complex and spans multiple files?

For complex Perl fixes spanning several hunks or files, Atlas provides the `apply_patch` tool. You can prepare a standard git patch file and have Atlas apply it, ensuring atomic and reliable changes across your Perl project.

Debug a single failing test in Perl with Atlas in 2026

To debug a single failing Perl test in 2026, Atlas helps you isolate the specific test using `prove (Test2::V0)` with focused filters, then employs its `lsp` tool to work through the call graph and `edit` to apply precise code fixes, ensuring the assertion remains untouched while the underlying code is corrected.

How to run a single Perl test with Atlas for debugging

Atlas streamlines debugging in 2026 by running a single Perl test in isolation, leveraging the `prove (Test2::V0)` test runner with specific filters. This approach ensures that only the relevant test output is generated, often reducing hundreds of lines of log data to a manageable 10-20 lines, making root cause analysis significantly faster.

When a Perl test fails, Atlas uses its `bash` tool to execute `prove (Test2::V0)` with precise arguments. For instance, to run a specific test file, you might see Atlas propose `prove -lr t/my_module/01_failing_test.t`. If the failure is within a subtest, Atlas can further refine this with `--test-args='--filter=my_failing_subtest'`, ensuring that `prove` only executes the relevant portion. This dramatically reduces the amount of TAP output, making it easier to pinpoint the exact assertion failure. Atlas reads this output directly from the terminal, allowing it to quickly identify the failing line and context within your Perl codebase. This focused execution is crucial for efficient debugging, preventing the noise of a full test suite run from obscuring the problem.

Tracing Perl code paths with Atlas lsp tool

Once a single Perl test is isolated, Atlas uses its `lsp` tool to meticulously trace the execution path through your Perl modules, even across complex CPAN distributions. This allows developers in 2026 to quickly jump from a failing assertion in `t/my_module/01_failing_test.t` directly to the `sub` definition in `lib/My/Module.pm` that the test exercises, often within 1-2 seconds.

After isolating the failing test, Atlas employs its `lsp` tool to work through the Perl codebase. This tool leverages an index built by AST declarations using `tree-sitter`, providing a deep understanding of your Perl modules, including those pulled in by `cpanm`. When a test in `t/my_module/01_failing_test.t` fails, Atlas can use `lsp goToDefinition` to jump directly from the test assertion to the `sub` definition in `lib/My/Module.pm` that it exercises. Conversely, `lsp findReferences` can show all locations where a particular Perl function or variable is used, helping to understand its impact. This capability is vital for tracing the call graph, especially when dealing with complex Perl applications that utilize `@EXPORT` lists and multiple nested modules, allowing developers to quickly understand the flow of data and logic leading to the failure.

Applying code fixes and temporary logging in Perl with Atlas

After identifying the root cause, Atlas facilitates precise code modifications and temporary logging in Perl using its `edit` tool. This allows developers in 2026 to insert `warn` or `say` statements into `lib/My/Module.pm` to confirm hypotheses, or to directly fix the production code, often requiring only 3-5 lines of change to resolve the issue.

Once the root cause of the Perl test failure is identified, Atlas provides the `edit` tool for making precise modifications to your production code. For instance, to add temporary logging to a Perl module, Atlas can insert a `warn` or `say` statement into `lib/My/Module.pm` at a specific line number, like `atlas edit lib/My/Module.pm "add warn 'Debug: value is $var' at line 42"`. This allows you to confirm your hypothesis by re-running the isolated test with the `bash` tool and observing the new output. For direct code fixes, `edit` is ideal for small, targeted changes. If the required fix is more extensive, spanning several hunks or even multiple Perl files, Atlas offers the `apply_patch` tool. This allows you to provide a standard git patch file, which Atlas will apply atomically, ensuring that complex changes are handled reliably and can be easily reviewed or rolled back.

Ensuring code quality and safety for Perl fixes with Atlas

Atlas integrates robust review and safety mechanisms for Perl code changes, ensuring every modification is thoroughly vetted before it is committed. In 2026, Atlas automatically runs `perltidy` on altered files to match your `.perltidyrc` and presents a unified diff for approval, preventing accidental regressions and maintaining code style across your project.

Atlas incorporates several layers of safety and review for any changes made to your Perl codebase. Before any modification is written, Atlas drafts a plan in a read-only plan agent and explicitly asks for your permission before switching to a build agent to execute the changes. Every file edit, whether through `edit` or `apply_patch`, results in Atlas computing a unified diff. This diff is then surfaced for your approval, giving you a clear overview of exactly what will be changed in your Perl modules before it is committed. Furthermore, Atlas automatically runs `perltidy` on all changed Perl files. This ensures that any modifications adhere to your project's `.perltidyrc` configuration, maintaining consistent code style and preventing formatting-related merge conflicts. Atlas also reads git branches, status, and diffs, and can stage and create commits on your behalf, with the ability to snapshot file changes as git patches for easy rollback.

Step by step

01Run just the failing Perl test with Atlas `bash`, using `prove (Test2::V0)` with a filter: `atlas bash "prove -lr t/my_module/01_failing_test.t --test-args='--filter=my_failing_subtest'"`
02Read the test and the Perl module it exercises, then walk the call graph using Atlas `lsp` operations like `goToDefinition` and `findReferences` on relevant subs in `lib/My/Module.pm`.
03Form a hypothesis and check it: add temporary logging with Atlas `edit` (e.g., `atlas edit lib/My/Module.pm "add warn 'Debug: value is $var' at line 42"`) or re-run the test with a verbose flag through `bash`.
04Fix the production Perl code with Atlas `edit` for small changes, or `apply_patch` if the change spans several hunks or files, ensuring the assertion remains untouched.
05Re-run the single test with `prove (Test2::V0)` to confirm the fix, then run the full test suite (`prove -lr t/`), and finally remove any temporary logging you added using Atlas `edit`.

Frequently asked questions

How do I run a specific Perl test file with Atlas?: You can run a specific Perl test file like `t/my_module/01_failing_test.t` using the Atlas `bash` tool with `prove -lr t/my_module/01_failing_test.t`. For subtests, add `--test-args='--filter=my_subtest_name'` to focus the execution.
Can Atlas help me understand Perl module dependencies?: Yes, Atlas indexes Perl code by AST declarations using `tree-sitter`, allowing its `lsp` tool to accurately trace dependencies, `goToDefinition` for subs, and `findReferences` across `.pm` modules and CPAN distributions.
Does Atlas support `perltidy` for Perl code formatting?: Absolutely. Atlas automatically runs `perltidy` on any changed Perl files before committing, ensuring your code adheres to your `.perltidyrc` and maintaining consistent formatting across your project.
How does Atlas ensure I don't accidentally commit bad Perl code?: Atlas operates with a read-only plan agent and a build agent, requiring explicit permission for tool calls. It computes a unified diff for every file edit and surfaces it for your approval before writing, providing a critical review step.
Can Atlas debug Perl code that uses `cpanm` installed modules?: Yes, Atlas is designed to work within Perl distributions that use `cpanm`. It reads your packages and the modules pulled in by `cpanm`, allowing it to understand and navigate your entire Perl codebase effectively.
What if my Perl fix is complex and spans multiple files?: For complex Perl fixes spanning several hunks or files, Atlas provides the `apply_patch` tool. You can prepare a standard git patch file and have Atlas apply it, ensuring atomic and reliable changes across your Perl project.

Try Atlas in your terminal

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

Install Atlas

Related 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.

Atlas for Perl: A Terminal-Native AI Coding Agent for CPAN Distributions in 2026

Atlas is a terminal-native AI coding agent for Perl in 2026. It reads cpanfile deps and @EXPORT lists, writes Test2::V0 cases, runs prove -lr t/, and runs perltidy on the diff.

Migrate a Deprecated API Across Every Callsite in Perl with Atlas in 2026

Effortlessly migrate deprecated Perl APIs across your entire codebase using Atlas. Find all callers, track progress, and apply changes safely with prove (Test2::V0) and perltidy.

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

Streamline GitHub issue and pull request triage for your Perl projects in 2026 using Atlas. Automate responses safely with `cpanm`, `prove (Test2::V0)`, and `perltidy` integration, ensuring trusted user control.

Plan a Multi-File Change in Perl with Atlas in 2026

Design and review complex, multi-file Perl changes with Atlas's plan agent before modifying a single line of code. Leverage prove, cpanm, and perltidy for safe development.

Review a Pull Request in Perl with Atlas in 2026

Review Perl pull requests efficiently in 2026 with Atlas. Catch subtle bugs by examining full file context, running prove (Test2::V0) tests, and ensuring perltidy formatting.

Rename a symbol across the repo in Perl with Atlas in 2026

Rename Perl functions, classes, or constants across your entire codebase with Atlas in 2026. Leverage lsp, grep, and edit for precise, safe refactoring, ensuring your prove (Test2::V0) tests pass and perltidy formatting

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

Pinpoint Perl runtime bugs from production stack traces using Atlas in 2026. Leverage Atlas's code indexing, grep, and lsp tools to quickly identify the root cause and apply fixes, all without a debugger.

Browse this resource hub