> 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 The SeaLights Node.js Agent adds **code coverage and test intelligence** to JavaScript and TypeScript applications. It works with both frontend frameworks (Angular, React, Vue) and backend Node.js services, and integrates into any CI/CD pipeline. There are two coverage modes — which one you use depends on your application type:
ModeCommandUsed for
Static instrumentationinstrumentFrontend bundles — coverage API calls baked into JS files before deployment
Dynamic instrumentationrunBackend Node.js services — agent attaches at process startup, no pre-processing
### The SeaLights lifecycle Every integration follows the same sequence. The middle step depends on your application type. ``` config ──► scan ──► Capture Unit Tests ───► instrument (FE) ───► capture functional tests └────► run (BE) ─────┘ ``` {% stepper %} {% step %} #### Create a build session (`config`) Generates a **Build Session ID** that ties all subsequent steps to this build. In CI, writes a `buildSessionId` file reused by every later command. {% endstep %} {% endstep %} {% step %} ### Scan the build (scan) Analyzes your source or build output and uploads the build's method-level map to SeaLights. Required for both frontend and backend. See [Scanning Your Application](https://file+.vscode-resource.vscode-cdn.net/c%3A/Work/Customers/GEVernova/ADO/qTestUpdate/sealights-nodejs-docs/scanning-your-application.md). {% endstep %} {% endstep %} {% step %} ### Capture In-Process Tests Coverage (Unit Tests) Open a test stage (`start`), run your tests, upload results (`uploadReports`) and coverage (`nycReport`), then close (`end`). See [Capturing Tests](https://file+.vscode-resource.vscode-cdn.net/c%3A/Work/Customers/GEVernova/ADO/qTestUpdate/sealights-nodejs-docs/capturing-tests.md). {% endstep %} {% step %} ### Make code report coverage * **Frontend (Angular, React, Vue…):** [`instrument`](https://file+.vscode-resource.vscode-cdn.net/c%3A/Work/Customers/GEVernova/ADO/qTestUpdate/sealights-nodejs-docs/capturing-runtime-coverage/frontend-instrumentation.md) — processes your bundle **offline** before deployment. * **Backend (Node.js services):** [`run`](https://file+.vscode-resource.vscode-cdn.net/c%3A/Work/Customers/GEVernova/ADO/qTestUpdate/sealights-nodejs-docs/capturing-runtime-coverage/backend-instrumentation.md) — instruments at **runtime**, no file pre-processing. {% endstep %} {% step %} ### Capture Functional tests Depending on your testing framework, capture the test executions, results, and details. {% endstep %} {% endstepper %} ### Which path is mine? | | Frontend app | Backend service | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Examples | Angular, React, Vue, plain JS bundles | Express/Nest/Fastify APIs, workers, Lambdas | | Instrumentation | **Static** — files pre-processed offline ([`instrument`](https://file+.vscode-resource.vscode-cdn.net/c%3A/Work/Customers/GEVernova/ADO/qTestUpdate/sealights-nodejs-docs/capturing-runtime-coverage/frontend-instrumentation.md)) | **Dynamic** — agent attaches at runtime ([`run`](https://file+.vscode-resource.vscode-cdn.net/c%3A/Work/Customers/GEVernova/ADO/qTestUpdate/sealights-nodejs-docs/capturing-runtime-coverage/backend-instrumentation.md)) | | What you deploy | The instrumented `sl_dist` output (test env only) | Your original code, started via the agent | ### End-to-end CI examples Both examples use [standardized CLI parameters](https://file+.vscode-resource.vscode-cdn.net/c%3A/Work/Customers/GEVernova/ADO/qTestUpdate/sealights-nodejs-docs/scanning-your-application.md) (Agent 6.2.1+). The token is passed from a secret with `--token`; the `config` step writes the `buildSessionId` file that every later step reuses. {% tabs %} {% tab title="GitHub Actions" %} ```yaml # .github/workflows/sealights.yml name: Build with SeaLights on: [push] jobs: build-test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 18 - name: Install dependencies run: npm ci && npm install slnodejs # 1) Create build session -> writes ./buildSessionId - name: SeaLights config run: | npx slnodejs config \ --token "${{ secrets.SL_TOKEN }}" \ --appName "${{ github.repository }}" \ --branchName "${{ github.ref_name }}" \ --buildName "${GITHUB_SHA::7}_${{ github.run_attempt }}" # 2) Scan the build - name: SeaLights scan run: | npx slnodejs scan \ --token "${{ secrets.SL_TOKEN }}" \ --buildSessionIdFile buildSessionId \ --scanDir "." \ --scmType git # 3a) Frontend: instrument — OR replace with step 3b for backend - name: SeaLights instrument (frontend) run: | npx slnodejs instrument \ --token "${{ secrets.SL_TOKEN }}" \ --buildSessionIdFile buildSessionId \ --scanDir dist \ --outputPath sl_dist \ --splitPreambleIntoFile \ --failOnError # Deploy ./sl_dist to your test environment, then run functional tests. # 3b) Backend: run — replace the instrument step above with this for Node.js services # - name: Start backend with SeaLights # run: | # npx slnodejs run \ # --token "${{ secrets.SL_TOKEN }}" \ # --buildSessionIdFile buildSessionId \ # --scanDir ./server \ # --labId my_lab_id \ # --testStage "Functional Tests" \ # -- ./server/app.js & # 4) Capture unit tests (Build Session ID, no Lab ID) - name: Capture unit tests run: | npx slnodejs start --token "${{ secrets.SL_TOKEN }}" --buildSessionIdFile buildSessionId --testStage "Unit Tests" npm test npx slnodejs nycReport --token "${{ secrets.SL_TOKEN }}" --buildSessionIdFile buildSessionId --report ./coverage/coverage-final.json npx slnodejs uploadReports --token "${{ secrets.SL_TOKEN }}" --buildSessionIdFile buildSessionId --file ./reports/junit.xml npx slnodejs end --token "${{ secrets.SL_TOKEN }}" --buildSessionIdFile buildSessionId ``` {% endtab %} {% tab title="Azure DevOps" %} ```yaml # azure-pipelines.yml trigger: - main pool: vmImage: ubuntu-latest variables: - group: sealights # variable group containing SL_TOKEN (mark it secret) steps: - task: NodeTool@0 inputs: versionSpec: '18.x' - script: npm ci && npm install slnodejs displayName: Install dependencies # $(Build.SourceVersion) is the full SHA — shorten to 7 chars - script: echo "##vso[task.setvariable variable=shortSha]$(echo $(Build.SourceVersion) | cut -c1-7)" displayName: Compute short SHA # 1) Create build session -> writes ./buildSessionId - script: | npx slnodejs config \ --token "$(SL_TOKEN)" \ --appName "$(Build.Repository.Name)" \ --branchName "$(Build.SourceBranchName)" \ --buildName "$(shortSha)_$(System.JobAttempt)" displayName: SeaLights config # 2) Scan the build - script: | npx slnodejs scan \ --token "$(SL_TOKEN)" \ --buildSessionIdFile buildSessionId \ --scanDir "." \ --scmType git displayName: SeaLights scan # 3a) Frontend: instrument — OR replace with 3b for backend - script: | npx slnodejs instrument \ --token "$(SL_TOKEN)" \ --buildSessionIdFile buildSessionId \ --scanDir dist \ --outputPath sl_dist \ --splitPreambleIntoFile \ --failOnError displayName: SeaLights instrument (frontend) # Deploy ./sl_dist to your test environment, then run functional tests. # 4) Capture unit tests (Build Session ID, no Lab ID) - script: | npx slnodejs start --token "$(SL_TOKEN)" --buildSessionIdFile buildSessionId --testStage "Unit Tests" npm test npx slnodejs nycReport --token "$(SL_TOKEN)" --buildSessionIdFile buildSessionId --report ./coverage/coverage-final.json npx slnodejs uploadReports --token "$(SL_TOKEN)" --buildSessionIdFile buildSessionId --file ./reports/junit.xml npx slnodejs end --token "$(SL_TOKEN)" --buildSessionIdFile buildSessionId displayName: Capture unit tests ``` {% endtab %} {% endtabs %} *** **Start here →** [Scanning Your Application](https://file+.vscode-resource.vscode-cdn.net/c%3A/Work/Customers/GEVernova/ADO/qTestUpdate/sealights-nodejs-docs/scanning-your-application.md) · [Command Reference](https://file+.vscode-resource.vscode-cdn.net/c%3A/Work/Customers/GEVernova/ADO/qTestUpdate/sealights-nodejs-docs/command-reference.md) --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.