how to debug a single failing phpunit test with an ai agent

Ask Atlas to run just that test through bash with PHPUnit's filter flag, read the test and the PHP class it exercises, and walk the call path with the lsp tool's goToDefinition and findReferences operations before editing anything in src/.

phpunit filter flag run one test atlas

Atlas runs PHPUnit through its bash tool, so the framework's filter flag works exactly as it does in your shell. Filtering to one test method keeps the output small enough to reason about, which is the whole point of isolating a failure.

how do i find what a failing php test actually calls

Use the lsp tool through Atlas. goToDefinition descends into each helper the PHPUnit test touches, and findReferences shows every other caller of the suspect method, which is how you tell a broken method from a broken caller.

should i change the assertion or the code when a phpunit test fails

Change the code. A failing PHPUnit assertion is evidence the PHP production code in src/ is wrong. Atlas debugs toward the responsible method rather than relaxing the assertion, and surfaces a unified diff of the fix for approval before it writes.

atlas edit vs apply_patch for php files

Use edit for a single contiguous change to a PHP method. Use apply_patch when the fix spans several hunks in one class, because chained edits each run against a file the previous edit already shifted.

how do i add temporary logging to debug php code with atlas

Have Atlas add the logging with the edit tool, which shows a unified diff for approval first, then re-run the filtered PHPUnit command through bash. Atlas removes the temporary logging before finishing, and snapshots let you roll back anything left behind.

does atlas work with composer and psr-12

Yes. Run atlas in a project with a composer.json, let Atlas read your namespaces, autoload config, and dependencies, then ask it to add PHPUnit tests or apply PSR-12 formatting with PHP-CS-Fixer, reviewing the diff each time.

Debug a Single Failing Test in PHP with Atlas (2026)

To debug a single failing test in PHP with Atlas, run just that PHPUnit test through Atlas's bash tool using the framework's filter flag, so the output is small enough to reason about instead of a full suite dump. Atlas then reads the failing test and the PHP class it exercises, walks the call path with the lsp tool's goToDefinition and findReferences operations, and only then edits. Because bash is a real shell, every lever you would pull by hand is still available: temporary logging added with edit, a focused PHPUnit filter, a verbose flag. The goal throughout is to fix the production code in src/, not to weaken the assertion in tests/.

How do I run just one failing PHPUnit test with Atlas?

Atlas runs a single failing PHPUnit test through its bash tool using the framework's filter flag, so one test method's output replaces a full suite dump. In a Composer project, that turns 800 lines of PHP test output into the 12 you actually need to read.

Debugging starts by shrinking the problem. Atlas invokes PHPUnit through bash with the filter flag targeting the one failing test method, which is the difference between reading an assertion and reading a suite. The narrow run also makes iteration cheap: each hypothesis costs one fast PHPUnit invocation rather than a full pass over tests/. Because bash is a real shell, Atlas can add PHPUnit's verbose flag to the same command when the default output does not say enough, and it can chain the run with anything else your Composer scripts already define. The isolated failure, with its assertion message and its stack of PHP frames, is the input to everything that follows.

How does Atlas trace a PHPUnit failure back to the PHP code that broke?

Atlas reads the failing PHPUnit test and the PHP class it exercises, then uses 2 lsp operations, goToDefinition and findReferences, to walk the call path from the assertion down to the method that produced the wrong value. Atlas indexes code by AST declarations using tree-sitter, not blind line windows.

A PHPUnit assertion tells you what was wrong, never why. Atlas closes that gap by reading the test method, reading the class under test in src/, and then walking the graph with the lsp tool: goToDefinition to descend into each helper the test touches, findReferences to see who else calls the suspect method and with what. Namespaced PHP makes this worse by hand, because the class name in the failure and the file on disk are connected only through the PSR-4 autoload map in composer.json. Atlas resolves that for you. Its retrieval also fuses hybrid semantic and keyword search with reciprocal rank fusion, so a method you can describe but cannot name is still findable.

How do I test a hypothesis about a failing PHP test?

Atlas forms one hypothesis about the failing PHPUnit test and then checks it: temporary logging added with the edit tool, or a re-run through bash with a verbose flag. In 2026 that is still the fastest loop in PHP, because bash gives Atlas the same levers you would use by hand.

Guessing is not debugging. After the call path is clear, Atlas states what it thinks is wrong, then proves or kills the idea in one cheap step. Temporary logging goes in with the edit tool, which surfaces a unified diff for approval before the line lands in your PHP source. The focused PHPUnit run through bash then either confirms the value is wrong where Atlas predicted or does not, and either answer moves things forward. Atlas removes the temporary logging before it finishes, and because Atlas snapshots file changes as git patches, any scaffolding it forgot is still visible as a diff you can roll back.

When should Atlas use apply_patch instead of edit on a PHP file?

Atlas fixes the PHP production code with the edit tool for a single change, and switches to apply_patch when the fix spans 3 or more hunks in one file, because chaining brittle edits across a large PHP class is how a refactor silently misapplies. Both surface a unified diff before writing.

Edit is right for one contiguous change to a method in src/. When the correct fix touches three separated regions of the same PHP class, chaining three edits means each one runs against a file the previous one already moved. Atlas uses apply_patch there instead: the whole change lands as one context-anchored patch that either applies cleanly or fails loudly. Either way, Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so the fix is reviewed as a change, not accepted as an outcome. After the fix, run PHP-CS-Fixer separately so PSR-12 formatting does not smuggle unrelated churn into the bug fix diff.

How do I confirm the PHP fix did not break anything else?

Atlas re-runs the single PHPUnit test with the same bash filter command that proved the failure, then runs the full suite. Those 2 runs prove different things: the filtered PHPUnit run proves the fix works, and the full suite proves the fix cost nothing elsewhere in the Composer project.

Two runs, in that order. The narrow PHPUnit run with the filter flag is the direct evidence that the specific bug is gone, and using the identical bash command that produced the failure keeps the comparison honest. The full suite is the collateral damage check, and Atlas triages any new red against the whole saved log rather than the terminal tail. Finally, Atlas deletes the temporary logging it added during the hypothesis loop, because debugging scaffolding that ships is a defect of its own. Every one of those tool calls is permission-gated against allow, ask, and deny rules, so you can allow PHPUnit runs freely while still approving each write.

Step by step

01Run atlas in the PHP project where composer.json lives so Atlas can resolve namespaces and autoload config before it reads anything.
02Ask Atlas to run only the failing test through bash using PHPUnit's filter flag, so the output is small enough to reason about.
03Have Atlas read the failing test method and the PHP class in src/ that it exercises, in full, not just the asserted line.
04Use the lsp tool's goToDefinition and findReferences operations to walk the call path from the PHPUnit assertion down to the method that produced the wrong value.
05State one hypothesis, then check it: add temporary logging with the edit tool, or re-run the filtered PHPUnit command through bash with a verbose flag.
06Fix the production code with edit, or use apply_patch when the change spans several hunks in one PHP class instead of chaining brittle edits.
07Re-run the same filtered PHPUnit command with bash to confirm the test now passes, then run the full suite to check for collateral damage.
08Remove the temporary logging you added, and apply PHP-CS-Fixer separately so PSR-12 formatting stays out of the bug fix diff.

Frequently asked questions

how to debug a single failing phpunit test with an ai agent: Ask Atlas to run just that test through bash with PHPUnit's filter flag, read the test and the PHP class it exercises, and walk the call path with the lsp tool's goToDefinition and findReferences operations before editing anything in src/.
phpunit filter flag run one test atlas: Atlas runs PHPUnit through its bash tool, so the framework's filter flag works exactly as it does in your shell. Filtering to one test method keeps the output small enough to reason about, which is the whole point of isolating a failure.
how do i find what a failing php test actually calls: Use the lsp tool through Atlas. goToDefinition descends into each helper the PHPUnit test touches, and findReferences shows every other caller of the suspect method, which is how you tell a broken method from a broken caller.
should i change the assertion or the code when a phpunit test fails: Change the code. A failing PHPUnit assertion is evidence the PHP production code in src/ is wrong. Atlas debugs toward the responsible method rather than relaxing the assertion, and surfaces a unified diff of the fix for approval before it writes.
atlas edit vs apply_patch for php files: Use edit for a single contiguous change to a PHP method. Use apply_patch when the fix spans several hunks in one class, because chained edits each run against a file the previous edit already shifted.
how do i add temporary logging to debug php code with atlas: Have Atlas add the logging with the edit tool, which shows a unified diff for approval first, then re-run the filtered PHPUnit command through bash. Atlas removes the temporary logging before finishing, and snapshots let you roll back anything left behind.
does atlas work with composer and psr-12: Yes. Run atlas in a project with a composer.json, let Atlas read your namespaces, autoload config, and dependencies, then ask it to add PHPUnit tests or apply PSR-12 formatting with PHP-CS-Fixer, reviewing the diff each time.

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 PHP in 2026

Atlas, the terminal-native AI coding agent, empowers PHP developers in 2026 with intelligent code understanding, secure workflows, and direct integration for Composer and PSR standards.

Audit a PHP Repository with Parallel Subagents in 2026

Sweep your entire PHP codebase for issues without context window limits. Atlas uses parallel subagents to audit Composer packages and PSR standards, integrating with PHPUnit and PHP-CS-Fixer.

Write unit tests for untested code in PHP with Atlas (2026)

Write PHPUnit tests for untested PHP code in 2026 with Atlas: enumerate exported symbols with documentSymbol, copy the repo's test conventions, then actually run them.

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

Catch your own mistakes in PHP code before they reach a reviewer or CI. Atlas helps PHP developers in 2026 self-review uncommitted diffs, run PHPUnit tests, and apply PHP-CS-Fixer formatting.

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

Move your PHP codebase off deprecated functions or modules onto replacements without missing a single caller. Atlas integrates with Composer and PHPUnit for a verified migration.

Onboard to an Unfamiliar PHP Codebase with Atlas (2026)

Build a mental model of an unfamiliar PHP repo in 2026 without reading every file. Atlas maps the Composer layout, delegates sweeps to a read-only explore subagent.

Add a regression test for a bug fix in PHP with Atlas (2026)

Add a PHP regression test for a bug fix in 2026: Atlas proves the PHPUnit test fails red first, applies the fix with edit, and re-runs the same command to prove green.

Browse this resource hub