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

# Unit Tests

Use this flow for unit tests that already produce an NYC (Istanbul) JSON coverage report and a JUnit XML report, for example Karma, AVA, or Jest without the SeaLights plugin. For Mocha, use [`slnodejs mocha`](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-tests/mocha-tests-framework.md) instead: it collects coverage per test and applies Test Impact Analysis.

Unit tests are captured after the [scan](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/scanning-your-application.md) and before deployment. The test stage is identified by the build session ID; no lab ID is needed.

## Lifecycle <a href="#lifecycle" id="lifecycle"></a>

{% stepper %}
{% step %}

### Open the test stage

{% endstep %}

{% step %}

### Run the unit tests, producing `coverage-final.json` and a JUnit XML report

{% endstep %}

{% step %}

### Upload the NYC coverage report and the JUnit results

{% endstep %}

{% step %}

### Close the test stage

{% endstep %}
{% endstepper %}

## Commands <a href="#commands" id="commands"></a>

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

```bash
printf '%s' "$SEALIGHTS_AGENT_TOKEN" > sltoken.txt

npx slnodejs openTestStage --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --testStage "Unit Tests"

npm test   # writes coverage/coverage-final.json and reports/junit.xml

npx slnodejs nycReport --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --report coverage/coverage-final.json
npx slnodejs uploadReports --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --file reports/junit.xml

npx slnodejs closeTestStage --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --testStage "Unit Tests"
```

{% endtab %}

{% tab title="PowerShell" %}

```powershell
npx slnodejs openTestStage --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --testStage "Unit Tests"
npm test
npx slnodejs nycReport --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --report coverage\coverage-final.json
npx slnodejs uploadReports --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --file reports\junit.xml
npx slnodejs closeTestStage --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --testStage "Unit Tests"
```

{% endtab %}

{% tab title="GitHub Actions" %}

```yaml
- name: Open the SeaLights test stage
  run: npx slnodejs openTestStage --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --testStage "Unit Tests"
- name: Unit tests
  run: npm test
- name: Upload results and close the SeaLights test stage
  if: always()
  run: |
    npx slnodejs nycReport --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --report coverage/coverage-final.json
    npx slnodejs uploadReports --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --file reports/junit.xml
    npx slnodejs closeTestStage --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --testStage "Unit Tests"
```

{% endtab %}

{% tab title="Azure DevOps" %}

```yaml
- script: npx slnodejs openTestStage --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --testStage "Unit Tests"
  displayName: Open the SeaLights test stage
- script: npm test
  displayName: Unit tests
- script: |
    npx slnodejs nycReport --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --report coverage/coverage-final.json
    npx slnodejs uploadReports --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --file reports/junit.xml
    npx slnodejs closeTestStage --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --testStage "Unit Tests"
  displayName: Upload results and close the SeaLights test stage
  condition: always()
```

{% endtab %}
{% endtabs %}

Upload the results and close the test stage even when tests fail (`if: always()`, `condition: always()`), so failed tests are reported and the test stage does not stay open.

## Producing the reports <a href="#producing-the-reports" id="producing-the-reports"></a>

* **Coverage:** NYC (Istanbul) JSON reporter, which writes `coverage-final.json`. For example `nyc --reporter=json`, or Karma's `karma-coverage` with a `json` reporter. Jest writes it with `--coverage --coverageReporters=json`.
* **Results:** a JUnit XML reporter for your framework.

Framework examples: [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). To merge several NYC reports into one, see [Merge multiple NYC coverage files into one](https://docs.sealights.io/knowledgebase/setup-and-configuration/troubleshooting-faq/node-javascript/merge-multiple-nyc-coverage-files-into-one.md).

## Flags <a href="#parameters" id="parameters"></a>

| Flag            | Command                           | When to use                                                                                                                                                                           |
| --------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--testStage`   | `openTestStage`, `closeTestStage` | Name of the test stage, for example `"Unit Tests"`.                                                                                                                                   |
| `--report`      | `nycReport`                       | Path of `coverage-final.json` (default: `coverage/coverage-final.json` in the working directory).                                                                                     |
| `--projectRoot` | `nycReport`                       | The tests ran in another directory than the scan (for example in a container), so the absolute paths in the report do not resolve. Set it to the project root in which the tests ran. |
| `--file`        | `uploadReports`                   | JUnit XML report(s), comma-separated.                                                                                                                                                 |

{% hint style="info" %}
Before the first CI run, check that the NYC report matches the scan: `npx slnodejs dryRun --scanDir src --hasNycReport --report coverage/coverage-final.json --verbose`. See [dryRun](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/advanced-features/dryrun-command-troubleshooting-and-validation.md).
{% endhint %}


---

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