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

1

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

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

2

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.

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"

3

Run Jest with SeaLights

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

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

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.

Common Jest Command Use Cases

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

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

Here are common use cases explained with sample commands

Scenario	Example Command
Run Jest via npx (recommended)	npx sl-jest-runner npx jest --sl-testStage="Integration"
Use existing npm script	npx sl-jest-runner npm test --sl-testStage="Integration"
Run with custom Jest config file	npx sl-jest-runner npx jest --config my-jest.config.js --sl-testStage="Integration"
Add extra Jest options	npx sl-jest-runner npx jest --verbose --testNamePattern="user tests" --sl-testStage="Integration"
Run a custom Jest command	npx sl-jest-runner my-custom-jest-command --coverage --silent --sl-testStage="Integration"

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.

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

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

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

Logging and Debugging

Enable detailed logging:

export SL_LOG_LEVEL=debug

Write logs to file:

export SL_LOG_FILE=sealights.log

Logs are visible during execution and cleaned automatically.

Sample End-to-End Pipeline Script

# 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

For advanced use cases, refer to 👉 Advanced Options on npm, including:

• Manual integration

• TypeScript setups

• Create React App (CRA) setups

• Legacy Jest (< v27)

• Custom runners

• Monorepo edge cases

• Hook-dependency guards

Common SeaLights Parameters

Environment variables override default file-based configuration and are recommended for CI/CD usage.

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