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

# Add a test from Peeps

> Describe a test in Peeps, and Peeps writes it into your repository: it follows your existing tests, checks the new one passes in your CI, and opens a pull request.

You can write new tests in your repository as you always have, and Peeps picks them up on the next sync. You can also describe a test in Peeps and have Peeps write it for you. It arrives as a pull request, with a test that already passed in your CI.

Generating 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).

<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 test.
</Note>

## Describe the test

<Steps>
  <Step title="Add a test case">
    On **Test cases**, click **Add test case**. The dialog says the test will live in Peeps until you generate it into your repository.
  </Step>

  <Step title="Choose the branch">
    When Peeps follows more than one branch, pick the **Branch** the test belongs on. It's the headline branch unless you choose another.
  </Step>

  <Step title="Write the steps">
    Give the test a title and the steps a person would follow, with what they should see. Peeps writes the test from these.
  </Step>
</Steps>

The new test case is marked **Peeps only**: it has no file in your repository yet, so it can't run.

## Generate it in your repository

Open the test case. A card on its page says the test isn't in your repository yet.

<Steps>
  <Step title="Check the branch">
    The line under the button says which branch the pull request opens against. When Peeps follows more than one branch, you can change it there.
  </Step>

  <Step title="Click Generate in your repository">
    Peeps starts a job in your CI and the card says **Being generated in your CI**.
  </Step>
</Steps>

You can also comment `/peeps generate ABC-12` on an issue or pull request, using the test case's id. Peeps replies with the pull request when it's ready.

## What happens in your CI

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

1. **It learns your conventions** from up to five of the tests already on that branch: how they're laid out, which fixtures and page objects they use.
2. **It explores your app.** Peeps opens your app in its own browser to work out each step, at the `BASE_URL` of the project's first environment that sets one. That browser runs in Peeps, not on your runner, so it must be able to reach that address. An app behind a VPN or firewall can't be explored this way.
3. **It writes the test** under your test root, following those conventions. It's instructed to leave your existing tests alone and to change nothing outside the test root except a page object, and it can't write workflow files. Review the diff as you would any pull request.
4. **It runs the new test on your runner.** Only a test that passes there goes any further.
5. **It opens a pull request** from a `peeps/add-…` branch into the branch you chose. It's a draft if you set **Generated tests arrive as** to **Draft pull request**.

The test case says **In pull request #N** as soon as the pull request is open. Your pull request's own CI checks are the verification of record.

To follow along, the test case's **Peeps on your runner** card lists each job Peeps ran, with every file it read or wrote and every test it ran, and a link to the **Job log** in your CI.

## When the pull request merges or closes

* **Merged into the headline branch:** the next sync links the new file to the same test case. It becomes an ordinary test case, with the runs it already had.
* **Merged into another branch Peeps follows:** the test case shows the test is on that branch straight away.
* **Closed without merging:** the test case goes back to **Peeps only**, and you can generate it again.

## When generation fails

The card says the generation didn't produce a test and why, links to the job with **View the CI run**, and offers **Try again**. The most common reasons:

* **The workflow isn't on that branch.** GitHub runs the workflow file as it is on the branch, so a branch without `peeps.yml` can't start the job. Merge the workflow into that branch, or generate onto another one.
* **The CI job never connected.** See [the CI job never connected](/repository/faq#the-ci-job-never-connected).
* **A missing permission.** The card names the permission. Grant it, then click **Re-check permissions** on the **Repository** page.
* **Changes Peeps didn't make.** Peeps pushes only the files it wrote. If running the test left other files behind, such as `test-results/` or a saved sign-in state, nothing is pushed and the card lists them. Add them to your `.gitignore`, then try again.
* **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.
* **The test didn't pass.** Peeps opens a pull request only for a test that passed on your runner. Make the steps more specific and try again.


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