> 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.md).

# Lightweight V8 Coverage Mode

> **Applies to:** Node.js services, workers and in-process tests started with `slnodejs run`, `slnodejs mocha` or the preload script. Available from `slnodejs` **6.2.100**. Requires Node.js **later than 20.6.0**.

## What it is <a href="#what-is-it" id="what-is-it"></a>

The test listener has two ways to collect coverage:

|                                                                    | **Default (NYC)**                                                                                                                                                                                                                                                                                                                                                              | **Lightweight V8 mode**                                                                   |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| **How it collects coverage**                                       | Instruments your code in memory as it loads, adding counters to every function.                                                                                                                                                                                                                                                                                                | Reads the coverage that Node.js itself records (V8 coverage). Your code runs unchanged.   |
| **Overhead**                                                       | Higher: the instrumented code uses more memory and runs slower. Large services can start slowly or run out of memory.                                                                                                                                                                                                                                                          | Lower: no instrumented copy, no counters.                                                 |
| **Node.js version**                                                | 18 and later                                                                                                                                                                                                                                                                                                                                                                   | **Later than 20.6.0**                                                                     |
| **Applications**                                                   | Node.js processes. (Browser code is covered by the [Browser Agent](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent.md); Lambda by the [Lambda layer](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-runtime-coverage/aws-lambda-support.md).) | Node.js processes only.                                                                   |
| **Coverage per test**                                              | Yes                                                                                                                                                                                                                                                                                                                                                                            | No: coverage is reported per test stage                                                   |
| **HTTP coloring** (`--httpServerColoring`, `--httpClientColoring`) | Yes                                                                                                                                                                                                                                                                                                                                                                            | No                                                                                        |
| **Set-up change**                                                  | None (default)                                                                                                                                                                                                                                                                                                                                                                 | Scan with `--rawCoverage`; set `SL_useLeanCoverageListener=true` where the service starts |

Both modes use the same package, the same commands, and the same start-up methods. If lightweight mode cannot start, `slnodejs` logs `Lean coverage listener failed to start, falling back to NYC` and collects coverage with NYC.

## When to use it <a href="#when-to-use-lightweight" id="when-to-use-lightweight"></a>

* The service runs out of memory, or starts slowly, after adding SeaLights.
* Tests run noticeably slower against the instrumented service.
* You want the lowest overhead, and coverage per test stage is enough.

## When not to use it <a href="#when-to-use-regular" id="when-to-use-regular"></a>

* You need coverage per test, for example for Test Impact Analysis of functional tests through HTTP headers.
* The process runs on Node.js 20.6.0 or earlier. On those versions, `slnodejs run` and `slnodejs mocha` run your program inside the `slnodejs` process, where V8 coverage cannot be turned on: only child processes would be covered.
* You want to check the setup with `dryRun`, which does not simulate this mode.

## How it works <a href="#how-it-works" id="how-it-works"></a>

1. `slnodejs scan --rawCoverage` reports the build, plus the metadata SeaLights needs to process V8 coverage.
2. `slnodejs run` (or `mocha`, or the preload script) starts your program in a new Node.js process, with the Node.js variable `NODE_V8_COVERAGE` pointing to a coverage folder.
3. Inside your program, the agent makes Node.js write the coverage collected so far every `SL_COVERAGE_INTERVAL` milliseconds (10 seconds by default).
4. The `slnodejs` process watches the folder, reads each new coverage file, and sends the functions that ran to SeaLights, for the test stage open on the lab.
5. SeaLights maps the coverage to the methods of the scanned build.

With `slnodejs mocha`, the SeaLights Mocha reporter still opens the test stage, reports results and applies Test Impact Analysis; the lightweight listener sends the coverage to that test stage.

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

* [How to Use](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): set-up, TypeScript, shutdown.
* [Configuration](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/advanced-features/lightweight-v8-coverage-mode/configuration.md): the settings of this mode.
* [Troubleshooting](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/advanced-features/lightweight-v8-coverage-mode/troubleshooting.md): common problems and their log messages.


---

# 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.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.
