# sealights-jest-plugin > Sealights Jest integration plugin Latest version **3.0.34** (published 2026-09-29) · ISC license · 0 weekly downloads ## Install ```sh npm install sealights-jest-plugin pnpm add sealights-jest-plugin yarn add sealights-jest-plugin bun add sealights-jest-plugin ``` Provides the command `sl-jest-runner`. ## Health **Score 65/100 (B)** — status: active. Positive: has types; no vulnerabilities; recently updated; high maintenance score; high quality score. Warnings: low downloads; no esm support. ## Facts | | | |---|---| | Version | 3.0.34 | | Published | 2026-09-29 | | First published | 2022-02-16 | | Weekly downloads | 0 | | License | ISC | | TypeScript types | bundled | | Module format | CommonJS | | Dependencies | 4 | | Unpacked size | 127.4 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Author | Lasha Gogichaishvili | | Maintainers | sealights | ## Links - npm: https://www.npmjs.com/package/sealights-jest-plugin - npm.io page: https://npm.io/package/sealights-jest-plugin ## Dependencies (4) - [globby](https://npm.io/package/globby.md) ^11.1.0 - [ts-morph](https://npm.io/package/ts-morph.md) ^27.0.0 - [@achrinza/node-ipc](https://npm.io/package/@achrinza/node-ipc.md) ^10.1.9 - [sealights-plugins-common](https://npm.io/package/sealights-plugins-common.md) 2.1.2 ## Recent versions - 3.0.34 (latest) — 2026-09-29 - 3.0.33 — 2026-09-29 - 3.0.32 — 2026-06-17 - 3.0.31 — 2026-04-29 - 3.0.30 — 2026-04-09 - 3.0.29 — 2026-02-24 - 3.0.28 — 2026-01-27 - 3.0.25 — 2026-01-14 - 3.0.24 — 2025-12-18 - 3.0.23 — 2025-12-17 - 3.0.21 — 2025-12-11 - 3.0.20 — 2025-12-08 - 3.0.19 — 2025-11-19 - 3.0.18 — 2025-11-19 - 3.0.16 — 2025-11-04 - … 37 more at https://npm.io/package/sealights-jest-plugin/versions ## README # Sealights Jest Plugin A Jest plugin that integrates with Sealights' testing platform to provide advanced test analytics and coverage reporting. ## Using the Sealights Jest Runner (Beta) > ⚠️ **Beta Notice** > > The SeaLights Jest Runner is still in **beta**. Behaviour and public-facing APIs may change between releases. > ES-Module style Jest configurations (for example files that use `export default …` or have a `.mjs`/`.mts` extension) > haven’t been fully validated yet and **might not work out-of-the-box**. > > If you encounter a configuration pattern the runner can’t handle, please open a support ticket with a minimal > reproduction – we’ll be happy to extend support. - The command-line runner (`sl-jest-runner`) now **automatically integrates SeaLights with your Jest project**. - It **backs-up** your existing Jest configuration files, **injects** the required Sealights configuration wrapper ( `configCreator`), runs the tests and then **restores** the original files. - It **automatically detects** Jest configuration in multiple formats: `jest.config.{js,ts,mjs,cjs,cts,json}` files or `package.json` "jest" field. - It supports both inline package.json configurations and external file references. Because all configuration is performed automatically, you **only need two steps** to use the runner: 1. Install the plugin: ```bash npm install --save-dev sealights-jest-plugin ``` 2. Execute your Jest command through the runner ```bash npx sl-jest-runner npx jest --sl-testStage="Integration" ``` ### Usage You can invoke the runner by passing your original Jest command to it followed by the usual configuration parameters for Sealights, like test-stage, token etc... 1. Using **npx** (recommended): ```bash npx sl-jest-runner npx jest --sl-testStage="Integration" ``` 2. With your existing npm test script: ```bash npx sl-jest-runner npm test --sl-testStage="Integration" ``` 3. With custom Jest configuration: ```bash npx sl-jest-runner npx jest --config my-jest.config.js --sl-testStage="Integration" ``` 4. Pass any Jest arguments as you normally would: ```bash npx sl-jest-runner npx jest --watch --verbose --testNamePattern="user tests" --sl-testStage="Integration" ``` 5. With package manager scripts: ```bash npx sl-jest-runner yarn test --sl-testStage="Integration" npx sl-jest-runner pnpm test --sl-testStage="Integration" ``` You may pass any command after the runner – it will be executed verbatim: ```bash npx sl-jest-runner my-custom-jest-command --coverage --silent --sl-testStage="Integration" ``` **Note**: Simply replace your original Jest command with `npx sl-jest-runner `. For example: - If you normally run: `npm test --sl-testStage="Integration"` - With SeaLights runner: `npx sl-jest-runner npm test --sl-testStage="Integration"` - If you normally run: `npx jest --watch --sl-testStage="Integration" ` - With SeaLights runner: `npx sl-jest-runner npx jest --watch --sl-testStage="Integration"` The runner will: - Automatically locate your Jest configuration (priority: explicit `--config` → config files → package.json) - Create safe backups of configuration files (.slbak) - Inject the SeaLights `configCreator` wrapper - Execute the supplied command with SeaLights integration - Restore the original files after completion - Handle interruption signals (SIGINT/SIGTERM) with proper cleanup - Fall back to vanilla Jest execution if setup fails ### Runner-specific flags In addition to `--sl-` Sealights parameters, the runner supports the following flags: - `--copyConfigTo ` or `--copyConfigTo=`: Comma-separated list of directories (absolute or relative) where a minimal SeaLights-enabled `jest.config.js` will be created for the duration of the run. - `--recursiveCopyDepth ` or `--recursiveCopyDepth=`: When used with `--copyConfigTo`, copies into subdirectories up to depth `n` (0 = only the provided directory). #### Monorepo examples - Copy into each application under `packages` (one level deep): ```bash npx sl-jest-runner npx jest --copyConfigTo=packages --recursiveCopyDepth=1 --sl-testStage="Integration" ``` - Copy into multiple roots: ```bash npx sl-jest-runner npx jest --copyConfigTo=packages,packages2 --recursiveCopyDepth=1 --sl-testStage="Integration" ``` - Copy only into the provided directories (no recursion): ```bash npx sl-jest-runner npx jest --copyConfigTo=./services/api,./services/web --sl-testStage="Integration" ``` ### Important Notes _The manual configuration instructions shown below are **not required** when you use the runner – they are kept for users who wish to integrate the plugin manually. The runner still needs the Sealights related arguments to be provided like `--sl-testStage="Integration"` for example._ - The plugin requires the `jest-circus` test runner (default in recent Jest versions) - For CRA projects using watch mode, you may need to disable it with `--watchAll=false` for proper coverage collection #### Notes and expectations for `--copyConfigTo` - The runner creates a minimal `jest.config.js` file that enables SeaLights in each target directory. These files are treated as synthetic and are removed when the run finishes (during restore/cleanup). - Existing Jest configuration is respected. If a directory already contains any `jest.config.{js,ts,mjs,cjs,cts,json}` or a `package.json` with an inline `jest` field, the runner will skip creating a file there. - Only directories are supported. Non-existing paths or files are ignored. - Subdirectory traversal uses a breadth-first strategy up to `--recursiveCopyDepth`, ignoring common folders like `node_modules`, `.git`, and hidden dot-directories. - Relative paths are resolved from the current working directory where you invoke `sl-jest-runner` (e.g., your monorepo root). - This feature does not change how Jest discovers projects/tests. Ensure your Jest command/projects configuration already includes those packages you expect to test. ## Quick Start 1. Install the plugin: ```bash npm install sealights-jest-plugin ``` 2. Configure and scan you project using Sealights Node.js agent: ```bash slnodejs config ... slnodejs scan ... ``` Check out [Sealights Node.js Agent Command Reference](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents/node.js-agent/command-reference) for more details on the commands. 3. Update your Jest configuration: ```js const { configCreator } = require('sealights-jest-plugin'); module.exports = configCreator({ // Your existing Jest configuration }); ``` 4. Run your tests with Sealights parameters: ```bash jest __tests__ --sl-testStage="Integration" ``` ## Configuration Options ### Command Line Parameters All Sealights parameters use the `--sl-` prefix: | Parameter | Description | Required | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | | `--sl-token` | Sealights authentication token | No (defaults to using tokenFile) | | `--sl-tokenFile` | Path to file containing the token | No (defaults to 'sltoken.txt') | | `--sl-buildSessionId` | Sealights build session ID | No (defaults to using buildSessionIdFile) | | `--sl-buildSessionIdFile` | Path to file containing build session ID | No (defaults to 'buildSessionId') | | `--sl-testStage` | Name of the test stage | Yes | | `--sl-labId` | Pre-defined Sealights lab ID | No | | `--sl-proxy` | Proxy server configuration | No | | `--sl-testProjectId` | Test project ID differentiates between different test stages with the same test stage name of different teams/products/etc. | No | | `--sl-prID` | Identifies PR pipeline executions, allowing them to be distinguished from eachother and from other executions of the same test-stage. | No | ## Project Setup Guides ### TypeScript Projects Add the following to your `tsconfig.json`: ```json { "compilerOptions": { "sourceMap": true, "sourceRoot": "." } } ``` ### Create React App Projects 1. Eject your CRA project (`npm run eject`) 2. Create `jest.config.js` in your project root: ```js const { configCreator } = require('sealights-jest-plugin'); module.exports = configCreator({ // Copy your Jest config from package.json }); ``` 3. Update `config/webpack.config.js`: ```js module.exports = { // ... other config devtool: false, optimization: { minimize: true, minimizer: [ new TerserPlugin({ keep_classnames: true, keep_fnames: true, }), ], }, plugins: [ new webpack.SourceMapDevToolPlugin({ noSources: true, columns: true, sourceRoot: '.', filename: 'static/js/[name].[contenthash:8].chunk.js.map', moduleFilenameTemplate: '[resource-path]', }), ], }; ``` 4. Update your test script: ```bash node scripts/test.js --watchAll=false --sl-testStage="Integration" ``` ## Legacy Jest Support ### Using with Older Jest Versions For Jest v26 and below: 1. Install required dependencies: ```bash npm i jest@26 jest-environment-node@26 jest-circus@26 # Or for jsdom environment: npm i jest@26 jest-environment-jsdom@26 jest-circus@26 ``` 2. Update configuration: ```js const { configCreator } = require('sealights-jest-plugin'); module.exports = configCreator( { // Your Jest config }, { version: 26 }, ); ``` ## Advanced Configuration ### Hook Dependency Guard The plugin includes a safety feature that handles test dependencies in nested test suites. When tests are selectively run, this guard prevents failures that could occur when a nested test suite depends on setup from its parent suite's hooks (like `beforeAll`). For example, consider this structure: ```js describe('Parent Suite', () => { beforeAll(() => { // Setup required by nested tests initializeTestData(); }); describe('Nested Suite', () => { test('depends on parent setup', () => { // This test assumes parent's beforeAll was executed }); }); }); ``` By default, the plugin adds dummy test runs to ensure proper hook execution order. If you want to disable this behavior: ```js const { configCreator } = require('sealights-jest-plugin'); module.exports = configCreator( { // Jest config }, { disableHookDependencyGuard: true }, ); ``` Note: Only disable this guard if you're certain your test suites don't have cross-dependencies through hooks. ## Important Notes - The plugin requires the `jest-circus` test runner (default in recent Jest versions) - For CRA projects using watch mode, you may need to disable it with `--watchAll=false` for proper coverage collection ## Support For additional support or issues, please contact Sealights support team. --- _Source: https://npm.io/package/sealights-jest-plugin · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._