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

# 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](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent.md) 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](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-testing-plugins.md).
* **AWS Lambda functions**, through the SeaLights Lambda layer.

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

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`](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/command-reference.md#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         | [`scan`](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/command-reference.md#scan)                                                                                                                                                                                                                                                                                                                                                                                        | `slnodejs` reports the files, methods and branches of the build. For web applications it also writes an instrumented copy.          |
| 3. Collect coverage       | [`run`](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/command-reference.md#run), the preload script, the instrumented front end, or [`mocha`](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/command-reference.md#mocha)                                                                                                                                                                                     | The code reports which methods ran, for the lab it runs in.                                                                         |
| 4. Capture tests          | [`openTestStage`](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/command-reference.md#openteststage) / [`closeTestStage`](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/command-reference.md#closeteststage), `mocha`, a testing plugin, or [`uploadReports`](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/command-reference.md#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](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/configuration.md#labs-and-test-stages).

## Quick start: Mocha unit tests <a href="#quick-start" id="quick-start"></a>

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

```bash
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 <a href="#where-to-start" id="where-to-start"></a>

{% stepper %}
{% step %}

### Pick your setup

Answer the questions in [Choosing Your Setup](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/choosing-your-setup.md), then copy the matching setup from [Recommended Configurations](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/recommended-configurations.md).
{% endstep %}

{% step %}

### Install, create a session, scan

1. [Installing the Node.js Agent](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/downloading-the-node.js-agent.md)
2. [Generating a Session ID](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/generating-a-session-id.md)
3. [Scanning Your Application](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/scanning-your-application.md)
   {% endstep %}

{% step %}

### Collect runtime coverage

* Node.js service: [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)
* Web application: [Frontend Instrumentation (static)](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-runtime-coverage/frontend-instrumentation-static.md) and the [Browser Agent](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent.md)
* AWS Lambda: [AWS Lambda Instrumentation](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-runtime-coverage/aws-lambda-support.md)

Skip this step for unit tests only.
{% endstep %}

{% step %}

### Capture tests

[Capturing Tests](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-tests.md): Mocha, NYC reports, other frameworks, and functional tests against a running application.
{% endstep %}
{% endstepper %}

## Reference <a href="#reference" id="reference"></a>

| Page                                                                                                                                                 | Covers                                                                                                     |
| ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| [Flags Guide](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/flags-guide.md)             | What each flag solves and how to tell whether you need it                                                  |
| [Command Reference](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/command-reference.md) | Every command and flag, with defaults and when to use each flag                                            |
| [Configuration](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/configuration.md)         | Configuration sources and precedence, token, build session, labs, ignore files, every environment variable |
| [Troubleshooting](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/troubleshooting.md)     | Logs, common problems, TLS and proxy, what to send to support                                              |
| [Advanced Features](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/advanced-features.md) | `dryRun`, Next.js, Cloud Foundry, lightweight V8 coverage mode, uploading other reports                    |

## Supported versions <a href="#supported-versions" id="supported-versions"></a>

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


---

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