Guided Tutorials
Fix Failing Tests with Debugging Agent
Use Autohand's debugging workflow to diagnose and fix failing tests systematically. The agent reads the error output, traces it to the source, and fixes the right thing.
What you'll learn
- How to capture and share test output so the agent can trace failures to their source
- How to instruct the agent to fix the code rather than change the test assertions
- How to review a targeted fix and verify the full suite still passes
- How to ask the agent to scan for the same bug pattern across the codebase
Before you start
- Autohand Code installed
- A failing test suite with visible error output
- A test runner accessible from the command line (
npm testor equivalent) - The file path of the failing test, if it lives in a deeply nested module
Capture the test output
Run your test suite and copy the full output. Do not trim it. The stack trace and the diff between expected and received values are both important.
Piping to a file lets you share the complete output without scrolling back through your terminal. The output will look something like this.
Provide context to the agent
Start an Autohand session and paste the failing output directly into the prompt. Use the instruction from the prompt block above so the agent knows the rules of engagement.
The instruction "do not modify the tests unless they have a bug" is important. Without it, the agent might take the path of least resistance and change the expected value to match the current broken behavior. That would make the test pass but hide the bug.
Tip: If you know the test is wrong and that is what you want fixed, say so explicitly: "The test expected value is wrong. Fix the test to match the correct behavior." Be direct about which side of the assertion needs to change.
Watch the debugging process
The agent follows a systematic approach rather than guessing. Here is what you will see it do.
First, it reads the test file to understand what the test is asserting.
Then it locates the function under test and reads its implementation.
It identifies that tax is calculated but left out of total. It then shows you the fix before writing it.
It applies the fix and runs the test suite to confirm the failure is resolved.
Review the fix
Always look at what the agent changed before moving on. The fix should be minimal and targeted. A good fix changes exactly what caused the failure and nothing else.
If the fix looks larger than expected, ask the agent to explain every change it made. Understand each one before accepting.
Verify all tests pass
After the fix, run the full test suite. A targeted fix should not break other tests. If it does, you have uncovered a wider problem.
If a different test now fails that was passing before, paste the new failure into the session and continue. The agent has context from the previous fix and can see whether the new failure is related.
Learn from the pattern
After the tests are green, ask the agent to summarize what it found. This is useful for team retrospectives and for updating your code review checklist.
Common patterns the agent identifies include return statements that compute a value but use the wrong variable, off-by-one errors in loops, missing await on async calls in synchronous-looking code, and mutation of function arguments that other tests depend on being unchanged.
You can also ask the agent to scan for similar patterns elsewhere in the codebase before they turn into future failures.
Tip: Proactively finding related bugs after fixing one is one of the highest-value things Autohand can do during a debugging session. The agent already has context about what went wrong and can apply that understanding across the whole codebase in seconds.
What you learned
- You captured test output and provided it to the agent with clear instructions about what should change
- You watched the agent trace a failure from assertion to root cause and apply a minimal fix
- You verified the full test suite passes after the fix without regressions
- You asked the agent to scan for the same bug pattern elsewhere in the codebase