# Jest framework

The **SeaLights Jest Plugin** (`sealights-jest-plugin`) integrates Jest tests with the SeaLights Quality Platform to provide test analytics and code coverage visibility across your pipelines.

It’s a **non-intrusive setup** — no changes to your Jest configuration files are required.\
Simply install the plugin, export your environment variables, and run your Jest tests using the **SeaLights Jest Runner**.

## Configuration

{% stepper %}
{% step %}

#### Install the Plugin

To install the Sealights Jest plugin, follow the instructions below. For more details, you can also refer to <https://www.npmjs.com/package/sealights-jest-plugin>

```bash
npm install --save-dev sealights-jest-plugin
```

{% endstep %}

{% step %}

#### Set Environment Variables

Define your SeaLights configuration via environment variables — this is the preferred approach for CI/CD systems like GitHub Actions, Jenkins, Tekton, Azure Pipelines, or Kubernetes Pods.

```bash
export SL_TOKEN=<your_token>             # from CI secret or vault
export SL_BUILDSESSIONID=<your_bsid>     # unique per app build/version
export SL_TESTSTAGE="Unit Tests"
```

{% endstep %}

{% step %}

#### Run Jest with SeaLights

Execute your Jest command through the SeaLights runner. Works seamlessly with `npm`, `yarn`, or `pnpm`

```bash
npx sl-jest-runner npx jest --sl-testStage="Unit Tests"
```

The plugin is used as a runner automatically:

* Detects and wraps your Jest configuration (`jest.config.*` or `package.json`)
* Injects SeaLights instrumentation dynamically
* Executes tests with coverage collection
* Restores original configs afterward
  {% endstep %}
  {% endstepper %}

{% hint style="success" %}
When the command and **Jest tests complete successfully**, a new test stage (with the name you specified) will appear in the Sealights dashboard under the corresponding build. This stage will include the **associated test results and coverage data.**
{% endhint %}

## Common Jest Command Use Cases

Generally speaking, for any configuration, simply replace your original executable in your jest command with `npx sl-jest-runner` :

```bash
npx sl-jest-runner <your-original-jest-command> [jest-args...] [--sl-* Sealights parameters]
```

Here are common use cases explained with sample commands

<table><thead><tr><th width="275.22222900390625">Scenario</th><th>Example Command</th></tr></thead><tbody><tr><td><strong>Run Jest via npx (recommended)</strong></td><td><code>npx sl-jest-runner npx jest --sl-testStage="Integration"</code></td></tr><tr><td><strong>Use existing npm script</strong></td><td><code>npx sl-jest-runner npm test --sl-testStage="Integration"</code></td></tr><tr><td><strong>Run with custom Jest config file</strong></td><td><code>npx sl-jest-runner npx jest --config my-jest.config.js --sl-testStage="Integration"</code></td></tr><tr><td><strong>Add extra Jest options</strong></td><td><code>npx sl-jest-runner npx jest --verbose --testNamePattern="user tests" --sl-testStage="Integration"</code></td></tr><tr><td><strong>Run a custom Jest command</strong></td><td><code>npx sl-jest-runner my-custom-jest-command --coverage --silent --sl-testStage="Integration"</code></td></tr></tbody></table>

## Monorepo support

The runner supports additional CLI flags that simplify testing in **monorepos** or multi-package environments. These options let you copy temporary Jest configurations across multiple package folders and control the recursion depth.

<table><thead><tr><th width="198.22222900390625">Option</th><th>Description</th></tr></thead><tbody><tr><td><code>--copyConfigTo</code></td><td>Creates temporary SeaLights-enabled <code>jest.config.js</code> files inside the specified directories. Accepts a comma-separated list of paths. For example: <code>--copyConfigTo=packages,services</code></td></tr><tr><td><code>--recursiveCopyDepth</code></td><td>Sets how deep to traverse subdirectories when copying configs. <code>0</code> = only listed dirs, <code>1</code> = include one level of sub-folders (ignores <code>.git</code>, <code>node_modules</code>, hidden dirs). For example: <code>--copyConfigTo=packages --recursiveCopyDepth=1</code><br></td></tr></tbody></table>

Here is a combined example of a standard integrated command with these options:

```bash
npx sl-jest-runner npx jest --copyConfigTo=packages,services \
  --recursiveCopyDepth=1 --sl-testStage="Integration"
```

## Logging and Debugging

Enable detailed logging:

```bash
export SL_LOG_LEVEL=debug
```

Write logs to file:

```bash
export SL_LOG_FILE=sealights.log
```

Logs are visible during execution and cleaned automatically.

## Sample End-to-End Pipeline Script

```bash
# 1. Install dependencies
npm ci

# 2. Install SeaLights Jest plugin
npm install --save-dev sealights-jest-plugin

# 3. Set environment variables (from secrets)
export SL_TOKEN=$SL_TOKEN
export SL_BUILDSESSIONID=$SL_BSID
export SL_TESTSTAGE="Integration"
#export SL_LOG_LEVEL=debug

# 4. Run tests with SeaLights
npx sl-jest-runner npx jest 
```

✅ Coverage data are test results are uploaded automatically to your SeaLights dashboard.

## Advanced Configuration and Developer Options

{% hint style="warning" %}
For advanced use cases, refer to 👉 [**Advanced Options on npm**](https://www.npmjs.com/package/sealights-jest-plugin)**, including:**

* Manual integration
* TypeScript setups
* Create React App (CRA) setups
* Legacy Jest (< v27)
* Custom runners
* Monorepo edge cases
* Hook-dependency guards
  {% endhint %}

## Common Plugin Parameters

{% hint style="info" %}
Environment variables override default file-based configuration and are recommended for CI/CD usage.
{% endhint %}

<table><thead><tr><th width="222.88885498046875">CLI Parameter</th><th>Description</th><th width="99.3333740234375">Required</th><th>Environment Variable Equivalent</th></tr></thead><tbody><tr><td><code>--sl-testStage</code></td><td>Name of the test stage (“Unit”, “Integration”, etc.)</td><td>✅</td><td><code>SL_TESTSTAGE</code></td></tr><tr><td><code>--sl-token</code> or <code>--sl-tokenFile</code></td><td>Authentication token or Path to file containing the token (by default <code>sltoken.txt</code>)</td><td>✅</td><td><code>SL_TOKEN</code> or <code>SL_TOKENFILE</code></td></tr><tr><td><code>--sl-buildSessionId</code> or <code>--sl-buildSessionIdFile</code></td><td>Build Session ID or Path to file containing the Build Session ID (by default <code>buildSessionId</code>)</td><td>✅</td><td><code>SL_BUILDSESSIONID</code> or <code>SL_BUILDSESSIONIDFILE</code></td></tr><tr><td><code>--sl-labId</code></td><td>Lab ID used to group results</td><td>Optional</td><td><code>SL_LABID</code></td></tr><tr><td><code>--sl-proxy</code></td><td>Proxy configuration (host:port or URL)</td><td>Optional</td><td><code>SL_PROXY</code></td></tr><tr><td><code>--sl-testProjectId</code></td><td>Identifier for the current test project</td><td>Optional</td><td><code>SL_TESTPROJECTID</code></td></tr><tr><td><code>--sl-targetTestProjectId</code></td><td>Target test-project ID (for PR builds / TGA model)</td><td>Optional</td><td><code>SL_TARGETTESTPROJECTID</code></td></tr></tbody></table>


---

# Agent Instructions: 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-testing-plugins/jest-framework.md?ask=<question>
```

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.