# 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> &#x20;

```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&#x20;

<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>