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):
slnodejsinstruments 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.
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
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 testconfigcreates a build session for applicationmy-app, branchmainand build1.0.0, and writes its ID tobuildSessionId.scanreports the code insrc.mocharuns the tests intest, reports coverage and results to the test stageUnit Tests, and skips the tests that Test Impact Analysis does not recommend.
Where to start
Pick your setup
Answer the questions in Choosing Your Setup, then copy the matching setup from Recommended Configurations.
Collect runtime coverage
Node.js service: Backend Instrumentation (dynamic)
Web application: Frontend Instrumentation (static) and the Browser Agent
AWS Lambda: AWS Lambda Instrumentation
Skip this step for unit tests only.
Capture tests
Capturing Tests: Mocha, NYC reports, other frameworks, and functional tests against a running application.
Reference
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
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?

