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

# Call your system when tests finish

> Use a cleanup companion to call an external URL after a test run, so your system knows the tests are done and can release what it lent them.

Peeps has no outgoing webhooks. To tell your system that tests are done, add a **cleanup companion** whose script calls your URL. A cleanup companion runs after the test it's linked to, whether that test passed or failed.

A typical use is a pool of shared resources. Your CI takes a device or account from the pool, [triggers a run](/automation/incoming-webhooks), and the cleanup companion returns it to the pool when the tests finish.

## How a cleanup companion runs

A cleanup companion is a test case linked to another test case. When the linked test runs, the companion runs after it, and after every test in the run that depends on the linked test, directly or through other tests.

* **It runs when the tests fail.** A failed test doesn't stop its companion.
* **It doesn't wait for unrelated tests.** A test in the same run that doesn't depend on the linked test can still be running when the companion calls back.
* **It runs once per copy of the linked test.** If you link one companion to three tests, it runs three times. If a test depends on two tests that share a prerequisite, Peeps runs each path as its own copy, and each copy of the linked test gets its own companion.
* **It starts in a new browser if the linked test failed.** A companion that only calls a URL doesn't need a browser session either way.
* **A stopped run may not call back.** If someone cancels the run, it hits a hard time limit, or the machine running it stops, the companion may not run.

So, to get one callback after the whole run:

* Link the companion to a test that every other test in the run depends on, such as the test that signs in.
* Keep the tests below it free of diamonds, where one test depends on two tests that share a prerequisite.
* Make your endpoint safe to call twice, and have your system take the resource back on its own after a timeout.

## Write the callback test

<Steps>
  <Step title="Store the token in your environment">
    In Peeps, open **Settings** and select **Environments** under **Project**. In the environment your tests run in, add a variable for your endpoint's token, such as `POOL_TOKEN`, with the type **API key**. Peeps stores it encrypted.
  </Step>

  <Step title="Create the test case">
    Create a test case, for example "Return device to pool", and set its **Test type** to **Cleanup**. A cleanup test only runs as a companion. A test of any other type also runs on its own when a selection that includes it runs, and would call back in the middle of the run.
  </Step>

  <Step title="Give it a script">
    The script calls your URL:

    ```ts theme={null}
    import { test, expect } from '@playwright/test';

    test('Return device to pool', async ({ request }) => {
      const response = await request.post('https://pool.example.com/return', {
        headers: { Authorization: 'Bearer {{POOL_TOKEN}}' },
      });
      expect(response.ok()).toBeTruthy();
    });
    ```

    Peeps replaces each `{{NAME}}` with that environment variable's value when the run starts. The values come from the environment as it is set in Peeps: the request that started the run can't add any. See [what a call can't do yet](/automation/incoming-webhooks#what-a-call-cant-do-yet). Your coding agent can add and publish a script you wrote: see [add a script you wrote](/mcp/create-and-import#get-a-script-for-a-new-test-case).
  </Step>

  <Step title="Publish the script">
    Without a published script, the callback never happens. In a run of several tests, Peeps skips the companion. A run of only its linked test is refused.
  </Step>
</Steps>

<Note>
  Test recordings can include the requests a test makes. Use a token that can only do this one call.
</Note>

## Link it

You need the Contributor role or above.

<Steps>
  <Step title="Open the test to link it to">
    Open the test case that should trigger the callback, for example the test every other test depends on.
  </Step>

  <Step title="Choose the companion">
    In the **Cleanup companion** panel, next to the steps, open **Select a cleanup test case...** and pick your callback test.
  </Step>

  <Step title="Apply the change">
    Click **Preview change** to see what it affects, then **Apply change**. The link applies to future runs.
  </Step>
</Steps>

Your coding agent can also link cleanup companions for you, and shows you the change before it makes it.

## Where results show

The companion's result shows with the batch, counted apart from the tests it follows. If your endpoint doesn't answer with a success, the companion fails and Peeps notifies you as it does for a failed batch. The tests' pass and fail counts don't change.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.