> ## 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 to your repository from your coding agent > Ask Peeps to write a new Playwright test at the commit you pushed. Peeps writes it in your CI, checks it passes there, and hands it back as a patch your agent applies. Nothing is pushed to your repository. When your project's tests live in your GitHub repository, your coding agent can ask Peeps to write a new test for what you just built. Peeps's own generator writes it, on Peeps's tokens, in the style of the tests you already have. It runs the test in your CI to check it passes, then hands it back as a patch. Your agent shows it to you, applies it in your checkout, and you commit it on your own branch. Nothing is pushed to your repository and no pull request is opened. Only you commit the test. > [!NOTE] > > 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](https://docs.peepsai.com/mcp/access-and-approvals.md#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. ## Use the app running on your machine Your agent can also ask Peeps to explore the app you're running locally, such as `http://localhost:3000`, instead of a deployment. Ask, for example: *"Write a Peeps test for the new checkout total, against my local app."* This needs your connection's **Local discovery** permission as well as Edit and Run, and your organization must have local discovery turned on. **1. You start the runner** Your agent gives you one command to run in your terminal. It opens a browser on your machine for Peeps's generator. The command carries a one-time grant for this generation only, so run it as given. **2. Peeps explores and writes the test** Peeps drives that browser to walk your steps, and reads your repository at the commit you pushed, through the Peeps GitHub App. It reads only your test files: the test root, your Playwright config and the files your tests import. Peeps doesn't run the test. Nothing runs in your CI. **3. Your agent checks, applies and runs it** With the patch, Peeps lists the files it was written against, with their hashes. Your agent checks your checkout still matches, applies the patch, and runs the test on your machine before you commit. You can have one of these running at a time in each project, and your organization up to 5. Your agent can cancel one to start another. It doesn't work when your test root is in a dot folder, like `.e2e`, or a folder that holds credentials or CI configuration, like `.github` or `.ssh`: change the test root in **Repository settings**. ### Unpushed changes If you changed a page object or fixture and haven't pushed it yet, your agent can send those test files along, so the new test uses them. They go to Peeps and its AI provider: * Only test files: the test root, your Playwright config and files your tests import. Never `.env` files, dot-folders, `node_modules` or credential files. * At most 20 files and 64 KiB in all, or nothing is sent. A file you deleted or renamed isn't sent: commit and push it first. * Peeps masks your project's secrets in them first, and never puts them in the patch. Peeps doesn't check that they're all your changes. If the test needs to change one of those files, Peeps stops rather than overwrite your local change. If you edit one of them while Peeps works, your agent sees the hash no longer matches and doesn't apply the patch. ## 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. You can cancel a generation while it runs. Cancelling one whose patch is already ready keeps the patch, but its steps aren't carried onto the test case. ## Follow a heal from your agent Heals for these projects run in your CI too, and open a pull request. Start one from the run's page in Peeps with **Heal in your repository**. Your agent can then follow it: ask *"Is the heal for that failure done?"* and it reports when the pull request is open. ## Search the docs from your agent The Peeps plugin for Claude Code, Codex and Cursor also connects your agent to these docs, so it can look things up while it works. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.