> ## 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 a bug scan

> Start a bug scan from the Bugs page: pick an environment and URL, optionally narrow the scope, sign in, and add reference documents or upload files, then follow the scan live.

You start a scan from the **Bugs** page in the Peeps web app. Starting and cancelling scans needs the **Contributor** role or above.

## Start a scan

**1. Open the Bugs page**

Select your project in the project switcher, then click **Bugs** in the sidebar under **Runs**. Click **New scan**. If the project has never been scanned, click **Scan for bugs** instead.

The **Discover new tests** dialog opens with **Find bugs** selected.

![The Discover new tests dialog in Find bugs mode, with Staging selected as the environment and a BASE\_URL variable as the application URL](https://mintcdn.com/peeps-ai/e5SiOQ2AD7q-J5yy/images/bug-scan/find-bugs-dialog.png?fit=max\&auto=format\&n=e5SiOQ2AD7q-J5yy\&q=85\&s=dd50abd34a3a376deb53e96010332424)

**2. Choose an environment**

Pick an environment under **Environment**. An environment is required, because sign-in details and files come from its variables. To make one, choose **Create new environment**, type a name such as `staging`, and click **Create**.

**3. Set the application URL**

Under **Application URL**, pick a URL variable from the environment, or click **+** to add one. To type an address instead, click **Or enter a URL directly**.

The agent starts at this URL. It can be your app's home page or a deeper page, such as `https://staging.example.com/login`.

**4. Add options, if you need them**

Four optional sections sit below the URL. Tick a section's checkbox to open it:

* **Exploration scope** narrows where the agent looks.
* **Authentication** signs the agent in to your app.
* **Reference documents** give the agent your specs.
* **File uploads** let the agent test upload fields.

Each option is described [below](#exploration-scope).

**5. Start the scan**

Click **Scan for bugs**. Peeps opens the scan's progress page.

To run the same scan on a timetable instead, click **Schedule**. See [Schedule scans](https://docs.peepsai.com/bug-scan/schedule-scans.md).

## Exploration scope

By default, the agent explores everything it can reach from the starting URL. Tick **Exploration scope** to choose how it explores instead.

![The Exploration scope section with Focus on specific areas selected and checkout flow, cart, account order history entered as the areas to prioritize](https://mintcdn.com/peeps-ai/e5SiOQ2AD7q-J5yy/images/bug-scan/find-bugs-scope.png?fit=max\&auto=format\&n=e5SiOQ2AD7q-J5yy\&q=85\&s=9fd8ac899abe26940d21a487bb805b2a)

| Option | What the agent does |
| - | - |
| **Explore everything** | Scans every page it can reach. This is the default. |
| **Focus on specific areas** | Runs every check on the areas you list, and only quick checks, such as console errors and broken images, on other pages. |
| **Restrict to specific areas only** | Scans only the pages and areas you list, and doesn't navigate beyond them. If it can't find an area, it says so in the scan summary. |
| **Document-guided only** | Scans only the pages and features described in the reference documents you select. |

For **Focus** and **Restrict**, list the areas in plain words, such as `checkout flow, cart, account order history`. The list can be up to 1,000 characters. **Document-guided only** needs at least one reference document, and the text box becomes optional guidance.

## Sign in to your app

To scan pages behind a login, tick **Authentication**. The agent signs in with test-account details stored as variables in the environment you picked, so you never type a password into the scan itself.

![The Authentication section with Username & password selected and username and password variables chosen](https://mintcdn.com/peeps-ai/e5SiOQ2AD7q-J5yy/images/bug-scan/find-bugs-auth.png?fit=max\&auto=format\&n=e5SiOQ2AD7q-J5yy\&q=85\&s=fb7125eabcc92a3e0a5b350102190391)

> [tab] Username & password
>
> Select **Username & password**, then choose a **Username variable** and a **Password variable**. The username variable must be of type username or email, and the password variable must be of type password. Click **+** next to a field to add a variable.
>
> The agent signs in when it reaches a login page, then scans both the public pages and the pages behind the login.

> [tab] Magic link
>
> Select **Magic link**, then choose a **Magic link email variable**. The variable must be of type magic-link email.
>
> The agent requests a sign-in link for that address and waits up to 60 seconds for the email to arrive.

The agent never completes a third-party sign-in, such as **Continue with Google**. It may click those buttons to check they open, but it signs in only with the method you configure.

> [!TIP]
>
> Use a dedicated test account. The agent clicks through your app as a real user would, and anything it does is done as that account.

## Reference documents

Tick **Reference documents** to give the agent your product specs or PRDs. It uses them to learn how your app should behave, and reports where the app differs from them.

The section lists the project's context documents. A document becomes selectable once Peeps has extracted its text, shown as **Extracted**. Click **Upload document** to add a new one. You can select up to 10 documents per scan.

## File uploads

Tick **File uploads** to let the agent test upload fields. Choose a file variable from the environment, or click **Add file variable** to upload a file. The agent uploads that file into any upload field it finds, and reports the field as a bug if the upload fails.

## Follow the scan

While the scan runs, its progress page shows each step the agent takes, such as **Running accessibility audit** or **Scanning /settings page**.

![The Scanning for bugs progress page listing completed steps and the current step, Checking broken links, with Go back and Cancel scan buttons](https://mintcdn.com/peeps-ai/e5SiOQ2AD7q-J5yy/images/bug-scan/scan-running.png?fit=max\&auto=format\&n=e5SiOQ2AD7q-J5yy\&q=85\&s=5b2317a671c3e5f994e35a228fa29593)

You don't need to keep the page open. Click **Go back** to return to the **Bugs** page. While the scan runs, its **New scan** button reads **Scanning...**, and clicking it reopens the progress page. Peeps also notifies you when the scan finishes. See [Notifications](https://docs.peepsai.com/bug-scan/schedule-scans.md#notifications).

When the scan completes, Peeps opens the **Bugs** page with the new results. Next, [review the bugs](https://docs.peepsai.com/bug-scan/review-bugs.md).

### Cancel a scan

Click **Cancel scan** on the progress page. The scan stops and is marked cancelled. A cancelled scan's results aren't saved.

### If a scan doesn't start

Peeps shows **Failed to start bug scan** with the reason. The most common ones:

* **A bug scan is already running for this project.** Wait for it to finish, or cancel it.
* **None of the selected documents have extracted text available yet.** Wait until the document shows **Extracted**, then try again.
* **Please enter a valid URL.** Check the address, for example `https://staging.example.com`.

### If a scan fails

The progress page shows **Bug scan failed**. Common causes:

* **The agent couldn't load your app.** Check that the URL is reachable from the internet, not only from your network.
* **The sign-in environment was deleted** after the scan was set up. Start a new scan with an existing environment.
* **The agent couldn't finish its report in time.** Narrow the scan with [Restrict to specific areas only](#exploration-scope).

If a scan keeps failing, [get in touch](mailto:support@peepsai.com) with the project and the time of the scan.


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