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:

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

2. Execute your Jest command through the runner

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

   npx sl-jest-runner npx jest --sl-testStage="Integration"

2. With your existing npm test script:

   npx sl-jest-runner npm test --sl-testStage="Integration"

3. With custom Jest configuration:

   npx sl-jest-runner npx jest --config my-jest.config.js --sl-testStage="Integration"

4. Pass any Jest arguments as you normally would:

   npx sl-jest-runner npx jest --watch --verbose --testNamePattern="user tests" --sl-testStage="Integration"

5. With package manager scripts:

   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:

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 <your-original-command>. 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 <dirs> or --copyConfigTo=<dirs>: 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 <n> or --recursiveCopyDepth=<n>: 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):

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

• Copy into multiple roots:

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

• Copy only into the provided directories (no recursion):

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:

npm install sealights-jest-plugin

2. Configure and scan you project using Sealights Node.js agent:

slnodejs config ...
slnodejs scan ...

Check out Sealights Node.js Agent Command Reference for more details on the commands.

3. Update your Jest configuration:

const { configCreator } = require('sealights-jest-plugin');

module.exports = configCreator({
  // Your existing Jest configuration
});

4. Run your tests with Sealights parameters:

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-targetTestProjectId | Test project ID to set for PR builds. The target test-project-id will be used to the statistical-model used for recommendations. | No |

Project Setup Guides

TypeScript Projects

Add the following to your tsconfig.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:

const { configCreator } = require('sealights-jest-plugin');

module.exports = configCreator({
  // Copy your Jest config from package.json
});

3. Update config/webpack.config.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:

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:

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:

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:

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:

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.