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

# Mocha Tests framework

`slnodejs mocha` runs the Mocha installed in your project with the SeaLights Mocha reporter. It:

* collects coverage per test;
* reports each test result (passed, failed or skipped) to SeaLights;
* asks SeaLights which tests to run (Test Impact Analysis) and skips the others.

If `slnodejs` cannot start (for example, the token is invalid), the tests still run, without SeaLights.

## Basic command <a href="#basic-command" id="basic-command"></a>

Install Mocha in the project, scan the build, then run the tests. Everything after `--` is passed to Mocha.

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

```bash
printf '%s' "$SEALIGHTS_AGENT_TOKEN" > sltoken.txt
npm install --save-dev mocha slnodejs
npx slnodejs config --tokenFile sltoken.txt --appName my-app --branchName main --buildName "$BUILD_NUMBER"
npx slnodejs scan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --scanDir src --scmType git
npx slnodejs mocha --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
  --testStage "Unit Tests" -- --recursive test
```

{% endtab %}

{% tab title="PowerShell" %}

```powershell
npx slnodejs mocha `
  --tokenFile sltoken.txt `
  --buildSessionIdFile buildSessionId `
  --testStage "Unit Tests" `
  -- --recursive test
```

{% endtab %}

{% tab title="GitHub Actions" %}

```yaml
- name: Mocha tests with SeaLights
  run: |
    npx slnodejs mocha --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
      --testStage "Unit Tests" -- --recursive test
```

{% endtab %}

{% tab title="Azure DevOps" %}

```yaml
- script: |
    npx slnodejs mocha --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
      --testStage "Unit Tests" -- --recursive test
  displayName: Mocha tests with SeaLights
```

{% endtab %}
{% endtabs %}

Replace `--recursive test` with your Mocha arguments. A `.mocharc.*` file in the project is still used.

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

| Flag                        | When to use                                                                                                                            |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `--testStage`               | Name of the test stage. Default `Unit Tests`.                                                                                          |
| `--disableTia`              | Run all tests, ignoring Test Impact Analysis, for example in nightly full runs.                                                        |
| `--es6Modules`              | The tests or the code are ES modules.                                                                                                  |
| `--projectRoot`             | The tests run from another directory than the scan.                                                                                    |
| `--labId`                   | The tests drive a separately running application on that lab (functional tests written in Mocha).                                      |
| `--httpClientColoring`      | Functional tests that call an instrumented back end: sends the current test in outgoing HTTP requests, for per-test back-end coverage. |
| `--testProjectId`, `--prID` | Keep apart test stages with the same name from different teams, or from pull request pipelines.                                        |

Every flag: [Command Reference → mocha](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/command-reference.md#mocha). `--useSlNode2`, found in older examples, is deprecated and has no effect.

## Reporter options <a href="#reporter-options" id="reporter-options"></a>

`slnodejs mocha` sets the SeaLights reporter itself. **Do not pass `--reporter` (`-R`) in the Mocha arguments.** The SeaLights reporter prints the test output through another Mocha reporter, which you choose with Mocha reporter options after `--`:

| Option              | Effect                                                                                                                                                                                                                                                       |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `reporter=<name>`   | The reporter that prints the test output: a built-in Mocha reporter (`spec`, `dot`, `list`, ...) or an installed reporter module. Default `spec`. When the module is not found, a warning is printed and `spec` is used. Its own options are passed through. |
| `reportSuites=true` | Report results per suite instead of per test. Test Impact Analysis then skips whole suites.                                                                                                                                                                  |
| `skipEpilogue=true` | Do not print the summary at the end of the run.                                                                                                                                                                                                              |

```bash
npx slnodejs mocha --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --testStage "Unit Tests" \
  -- --recursive test --reporter-options reporter=dot
```

### JUnit XML output <a href="#junit-output" id="junit-output"></a>

Chain `mocha-junit-reporter` and pass its options in the same list:

```bash
npm install --save-dev mocha-junit-reporter
npx slnodejs mocha --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --testStage "Unit Tests" \
  -- --recursive test --reporter-options reporter=mocha-junit-reporter,mochaFile=reports/junit.xml
```

### Several reporters <a href="#multiple-reporters" id="multiple-reporters"></a>

Chain `mocha-multi-reporters` and list the other reporters in its configuration file. Do not list the SeaLights reporter there: it is already active.

```bash
npm install --save-dev mocha-multi-reporters mocha-junit-reporter
cat > mocha-reporters.json <<'JSON'
{
  "reporterEnabled": "spec, mocha-junit-reporter",
  "mochaJunitReporterReporterOptions": {
    "mochaFile": "reports/junit.xml"
  }
}
JSON
npx slnodejs mocha --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --testStage "Unit Tests" \
  -- --recursive test --reporter-options reporter=mocha-multi-reporters,configFile=mocha-reporters.json
```

## Test Impact Analysis <a href="#test-impact-analysis" id="test-impact-analysis"></a>

* A test that Test Impact Analysis does not recommend is marked as pending in Mocha and reported to SeaLights as skipped.
* Tests are identified by their full title (suite titles and test title). Renaming a test makes it a new test.
* When every test of a suite that has a `beforeEach` hook and a child suite with a `before` hook is skipped, the reporter adds a placeholder test named `SLEmptyTest` to avoid a hook failure. `SL_disableHookDependencyGuard=true` turns this off.
* `--disableTia` runs all tests.

## TypeScript <a href="#typescript" id="typescript"></a>

* Tests run with a TypeScript loader (for example `ts-node/register` in `.mocharc`): scan the `.ts` sources with `SL_fileExtensions=.ts --scanDir src`.
* Code compiled to `dist` before the tests: scan `dist` with source maps, and run the tests against `dist`.

## Lightweight V8 coverage <a href="#lightweight-v8" id="lightweight-v8"></a>

`slnodejs mocha` also works with [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) (`SL_useLeanCoverageListener=true`, scan with `--rawCoverage`). Test results and Test Impact Analysis work as usual; coverage is reported per test stage instead of per test.

## Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

| Symptom                                                    | Cause and fix                                                                                                                                                                                                                                                                                          |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Sealights is disabled, running command without sealights` | The token or build session ID is missing or invalid; the tests ran without SeaLights. See [Troubleshooting](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/troubleshooting.md#tests-or-the-application-run-but-sealights-reports-nothing). |
| Tests run but no results or coverage appear                | A `--reporter` in the Mocha arguments replaced the SeaLights reporter. Remove it and use `--reporter-options reporter=<name>`.                                                                                                                                                                         |
| `Cannot find reporter <name>, using default Spec reporter` | The reporter module in `reporter=<name>` is not installed in the project.                                                                                                                                                                                                                              |
| Fewer tests ran than expected                              | Test Impact Analysis skipped the tests it does not recommend. Use `--disableTia` for a full run.                                                                                                                                                                                                       |
| `Cannot find module 'mocha/bin/mocha'`                     | Mocha is not installed in the project. `npm install --save-dev mocha`.                                                                                                                                                                                                                                 |


---

# 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/mocha-tests-framework.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.
