> For the complete documentation index, see [llms.txt](https://docs.sealights.io/knowledgebase/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent.md).

# Browser Agent

The SeaLights Browser Agent collects code coverage from web applications in the browser while tests run.

The SeaLights Browser Agent collects code coverage from your web application (React, Angular, Vue, Svelte or any other JavaScript front end) while tests run against it in a browser. It reports the coverage to SeaLights for the build and for the test stage that is open on its lab.

## How the agent gets into your application <a href="#how-it-gets-into-your-application" id="how-it-gets-into-your-application"></a>

You do not add the agent to your code. The [Node.js agent](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent.md) (`slnodejs`) instruments the built JavaScript of your application and adds a small loader, the **preamble**, to the instrumented files. When the page loads, the preamble:

1. sets the agent configuration of the build (application, branch, build, build session ID, lab ID, server, token);
2. loads the agent script from SeaLights, or from your SeaLights Collector when the build was instrumented with a Collector URL;
3. loads the build's mapping file (sl-mapping), unless the build resolves coverage on the server.

You deploy the instrumented files instead of the original files to the environment where tests run.

```
 CI:   build ──► slnodejs scan --instrumentForBrowsers ──► sl_dist/ (instrumented copy)
 Test environment:  browser loads sl_dist/ ──► preamble ──► Browser Agent ──► SeaLights (or Collector)
```

## What the agent sends <a href="#what-the-agent-sends" id="what-the-agent-sends"></a>

* **Footprints:** which instrumented code ran, grouped by the active test, sent to SeaLights or to the Collector.
* **Agent events:** agent start and shutdown, and errors.
* **Execution queries:** the agent periodically asks SeaLights which test stage is open for its lab ID, so that coverage is attributed to it. When the build has a Collector URL, the agent does not send these queries itself.

## Pages in this section <a href="#pages" id="pages"></a>

| Page                                                                                                                                                                     | Covers                                                                                                                                        |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| [Setting Up Browser Coverage](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/setting-up-browser-coverage.md) | End-to-end setup, checking the agent in the browser, multiple builds on one page, source maps                                                 |
| [Framework and Bundler Setups](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/framework-setups.md)           | Angular, React, Vue, Vite, webpack, esbuild, Rsbuild and Rspack, Rollup, micro-frontends                                                      |
| [Flags and Settings Guide](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/flags-and-settings-guide.md)       | Every flag and setting: what it does, the problem it solves, how to tell you need it, an example                                              |
| [Configuration and Runtime Overrides](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/configuration.md)       | Lab ID, Collector and token, allowed domains, content security policy, coverage settings, settings read at instrumentation, runtime overrides |
| [Context Propagation](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/context-propagation.md)                 | Attributing back-end coverage to the browser test: `--enableOpenTelemetry`, `--allowCORS`, test context events and cookies                    |
| [Troubleshooting](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/troubleshooting.md)                         | Agent not loading, no footprints, sl-mapping not found, missing context headers                                                               |

The `slnodejs` commands and flags that instrument the build are on [Frontend Instrumentation (static)](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-runtime-coverage/frontend-instrumentation-static.md) and in the [Command Reference](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/command-reference.md#browser-instrumentation).

## Requirements <a href="#requirements" id="requirements"></a>

| Requirement               | Status   | Effect when missing                                                                          |
| ------------------------- | -------- | -------------------------------------------------------------------------------------------- |
| `window` and `document`   | Required | The agent does not start.                                                                    |
| JavaScript language level | ES2015   | The agent bundle is compiled to ES2015 (ES6). Browsers without ES2015 support cannot run it. |
| `document.head`           | Required | The preamble cannot add the agent script; the agent does not load.                           |
| `window.sessionStorage`   | Optional | Test context set with `set:context` is not restored after a page navigation.                 |
| `console.log`             | Optional | The agent does not log.                                                                      |

## Quick check in the browser <a href="#quick-check" id="quick-check"></a>

Open the developer tools console on an instrumented page:

```js
window.$Sealights;                        // configuration written by the preamble
window.$SealightsAgent;                   // the agent; undefined when the agent script did not load
window.$SealightsAgent.getSlMapping();    // mapping the agent uses for the first build on the page
window.$SealightsAgent.dumpSlMappings();  // mappings of all builds on the page
```

A working agent also logs a line containing `has been loaded` for each build. See [Check that it works](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/setting-up-browser-coverage.md#check-that-it-works).


---

# 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.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent.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.
