> 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/preventing-failed-tests/project-settings.md).

# Project settings

Every BugBug project setting explained: timeouts, default sleep, logs and DOM snapshots, incognito mode, headers and user agent, screen sizes, selectors, waiting conditions, tags, visual regression, e

Project settings apply to every test and suite in the project. They have eight tabs: **General**, **Browser**, **Screen sizes**, **Selectors**, **Waiting conditions**, **Tags**, **Visual regression** and **Export & Backup**. Some settings can be overridden for a single step; each section below says which.

<figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2FaghxyHxi9ZiG6nodt7Yu%2Fimage.png?alt=media&amp;token=2b265b29-d481-49b5-9650-d44a75c86753" alt="Project settings page"><figcaption></figcaption></figure>

You can also read and change them through the [Public API](https://docs.bugbug.io/integrations/public-api.md), the [CLI](https://docs.bugbug.io/integrations/cli.md) (`bugbug project settings`) and in the `project.bugbug.yaml` file of a [project export](https://docs.bugbug.io/export-import-and-backup/yaml-schema.md).

## General

| Setting                                  | What it does                                                                                                                                                                                                                                                     |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Project name**                         | Name of the project.                                                                                                                                                                                                                                             |
| **Cover image**                          | Image shown on the projects list. Square, at least 256×256 px. Defaults to the website's favicon. Changes are saved immediately.                                                                                                                                 |
| **Timezone**                             | Timezone of the project's schedules. Default: UTC. When you change it, BugBug converts the hours of existing schedules, so they keep running at the same moment.                                                                                                 |
| **Cloud Proxy**                          | The proxy that cloud runs go through, so your site sees requests from a known IP address. Each option shows its IP, which you can allow in a firewall. Default: **UK - London** (`57.128.183.170`). See [Cloud runner IP addresses](#cloud-runner-ip-addresses). |
| **Default local run timeout**            | How long, in seconds, a step can take in local runs before it fails. Default: 30. See [Timeout](https://docs.bugbug.io/preventing-failed-tests/timeout.md).                                                                                                      |
| **Default cloud run timeout**            | The same for cloud runs. Default: 60.                                                                                                                                                                                                                            |
| **Default sleep**                        | Seconds to wait before every step that doesn't set its own delay. Default: 0. See [Delay / Sleep](https://docs.bugbug.io/preventing-failed-tests/delay-sleep.md).                                                                                                |
| **Close windows on successful test run** | Closes the browser window after a local run that passed. Only affects local runs.                                                                                                                                                                                |
| **Capture DOM on failure**               | Saves the page's DOM when a test fails, so you can inspect it in the run details. Enabled by default.                                                                                                                                                            |
| **Collect console logs**                 | Disabled by default. **Console logs** collects the browser console for each run. Large logs can slow tests down. **Full BugBug debugging** also collects BugBug's own logs; turn it on only when the support team asks.                                          |
| **Collect network logs**                 | **Basic** (default): Fetch/XHR, documents and manifests. **Full network logs**: also sockets, Wasm and other requests, which can make the log file very large. Error responses (4xx/5xx) and transport errors are always collected, even when this is disabled.  |

Steps can override the timeout and the sleep. Each step has its own **Timeout** and **Delay / Sleep** fields.

### Cloud runner IP addresses

Cloud runs reach your site through the proxy selected in **Cloud Proxy**. To let them through a firewall or allowlist, allow the IP address of that proxy:

| Cloud Proxy                        | IP address       |
| ---------------------------------- | ---------------- |
| UK - London (default)              | `57.128.183.170` |
| UK - London                        | `46.101.64.236`  |
| USA - San Francisco                | `146.190.14.118` |
| Poland - Gdansk (best performance) | `46.248.173.43`  |

The current list is also available, without authentication, at:

```
https://api.bugbug.io/v2/config/ips/
```

Local runs use your own browser and network, so they come from your own IP address.

## Browser

These settings apply to both recording and running tests.

| Setting                  | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Incognito mode**       | On by default: recording and local runs open a new incognito window, so each test starts with no cookies, local storage or session from earlier runs. Turn it off only to test something that depends on an existing session. See [Incognito mode and your Chrome profile](#incognito-mode-and-your-chrome-profile).                                                                                                                                                                                                              |
| **Browser language**     | Forces the browser language code, for example `de-DE`. Empty by default, so the browser's own language is used.                                                                                                                                                                                                                                                                                                                                                                                                                   |
| **User agent**           | Forces the browser's user agent string, up to 256 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| **HTTP request headers** | Extra headers sent with every request, as name and value pairs, for example to let BugBug through a [VPN or firewall](https://docs.bugbug.io/troubleshooting/vpn-or-a-firewall.md). Header names can contain letters, digits and common punctuation, but no spaces or colons. All headers together can be up to 4096 characters.                                                                                                                                                                                                  |
| **Media permissions**    | What the page gets when it asks for the camera or microphone during a run: **Do not fake**, **Always accept with default source** (default, fake devices) or **Always accept with custom source** (your own video and audio files). **Always decline** shows only when it is already set. A test can override it, and the [Media source](https://docs.bugbug.io/editing-tests/actions.md#media-source) step changes it mid-test. See [Camera & microphone](https://docs.bugbug.io/editing-tests/faking-camera-and-microphone.md). |
| **Blocked scripts**      | Stops scripts from the hosts or URLs you list, for example to keep chat widgets or popups out of your tests. Empty by default. See [Blocking scripts](https://docs.bugbug.io/preventing-failed-tests/blocking-scripts.md).                                                                                                                                                                                                                                                                                                        |

### Location permission

What the page is told when it asks for the user's location (`navigator.geolocation`), in every test of the project:

* **Do not fake**: nothing changes, the browser asks as usual. The [Geolocation](https://docs.bugbug.io/editing-tests/actions.md#geolocation) step fails in this mode.
* **Always accept with default location** (default): the page gets the location of the project's cloud proxy, or a fixed position in Warsaw (52.2297, 21.0122) when the proxy has none.
* **Always accept with custom location**: the page gets the latitude and longitude you enter, and optionally the accuracy in meters (10 by default). Set both coordinates.
* **Always decline**: the page is told that the user denied the permission.

A test can override the setting in its own settings, and a [Geolocation](https://docs.bugbug.io/editing-tests/actions.md#geolocation) step changes the position until the end of its test. See [Geolocation](https://docs.bugbug.io/editing-tests/faking-location.md) for the three levels.

### Incognito mode and your Chrome profile

* **On (default).** BugBug opens a new incognito window for recording and local runs. Before that, it asks you to close any other incognito windows. The BugBug extension needs **Allow in Incognito**, see [Install Test Recorder](https://docs.bugbug.io/quick-start/install-test-recorder.md).
* **Off.** BugBug opens a normal window of the Chrome profile where the BugBug extension is installed. The test has that profile's cookies, local storage and signed-in sessions, and whatever the test changes stays in the profile. Use it, for example, to test with an account you're already signed in to.
* **Other Chrome profiles.** BugBug uses the profile where the extension is installed. To use another profile, install the extension in that profile.
* **Cloud runs** don't use incognito mode, whatever this setting is. Every cloud run gets a fresh browser, so it always starts without cookies, local storage or sessions from earlier runs.

## Screen sizes

The window size, in pixels, used for recording and running tests:

| Screen size | Default    |
| ----------- | ---------- |
| **Desktop** | 1366 × 786 |
| **Mobile**  | 500 × 750  |

The minimum width and height is 500 px. The size is the whole browser window, including its toolbars. Each test uses one of the two sizes, chosen in the test's settings. There's no full screen, maximized window or zoom, by design: a defined window size makes every run see the same layout, so tests are deterministic. To test a bigger screen, set a bigger Desktop size. See [Changing the test screen size](https://docs.bugbug.io/workflow-tips/changing-the-test-screen-size.md) and [Mobile testing](https://docs.bugbug.io/workflow-tips/mobile-version-testing.md).

## Selectors

How BugBug builds [selectors](https://docs.bugbug.io/preventing-failed-tests/selectors.md) when you record a test.

Choose a **Selectors generation mode**:

* **Automatic**: BugBug decides which selectors are best. You can set:
  * **Include custom attributes**: attributes BugBug should prefer. Default: `data-testid, data-test`.
  * **Excluded attributes**: attributes BugBug should never use, for example `style, onclick, onload`.
  * **Include non-semantic classes**: whether class names that don't describe the element, such as generated CSS class names, can be used. Disabled by default.
* **Manual**: you choose which kinds of selectors are recorded and in which order. Drag the rows to change the priority, and enable or disable each kind: `id`, input or form name, `href`, input placeholder, class name, text content, XPath, custom attributes, ARIA attributes, unique attributes, data attributes, short tags XPath, tag, URL attributes and other attributes. Custom attributes take a list of attributes to include, and unique attributes a list of attributes to exclude.

## Waiting conditions

The default [waiting conditions](https://docs.bugbug.io/preventing-failed-tests/waiting-conditions.md) for every step: which are on, and the **Max. pending requests** for **Page network requests are finished**. A step can override any condition in its own **Waiting conditions** section.

## Tags

Create, rename, recolor and delete the project's [tags](https://docs.bugbug.io/organizing-tests/tags.md).

## Visual regression

Defaults for visual regression steps:

| Setting                        | What it does                                                                                                   |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| **Maximum allowed difference** | The percentage of pixels that can differ between the images before the step fails, from 0 to 100. Default: 10. |
| **Color sensitivity**          | How different the color of the same pixel can be before it counts as changed, from 0 to 1. Default: 0.2.       |
| **Include anti-aliasing**      | Whether anti-aliased pixels are compared. Enabled by default. Disable it to ignore anti-aliasing differences.  |

## Export & Backup

* **Export project** downloads the whole project as a ZIP: tests, components, profiles and suites. See [Exporting](https://docs.bugbug.io/export-import-and-backup/exporting.md).
* **List of backups** shows the [automatic daily backups](https://docs.bugbug.io/export-import-and-backup/backups.md). To restore one, download it and import it from the projects list with **Import project**. It's imported as a new project.

## What isn't in project settings

* **API token**: in **Integrations → API Token**. See [Public API](https://docs.bugbug.io/integrations/public-api.md).
* **Variables and profiles**: in **Variables**. See [Variables](https://docs.bugbug.io/editing-tests/variables.md).
* **Team members and plan**: in the organization settings.

## FAQ

<details>

<summary>Can I set a different window size for one test?</summary>

Each test uses either the **Desktop** or the **Mobile** size from project settings. Choose which one in the test's settings. A per-test custom resolution isn't available. See [Changing the test screen size](https://docs.bugbug.io/workflow-tips/changing-the-test-screen-size.md).

</details>

<details>

<summary>Can a test run in full screen or with page zoom?</summary>

No, by design. A full screen window has a different size on every computer, so the same test could behave differently on a laptop, a large monitor and in the cloud. The test window always opens in normal mode at the Desktop or Mobile size, so the test is deterministic. To test a bigger screen, set a bigger Desktop size, for example 1920 × 1080.

</details>

<details>

<summary>Can BugBug run tests in my Chrome profile, without incognito mode?</summary>

Yes, for recording and local runs. Turn off **Incognito mode** in the **Browser** tab. BugBug then uses a normal window of the Chrome profile where the extension is installed, with its cookies and signed-in sessions. Cloud runs always use a fresh browser. See [Incognito mode and your Chrome profile](#incognito-mode-and-your-chrome-profile).

</details>

<details>

<summary>What's the difference between "Collect console logs" and "Collect network logs"?</summary>

Console logs are what the page writes to the browser console. Network logs are the HTTP requests the page makes. They're collected separately, and both appear in the run details.

</details>

<details>

<summary>Can I change project settings through the API or MCP?</summary>

Yes. The Public API and MCP can read and update project settings.

</details>

<details>

<summary>Which IP addresses do BugBug cloud runs use?</summary>

The IP address of the Cloud Proxy selected in project settings. By default that's UK - London, `57.128.183.170`. See [Cloud runner IP addresses](#cloud-runner-ip-addresses) for all options.

</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/preventing-failed-tests/project-settings.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.
