> For the complete documentation index, see [llms.txt](https://docs.bugbug.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bugbug.io/running-tests/test-in-your-browser.md).

# Run (locally)

Run a BugBug test locally in your own Chrome: what you need, the incognito window, what to avoid during the run, what happens after a passed or failed run, local suites, using your Chrome profile, and

A local run runs the test in your own Chrome, through the BugBug extension. You see every step in the browser window, so it's the best way to write and debug tests. For runs without your computer, use [Run in cloud](/running-tests/in-cloud-on-server.md). See [other ways to run tests](/running-tests/running-tests.md).

{% hint style="info" %}
**In short**

* Click **Run** in the test. BugBug opens a new Chrome window and runs the steps.
* You need the [BugBug Chrome extension](/quick-start/install-test-recorder.md). Local runs are available on all plans, including Free.
* Don't use the mouse or keyboard in the test window, and keep it open and visible until the test ends.
* Local runs always open a visible window. There's no headless mode; to run tests without a window on your computer, run them in the cloud.
* A failed test leaves its window open so you can debug it.
  {% endhint %}

## Run a test locally

1. Open the test.
2. Choose the [profile](/editing-tests/variables.md#profiles) next to the **Run** button, if your project has more than one.
3. Click **Run**.
4. BugBug opens a new Chrome window at the test's screen size and runs the steps. The test editor shows the status of each step.

![Run button in the test editor](https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2FhmWdSYpham7BxEcrwn2I%2Fimage.png?alt=media\&token=a84224c4-1d38-4f9d-834e-699b5b73a249)

## What you need

* **The BugBug extension** in Chrome or another Chromium-based browser, such as Edge, Opera or Brave. Firefox and Safari aren't supported. See [Install Test Recorder](/quick-start/install-test-recorder.md).
* **Allow in Incognito** turned on for the extension, while **Incognito mode** is on in project settings (the default). In Opera, also turn on **Allow access to search page results**.

## The test window

By default, BugBug opens a new incognito window, so the test starts without cookies, local storage or sessions from your normal browsing.

* **Other incognito windows are closed first.** All incognito windows share cookies and storage, so BugBug asks you to close them before the run. Save any work in them before you confirm.
* **Don't use the mouse or keyboard in the test window.** The test runs in a real browser window, so your own actions reach the page too. For example, moving the mouse over the window can break a **Hover** step or open a menu the test doesn't expect. Let the test finish, then work in the window.
* **Keep the window visible.** Chrome can stop running a page that isn't visible. If you minimize or close the window, the run ends with the **Stopped** status.
* **No headless mode.** A local run always opens a visible window. To run tests in the background, without a window on your computer, use [Run in cloud](/running-tests/in-cloud-on-server.md).
* **Your Chrome profile instead of incognito.** Turn off **Incognito mode** in [project settings](/preventing-failed-tests/project-settings.md#incognito-mode-and-your-chrome-profile). BugBug then uses a normal window of the Chrome profile where the extension is installed, with its cookies and signed-in sessions.

## After the run

* **Failed test:** the window stays open on the page where the test stopped, so you can [debug it in Chrome](/debugging-tests/debug-in-chrome.md), for example check a selector in DevTools.
* **Passed test:** the window is closed if **Close windows on successful test run** is on in [project settings](/preventing-failed-tests/project-settings.md#general).
* The run is saved in [runs history](/debugging-tests/runs-history.md) with its [status](/running-tests/statuses.md), error codes and screenshots.

To stop in the middle of a test, use [Run and pause here](/running-tests/run-and-pause-here.md) or a [breakpoint](/debugging-tests/breakpoint-run-step-by-step.md). To change a step and continue from it, use [Edit & Rewind](/workflow-tips/edit-and-rewind.md).

## Local runs and suites

**Run** in a [suite](/organizing-tests/suites.md) runs its tests locally, one after another, because they share your browser's incognito storage. To run several tests at the same time, use **Run in cloud**.

## Local and cloud runs compared

|                              | Local run                | Cloud run                                     |
| ---------------------------- | ------------------------ | --------------------------------------------- |
| Browser window               | Visible on your computer | On BugBug's servers, nothing on your computer |
| Default step timeout         | 30 seconds               | 60 seconds                                    |
| Maximum duration of one test | No limit                 | 10 to 30 minutes, depending on the plan       |
| Network and IP address       | Your own                 | The Cloud Proxy's                             |
| Several tests at once        | No                       | Yes, up to your parallel runs                 |
| Plan                         | All plans                | Paid plans and trial                          |

See [Run in cloud](/running-tests/in-cloud-on-server.md) for details.

## FAQ

<details>

<summary>Why does BugBug want to close my incognito windows?</summary>

All incognito windows share cookies and storage. To start each test without leftovers from other windows, BugBug closes them before a local run or recording. Turn off **Incognito mode** in project settings to run tests in your Chrome profile instead.

</details>

<details>

<summary>Why did my local run stop or fail when I used my computer?</summary>

The test runs in a real window, so your mouse and keyboard reach the page too. Moving the mouse over the window can break a Hover step or open something the test doesn't expect. Minimizing or closing the window stops the run. Leave the window alone until the test ends, or run the test in the cloud.

</details>

<details>

<summary>Can I run tests locally in headless mode?</summary>

No. A local run always opens a visible browser window. If you need tests to run without a window on your computer, use [Run in cloud](/running-tests/in-cloud-on-server.md).

</details>

<details>

<summary>Can I use my own Chrome profile and its logged-in sessions?</summary>

Yes. Turn off **Incognito mode** in project settings. BugBug uses the Chrome profile where the extension is installed. To use another profile, install the extension in that profile. Cloud runs always use a fresh browser.

</details>

<details>

<summary>Can I run a test locally in Firefox or Safari?</summary>

No. BugBug supports Chrome and other Chromium-based browsers, such as Edge, Opera and Brave.

</details>

<details>

<summary>Can I run tests locally from the CLI or an AI agent?</summary>

No. The CLI, the Public API and BugBug MCP run tests in the cloud. Local runs are started with **Run** in the app.

</details>

<details>

<summary>Does the window close after the test?</summary>

After a failed test, no: it stays open for debugging. After a passed test, only if **Close windows on successful test run** is on in project settings.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.bugbug.io/running-tests/test-in-your-browser.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
