For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

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; Lambda by the Lambda layer.)

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

  • 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

  • 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

  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

Last updated

Was this helpful?