sealights-jest-plugin

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

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

1. Update your Jest configuration:

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

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

1. 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-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:

{
  "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
});

1. 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]',
    }),
  ],
};

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

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