> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peepsai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fix a failing test

> Ask Peeps to heal a failing test in your repository. Peeps works out the fix in a job in your CI, re-runs the test there, and opens a pull request only when it passes.

When a test in your repository fails because the test is out of date, rather than because your app is broken, Peeps can fix it. The fix arrives as a pull request, and it has already passed in your CI.

Healing a test takes Contributor or above, and Peeps needs the permissions listed under **Open fix and new-test pull requests** on the [Repository page](/repository/connect#check-what-peeps-can-do). Peeps heals a test in your repository only when you ask: there's no automatic healing for these projects.

<Note>
  Fixing and generating tests work with TypeScript Playwright tests only. On a pytest suite the button still appears, but the job won't produce a fix.
</Note>

## Start a fix

<Steps>
  <Step title="Open the failed run">
    Open the failed run from the test case's page. Read the failure analysis first: if it points at a bug in your app, the test is doing its job and there's nothing to heal.
  </Step>

  <Step title="Check the branch">
    The heal card on the run page says which branch the fix opens against: the branch the run failed on, when Peeps follows it, and otherwise the headline branch.
  </Step>

  <Step title="Click Heal in your repository">
    Peeps starts a job in your CI. The card shows its progress, then the outcome.
  </Step>
</Steps>

You can also comment `/peeps heal ABC-12` on an issue or pull request, using the test case's id. A fix started that way opens against the headline branch, and Peeps replies in the same thread with the outcome.

## What happens in your CI

Peeps starts the Peeps workflow on that branch, in `agent` mode, and works in that job:

1. **It reads the failure and the code**: the error, where it was thrown, the test file and the page objects and fixtures it uses, as they are now on that branch.
2. **It changes the test where the breakage is.** That's often a page object rather than the test itself. It's instructed never to skip the test, loosen an assertion, or add a fixed wait just to get a pass. Review the diff as you would any pull request.
3. **It re-runs the test on your runner**, in the same Playwright project the failure ran in. Only a fix that passes there goes any further.
4. **It opens a pull request** from a `peeps/fix-…` branch into the branch the card named. The title says what kind of fix it is, such as **Fix locator:** followed by the test's title, and the description lists the files it changed and the commit it started from. It's a draft if you set **Healed fixes arrive as** to **Draft pull request**.

When your CI runs on the fix branch, Peeps adds a **Peeps / fix verification** check to the pull request (a commit status on GitLab), saying whether the test passed there.

Peeps doesn't ask for your CI secrets, and the job masks many of the values in its environment before sending anything back, but not all of them: a secret that appears in a test's error message, for example, reaches Peeps. The files Peeps reads and the output of the tests it runs are sent to Peeps, and while it works Peeps can run code on your runner. The [Peeps action's security notes](https://github.com/Peeps-Labs/peeps-action/blob/main/SECURITY.md) say exactly what that means. Every step is written to your CI job's log, and the test case's **Peeps on your runner** card lists them too.

## Outcomes

The card on the run page, and the **Peeps on your runner** card on the test case, end with one of these:

| Outcome | What it means |
| - | - |
| **Opened a pull request** | The fix passed on your runner. Review and merge it. |
| **No verified fix** | Peeps couldn't find a change that made the test pass, so nothing was pushed. The line under it says what it tried. |
| **Stopped at the open pull request limit** | Peeps already has as many pull requests open as the project allows, counting fixes and new tests together. Merge or close some, or raise **Open fix pull requests** in the project's settings. It's 5 unless you change it. |
| **The CI job never connected** | Peeps started the workflow, but no job reported back. See [the CI job never connected](/repository/faq#the-ci-job-never-connected). |
| **Expired — the CI job stopped reporting** | The job connected, then went quiet, for example because it was cancelled or the runner went away. Start the fix again. |
| **Failed** | Something stopped the job, such as a missing permission or files Peeps didn't write. The line under it says what, and what to do. |

Peeps heals one test at a time: while a fix for a test is running, you can't start another for the same test.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.