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

Node.js Agent

Set up the SeaLights Node.js agent (slnodejs) for Node.js services, web applications, and their tests.

The SeaLights Node.js agent, slnodejs, collects code coverage and test results from JavaScript and TypeScript applications and reports them to SeaLights for coverage analysis, quality gates and Test Impact Analysis.

It covers:

  • Node.js services, workers and CLIs: coverage is collected at runtime while tests run against the process.

  • Web applications (React, Angular, Vue and other bundled front ends): slnodejs instruments the built files, and the SeaLights Browser Agent collects coverage in the browser.

  • Unit tests: Mocha through slnodejs mocha, NYC reports from any framework, and Jest, Cypress, Playwright, Cucumber.js and TestCafe through the Node.js Testing Plugins.

  • AWS Lambda functions, through the SeaLights Lambda layer.

How it works

Every setup follows the same four steps. Only step 3 changes with the kind of application.

Step
Command
What happens

1. Create a build session

config (or prConfig for pull requests)

SeaLights creates a build session for the application, branch and build, and slnodejs writes its ID to the file buildSessionId.

2. Scan the build

slnodejs reports the files, methods and branches of the build. For web applications it also writes an instrumented copy.

3. Collect coverage

run, the preload script, the instrumented front end, or mocha

The code reports which methods ran, for the lab it runs in.

4. Capture tests

openTestStage / closeTestStage, mocha, a testing plugin, or uploadReports

A test stage is open on the lab while tests run, so coverage is attributed to it. Test results are reported.

Coverage reaches the right test stage only when the agent collecting it and the test stage use the same lab ID. See Labs and test stages.

Quick start: Mocha unit tests

Run from the project root. Replace <your-agent-token> with the agent token from the SeaLights dashboard.

npm install --save-dev slnodejs
echo "<your-agent-token>" > sltoken.txt
npx slnodejs config --tokenFile sltoken.txt --appName my-app --branchName main --buildName 1.0.0
npx slnodejs scan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --scanDir src --scmType git
npx slnodejs mocha --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --testStage "Unit Tests" -- --recursive test
  1. config creates a build session for application my-app, branch main and build 1.0.0, and writes its ID to buildSessionId.

  2. scan reports the code in src.

  3. mocha runs the tests in test, reports coverage and results to the test stage Unit Tests, and skips the tests that Test Impact Analysis does not recommend.

Where to start

1

Pick your setup

Answer the questions in Choosing Your Setup, then copy the matching setup from Recommended Configurations.

3

Collect runtime coverage

Skip this step for unit tests only.

4

Capture tests

Capturing Tests: Mocha, NYC reports, other frameworks, and functional tests against a running application.

Reference

Page
Covers

What each flag solves and how to tell whether you need it

Every command and flag, with defaults and when to use each flag

Configuration sources and precedence, token, build session, labs, ignore files, every environment variable

Logs, common problems, TLS and proxy, what to send to support

dryRun, Next.js, Cloud Foundry, lightweight V8 coverage mode, uploading other reports

Supported versions

Item
Supported

Node.js

18 and later (tested: 18, 20, 22)

Operating systems

Linux (tested); macOS and Windows (not tested by SeaLights)

Coverage engines

NYC (default), Istanbul (SL_useIstanbul=true), lightweight V8 (SL_useLeanCoverageListener=true, Node.js later than 20.6.0)

Test frameworks

Mocha (built in); any framework through run, NYC reports or JUnit uploads; plugins for Jest, Cypress, Playwright, Cucumber.js, TestCafe

Last updated

Was this helpful?