> 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/choosing-your-setup.md).

# Choosing Your Setup

Answer a short list of questions about your application, tests and environment to find the right slnodejs setup and the flags it needs.

The right `slnodejs` setup depends on what runs your code, how it is built, which tests you want to capture, and where they run. Answer the questions below (or go through them with your SeaLights Solution Architect), then follow the matching configuration in [Recommended Configurations](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/recommended-configurations.md). For web applications, also see [Framework and Bundler Setups](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/framework-setups.md). Each flag mentioned here is explained in the [Flags Guide](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/flags-guide.md) and the [Browser Agent Flags and Settings Guide](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/flags-and-settings-guide.md).

## Before you start: collect these facts <a href="#facts-to-collect" id="facts-to-collect"></a>

| Fact                                                   | Why it matters                                                                                 | How to check                                                                      |
| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Node.js version of the build agents and of the runtime | `slnodejs` supports Node.js 18 and later. Lightweight V8 mode needs Node.js later than 20.6.0. | `node -v`                                                                         |
| Module system                                          | ES modules need `--es6Modules`.                                                                | `"type": "module"` in `package.json`, or `.mjs` files                             |
| Build output                                           | Decides what you scan.                                                                         | Is there a `dist/` or `build/` folder? Is code bundled, transpiled, or run as is? |
| Source maps                                            | Bundled and transpiled code needs source maps during the scan.                                 | `*.js.map` files next to the output, or `sourceMappingURL` comments               |
| Test frameworks and where each runs                    | Decides how tests are captured.                                                                | `package.json` scripts, CI pipeline                                               |
| How the application starts in the test environment     | Decides between `slnodejs run` and the preload script.                                         | Dockerfile `CMD`, `npm start`, `pm2`, Kubernetes manifest                         |
| Network constraints                                    | Proxy, TLS inspection, SeaLights Collector, token exposure rules.                              | Ask the network or security team                                                  |

## The questions <a href="#the-questions" id="the-questions"></a>

### 1. What runs the code you want coverage for? <a href="#q1-what-runs-the-code" id="q1-what-runs-the-code"></a>

| Answer                                                  | Setup                                                                                                                                                               | Read                                                                                                                                                                                                                                                                                                                                          |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A Node.js process: API, service, worker, CLI            | Scan the code, then run the process with the test listener (`slnodejs run` or the preload script).                                                                  | [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)                                                                                                                                 |
| A browser: React, Angular, Vue or other web application | Scan and instrument the built files, deploy the instrumented copy to the test environment. The browser agent collects the coverage.                                 | [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), [Browser Agent](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent.md) |
| Both, in separate applications                          | One build session per application (one `config` each), each set up as above. Add context propagation if the front end calls the back end during tests (question 6). | [Full stack](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/recommended-configurations.md#full-stack-front-end-and-back-end)                                                                                                                                                      |
| Both, in one application (Next.js, Nuxt, other SSR)     | One build session, two scans with `--moduleName`: the browser bundles with `--instrumentForBrowsers`, the server bundles without.                                   | [Next.js](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/advanced-features/next.js-with-sealights-node-and-browser-agents-multi-module-scan.md)                                                                                                                                   |
| AWS Lambda functions                                    | Scan with `--awsConfigure`, attach the SeaLights Lambda layer.                                                                                                      | [AWS Lambda](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-runtime-coverage/aws-lambda-support.md)                                                                                                                                                                     |
| Only unit tests; the code never runs elsewhere          | Scan, then capture the unit tests. No runtime agent is needed.                                                                                                      | [Capturing Tests](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-tests.md)                                                                                                                                                                                              |

### 2. How is the code built? <a href="#q2-how-is-the-code-built" id="q2-how-is-the-code-built"></a>

Scan the files that actually run, so that runtime coverage matches the scan.

| Answer                                                            | What to scan                                                               | Flags                                                                                                                                                                                                                                                  |
| ----------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Plain JavaScript that runs as is                                  | The source folder, for example `src` or `.`                                | `--scanDir src`                                                                                                                                                                                                                                        |
| TypeScript or Babel, compiled to an output folder                 | The output folder, with source maps                                        | `--scanDir dist`; `--projectRoot` so that runtime paths match (see [Scanning](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/scanning-your-application.md#typescript-and-transpiled-code)) |
| TypeScript run directly with `ts-node`                            | The source folder                                                          | `--scanDir src`; `SL_fileExtensions=.ts` if `.ts` files must be scanned                                                                                                                                                                                |
| Bundled (webpack, Vite, Rollup, esbuild, Angular CLI)             | The bundle output folder, with source maps that include column information | `--scanDir dist --es6Modules` (if the bundles are ES modules)                                                                                                                                                                                          |
| ES modules (`"type": "module"`)                                   | As above                                                                   | `--es6Modules` on `scan` and on `run`/`mocha`                                                                                                                                                                                                          |
| Several packages or apps in one repository that ship as one build | Each package, into the same build session                                  | `--moduleName <name>` per scan, then `completeScan --ok`                                                                                                                                                                                               |

### 3. Which tests do you want to capture, and where do they run? <a href="#q3-which-tests" id="q3-which-tests"></a>

| Answer                                                                          | Model                                                                         | Key point                                                                                                                                                                                                                                                                                                |
| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Unit or component tests that load the code in the test process                  | **In-process.** Coverage comes from the test process.                         | Identify the test stage by the build session ID; no lab ID needed.                                                                                                                                                                                                                                       |
| Functional, API, integration or end-to-end tests against a deployed application | **Out-of-process.** Coverage comes from the agent in the running application. | The test runner and the application must use the **same lab ID**, and a test stage must be open on it while the tests run. 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). |
| Manual tests                                                                    | Out-of-process, with a test stage you open and close yourself.                | `openTestStage` before, `closeTestStage` after.                                                                                                                                                                                                                                                          |

### 4. Which test framework runs the tests? <a href="#q4-which-test-framework" id="q4-which-test-framework"></a>

| Framework                                                                                                          | Integration                                             | Test Impact Analysis                                                                                                                                                  |
| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Mocha                                                                                                              | `slnodejs mocha`                                        | Yes                                                                                                                                                                   |
| Jest, Cypress, Playwright, Cucumber.js, TestCafe                                                                   | SeaLights plugins                                       | See each plugin in [Node.js Testing Plugins](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-testing-plugins.md) |
| Karma, AVA, Vitest (Istanbul provider), or any framework that produces an NYC (Istanbul) JSON report and JUnit XML | `nycReport` + `uploadReports`                           | No                                                                                                                                                                    |
| Any other framework, for example Jasmine                                                                           | `slnodejs run --useinitialcolor true` + `uploadReports` | No                                                                                                                                                                    |

See [Capturing Tests](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-tests.md) and [Other Test Frameworks](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-tests/other-test-frameworks.md).

### 5. How does the application start in the test environment? <a href="#q5-how-does-it-start" id="q5-how-does-it-start"></a>

| Answer                                                                                       | Use                                   | Why                                                                            |
| -------------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------ |
| You control the start command, for example `node server.js` in a script or Dockerfile        | `slnodejs run ... -- server.js`       | Accepts every flag; can forward signals (`--forwardSignals`).                  |
| A wrapper starts it: `npm start`, `pm2`, `nodemon`, a platform entry point you cannot change | Preload script through `NODE_OPTIONS` | No change to the start command. Settings come from environment variables only. |
| Several Node.js processes in a dedicated test container, all of which should be covered      | Preload script through `NODE_OPTIONS` | Applies to every Node.js process started in that environment.                  |

The preload script does not forward signals, cannot turn on HTTP coloring (per-test coverage, question 6), and cannot collect NYC coverage from an ES modules program. Use `slnodejs run` for those.

### 6. Do you need coverage per test, or per test stage? <a href="#q6-per-test-coverage" id="q6-per-test-coverage"></a>

Per-test coverage lets SeaLights recommend which tests to run (Test Impact Analysis) for functional tests. Per-test-stage coverage shows what a whole test stage covered.

| Answer                                                   | What to turn on                                                                                                                                                                                                                                           |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Per test stage is enough                                 | Nothing extra.                                                                                                                                                                                                                                            |
| Per test, back-end service called by API tests           | The test framework plugin sends the test identity in HTTP headers; start the service with `slnodejs run --httpServerColoring` (not the preload script).                                                                                                   |
| Per test, service that calls other instrumented services | Also `--httpClientColoring` on the calling service.                                                                                                                                                                                                       |
| Per test, front end that calls instrumented back ends    | Instrument the front end with `--enableOpenTelemetry` and `--allowCORS <back-end origins>`. See [Context Propagation](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/context-propagation.md). |

Lightweight V8 mode reports per test stage only.

### 7. How many test environments run at the same time? <a href="#q7-environments" id="q7-environments"></a>

| Answer                                                     | What to do                                                                                                                                                                                                                                                                                                                                                |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| One                                                        | One lab ID, or none (the build session ID is used).                                                                                                                                                                                                                                                                                                       |
| Several, for example QA and staging, or parallel CI shards | One lab ID per environment. Back end: pass `--labId` (or `SL_labId`) per environment. Front end: instrument once per environment with its own `--labId`, or set the lab ID at runtime (see [Browser Agent → Lab ID](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/configuration.md#lab-id)). |

### 8. Does the code run in containers or Kubernetes? <a href="#q8-containers" id="q8-containers"></a>

* Mount the token as a secret file and pass `--tokenFile` (or `SL_tokenFile` for the preload script).
* Copy the `buildSessionId` file into the image, or pass `--buildSessionId` from a build argument.
* With `slnodejs run`, add `--forwardSignals` so that the application receives `SIGTERM` and shuts down cleanly.
* Install `slnodejs` as a regular dependency if the image installs production dependencies only.

See [Recommended Configurations → Containers](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/recommended-configurations.md#containers-and-kubernetes).

### 9. What are the network constraints? <a href="#q9-network" id="q9-network"></a>

| Constraint                                        | What to do                                                                                                                                                                                                                                               |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Outbound traffic goes through a proxy             | `--proxy http://proxy:port` (commands), `SL_proxy` (preload script).                                                                                                                                                                                     |
| A TLS-inspecting proxy replaces certificates      | Set `SL_TLS_VERIFY=true` and `SL_CA_FILE=<corporate CA PEM>`. See [Troubleshooting → TLS and proxy](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/troubleshooting.md#tls-and-proxy-issues). |
| Test environments cannot reach SeaLights directly | Install a SeaLights Collector; pass `--collectorUrl` to `run` and to browser instrumentation.                                                                                                                                                            |
| The agent token must not reach browsers           | Instrument with `--collectorUrl` and `--excludeTokenFromBrowserConfig`.                                                                                                                                                                                  |
| The web application has a content security policy | Allow the SeaLights or Collector hosts. See [Browser Agent → Content security policy](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/configuration.md#content-security-policy).              |

### 10. Does the agent's overhead matter? <a href="#q10-overhead" id="q10-overhead"></a>

If the service runs out of memory, starts slowly, or runs tests noticeably slower with the default agent, and per-test coverage is not needed, use [Lightweight V8 Coverage Mode](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/advanced-features/lightweight-v8-coverage-mode.md) (Node.js later than 20.6.0). For very large front-end bundles, use `--footprintsMapping server` and `SL_reduceInstrumentedFileSize=true`.

### 11. How is the pipeline organized? <a href="#q11-pipeline" id="q11-pipeline"></a>

| Answer                                             | What to do                                                                                                                                                                                                    |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Pull request pipelines                             | Use `prConfig` instead of `config`.                                                                                                                                                                           |
| Build and tests run in different jobs or pipelines | Keep the `buildSessionId` file as an artifact, or pass the ID as a pipeline variable with `--buildSessionId`.                                                                                                 |
| Many services tested together as one release       | Create an integration build with `--dependency` or `componentUpdate`. See [Integration Build](https://docs.sealights.io/knowledgebase/setup-and-configuration/build-and-test-execution/integration-build.md). |
| A SeaLights failure must fail the pipeline         | Add `--failOnError true`. By default, `slnodejs` commands exit with 0.                                                                                                                                        |

## From answers to a configuration <a href="#from-answers-to-a-configuration" id="from-answers-to-a-configuration"></a>

| Your answers                                                                    | Start from                                                                                                                                                                                                                  |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Node.js service + Mocha unit tests                                              | [Back-end service with Mocha unit tests](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/recommended-configurations.md#back-end-service-with-mocha-unit-tests)   |
| Node.js service + unit tests with Karma, AVA or another NYC-producing framework | [Unit tests with an NYC report](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/recommended-configurations.md#unit-tests-with-an-nyc-report)                     |
| Node.js service + functional or E2E tests against a deployed instance           | [Back-end service under functional tests](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/recommended-configurations.md#back-end-service-under-functional-tests) |
| Web application + E2E tests (Playwright, Cypress, Selenium, manual)             | [Web application under end-to-end tests](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/recommended-configurations.md#web-application-under-end-to-end-tests)   |
| Web application + back end, tested together, per-test coverage                  | [Full stack](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/recommended-configurations.md#full-stack-front-end-and-back-end)                                    |
| Anything above, in containers                                                   | [Containers and Kubernetes](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/recommended-configurations.md#containers-and-kubernetes)                             |
| Monorepo, one build                                                             | [Monorepo with several modules](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/recommended-configurations.md#monorepo-with-several-modules)                     |
| Memory or start-up problems with the default agent                              | [Low-overhead back-end coverage](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/recommended-configurations.md#low-overhead-back-end-coverage)                   |
| Pull request pipelines                                                          | [Pull request builds](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/recommended-configurations.md#pull-request-builds)                                         |


---

# 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/choosing-your-setup.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.
