> 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/setting-up-browser-coverage.md).

# Setting Up Browser Coverage

This page instruments a built web application, deploys it, checks that the Browser Agent runs, and captures tests. For your framework or bundler, start from [Framework and Bundler Setups](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/framework-setups.md). The `slnodejs` options used here are described in [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).

## End-to-end setup <a href="#end-to-end-setup" id="end-to-end-setup"></a>

The steps below instrument an application built into `dist/` and write the instrumented copy to `sl_dist/`.

{% stepper %}
{% step %}

### Install `slnodejs` and save the token

```bash
npm install --save-dev slnodejs
printf '%s' "$SEALIGHTS_AGENT_TOKEN" > sltoken.txt
```

See [Installing the Node.js Agent](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/downloading-the-node.js-agent.md) and [Configuration → Token](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/configuration.md#token).
{% endstep %}

{% step %}

### Build with source maps

Build the application so that source maps with column information are written next to the bundles. See [Scanning → Front-end builds](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/scanning-your-application.md#scanning-a-frontend-build-bundled).

```bash
npm run build
```

{% endstep %}

{% step %}

### Create a build session

```bash
npx slnodejs config --tokenFile sltoken.txt --appName my-web-app --branchName main --buildName "1.0.$BUILD_NUMBER"
```

{% endstep %}

{% step %}

### Scan and instrument

```bash
npx slnodejs scan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
  --scanDir dist --scmType git --es6Modules \
  --instrumentForBrowsers --outputPath sl_dist \
  --labId qa-env --excludeSourceMapFiles skipCopy
```

{% endstep %}

{% step %}

### Deploy the instrumented copy

Deploy the contents of `sl_dist/` to the test environment in place of `dist/`. Never deploy it to production.
{% endstep %}

{% step %}

### Run the tests on the same lab

Coverage is attributed to the test stage that is open for the agent's lab ID (`qa-env` here). Either use a SeaLights test framework plugin (Playwright, Cypress and others; see [Node.js Testing Plugins](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-testing-plugins.md)) with the same lab ID, or open and close the test stage yourself:

```bash
npx slnodejs openTestStage --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --labId qa-env --testStage "E2E Tests"
# run the browser tests against the qa-env environment
npx slnodejs closeTestStage --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --labId qa-env --testStage "E2E Tests"
```

{% endstep %}
{% endstepper %}

## Check that it works <a href="#check-that-it-works" id="check-that-it-works"></a>

Open an instrumented page of the test environment and the browser developer tools console:

1. The agent logs `Sealights browser version <version> has been loaded` for each build that started. The line is logged at the `info` level, so it is hidden when the log level is `warning` or lower; see [Agent log level](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/troubleshooting.md#agent-log-level).
2. `window.$SealightsAgent` is defined. It is also defined when the agent rejected the configuration of every build on the page, so check the log line as well.
3. `window.$SealightsAgent.getSlMapping('<build-session-id>')` returns the mapping of that build (without an argument, the first build on the page). `window.$SealightsAgent.dumpSlMappings()` returns the mappings of all builds. An empty object means no mapping was loaded. (Builds instrumented with `--footprintsMapping server` or `--embedCorrectUniqueId` do not download a mapping.)
4. The agent logs the lab ID it uses as `LabId:<value>`. It must match the lab of the open test stage.
5. In the network tab, requests to SeaLights (or to the Collector) for footprints return success while you use the page.

If one of these fails, see [Troubleshooting](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/troubleshooting.md).

## Multiple builds on one page <a href="#multiple-builds-on-one-page" id="multiple-builds-on-one-page"></a>

Micro-frontends, separately deployed bundles and shared component libraries can each be instrumented as their own build (their own `config` and `scan`). Each instrumented build carries its own configuration, identified by its build session ID, and the agent runs one instance per build session ID on the page. A second configuration with a build session ID that is already running is ignored.

Give all builds that are tested together the same lab ID.

Code split into chunks of one build needs no extra setup: every chunk produced by the instrumented build reports to the same build session.

## Source maps <a href="#source-maps" id="source-maps"></a>

`slnodejs` uses your build's source maps during the scan to map the built files back to your source files. Keep the source maps next to the built files when you run the scan. To keep them out of the deployed output, scan with `--excludeSourceMapFiles skipCopy` (or `skipAndDelete`, which also deletes them from the scanned folder).

## Several test environments <a href="#several-test-environments" id="several-test-environments"></a>

Each environment needs its own lab ID. Instrument once per environment with its own `--labId`, or instrument once and set the lab ID at runtime with `window["__sl.labId__"]`. See [Frontend Instrumentation → Multiple test environments](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-runtime-coverage/frontend-instrumentation-static.md#multiple-test-environments) and [Configuration → Lab ID](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/configuration.md#lab-id).

## Next steps <a href="#next-steps" id="next-steps"></a>

* Content security policy, Collector, token exposure, allowed domains: [Configuration and Runtime Overrides](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/configuration.md).
* Back-end coverage per browser test: [Context Propagation](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/context-propagation.md).


---

# 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/setting-up-browser-coverage.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.
