> 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/flags-and-settings-guide.md).

# Flags and Settings Guide

Every flag and setting that affects browser coverage: what it does, the problem it solves, how to tell whether you need it, and an example.

Browser coverage is configured when `slnodejs` instruments the build (`slnodejs scan --instrumentForBrowsers` or `slnodejs instrument`), and a few values can be changed in the page at runtime. This page explains each setting: what it does, which problem it solves, how to tell whether you need it, and an example.

For the plain list of flags with defaults and aliases, see the [Command Reference](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/command-reference.md#browser-instrumentation).

## Quick reference <a href="#quick-reference" id="quick-reference"></a>

| Setting                                                                               | Solves                                               | You need it if                                                                |
| ------------------------------------------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------- |
| [`--instrumentForBrowsers`](#instrumentforbrowsers) + [`--outputPath`](#outputpath)   | Browser code reports coverage                        | Always, for browser coverage                                                  |
| [`--es6Modules`](#es6modules)                                                         | Parse errors on ES module bundles                    | The page loads bundles with `<script type="module">`                          |
| [`--labId`](#labid)                                                                   | Coverage lands in the wrong test stage               | More than one test environment, or parallel runs                              |
| [`--useRelativeSlMapping`](#userelativeslmapping)                                     | `instrument` refuses the build                       | You instrument with the separate `instrument` command                         |
| [`--instrumentationOnly`](#instrumentationonly)                                       | Re-instrumenting reports a duplicate build           | You instrument the same build again                                           |
| [`--collectorUrl`](#collectorurl)                                                     | Browsers cannot reach SeaLights                      | Test browsers have no internet access, or the token must stay out of the page |
| [`--excludeTokenFromBrowserConfig`](#excludetokenfrombrowserconfig)                   | Agent token readable in the page                     | Security policy forbids secrets in front-end code                             |
| [`--allowedDomains`](#alloweddomains)                                                 | Agent loads where it should not                      | The same files are served on several domains                                  |
| [`--splitPreambleIntoFile`](#splitpreambleintofile)                                   | Configuration copied into every file                 | You want one configuration file, served non-cacheable                         |
| [`--preambleFileUrl`](#preamblefileurl)                                               | 404 for the configuration file on deep routes        | You use `--splitPreambleIntoFile` in a single-page app without `<base href>`  |
| [`--toggleBasedBrowserInstrumentation`](#togglebasedbrowserinstrumentation)           | One artifact with and without SeaLights              | You must deploy one artifact everywhere                                       |
| [`--footprintsMapping server`](#footprintsmapping)                                    | Large sl-mapping download                            | Large applications with slow page loads                                       |
| [`--embedCorrectUniqueId`](#embedcorrectuniqueid)                                     | sl-mapping download blocked                          | The browser cannot download the sl-mapping                                    |
| [`--enableLineCoverage`](#enablelinecoverage)                                         | Method-level coverage only                           | You need line coverage                                                        |
| [`--enableOpenTelemetry`](#enableopentelemetry) + [`--allowCORS`](#allowcors)         | Back-end coverage not attributed to the browser test | E2E tests drive instrumented back ends                                        |
| [`--ctxPropagationOnly`](#ctxpropagationonly)                                         | Want test context, not browser coverage              | Only back-end coverage matters for this front end                             |
| [`--excludeSourceMapFiles`](#excludesourcemapfiles)                                   | Source maps shipped with the app                     | Source maps must not be deployed                                              |
| [`--preferSourceMapFromFile`](#prefersourcemapfromfile)                               | Wrong source map used                                | Bundles have both inline maps and `.map` files                                |
| [`--skipInstrumentingFilesWithoutSourceMap`](#skipinstrumentingfileswithoutsourcemap) | Vendor bundles instrumented                          | Third-party bundles without maps sit next to your code                        |
| [`.slignore.instrument`](#slignore-instrument)                                        | Libraries inside your bundles instrumented           | UI libraries add noise or break after instrumentation                         |
| [`--babylonPlugins`](#babylonplugins)                                                 | Parse errors on JSX or decorators                    | You scan un-transpiled JSX or decorator code                                  |
| [`--skipEsiScripts`](#skipesiscripts)                                                 | ESI blocks broken by instrumentation                 | You instrument `.html` pages with ESI blocks                                  |
| [`SL_reduceInstrumentedFileSize`](#reduce-file-size)                                  | Instrumented pages load slowly                       | Tests time out on page load after instrumentation                             |
| [`SL_fileExtensions`](#sl_fileextensions)                                             | Files not scanned                                    | Output uses `.cjs`, or inline scripts in `.html` must be covered              |
| [`SL_executionQueryIntervalSecs`](#sl_executionqueryintervalsecs)                     | Start of short tests not attributed                  | Tests are very short, or start right after the test stage opens               |
| [`SL_blockBrowserHttpTraffic`](#sl_blockbrowserhttptraffic)                           | Agent calls SeaLights                                | An environment must not send anything                                         |
| [`window["__sl.labId__"]`](#runtime-lab-id)                                           | Lab ID baked into the build                          | One build deployed to several environments                                    |
| [`sendAllFootprints()`](#sendallfootprints)                                           | Coverage lost when the page closes                   | Tests close pages or the browser right after an action                        |

***

## Core <a href="#core" id="core"></a>

### `--instrumentForBrowsers` <a href="#instrumentforbrowsers" id="instrumentforbrowsers"></a>

* **What it does:** besides scanning the build, writes an instrumented copy of the JavaScript files. Each instrumented file loads the Browser Agent.
* **Problem it solves:** a scan alone only reports the build's structure; the browser has nothing that records which code ran.
* **You need it if:** you want coverage from code that runs in a browser.
* **How to tell:** the code is served to browsers (a `dist`/`build` folder of bundles referenced by an `index.html`).
* **Example:** `npx slnodejs scan ... --scanDir dist --instrumentForBrowsers --outputPath sl_dist`

### `--outputPath` <a href="#outputpath" id="outputpath"></a>

* **What it does:** the folder for the instrumented copy. All files of `--scanDir` are copied there; JavaScript files are instrumented.
* **Problem it solves:** keeps the original build untouched, so you can deploy instrumented code to test environments and clean code to production.
* **You need it if:** always with `--instrumentForBrowsers` (required). It must differ from `--scanDir`.
* **Example:** `--outputPath sl_dist`, then deploy `sl_dist`.

### `--es6Modules` <a href="#es6modules" id="es6modules"></a>

* **What it does:** parses files as ES modules instead of classic scripts.
* **Problem it solves:** ES module bundles (`import`/`export` at top level) do not parse as classic scripts. Methods can be missed, and the dashboard shows warnings.
* **You need it if:** the bundler emits ES modules: Vite, Angular 17+, esbuild or Rollup with `format: esm`, webpack with `output.module`.
* **How to tell:** `index.html` loads the bundles with `<script type="module">`, or `grep -lE '^(import|export) ' dist/**/*.js` finds files, or the dashboard shows `File '<file>' parsed to AST with the following error(s): ...` mentioning `import`/`export`.
* **Example:** `npx slnodejs scan ... --es6Modules --instrumentForBrowsers --outputPath sl_dist`

### `--labId` <a href="#labid" id="labid"></a>

* **What it does:** the lab ID written into the build's configuration. The agent reports coverage for that lab, and SeaLights attributes it to the test stage open on that lab.
* **Problem it solves:** without it, the lab ID is the build session ID. When the same build runs in two environments, or two test stages run at the same time, their coverage mixes.
* **You need it if:** the build runs in more than one test environment, tests run in parallel on different environments, or the back end of the same environment already uses a lab ID.
* **How to tell:** coverage of one environment appears in another environment's test stage; the console shows `LabId:<value>` that differs from the lab the tests open their test stage on.
* **Example:** `--labId qa-env`. For several environments, instrument once per environment, or use the [runtime override](#runtime-lab-id).

***

## Instrumenting separately from the scan <a href="#instrument-later" id="instrument-later"></a>

### `--useRelativeSlMapping` <a href="#userelativeslmapping" id="userelativeslmapping"></a>

* **What it does:** keys the build's mapping by paths relative to `--scanDir`.
* **Problem it solves:** the `instrument` command, which can run later and in another folder, must find each file in the mapping.
* **You need it if:** you instrument with `slnodejs instrument` (for example once per environment, or in the deployment pipeline) instead of `scan --instrumentForBrowsers`.
* **How to tell:** `instrument` fails with `Build was performed without 'useRelativeSlMapping' flag`.
* **Example:** `npx slnodejs scan ... --scanDir dist --useRelativeSlMapping`, later `npx slnodejs instrument ... --workspacePath dist --outputPath sl_dist_qa --labId qa-env`

### `--instrumentationOnly` <a href="#instrumentationonly" id="instrumentationonly"></a>

* **What it does:** with `scan --instrumentForBrowsers`, instruments without reporting a new build.
* **Problem it solves:** a build session can be scanned only once; a second scan of the same build session fails.
* **You need it if:** you instrument an already scanned build again, for example for a second environment, and you do not use `instrument`.
* **How to tell:** the second scan fails because the build session was already scanned.
* **Example:** `npx slnodejs scan ... --instrumentForBrowsers --instrumentationOnly --outputPath sl_dist_staging --labId staging-env`

***

## Network and security <a href="#network-and-security" id="network-and-security"></a>

### `--collectorUrl` <a href="#collectorurl" id="collectorurl"></a>

* **What it does:** the browser loads the agent from your SeaLights Collector and sends coverage to it; the Collector forwards to SeaLights.
* **Problem it solves:** test browsers inside a closed network cannot reach SeaLights; and with a Collector, the token does not need to be in the page.
* **You need it if:** the test environment has no outbound internet access, a proxy blocks browser traffic to SeaLights, or the token must stay out of the page.
* **How to tell:** in the browser network tab, requests to `*.sealights.co` fail or are blocked; or the security team rejects the token in front-end files.
* **Example:** `--collectorUrl https://collector.qa.example.com:16500/api`

### `--excludeTokenFromBrowserConfig` <a href="#excludetokenfrombrowserconfig" id="excludetokenfrombrowserconfig"></a>

* **What it does:** leaves the agent token out of the build's browser configuration.
* **Problem it solves:** by default, anyone who can open the test environment can read the agent token from the page.
* **You need it if:** your security policy forbids secrets in front-end code, or test environments are reachable by people who must not have the token.
* **How to tell:** search the instrumented output for the token: `grep -rl "$(cat sltoken.txt | cut -c1-20)" sl_dist` finds files.
* **Example:** `--collectorUrl https://collector.qa.example.com:16500/api --excludeTokenFromBrowserConfig`. Always together with `--collectorUrl`; without a Collector, the agent calls SeaLights without a token and gets nothing through.

### `--allowedDomains` <a href="#alloweddomains" id="alloweddomains"></a>

* **What it does:** the preamble loads the agent only when the page's host name is in the comma-separated list.
* **Problem it solves:** the same instrumented files can be served on domains where the agent must not run (a demo site, a partner portal, production by mistake).
* **You need it if:** one instrumented artifact is reachable on several host names, and only some are test environments.
* **How to tell:** the instrumented artifact is published to a shared CDN or bucket that also serves non-test sites, or the console of a non-test site shows `has been loaded`.
* **Example:** `--allowedDomains app.qa.example.com,app.staging.example.com`

***

## The agent configuration file <a href="#configuration-file" id="configuration-file"></a>

### `--splitPreambleIntoFile` <a href="#splitpreambleintofile" id="splitpreambleintofile"></a>

* **What it does:** writes the browser agent configuration to one file in the output folder (`sl-preamble-config.js` by default) instead of embedding it in every instrumented file. The page loads it from `{preambleFileUrl}/{preambleFileName}`.
* **Problem it solves:** the configuration is in one place, which you can serve with its own cache headers.
* **You need it if:** your CDN or server caches bundles aggressively and the configuration must not be cached, or you need `--toggleBasedBrowserInstrumentation`.
* **How to tell:** your bundles are served with long-lived cache headers (`Cache-Control: immutable`, hashed file names on a CDN).
* **Example:** `--splitPreambleIntoFile --preambleFileUrl https://app.qa.example.com/static`. Deploy the configuration file with the bundles and serve it non-cacheable; when the browser cannot load it, the agent does not load. The page still loads the agent script from SeaLights or the Collector, so this does not remove the content security policy entries.

### `--preambleFileName` <a href="#preamblefilename" id="preamblefilename"></a>

* **What it does:** the name of the configuration file (default `sl-preamble-config.js`).
* **You need it if:** the default name clashes with a file you already serve. Do not change it with `--toggleBasedBrowserInstrumentation` (see below).

### `--preambleFileUrl` <a href="#preamblefileurl" id="preamblefileurl"></a>

* **What it does:** the folder URL the browser loads the configuration file from.
* **Problem it solves:** without it, or with a relative path, the browser resolves the file relative to the page URL (or `<base href>`). On a deep route of a single-page application (for example `/orders/42`) it requests `/orders/sl-preamble-config.js` and gets a 404.
* **You need it if:** you use `--splitPreambleIntoFile`, and the app has client-side routes and no `<base href>`, or the bundles are served from another host or sub-path.
* **How to tell:** the network tab shows a 404 for `sl-preamble-config.js` on some pages but not on the start page.
* **Example:** `--preambleFileUrl https://app.qa.example.com` (a full URL, or a relative path without leading or trailing `/`).

### `--toggleBasedBrowserInstrumentation` <a href="#togglebasedbrowserinstrumentation" id="togglebasedbrowserinstrumentation"></a>

* **What it does:** for each JavaScript file, writes `<name>_original.js`, `<name>_instrumented.js`, and replaces `<name>.js` with a small loader. The loader checks whether `/sl-preamble-config.js` exists at the root of the web server, then adds a `<script>` for the instrumented or the original file.
* **Problem it solves:** one artifact can be deployed everywhere; environments that serve the configuration file run with SeaLights, the others run the original code.
* **You need it if:** your release process allows only one artifact for all environments.
* **Requirements and limits:**
  * Requires `--splitPreambleIntoFile`. Without it, `slnodejs scan` prints `toggleBasedBrowserInstrumentation can only be used when splitPreambleIntoFile is true.` and neither scans nor instruments.
  * The loader always checks `/sl-preamble-config.js` at the web server root, whatever `--preambleFileName` and `--preambleFileUrl` say. Serve the configuration file there, with the default name.
  * The loader adds the chosen file as a classic, asynchronous script. ES module bundles, and bundles that the bundler's runtime loads itself (lazy chunks), do not fit this model. Use it only for classic-script bundles referenced from your HTML, and test it before relying on it.
* **Example:** `--splitPreambleIntoFile --toggleBasedBrowserInstrumentation`

***

## Coverage resolution <a href="#coverage-resolution" id="coverage-resolution"></a>

### `--footprintsMapping` <a href="#footprintsmapping" id="footprintsmapping"></a>

* **What it does:** `agent` (default): the browser downloads the build's sl-mapping and resolves coverage itself. `server`: the browser sends raw coverage and SeaLights resolves it.
* **Problem it solves:** for large applications, the sl-mapping is large; downloading it slows page loads and uses memory.
* **You need it if:** the application is large and pages load noticeably slower after instrumentation, or the sl-mapping download fails.
* **How to tell:** in the network tab, the sl-mapping request is large (several megabytes) or slow; or the console shows `Error while trying to load slMapping from server`.
* **Example:** `--footprintsMapping server`

### `--embedCorrectUniqueId` <a href="#embedcorrectuniqueid" id="embedcorrectuniqueid"></a>

* **What it does:** embeds the mapping in the instrumented files; the browser does not download the sl-mapping (`scan` only).
* **Problem it solves:** the same as `--footprintsMapping server`, solved at instrumentation time.
* **You need it if:** the browser cannot download the sl-mapping, and you prefer not to resolve on the server.
* **Example:** `npx slnodejs scan ... --instrumentForBrowsers --embedCorrectUniqueId`

### `--enableLineCoverage` <a href="#enablelinecoverage" id="enablelinecoverage"></a>

* **What it does:** reports line-level coverage in addition to methods (`scan` only).
* **You need it if:** your quality gates or reports use line coverage for this application.
* **Example:** `npx slnodejs scan ... --instrumentForBrowsers --enableLineCoverage`

***

## Context propagation <a href="#context-propagation" id="context-propagation"></a>

### `--enableOpenTelemetry` <a href="#enableopentelemetry" id="enableopentelemetry"></a>

* **What it does:** the agent adds the current test context (`baggage` header) to outgoing Fetch and XHR requests.
* **Problem it solves:** without it, back-end agents do not know which browser test triggered a request, so back-end coverage is attributed to the test stage only, not to individual E2E tests.
* **You need it if:** E2E tests drive this front end, it calls instrumented back ends, and you want per-test back-end coverage (for example for Test Impact Analysis of E2E tests).
* **How to tell:** back-end coverage appears in the test stage but not per test; requests in the network tab have no `baggage` header.
* **Example:** `--enableOpenTelemetry --allowCORS "https://app.qa.example.com,https://api.qa.example.com"`. Details: [Context Propagation](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/context-propagation.md).

### `--allowCORS` <a href="#allowcors" id="allowcors"></a>

* **What it does:** the origins that receive the context headers. The list replaces the page's own origin; `*` means every origin.
* **Problem it solves:** without it, headers go only to the page's own origin; APIs on other origins get nothing.
* **You need it if:** the front end calls back ends on another origin (another host, port or scheme).
* **How to tell:** the console shows `Not adding header ... because of origin difference`.
* **Example:** `--allowCORS "https://app.qa.example.com,https://api.qa.example.com"`. Include the page's own origin. Pass it to `scan --instrumentForBrowsers`; `instrument` currently drops it. The back end must allow `baggage` in `Access-Control-Allow-Headers`.

### `--ctxPropagationOnly` <a href="#ctxpropagationonly" id="ctxpropagationonly"></a>

* **What it does:** the preamble loads only the SeaLights OpenTelemetry plugin, not the Browser Agent: test context is propagated, browser coverage is not collected.
* **You need it if:** you need per-test back-end coverage but not this front end's coverage, for example a third-party or legacy UI.
* **Example:** `npx slnodejs scan ... --instrumentForBrowsers --outputPath sl_dist --ctxPropagationOnly`

***

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

### `--excludeSourceMapFiles` <a href="#excludesourcemapfiles" id="excludesourcemapfiles"></a>

* **What it does:** `none` (default): `.js.map` files are copied to `--outputPath`. `skipCopy`: not copied. `skipAndDelete`: not copied, and deleted from `--scanDir`.
* **Problem it solves:** source maps expose your source code to anyone who opens the deployed app.
* **You need it if:** your policy forbids deploying source maps (most production-like environments).
* **How to tell:** `ls sl_dist/**/*.js.map` lists files after the scan.
* **Example:** `--excludeSourceMapFiles skipCopy`

### `--preferSourceMapFromFile` <a href="#prefersourcemapfromfile" id="prefersourcemapfromfile"></a>

* **What it does:** when a bundle has both an inline source map and a `.map` file, uses the `.map` file.
* **Problem it solves:** some pipelines leave an inline map from an intermediate step (for example TypeScript output) and write the final map to a file; the inline one points to intermediate files.
* **You need it if:** methods resolve to compiled or intermediate files instead of your original sources, and the bundles also have `.map` files.
* **How to tell:** `sl-dry-run-output/sl-mapping.json` from `dryRun` lists generated files where you expect `src/...`.
* **Example:** `--preferSourceMapFromFile`

### `--skipInstrumentingFilesWithoutSourceMap` <a href="#skipinstrumentingfileswithoutsourcemap" id="skipinstrumentingfileswithoutsourcemap"></a>

* **What it does:** files without a source map are copied but not instrumented.
* **Problem it solves:** third-party scripts copied into the build folder (analytics, vendor SDKs, legacy libraries) get instrumented: noise in coverage, larger files, sometimes runtime errors.
* **You need it if:** the output folder contains JavaScript you did not build and that has no source map.
* **How to tell:** the coverage tree shows files such as `vendor/sdk.min.js`; `dryRun` lists them in `included-files.json`.
* **Example:** `--skipInstrumentingFilesWithoutSourceMap`

***

## What gets instrumented <a href="#what-gets-instrumented" id="what-gets-instrumented"></a>

### `.slignore.instrument` <a href="#slignore-instrument" id="slignore-instrument"></a>

* **What it does:** packages listed here are scanned but not instrumented. Patterns match package paths inside bundles, as resolved from source maps.
* **Problem it solves:** libraries bundled into your code (UI kits, charting, state management) inflate instrumented size and coverage noise; instrumenting some framework internals causes runtime errors (for example Angular `NullInjectorError`).
* **You need it if:** large libraries are bundled with your code, or the app breaks only when instrumented.
* **How to tell:** the coverage tree shows library code; or the instrumented app throws errors from inside a library that the original does not.
* **Example:** create `.slignore.instrument` in the project root. It **replaces** the built-in list (Angular, React, Vue, Svelte, Stencil, `core-js`, `regenerator-runtime`), so copy your framework's entries into it; see [Framework and Bundler Setups](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/framework-setups.md#common).

### `--babylonPlugins` <a href="#babylonplugins" id="babylonplugins"></a>

* **What it does:** extra parser plugins: `jsx`, `decorators-legacy`.
* **Problem it solves:** un-transpiled JSX or decorator syntax does not parse.
* **You need it if:** you scan sources that still contain JSX or decorators. Not needed for bundler output.
* **How to tell:** the dashboard shows `parsed to AST with the following error(s)` for `.jsx` or decorator code.
* **Example:** `--babylonPlugins jsx,decorators-legacy`

### `--skipEsiScripts` <a href="#skipesiscripts" id="skipesiscripts"></a>

* **What it does:** does not instrument `<script>` tags inside ESI comment blocks (`<!--esi ... -->`).
* **Problem it solves:** ESI blocks are processed by an edge server (Akamai, Varnish); instrumenting scripts inside them can break the page.
* **You need it if:** you instrument `.html` files (`SL_fileExtensions` includes `.html`) and they contain ESI blocks.
* **Example:** `SL_fileExtensions=.js,.html npx slnodejs scan ... --instrumentForBrowsers --skipEsiScripts`

### `SL_fileExtensions` <a href="#sl_fileextensions" id="sl_fileextensions"></a>

* **What it does:** replaces the list of scanned and instrumented extensions (default `.js`, `.jsx`, `.mjs`, `.es6`). `.html` and `.ftl` turn on instrumentation of inline `<script>` blocks.
* **You need it if:** the output uses `.cjs`, or inline scripts in HTML or FreeMarker pages must be covered.
* **How to tell:** files you expect are missing from `included-files.json` in `dryRun`.
* **Example:** `SL_fileExtensions=.js,.mjs,.html npx slnodejs scan ...`

***

## Size and performance <a href="#size-and-performance" id="size-and-performance"></a>

### `SL_reduceInstrumentedFileSize` / `--reduceFileSize` <a href="#reduce-file-size" id="reduce-file-size"></a>

* **What it does:** instruments without line-level counters, which makes instrumented files much smaller. `instrument` does it by default (`--no-reduceFileSize` turns it off); `scan --instrumentForBrowsers` does it only with `SL_reduceInstrumentedFileSize=true` or when SeaLights sets it remotely.
* **Problem it solves:** instrumented bundles can be several times larger; pages load slowly and tests time out.
* **You need it if:** tests time out on page load, or bundles grow beyond what your CDN or server accepts.
* **How to tell:** compare `du -sh dist sl_dist`; compare page load time with and without instrumentation.
* **Example:** `SL_reduceInstrumentedFileSize=true npx slnodejs scan ... --instrumentForBrowsers --outputPath sl_dist`

### `SL_minifyInstrumentedOutput` <a href="#sl_minifyinstrumentedoutput" id="sl_minifyinstrumentedoutput"></a>

* **What it does:** minifies the instrumented output.
* **You need it if:** instrumented files are too large even with reduced file size.
* **Example:** `SL_minifyInstrumentedOutput=true`

### `SL_inProcessInstrumentation` <a href="#sl_inprocessinstrumentation" id="sl_inprocessinstrumentation"></a>

* **What it does:** instruments in the `slnodejs` process instead of a pool of child processes.
* **You need it if:** the build environment restricts child processes, or instrumentation fails in the worker pool.
* **Example:** `SL_inProcessInstrumentation=true`

***

## Agent behavior in the browser (set at instrumentation) <a href="#agent-behavior" id="agent-behavior"></a>

These environment variables are read on the CI step that instruments the build and written into the build. Setting them in the browser has no effect.

### `SL_executionQueryIntervalSecs` <a href="#sl_executionqueryintervalsecs" id="sl_executionqueryintervalsecs"></a>

* **What it does:** how often the agent asks SeaLights which test stage is open for its lab, in seconds. The agent also sends buffered footprints at this interval.
* **Problem it solves:** right after a test stage opens, the agent does not know about it until its next query; very short tests lose their first seconds.
* **You need it if:** tests start immediately after the test stage opens, or each test lasts only a few seconds.
* **Example:** `SL_executionQueryIntervalSecs=5`

### `SL_footprintsCollectIntervalSecs` and `SL_footprintsBufferThresholdMb` <a href="#collect-and-buffer" id="collect-and-buffer"></a>

* **What they do:** how often collected hits move into the send buffer, and the buffer size that triggers a send before the interval. `SL_footprintsSendIntervalSecs` has no effect on the Browser Agent.
* **You need them if:** SeaLights support asks you to tune them for very busy pages.

### `SL_blockBrowserHttpTraffic` <a href="#sl_blockbrowserhttptraffic" id="sl_blockbrowserhttptraffic"></a>

* **What it does:** the agent sends nothing to SeaLights or the Collector: no footprints, events, execution queries or sl-mapping download.
* **You need it if:** an instrumented build must run somewhere without reporting, for example a performance test that measures instrumentation overhead.
* **Example:** `SL_blockBrowserHttpTraffic=true npx slnodejs scan ...`

### `--delayShutdownInSeconds` <a href="#delayshutdowninseconds" id="delayshutdowninseconds"></a>

Written into the build configuration, but the current Browser Agent does not use it. Leave it unset.

***

## Runtime overrides (in the page) <a href="#runtime-overrides" id="runtime-overrides"></a>

Set these in a script that runs before the instrumented files. Details: [Configuration and Runtime Overrides](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/configuration.md#runtime-overrides).

### `window["__sl.labId__"]` <a href="#runtime-lab-id" id="runtime-lab-id"></a>

* **What it does:** sets the lab ID for every build on the page; takes precedence over `--labId`.
* **Problem it solves:** with `--labId`, the lab ID is fixed per instrumented build.
* **You need it if:** one instrumented build is deployed to several environments.
* **Example:** `<script>window['__sl.labId__'] = 'staging-env';</script>` in each environment's HTML template.

### `window.$Sealights = { skipSlAgent: true }` <a href="#skipslagent" id="skipslagent"></a>

* **What it does:** the preamble does not load the agent on that page.
* **You need it if:** some pages of an instrumented app must run without the agent, for example a page that breaks with it while you investigate.

### `window.$SealightsAgent.sendAllFootprints()` <a href="#sendallfootprints" id="sendallfootprints"></a>

* **What it does:** sends the footprints the agent holds now.
* **Problem it solves:** footprints collected since the last periodic send are lost when the page or browser closes.
* **You need it if:** tests close the page or the browser right after the last action, and coverage of the end of tests is missing.
* **Example:** `await page.evaluate(() => window.$SealightsAgent && window.$SealightsAgent.sendAllFootprints());` before `page.close()`.

### `window.$Sealights.configuration.logLevel` <a href="#loglevel" id="loglevel"></a>

* **What it does:** sets the agent's console log level (`debug` for investigations).
* **You need it if:** you troubleshoot; see [Troubleshooting → Agent log level](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/troubleshooting.md#agent-log-level).


---

# 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/flags-and-settings-guide.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.
