This works for GitHub repositories, with TypeScript Playwright tests. Your workflow needs peeps-action 1.4.0 or later.
Before you start
- Push your branch. Peeps writes the test against the commit you pushed, and it must be on that branch in your repository. A commit from a fork’s pull request is never run.
- The Peeps workflow must be on that branch. Peeps runs its job from your branch’s own copy of the workflow.
- Your connection needs Edit and Run, and you need the Contributor role or above. A connection that already has both can ask for a test with no new consent. See the permissions.
Ask for the test
Ask your agent in plain English, for example: “Write a Peeps test for the new checkout total on this branch.” Your agent proposes the test’s title and steps and asks you to approve. When you do:1
Peeps starts a job in your CI
Peeps runs your Peeps workflow on your branch, checked out at exactly the commit you pushed. Up to three generations run at once in a repository, and Peeps also limits how many run at once in your organization and in total. A generation over a limit waits its turn, oldest first; it’s never refused.
2
Peeps writes and runs the test
Peeps explores your app, learns your repository’s conventions (page objects, fixtures, where tests live), writes the test, and runs it in your CI until it passes. It explores the deployment of your commit when Peeps knows one, otherwise your environment’s
BASE_URL.3
Your agent fetches the patch
Your agent shows you the complete patch. It checks the patch applies in your checkout, applies it, and runs the test locally. A patch that applies cleanly isn’t proof the test works, so it runs it.
4
You commit and push
Your agent commits and pushes only with your approval.
What the patch may contain
A patch adds or changes files under your test root. Outside it, it may change a page object or fixture only when your existing tests already import it, never a file it creates or only the new test imports. If your test root is the top of your repository, a filename says little, so Peeps goes by the tests it has already found there: the new test must sit in a folder that already holds one of them, and an existing file may change only when one of those tests imports it. Until Peeps has found a test in your repository, your agent can’t start a generation there: it’s told to set your test root to the folder your tests live in, or to use Run inventory now, on the project’s Repository settings page. It never touches your Playwright config, your CI configuration,.peeps/, package manifests, lockfiles, other tool configs, or dotfiles. Peeps also checks that the patch is exactly what your CI runner held after the test passed. If anything doesn’t match, nothing is handed back.
After you push
When your CI first runs the new test, Peeps creates its test case with the title and steps you approved. Ask your agent “Did CI run the new test?” and it reads the results for the commit you pushed. If you change the test before you push it, the test case gets a placeholder description instead of your steps.When it can’t write the test
Your agent tells you why, and what to do:- The workflow or the action needs updating. Update peeps-action to 1.4.0 or later, or copy the current workflow from your project’s Repository page in Peeps, push, and ask again.
- The commit isn’t on the branch. Push it to the branch and ask again.
- You can no longer start it. If your role, your agent’s connection or your organization’s MCP access changed while it waited, Peeps runs nothing. Reconnect if needed, and ask again.
- The test didn’t pass. Peeps explains why in its own words. Change the steps or the app, then ask again.