> 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/capturing-tests.md).

# Capturing Tests

Capturing tests tells SeaLights which tests ran, their results, and what code they covered. This enables coverage per test stage, Test Impact Analysis, and quality gates.

There are two models, depending on where the code under test runs.

## Unit tests (in-process) <a href="#unit-tests-coverage-via-nyc--istanbul" id="unit-tests-coverage-via-nyc--istanbul"></a>

The test runner loads the code in its own process. There is no separate application under test, and no lab ID is needed: the test stage is identified by the build session ID.

| Framework                                                           | How                                                                  | Test Impact Analysis | Page                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------------------------------------- | -------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Mocha                                                               | `slnodejs mocha` collects coverage per test and reports results.     | Yes                  | [Mocha Tests framework](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-tests/mocha-tests-framework.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Jest                                                                | SeaLights Jest plugin                                                | See plugin           | [Jest framework](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-testing-plugins/jest-framework.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Karma, AVA, Vitest, or any framework that writes an NYC JSON report | `nycReport` uploads the coverage, `uploadReports` the JUnit results. | No                   | [Unit Tests](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-tests/unit-tests.md), [Karma](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-tests/karma-test-framework.md), [AVA](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-tests/ava-framework.md), [Other Test Frameworks](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-tests/other-test-frameworks.md) |
| Jasmine or any other Node.js test runner without a coverage report  | `slnodejs run` collects coverage, `uploadReports` the JUnit results. | No                   | [Other Test Frameworks](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-tests/other-test-frameworks.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

## Functional tests (out-of-process) <a href="#functional-tests" id="functional-tests"></a>

The tests drive a running application: API tests, integration tests, browser end-to-end tests, manual tests. Coverage comes from the agent in the application ([back end](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-runtime-coverage/backend-instrumentation-dynamic.md), [front end](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-runtime-coverage/frontend-instrumentation-static.md)), not from the test process.

For coverage to reach the test stage:

1. The application's agent reports with a **lab ID** (for example `qa-env`).
2. A test stage is **open on the same lab ID** while the tests run.

| Test framework                                                           | Who opens the test stage                                                                                                                                                                              |
| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Playwright, Cypress, Jest, Cucumber.js, TestCafe with a SeaLights plugin | The plugin. Give it the application's lab ID. See [Node.js Testing Plugins](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-testing-plugins.md). |
| Any other framework, or manual tests                                     | You, with `openTestStage` and `closeTestStage`.                                                                                                                                                       |

```bash
printf '%s' "$SEALIGHTS_AGENT_TOKEN" > sltoken.txt
npx slnodejs openTestStage --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --labId qa-env --testStage "E2E Tests"
# run the tests against the qa-env environment
npx slnodejs uploadReports --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --labId qa-env --file reports/junit.xml
npx slnodejs closeTestStage --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --labId qa-env --testStage "E2E Tests"
```

* `uploadReports` without `--testStage` adds the results to the test stage that is already open. Run it before `closeTestStage`.
* For coverage per individual test, the tests must send the test identity to the application: HTTP headers for back ends (`slnodejs run --httpServerColoring`), browser events for front ends. The SeaLights plugins do this.
* Do not run two test stages on the same lab at the same time. 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).

## Choosing the right model <a href="#choosing-the-right-approach" id="choosing-the-right-approach"></a>

|                        | Unit tests                                    | Functional tests                                              |
| ---------------------- | --------------------------------------------- | ------------------------------------------------------------- |
| Application under test | None: runs in the test process                | Running, instrumented application                             |
| Coverage source        | The test process (`mocha`, `run`, NYC report) | The agent in the application                                  |
| Identifier             | Build session ID                              | Lab ID (shared by the application and the test stage)         |
| Typical test stage     | `Unit Tests`, `Component Tests`               | `Integration Tests`, `API Tests`, `E2E Tests`, `Manual Tests` |

## Test stage lifecycle <a href="#the-test-stage-lifecycle" id="the-test-stage-lifecycle"></a>

When you manage the test stage yourself:

```
openTestStage ──► run the tests ──► [nycReport] ──► [uploadReports] ──► closeTestStage
```

`nycReport` and `uploadReports` can instead open and close a test stage of their own with `--testStage`; use that only when the upload is the whole test stage.

## Uploading several report files <a href="#uploading-multiple-report-files-uploading-multiple-reports" id="uploading-multiple-report-files-uploading-multiple-reports"></a>

Pass several files or folders as **one comma-separated list**. If you repeat `--file` or `--filesFolder`, only the last value is used.

```bash
npx slnodejs uploadReports --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
  --file reports/unit-a.xml,reports/unit-b.xml
```

```bash
npx slnodejs uploadReports --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
  --filesFolder reports
```

{% hint style="warning" %}
`--filesFolder` uploads every file in the folder, whatever its extension. Keep only report files there.
{% endhint %}

More options: [Uploading Reports - More options](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/advanced-features/uploading-reports-more-options.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 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/capturing-tests.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.
