> 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

Once your code reports coverage (via [Frontend](https://file+.vscode-resource.vscode-cdn.net/c%3A/Work/Customers/GEVernova/ADO/qTestUpdate/sealights-nodejs-docs/frontend-instrumentation.md) or [Backend](https://file+.vscode-resource.vscode-cdn.net/c%3A/Work/Customers/GEVernova/ADO/qTestUpdate/sealights-nodejs-docs/backend-instrumentation.md) instrumentation), SeaLights needs to know **which tests ran and what they covered**. Capturing tests records each test's execution and ties it to the code it exercised — enabling test impact analysis, broken-test detection, and risk-based test selection.

There are two ways tests are captured, depending on the kind of test.

### Unit Tests (coverage via NYC / Istanbul) <a href="#unit-tests-coverage-via-nyc--istanbul" id="unit-tests-coverage-via-nyc--istanbul"></a>

Unit tests run the code directly in the test process — there is **no separate application under test**. SeaLights collects JavaScript coverage produced by **NYC / Istanbul** (line, branch, and function level) during the test run, then uploads it.

* No instrumented deployment or running server is required.
* You upload the NYC coverage report with `nycReport`, and the test results (JUnit XML) with `uploadReports`.
* For unit tests, SeaLights recommends identifying the stage by **Build Session ID** rather than a Lab ID.

➡️ How-to with commands: [Unit Tests](https://file+.vscode-resource.vscode-cdn.net/c%3A/Work/Customers/GEVernova/ADO/qTestUpdate/sealights-nodejs-docs/unit-tests.md), and the framework guides — [Mocha](https://file+.vscode-resource.vscode-cdn.net/c%3A/Work/Customers/GEVernova/ADO/qTestUpdate/sealights-nodejs-docs/mocha.md), [Karma](https://file+.vscode-resource.vscode-cdn.net/c%3A/Work/Customers/GEVernova/ADO/qTestUpdate/sealights-nodejs-docs/karma.md), [AVA](https://file+.vscode-resource.vscode-cdn.net/c%3A/Work/Customers/GEVernova/ADO/qTestUpdate/sealights-nodejs-docs/ava.md).

### Functional Tests <a href="#functional-tests" id="functional-tests"></a>

Functional tests run against a **live, instrumented application** (see [Frontend](https://file+.vscode-resource.vscode-cdn.net/c%3A/Work/Customers/GEVernova/ADO/qTestUpdate/sealights-nodejs-docs/frontend-instrumentation.md) or [Backend](https://file+.vscode-resource.vscode-cdn.net/c%3A/Work/Customers/GEVernova/ADO/qTestUpdate/sealights-nodejs-docs/backend-instrumentation.md) Instrumentation). As tests drive the app, the instrumented code reports footprints, and SeaLights correlates each request with the test that triggered it — giving per-test functional coverage.

* Requires a running instrumented app **and** a **Lab ID** that connects the test listener to the coverage listener.
* Test results are uploaded with `uploadReports`; functional coverage comes from the running agent, not `nycReport`.

➡️ Set up the application first: [Frontend Instrumentation](https://file+.vscode-resource.vscode-cdn.net/c%3A/Work/Customers/GEVernova/ADO/qTestUpdate/sealights-nodejs-docs/frontend-instrumentation.md) · [Backend Instrumentation](https://file+.vscode-resource.vscode-cdn.net/c%3A/Work/Customers/GEVernova/ADO/qTestUpdate/sealights-nodejs-docs/backend-instrumentation.md).

### Choosing the right approach <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     | Live, instrumented app            |
| Coverage source        | NYC / Istanbul report (`nycReport`) | Footprints from the running agent |
| Identifier             | Build Session ID                    | Lab ID                            |
| Typical stage          | "Unit Tests"                        | "Functional Tests", "E2E", …      |

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

Whichever approach you use, the listener follows the same shape (the framework pages show the exact commands):

```
start ──► run your tests ──► uploadReports (JUnit)  ──► [nycReport (unit coverage)] ──► end
```

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

When your test suite produces **several JUnit XML files** (e.g. parallel test runs, per-package reports), there are two approaches to upload them all.

**Folder-based upload** — point `--reportFilesFolder` at the directory. SeaLights processes every file in the folder.

{% hint style="warning" %}
&#x20;`--reportFilesFolder` uploads **all files in the folder regardless of extension**. Make sure only report files are present, or use the loop approach for more control.
{% endhint %}

{% tabs %}
{% tab title="Bash" %}

```sh
npx slnodejs uploadReports \
  --tokenFile ./sltoken.txt \
  --buildSessionIdFile buildSessionId \
  --reportFilesFolder ./reports
```

{% endtab %}

{% tab title="GitHub Actions" %}

```yaml
- name: Upload all JUnit reports
  run: |
    npx slnodejs uploadReports \
      --token "${{ secrets.SL_TOKEN }}" \
      --buildSessionIdFile buildSessionId \
      --reportFilesFolder ./reports
```

{% endtab %}

{% tab title="PowerShell" %}

```powershell
npx slnodejs uploadReports `
  --tokenFile .\sltoken.txt `
  --buildSessionIdFile buildSessionId `
  --reportFilesFolder .\reports
```

{% endtab %}

{% tab title="Azure DevOps" %}

```yaml
- script: |
    npx slnodejs uploadReports \
      --token "$(SL_TOKEN)" \
      --buildSessionIdFile buildSessionId \
      --reportFilesFolder ./reports
  displayName: Upload all JUnit reports
```

{% endtab %}
{% endtabs %}

**Loop-based upload** — iterate over files matching a pattern for fine-grained control.

{% tabs %}
{% tab title="Bash" %}

```sh
for f in ./reports/*.xml; do
  npx slnodejs uploadReports \
    --tokenFile ./sltoken.txt \
    --buildSessionIdFile buildSessionId \
    --file "$f"
done
```

{% endtab %}

{% tab title="PowerShell" %}

```powershell
Get-ChildItem -Path .\reports -Filter *.xml | ForEach-Object {
  npx slnodejs uploadReports `
    --tokenFile .\sltoken.txt `
    --buildSessionIdFile buildSessionId `
    --file $_.FullName
}
```

{% endtab %}
{% endtabs %}

***

**Framework guides:** [Unit Tests](https://file+.vscode-resource.vscode-cdn.net/c%3A/Work/Customers/GEVernova/ADO/qTestUpdate/sealights-nodejs-docs/unit-tests.md) · [Mocha](https://file+.vscode-resource.vscode-cdn.net/c%3A/Work/Customers/GEVernova/ADO/qTestUpdate/sealights-nodejs-docs/mocha.md) · [Karma](https://file+.vscode-resource.vscode-cdn.net/c%3A/Work/Customers/GEVernova/ADO/qTestUpdate/sealights-nodejs-docs/karma.md) · [AVA](https://file+.vscode-resource.vscode-cdn.net/c%3A/Work/Customers/GEVernova/ADO/qTestUpdate/sealights-nodejs-docs/ava.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, and the optional `goal` query parameter:

```
GET https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-tests.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.