> 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/node.js-agent/advanced-features/lightweight-v8-coverage-mode/how-to-use.md).

# How to Use

This page turns on [Lightweight V8 Coverage Mode](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/advanced-features/lightweight-v8-coverage-mode.md) for a Node.js service or for in-process tests.

The set-up is the same as [Backend Instrumentation (dynamic)](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-runtime-coverage/backend-instrumentation-dynamic.md), with two changes:

1. Scan the build with **`--rawCoverage`**.
2. Start the service with **`SL_useLeanCoverageListener=true`**.

## Prerequisites <a href="#prerequisites" id="prerequisites"></a>

* `slnodejs` **6.2.100** or later.
* Node.js **later than 20.6.0** where the service runs.
* A token and a build session ID. See [Scanning Your Application → Prerequisites](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/scanning-your-application.md#prerequisites).
* A test stage open on the service's lab while tests run. This mode sends coverage only for an open test stage. Your test runner, a [testing plugin](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-testing-plugins.md), or `openTestStage` opens it.

{% stepper %}
{% step %}

### Scan with `--rawCoverage`

Add `--rawCoverage` to your scan command:

```bash
printf '%s' "$SEALIGHTS_AGENT_TOKEN" > sltoken.txt
npx slnodejs scan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
  --scanDir dist --scmType git --rawCoverage
```

{% hint style="warning" %}
A build scanned without `--rawCoverage` cannot receive lightweight coverage. SeaLights can also turn raw coverage on for your account through remote configuration.
{% endhint %}

Scan the same files that the service runs, from the same project root. SeaLights matches V8 coverage to the scanned files by path and by the position of each function in the file.
{% endstep %}

{% step %}

### Start the service with lightweight mode on

Set `SL_useLeanCoverageListener=true` in the environment of `slnodejs run`, `slnodejs mocha` or the preload script.

{% tabs %}
{% tab title="slnodejs run" %}

```bash
export SL_useLeanCoverageListener=true
npx slnodejs run --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
  --labId qa-env -- dist/server.js
```

{% endtab %}

{% tab title="Preload script" %}

```bash
export SL_tokenFile="$PWD/sltoken.txt"
export SL_buildSessionIdFile="$PWD/buildSessionId"
export SL_labId=qa-env
export SL_useLeanCoverageListener=true
export NODE_OPTIONS="--require $PWD/node_modules/slnodejs/lib/preload.js"
node dist/server.js
```

{% endtab %}

{% tab title="Dockerfile" %}

```dockerfile
ENV SL_tokenFile=/run/secrets/sltoken/sltoken.txt \
    SL_buildSessionIdFile=/app/buildSessionId \
    SL_labId=qa-env \
    SL_useLeanCoverageListener=true \
    NODE_OPTIONS="--require /app/node_modules/slnodejs/lib/preload.js"
CMD ["node", "dist/server.js"]
```

{% endtab %}

{% tab title="slnodejs mocha" %}

```bash
export SL_useLeanCoverageListener=true
npx slnodejs mocha --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
  --testStage "Unit Tests" -- --recursive test
```

`mocha` reports the test results, applies Test Impact Analysis, and sends the coverage to the same test stage.
{% endtab %}
{% endtabs %}

#### TypeScript and compiled output <a href="#typescript" id="typescript"></a>

If you scan a compiled output folder (for example `--scanDir dist`) but the service starts from the project root, set the runtime project root to the same folder. Otherwise the agent reports paths such as `dist/app.js` while the scan expects `app.js`, and nothing matches.

* `slnodejs run`: add `--projectRoot dist`.
* Preload script: set `SL_projectRoot=dist`.

When you scan the project root (`--scanDir .`), no project root setting is needed.
{% endstep %}

{% step %}

### Check that it works

1. Start the service. The log shows `Running agent using lean V8 coverage listener`. If it shows `Lean coverage listener failed to start, falling back to NYC`, see [Troubleshooting](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/advanced-features/lightweight-v8-coverage-mode/troubleshooting.md#the-agent-falls-back-to-nyc).
2. While the service runs, the coverage folder (`.sl-cov` in the working directory by default) receives `coverage-*.json` files every `SL_COVERAGE_INTERVAL`.
3. Open a test stage on the service's lab, run your tests, and wait for one more cycle before you stop the service or close the test stage (see below).
4. Check the coverage on the dashboard.
   {% endstep %}
   {% endstepper %}

## Shutdown and the end of a run <a href="#shutdown" id="shutdown"></a>

Coverage reaches SeaLights in cycles: the service writes its coverage every `SL_COVERAGE_INTERVAL` milliseconds (default 10 seconds), and the listener sends what it has read when `SL_footprintsQueueSize` files with hits are waiting (default 2) or every `SL_footprintsSendIntervalSecs` seconds (default 10), whichever comes first.

| Event                                 | What happens                                                                                                                                                                                                                                                                                                                                |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SIGTERM` or `SIGINT` to `slnodejs`   | `slnodejs run` and `slnodejs mocha` forward `SIGTERM`, `SIGINT`, `SIGHUP` and `SIGQUIT` to your program (with or without `--forwardSignals`), and the listener starts sending the coverage it holds. `slnodejs` exits when that sending finishes or your program exits, whichever comes first. The preload script does not forward signals. |
| `SIGTERM` or `SIGINT` to your program | Your program exits immediately with exit code `0`. Its own handlers for these signals do not run.                                                                                                                                                                                                                                           |
| Your program exits on its own         | `slnodejs` exits right after it, with the program's exit code. Coverage of the last cycle, and coverage not sent yet, are not sent.                                                                                                                                                                                                         |
| `SIGKILL` or an out-of-memory kill    | Nothing is flushed. Coverage not written or not sent yet is lost.                                                                                                                                                                                                                                                                           |

To lose less coverage at the end of a run:

* After the last test, keep the service running for at least one more cycle (`SL_COVERAGE_INTERVAL` plus `SL_footprintsSendIntervalSecs`) before you stop it.
* Close the test stage after that: coverage sent after the test stage closes is not counted.
* For short runs, lower `SL_COVERAGE_INTERVAL` and `SL_footprintsSendIntervalSecs`.
* In Kubernetes, give the pod a termination grace period of at least 10 seconds.

## Child processes <a href="#child-processes-and-worker-threads" id="child-processes-and-worker-threads"></a>

* Node.js child processes that your program starts (`spawn`, `exec`, `execFile`, `fork` and their synchronous variants) inherit `NODE_V8_COVERAGE` and write their coverage **when they exit**. A child process started with its own environment that drops `NODE_V8_COVERAGE` writes none.
* Coverage written at the very end of the run is not sent. For child processes that run until the end of the run, such as Jest workers or long-lived worker processes, set **`SL_enableChildProcessPatcher=true`**: they then also write their coverage every `SL_COVERAGE_INTERVAL`.
* Do not set `SL_enableChildProcessPatcher=false` in this mode: your program then writes its coverage only when it exits, and that coverage is not sent.

## Turning it off <a href="#turning-it-off" id="turning-it-off"></a>

Remove `SL_useLeanCoverageListener`, or set it to `false`. The test listener goes back to NYC.


---

# 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/node.js-agent/advanced-features/lightweight-v8-coverage-mode/how-to-use.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.
