> 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/organizing-tests/suites/reusable-browser-session.md).

# Reusable browser session

Log in once in a Before all test and start every main suite test with the same cookies and localStorage.

Most suites start every test with the same steps: open the app, log in, wait for the dashboard. With a reusable browser session, one test from [Before all](https://docs.bugbug.io/organizing-tests/suites.md#before-all-after-all-tests) logs in, BugBug saves its cookies and localStorage, and every main suite test starts with that session already in the browser.

{% hint style="info" %}
Reusable browser sessions work only in cloud runs, in suites with [Before all / After all](https://docs.bugbug.io/organizing-tests/suites.md#before-all-after-all-tests) enabled. Local runs of the same suite ignore this setting.
{% endhint %}

### How it works

1. The selected Before all test runs as usual.
2. When the source test reaches a successful end, BugBug saves the cookies and the localStorage of the pages open in the test's tabs.
3. The test is marked "passed" and its run details show "Session saved".
4. Each main suite test restores its own copy of the saved cookies and localStorage before its first step. Its run details link to the source test run and show the reported restore outcome. "Show session details" lists the saved metadata and any reported cookies or localStorage origins that the browser rejected.
5. When the suite run finishes, BugBug deletes the saved session.

Only main suite tests get the saved session. Other Before all tests and all After all tests start with a fresh browser and have to log in on their own.

### Turn it on

{% stepper %}
{% step %}

#### Prepare a login test

Add a test that logs in to [Before all](https://docs.bugbug.io/organizing-tests/suites.md#before-all-after-all-tests). End it with an assertion that the user is logged in, on a page of your application (for example the dashboard). BugBug saves localStorage only for the pages that are open when the test ends.
{% endstep %}

{% step %}

#### Select it as the session source

Open the suite and click the settings icon in the "Before all" section header. Turn on "Reuse browser session across main tests" and select the login test. Save.

<figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2Fgit-blob-3fd1f054fd3b44aa92415584202ac70491b5d9a9%2Freusable-browser-session-settings.png?alt=media" alt="Before all settings with reusable browser sessions enabled and Sign in to Demo SaaS selected as the source test."><figcaption><p>Enable session reuse and select the Before all test that logs in to your application.</p></figcaption></figure>

You can also open the menu of a Before all test and choose "Reuse browser session across main tests". The selected test shows a "SESSION REUSED" badge.
{% endstep %}

{% step %}

#### Make the login steps in other tests conditional

Main tests start already logged in, so their login steps have to run only when they are needed. Wrap them in an [if condition](https://docs.bugbug.io/editing-tests/conditional-logic-if-else.md), for example "Element is visible" on the login form. If you keep login in a [component](https://docs.bugbug.io/editing-tests/components.md), add the condition once in the component.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Keep the conditional login in main tests even though they get the saved session. It is what keeps a test working when it runs alone, in a local run, in a rerun, or after the application rejects the saved session.
{% endhint %}

### Via API and YAML

The [Public API](https://docs.bugbug.io/integrations/public-api.md) reads and updates the session source test of a suite as `browserStateSourceTestId`, and the [YAML schema](https://docs.bugbug.io/export-import-and-backup/yaml-schema.md) as `browser_state_source_test`.

### When main tests start without the saved session

* **Rerun of failed tests.** A rerun doesn't add the session source test. If it passed in the original run, the rerun starts without a saved session and the tests log in through their conditional login steps. If the source test failed, it is part of the rerun and saves the session as usual.
* **The source test failed.** Like any failed Before all test, it stops the suite and the main tests are skipped.
* **The session couldn't be saved.** The source test fails with [BROWSER\_STATE\_CAPTURE\_FAILED](https://docs.bugbug.io/debugging-tests/error-codes.md#browser_state_capture_failed) and the suite stops.
* **The session couldn't be restored.** The main test stops with [BROWSER\_STATE\_RESTORE\_FAILED](https://docs.bugbug.io/debugging-tests/error-codes.md#browser_state_restore_failed).

### Tests that change the session

Each main test receives its own browser copy of the same snapshot. Changing a cookie or localStorage in one main test doesn't change another test's copy or the saved snapshot.

The copied credentials can still refer to the same session on your application's server. A test that logs out, changes the password, or otherwise invalidates that session can log other tests out, including tests running in parallel. Move such tests to After all or to a separate suite.

The same happens when your application rotates refresh tokens and rejects a token once it has been used (for example some Auth0, Amazon Cognito, or Supabase setups): the first test that refreshes the token logs the others out. The conditional login steps make them log in again.

### Cookies and restore results

BugBug saves HttpOnly cookies as well as cookies accessible to JavaScript. After restore, HttpOnly cookies are still sent to your application but remain hidden from page JavaScript. Partitioned cookies (CHIPS) retain their top-level site partition: a cookie saved under one top-level site does not become available under a different site.

Cookies keep their original expiry time. Reusing a snapshot does not extend their lifetime. A cookie can be present when the source test saves the session and expire before a main test starts. Run details warn about cookies whose saved expiry precedes the main test's start time; keep conditional login steps for that situation.

The restore banner distinguishes "Session reused", "Session partially restored", "Session not restored" and "Session restore not confirmed". A missing report means the result is unknown. Rejected individual cookies or localStorage origins are reported, but the test continues so its conditional login can recover.

Restore counts reflect operations accepted by the browser, not the number of cookies that remain active or proof that your application accepts the session. The browser can accept a write for an already-expired cookie without keeping it, so "Session reused" and an expiry warning can appear together. Session details show metadata, not cookie or localStorage values; they do not currently identify the top-level partition of each CHIPS cookie.

### Limitations

* BugBug saves cookies and localStorage. It doesn't save sessionStorage or IndexedDB. If your application keeps required authentication state there, the saved session alone may not log the test in; keep its login steps conditional.
* localStorage is captured from accessible frames of the open test tabs and restored by origin. The original third-party storage partition is not preserved, so authentication that depends on partitioned localStorage in an iframe may still require login. This is separate from CHIPS cookie partitioning, which is preserved.
* Sessions tied to an IP address or a browser fingerprint may be rejected, because the main tests run in different browsers.
* Applications that allow one active session per user, or use cookies that expire quickly, may reject the saved session in long suites.
* The saved session can be up to 5 MB.

### Security

The saved session contains your application's cookies, so BugBug encrypts it, lets only the browsers running the main tests of this suite run download it, and deletes it when the suite run finishes. Network logs of a test run still record the request headers, including cookies, as they did before.

### FAQ

<details>

<summary>Do I need to remove the login steps from main tests?</summary>

No. Keep them, inside an if condition. They are skipped when the saved session already logs the test in, and they run when it doesn't.

</details>

<details>

<summary>Can I select more than one source test?</summary>

No. One suite has one session source test, and it has to be an active test in Before all. If you remove it from Before all or from the suite, the setting turns off. If you deactivate it in the suite, the suite runs without a saved session until you activate it again.

</details>

<details>

<summary>Can I reuse the session across suites?</summary>

No. The session is saved for one suite run and deleted when that run finishes.

</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/organizing-tests/suites/reusable-browser-session.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.
