> 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/context-propagation.md).

# Context Propagation

Context propagation attributes the coverage of your back-end services to the browser test that triggered it. The Browser Agent adds the current test context to outgoing Fetch and XHR requests, and the SeaLights agents on your back-end services read it.

**Use it when:** end-to-end tests drive a web application that calls instrumented back-end services, and you want back-end coverage per test (for example for Test Impact Analysis of your E2E tests).

## Set it up <a href="#set-it-up" id="set-it-up"></a>

1. **Front end:** instrument with `--enableOpenTelemetry`, and list the back-end origins (and the page's own origin) in `--allowCORS`:

   ```bash
   npx slnodejs scan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
     --scanDir dist --scmType git --es6Modules \
     --instrumentForBrowsers --outputPath sl_dist --labId qa-env \
     --enableOpenTelemetry --allowCORS "https://app.qa.example.com,https://api.qa.example.com"
   ```
2. **Back end:** run the Node.js service with `slnodejs run --httpServerColoring`, on the same lab ID. Back ends in other languages need the equivalent setting of their SeaLights agent.
3. **CORS:** a back end on another origin receives the headers only if its CORS preflight response allows them. Add `baggage` to its `Access-Control-Allow-Headers`. With `set:context` (below), also add each other key of the event `detail` (for example `persist`), because the agent sends each of them as a header.
4. **Tests:** a SeaLights test framework plugin, or your own test code, sets the current test in the browser (see [Setting the current test](#setting-the-current-test)).

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

* Without `--allowCORS`, the headers are added only to requests to the page's own origin. Relative URLs count as the page's own origin.
* The list **replaces** the page's own origin. Include the page's origin in the list, or requests to it, including relative URLs, lose the headers.
* `*` sends the headers to every origin.
* An origin in the list also matches every URL that starts with it: `https://api.example.com` also matches `https://api.example.com.other.io`.
* When several builds on the page set `--allowCORS`, the agent uses the value of the last build that sets one.
* If any build on the page enables `--enableOpenTelemetry`, propagation applies to every request from the page.
* `slnodejs` rejects `--allowCORS` without `--enableOpenTelemetry`.

{% hint style="warning" %}
Pass `--allowCORS` to `slnodejs scan --instrumentForBrowsers`. `slnodejs instrument` currently drops the list, so a build instrumented with `instrument` adds the headers only to requests to the page's own origin.
{% endhint %}

## Setting the current test <a href="#setting-the-current-test" id="setting-the-current-test"></a>

A test framework integration, or your own test code, sets the current test by dispatching a browser event:

```js
window.dispatchEvent(
  new CustomEvent('set:baggage', {
    detail: {
      'x-sl-test-session-id': '<execution-id>',
      'x-sl-test-name': 'checkout adds item to cart',
      'x-sl-test-stage': 'E2E Tests',
    },
  }),
);
```

* `x-sl-test-session-id` and `x-sl-test-name` are required; `x-sl-test-stage` is optional.
* The agent answers with an `ack:context` event, and stores the values in the cookies `x-sl-execution-id`, `x-sl-test-name` and `x-sl-test-stage`, so the test context survives page navigations.
* To also keep the context in session storage across navigations, dispatch `set:context` instead, with the same values under a `baggage` key in `detail`.

Outgoing requests then carry the context in a `baggage` header, for example:

```
baggage: x-sl-test-session-id=<execution-id>,x-sl-test-name=checkout%20adds%20item%20to%20cart
```

### Setting the test before the page loads <a href="#cookies" id="cookies"></a>

A test framework can also set the test context with cookies that page scripts can read (not `HttpOnly`):

* `x-sl-execution-id`: the test execution ID (the value that `set:baggage` takes as `x-sl-test-session-id`);
* `x-sl-test-name`: the test name;
* `x-sl-test-stage`: optional.

Both `x-sl-execution-id` and `x-sl-test-name` must be set. When the page loads, a context in session storage (from `set:context`) takes precedence over the cookies; events dispatched later replace both.

### Clearing the current test <a href="#clearing" id="clearing"></a>

* `delete:context` clears the test context and deletes the three cookies.
* `delete:baggage` does the same for a context set with `set:baggage`.
* Both events work only in builds instrumented with `--enableOpenTelemetry`. Without it, the console shows an uncaught error, nothing is cleared, and coverage is still attributed to the previous test.
* Neither event clears the session storage copy of a context set with `set:context`. On the next page navigation the agent restores it. To end such a test, dispatch `set:context` with the next test, or clear `sessionStorage` in the test.

## Propagation without browser coverage <a href="#ctx-propagation-only" id="ctx-propagation-only"></a>

To propagate test context without collecting browser coverage, instrument with `--ctxPropagationOnly`. The preamble then loads only the SeaLights OpenTelemetry plugin script, not the Browser Agent. It loads it from the Collector when the build has a Collector URL, and from `https://agents.sealights.co` otherwise.

When the page has no SeaLights configuration at all, the agent script runs in context-propagation-only mode; call `window.$Sealights.enableContextPropagation()` to start propagating headers without collecting coverage.

## Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

See [Troubleshooting → Context propagation headers missing](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/troubleshooting.md#context-propagation-headers-missing).


---

# 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/context-propagation.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.
