Skip to main content
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.
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.

​
Describe the test

1

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

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

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

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

Click Generate in your repository

Peeps starts a job in your CI and the card says Being generated in your CI.
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.
  • 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.