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

# Run tests

> Run a test case in Peeps's hosted CI from your editor. You approve a plan that names the environment and everything that will run, then your agent follows the run to its result.

Your agent can run a Peeps test case in Peeps's hosted CI and report the result, without you opening the web app. Any role can run tests. Your connection needs the **Run** permission.

> Run the checkout test against staging.

## How a run works

<Steps>
  <Step title="Your agent finds the test">
    It searches your test cases for the one you mean and asks you if more than one could match. A test case with no published script can't run yet, and your agent says so.
  </Step>

  <Step title="It shows you the run plan">
    The plan is what you approve. It names:

    * the environment and the host it reaches
    * whether that environment is production
    * every script that will run, including the tests that run first and any cleanup test after
    * how many runs it will start

    Asking for the plan starts nothing.
  </Step>

  <Step title="You approve, and Peeps queues the run">
    Peeps queues the run once. It re-checks your access just before it hands the run to CI.
  </Step>

  <Step title="Your agent follows it to the result">
    It checks the run's status at the pace Peeps recommends, and reports pass or fail when it settles. If you disconnect, ask again later: the run keeps going, and your agent can pick it up.
  </Step>
</Steps>

<Warning>
  One approval can reach production. Your agent says plainly when a plan targets a production environment. Read the plan before you approve it.
</Warning>

## What a plan protects you from

* **It is single-use.** One approval starts one run.
* **It expires after 30 minutes.** An old approval can't be spent later.
* **It binds what you approved.** If the environment, its variables, the scripts or the tests that run first change before the run starts, Peeps refuses it. Your agent asks you to approve a new plan.

## When Peeps can't tell whether a run started

Rarely, Peeps can't confirm whether a run reached CI. It then reports the outcome as unknown and never retries on its own. Your agent does not start a second run to find out, because a duplicate run against production is the worse outcome. Check the run in GitHub or the Peeps web app instead.

There is also an hourly limit on how many runs a person and an organization can start from coding agents. If you reach it, Peeps says how long to wait.

## Worked example: running against staging

> **You:** Run the password reset test against staging.

Your agent finds the test case and asks Peeps for a run plan. It shows you:

> Run plan for "Password reset sends a working link"
>
> * Environment: STAGING (not production)
> * Runs first: "Sign up a new user"
> * Scripts that will run: 2
>
> Shall I start it?

> **You:** Go ahead.

Your agent starts the run and checks back on it at the pace Peeps sets. When the run settles, it reports that it passed.

If it failed, you can go straight on:

> **You:** Why did it fail?

Your agent opens the failure. See [troubleshoot and fix a failure](/troubleshoot-and-fix).

## Limits today

* Runs started this way are web (Playwright) test cases on GitHub Actions.
* If your project runs specs from your own repository in your own CI, run them there. Peeps refuses the run over MCP.
* Your agent runs one test case per plan. To run a suite or a schedule, use the Peeps web app.