Find and fix a failing test

Name the failing test; Claude Code runs it, traces the failure into the source, explains the cause, fixes it and shows the passing test output.

Task: Find and fix a failing test · Other tasks

Fill in the details

Failing test (name or file) (required)

Command that runs it

Optional. Leave empty and Claude will find how the project runs its tests.

What you know about the failure

Optional. When it started, whether it fails every time or only sometimes, and where.

Failure output

Optional. Claude will run the test itself, but output from CI helps when the failure does not happen locally.

What may change

Copy your prompt

This site doesn't run Claude or show model output. Results depend on your input and the model you use.

Your prompt (you can edit it)

The [fill in: Failing test (name or file)] test is failing. Find out why and fix it.

Steps:
1. Run the test and confirm you see the failure. If it passes, run it a few more times and tell me; it may be flaky or depend on order or environment.
2. Trace the failure to its cause in the source. Read the test, the code it exercises, and recent commits that touched either.
3. State the cause in one or two sentences before you edit anything. If the evidence does not establish a cause, or it is unclear whether the test or the code is right, stop, say what is missing, and ask me before changing either.
4. Fix it. Assume the test is correct and change the code under test. If you think the test itself is wrong, stop and explain before touching it.
5. Run the test again, then the wider related suite, and keep going until both pass.

Rules:
- Do not skip, disable, delete or weaken the test, and do not add retries or longer timeouts to hide the failure.
- If the cause is outside the code, such as the environment, a missing service or test data, stop and tell me what you found.
- Do not commit.

Report: the cause, the change you made and why it fixes the cause, and the final test output.

1 required field is empty.

What you type is kept in this tab's session storage so a reload doesn't lose it. Use "Clear this task" to remove it. Browsers can restore session data when they reopen tabs, so closing a tab isn't a guaranteed way to erase it.

When to use this template

A specific test has started failing and you do not know which file is responsible. Naming the test is enough for Claude to run it and trace the failure.
You want the cause explained before the fix, so you can tell a real bug from a test that was already wrong.
The test fails in CI but not locally, and you can paste the CI output so Claude has the failure even when it cannot reproduce it.

When not to use it

Many unrelated tests fail at once. That usually points to one shared cause, such as a broken build or a missing service; fix the build error or the setup first.
You want new tests for code that has none. Use the unit test template; this one repairs a test that exists.
The failure depends on systems Claude Code cannot reach, such as a staging database. Paste the output, and expect a diagnosis rather than a verified fix.

Why this structure

Step 1 makes Claude run the test and see the failure first. A fix for a failure nobody reproduced is a guess, and a test that passes on rerun is a different problem: flakiness.
Asking for the cause in step 3, before any edit, gives you a moment to stop a fix aimed at the wrong thing.
The setting for what may change is explicit, because "make the test pass" can be done by changing the test. You decide whether the test counts as the specification.
The rule against skipping, weakening or adding retries rules out the usual shortcuts that turn a red test green without fixing anything.
Step 5 runs the wider suite after the fix, so a change that repairs one test but breaks its neighbors shows up before you review it.
Optional output from CI goes first inside <test_output> tags, which separate the pasted output from the task. Tags do not neutralize text hidden in output, so review what you paste.

Example input (fictional)

Failing test (name or file)

UserAuth

Command that runs it

npm test -- UserAuth

What you know about the failure

Started after the session library upgrade. Fails in CI every time, passes on my machine.

Failure output

FAIL tests/auth/UserAuth.test.ts
  UserAuth > refreshes an expired session
    Expected: 200
    Received: 401
      at Object.<anonymous> (tests/auth/UserAuth.test.ts:48:31)

What may change

Assume the test is correct and change the code under test. If you think the test itself is wrong, stop and explain before touching it

Follow-ups to send Claude

Write a short note for the commit message explaining the cause and the fix. Do not commit.
Are there other tests that rely on the same assumption that broke here? List them and say whether they could fail the same way.
Run the test 20 times in a row and report whether it ever fails, to check the fix did not just hide a flaky failure.

Common mistakes

Saying only that "the tests are failing". Name the test, or paste its output, so Claude starts from the right place.
Accepting a fix that edits the test without reading why. Keep the default setting unless you already suspect the test is wrong.
Leaving out that the failure is intermittent or only happens in CI. That detail changes where Claude should look.

Debug an error: Turn an error message and the code around it into a ranked list of likely causes, a check for each, and a fix you can try.
Write unit tests: Get unit tests for a function or module in your framework, covering normal cases, edge cases and errors, with each test explained.
Fix a build error at the root cause: Paste a build error; Claude Code reproduces it, fixes the root cause without suppressing the error, and shows the build and tests passing again.

See all templates

Sources

Claude Code docs: Prompt library (Anthropic documentation)
Claude Code docs: Common workflows, fix bugs efficiently (Anthropic documentation)
Claude Code best practices: Give Claude a way to verify its work (Anthropic documentation)