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

# Walkthroughs

> Three worked examples: troubleshoot a failing test, start with no URL and no IDs, and create new tests from coverage gaps or existing Playwright suites.

Three ways in. Pick the one that matches what you are doing.

## A. Troubleshoot a failing test

> The gallery test is failing. What's going on?

Your agent finds the failing run in your project, then opens that failure. Everything below arrives in a **single response**, not six round trips.

| What comes back | Example                                                 |
| --------------- | ------------------------------------------------------- |
| Analysis        | Blame: test data. The hard-coded listing URL now 404s.  |
| Error           | The exact Playwright error, with the surrounding lines. |
| Script          | The script that actually ran (v13, checksum-verified).  |
| Screenshot      | The failure screenshot, visually confirming the 404.    |
| History         | 24 runs, with a flakiness signal.                       |
| Dependencies    | The chain this test depends on.                         |

From here you have a diagnosis and can go straight to [what to do next](/next-steps).

## B. Start with no URL and no IDs

> What's failing in Peeps?

<Steps>
  <Step title="Your agent finds the project">
    It resolves which Peeps project this checkout belongs to, listing your projects if it needs to.
  </Step>

  <Step title="It lists what is currently failing">
    Asked about a recent period without naming a range, it looks back **seven days** by default. If that window comes back empty, the answer says why — see [reading the results](/reading-results).
  </Step>

  <Step title="You pick one">
    Or just say "look at the first one", and it opens the full failure exactly as in walkthrough A.
  </Step>
</Steps>

You get a list of what is red right now, and a way into any of it, without opening the Peeps web app or copying a run ID.

## C. Create new tests

Four questions, one engine. Pick the door that matches what you are doing — they all land in the same place.

<Warning>
  You approve **three times**, not once: the proposed cases, then a generation plan per case (up to ten chained scripts), then a run plan.
</Warning>

Up to 50 cases per call. Your agent continues in another call if there are more.

### C1. Am I covered?

> Do we have Peeps tests for password reset?

Your agent reads the behaviors out of your local code and searches your Peeps coverage for each one, using several phrasings and paging through all results. It sends **search terms only** — your source never leaves your machine.

You get one proposal, each behavior marked **covered**, **stale**, **gap**, or **uncertain**. Search is literal text matching, so read the proposal rather than assuming duplicates are impossible. Nothing is created without your approval.

### C2. Cover what I am building

> Cover what I've changed on this branch.

The same engine, entered from your branch diff at a natural milestone in the work. These cases carry their provenance — repo, base and head commit, PR — and show as "via MCP · you" in Peeps, so the team sees which change each test came from.

### C3. Add this specific test

> Add a test that verifies expired password-reset links are rejected.

For a known gap. Your agent searches first and reports any existing matches, then drafts the steps for your approval and creates the case.

New cases are **active but belong to no suite and no schedule**. Wire that up in Peeps.

### C4. Bring over my existing Playwright tests

> Bring my existing Playwright tests into Peeps.

This **converts**, it doesn't import. Your agent reads each test locally and keeps the intent, the assertions and the user flow, then drafts steps without your selectors and waits — which is where hand-written flakiness usually lives. Peeps stores exactly the steps you approve, so read them first.

Nothing else is uploaded. There is no source-code or file upload in the flow, only your approved steps plus commit references.

Peeps generates a fresh script from those steps using its own guidance for resilient selectors and timing, then attempts publication. Need your exact script bytes? Use the import in the Peeps web app instead.

### Then, from any door

A new case still needs a script. The rest of the flow is the same however you got here.

<Steps>
  <Step title="Pick an environment">
    One of your stored Peeps environments.
  </Step>

  <Step title="Approve the generation plan">
    Your agent shows you exactly which scripts will be created. A plan covers at most **ten** chained scripts. A dependency with no script gets one created; an existing dependency script is never replaced.
  </Step>

  <Step title="Peeps generates the script">
    By driving your app in a hosted browser. Generation is asynchronous, so your agent polls until it completes.
  </Step>

  <Step title="Peeps attempts publication, then you run it">
    Publication is attempted automatically after generation, but a generated script may still remain a draft. Your agent verifies **both** axes per script, then runs the new test and reports the result — all in the same conversation.
  </Step>
</Steps>