sealights-cypress-plugin

sealights-cypress-plugin is a custom plugin for the Cypress testing framework that enhances your testing capabilities by providing additional support for various tasks and configurations. This plugin adds support for Sealights, reporting coverage, test results, and test skipping as well.

Officially Supported Node / Cypress versions

• Node >= 12
• Cypress >= 9

Using the Sealights Cypress Runner (Beta)

⚠️ Warning: This is a beta feature. The functionality and API may change in future releases.

Note: Currently the runner only supports E2E tests.

• The command-line runner (sl-cypress-runner) now automatically integrates SeaLights with your Cypress project.
• It backs-up your existing Cypress configuration & support files, injects the required Sealights hooks (registerSealightsTasks and the support file import), runs the tests and then restores the original files.
• It validates that the mandatory environment variables are present and that your Sealights server / collector are reachable before the test run starts.
• Running with the --spec flag is fully supported – the runner will take care of quoting glob patterns and will expose the spec pattern to the plugin through an environment variable.

Because all configuration is performed automatically, you only need two steps to use the runner:

1. Install the plugin:

   npm install --save-dev sealights-cypress-plugin

2. Export the required environment variables (e.g. CYPRESS_SL_BUILD_SESSION_ID, CYPRESS_SL_TOKEN, CYPRESS_SL_TEST_STAGE, …) and execute your Cypress command through the runner:

   npx sealights-cypress-plugin npx cypress run --spec 'cypress/e2e/**/*spec.cy'

Usage

You can invoke the runner in two ways:

1. Using npx (recommended):

npx sealights-cypress-plugin npx cypress run --spec test.spec.cy

2. Directly from node_modules:

node ./node_modules/.bin/sl-cypress-runner npx cypress run --spec test.spec.cy

You may pass any command after the runner – it will be executed verbatim:

npx sealights-cypress-plugin my-own-cypress-command --headed --browser chrome

If you use a glob for the --spec pattern, remember to wrap it in quotes so that your shell doesn't expand it:

npx sealights-cypress-plugin npx cypress run --spec '*.spec.cy'

The runner will:

• Validate your Sealights configuration and connectivity
• Back-up and patch Cypress config & support files
• Log the resolved spec file pattern (if provided)
• Execute the supplied command
• Restore the original files after the run
• Exit with the same exit code as the command

Cleaning Up After Ungraceful Exit

If the runner exits unexpectedly (e.g., due to a crash, SIGKILL, or forced termination), the backup files (.slbak) may not be automatically restored. In such cases, you can manually clean up and restore the original Cypress configuration files using the clean or reset command:

npx sealights-cypress-plugin clean

or equivalently:

npx sealights-cypress-plugin reset

This command will:

• Read the backup file paths from the temporary tracking file (_sl.backup-paths)
• Restore the original Cypress config and support files from the .slbak backups
• Remove all temporary files created by the runner

Note: This command only works if the runner successfully created the backup tracking file before the ungraceful exit. If the tracking file doesn't exist, you may need to manually restore the .slbak files.

Important Notes

The manual configuration instructions shown below ("Cypress v10+" / "Cypress v9") are not required when you use the runner – they are kept for users who wish to integrate the plugin manually.

Features

• Support File: The plugin introduces a support file, it is automatically loaded before each test, providing a centralized location to manage the Sealights information and execute the required hooks

• Config File: The config file empowers the Cypress tests run by adding the required tasks and communicates with Sealights

Installation

To use sealights-cypress-plugin in your Cypress project, follow these steps:

1. Install and Setup Cypress if you haven't already:

   npm install cypress --save-dev

2. Install the plugin using npm

   npm install sealights-cypress-plugin

Cypress v10+

In your cypress.config.js register the plugin:

const { defineConfig } = require('cypress');
const { registerSealightsTasks } = require('sealights-cypress-plugin');

module.exports = defineConfig({
  e2e: {
    experimentalInteractiveRunEvents: true,
    testIsolation: false,
    async setupNodeEvents(on, config) {
      await registerSealightsTasks(on, config);
      return config;
    },
  },
});

Add to your cypress/support/e2e.js:

// This is your existing support/e2e.js file content
// ...

// Import sealights-cypress-plugin's support file
import 'sealights-cypress-plugin/support';

Cypress v9

Add to your cypress/plugins/index.js file

const { registerSealightsTasks } = require('sealights-cypress-plugin');

module.exports = async (on, config) => {
  await registerSealightsTasks(on, config);
  // IMPORTANT: return the config object
  // because the plugin might have changed it
  return config;
};

Add to your cypress/support/index.js file

import 'sealights-cypress-plugin/support';

Configuration

Minimal configuration

To enable Sealights integration with Cypress, you need to export three environment variables to the Cypress configuration. This can be achieved by using environment variables and exposing them to Cypress. The required environment variables are:

• SL_BUILD_SESSION_ID
• SL_TOKEN
• SL_TEST_STAGE

Optionally, you can also configure a proxy using the following environment variable and also provide Sealights LabId parameter:

• SL_PROXY
• SL_LAB_ID

Additionally, you can configure test project identification using the following environment variables:

• SL_TEST_PROJECT_ID or SL_testProjectId - Identifies the test project
• SL_PR_ID or SL_prID - Identifies PR pipeline executions, allowing them to be distinguished from eachother and from other executions of the same test-stage.

For these variables to be accessible by Cypress, they need to be prefixed with CYPRESS_. Here are the required environment variables with the correct prefix:

CYPRESS_SL_BUILD_SESSION_ID
CYPRESS_SL_LAB_ID
CYPRESS_SL_TOKEN
CYPRESS_SL_TEST_STAGE
CYPRESS_SL_PROXY
CYPRESS_SL_TEST_PROJECT_ID
CYPRESS_SL_PR_ID

Note: The plugin also supports the Node Agent standard format for test project variables without the CYPRESS_ prefix:

• SL_testProjectId
• SL_prID

By setting these environment variables, you ensure that Cypress can properly integrate with Sealights and leverage its capabilities.

More about defining the environment variables in Cypress at the following link: https://docs.cypress.io/guides/guides/environment-variables

Using remote-agent version

The primary goal of this implementation is to significantly reduce load times and test execution times, especially in scenarios where there are repeated page reloads. We aim to achieve this by providing an alternative method for skipping the download of our browser agent and use a remote-agent implementation instead.

To enable this feature please set the following Environment Variable:

export CYPRESS_SL_ENABLE_REMOTE_AGENT=true

Note: The registerSealightsTasks function is async and must always be called with await. Make sure your setupNodeEvents function (Cypress v10+) or plugin export function (Cypress v9) is declared as async and uses await when calling registerSealightsTasks. This is required for all configurations, not just when using Remote Agent mode.

Spec pattern

Cypress provides two ways of choosing which specs should be run:

• specPattern config option
• --spec CLI param

Both options use glob patterns. --spec is used to define a subset of what's defined in specPattern, e.g. a subdirectory. If --spec defines completely different pattern than specPattern, no specs will be run, e.g. if --spec is ./src/**, and specPattern is ./cypress/e2e/** - there will be no match.

Cypress exposes specPattern from config to the plugin, but --spec is not exposed. There are to ways to provide the spec to the plugin.

E2E tests

If you run E2E tests and want to define --spec param, the recommended way is to use the runner. You can also use CYPRESS_SL_SPEC which is described below.

Component tests

SL Cypress plugin introduces CYPRESS_SL_SPEC env var which in component tests must be set to the same value as Cypress' --spec CLI param. If this var is not set, for component tests cypress/component/**/*.cy.{js,jsx,ts,tsx} is used as the default spec pattern. This is different pattern than Cypress uses - in Cypress default specPattern for component tests is **/*.cy.{js,jsx,ts,tsx}, which also catches E2E tests (which are later on excluded from the execution internally in Cypress). If you do not use --spec CLI param, and your component tests directory is different from cypress/component, remember to set CYPRESS_SL_SPEC accordingly.

E.g. if you keep your component tests together with components themselves, like in the structure below:

/
|-- cypress/
|  |-- e2e/
|  | |-- some-e2e-spec.cy.js
|-- src/
|  |-- my-component.jsx
|  |-- my-component.cy.jsx
|  |-- module/
|  |  |-- other-component.jsx
|  |  |-- other-component.cy.jsx

you should set CYPRESS_SL_SPEC=src/**/*.cy.{js,jsx,ts,tsx}. If you define --spec "src/module/**.cy.jsx", then you should set CYPRESS_SL_SPEC=src/module/**.cy.jsx

after:run hook registration

The plugin registers an after:run hook by default as an additional close signal for execution finalization. This can improve reliability when per-spec counting is affected by external filtering/plugins.

If needed, you can disable this hook registration:

export CYPRESS_SL_DISABLE_AFTER_RUN_HOOK=true # default: false

When disabled, the plugin will skip registering after:run and rely only on the per-spec counter to close the test session. If the counter does not match (e.g. due to external spec filtering by @cypress/grep or other plugins), the test session may remain open, which can result in incomplete execution data, missed test events, and unreported coverage on the Sealights dashboard.

Note: This is a known Cypress limitation where multiple plugins sharing the same Node event can overwrite each other's handlers (cypress-io/cypress#5240, cypress-io/cypress#22428). If you use multiple Cypress plugins, consider using cypress-on-fix to compose event handlers safely instead of disabling this hook.

Using a collector

The primary goal of this implementation is to reduce load times and test execution times. A collector can reduce the time by taking the Sealights Mapping (for methods/files) part from the remote-agent which makes requests to the backend directly and handling it locally instead. This offloading improves efficiency and speeds up the overall test process.

To enable this feature please set the following Environment Variable:

export CYPRESS_SL_COLLECTOR_URL={your-collector-url}

Compatibility table

| | Browser Agent Version | Remote Agent Enabled | | :--------: | :-------------------: | :------------------: | | Compatible | NO | YES |

NOTE: This compatibility table refers to the Plugin only. Our Browser Agent supports using the Collector which is enabled during the build scan process of your application.

Using Optimized Coverage Collection

To improve performance, you can enable optimized coverage collection. This feature splits the NYC coverage data into two parts: coverage maps (written to the file system) and coverage counters (sent through IPC). By separating these components, large data transfers are minimized, resulting in faster test execution.

To enable optimized coverage collection, set the following environment variable:

export CYPRESS_SL_OPTIMIZE_COVERAGE_COLLECTION=true

This option is particularly useful when handling extensive coverage data, helping to streamline and accelerate the coverage collection process.

Compatibility table

| | Browser Agent Version | Remote Agent Enabled | | :--------: | :-------------------: | :------------------: | | Compatible | NO | YES |

Using per-spec-file reporting

In this mode the test events are reported at the end of each spec file and each spec is considered a single test. If a test belonging to the spec failed, the spec will be marked as failed as well. The reported test names are equal to the spec name. In this mode TIA is disabled by default because there are no separate tests being reported to Sealights. It is up to the user to decide which spec files to run before initiating Cypress run.

export CYPRESS_SL_PER_FILE_REPORTING=true

Compatibility table

| | Browser Agent Version | Remote Agent Enabled | | :--------: | :-------------------: | :------------------: | | Compatible | YES | YES |

Disable Test Recommendations

If you wish to disable TIA and enforce a full run by the plugin, you can set the following environment variable to true:

export CYPRESS_SL_TIA_DISABLED=true // default: false

Lite Mode Configuration

The plugin also supports running in "lite mode" configuration which will skip a few important steps in the plugin lifecycle:

• The plugin will not open nor close test sessions (can be disabled using CYPRESS_SL_LITE_MODE_MANAGE_EXECUTIONS, read more bellow)
• The plugin will not send the coverage to Sealights, instead the coverage will be written to files in the current working directory under a directory called sl-coverage-files
• Cypress can run with testIsolation turned off, we discourage this usage as it's not best practice and as well as it might cause issues with the plugin (https://docs.cypress.io/guides/core-concepts/test-isolation#What-is-Test-Isolation)
• Lite mode cannot work correctly with testIsolation and the plugin will throw an error if they are used together. You can use testIsolation with other modes instead.

You can enable this mode by setting the following environment variable:

export CYPRESS_SL_LITE_MODE=true // default: false

IMPORTANT: When running in this mode and CYPRESS_SL_LITE_MODE_MANAGE_EXECUTIONS is not set to true make sure SL_CYPRESS_TEST_STAGE matches you open tests stage!

Following is a small example on how to start a test session, run your tests, upload the coverage using our slnodejs agent, and close the test session:

// Start the test session
npx slnodejs start --tokenFile sltoken.txt --buildSessionIdFile buildSessionId --testStage "cypres e2e"
// Match the started test session with the one provided to Cypress
export CYPRESS_SL_TEST_STAGE="cypress e2e" // IMPORTANT!
// Other config variables for the plugin
export CYPRESS_SL_TOKEN={token}
export CYPRESS_SL_BUILD_SESSION_ID={bsid}
export CYPRESS_SL_ENABLE_REMOTE_AGENT=true
export CYPRESS_SL_LITE_MODE=true
// Run the tests
npx cypress run
// End the test session
npx slnodejs end --tokenFile sltoken.txt --buildSessionIdFile buildSessionId

Additionally we support managing executions by the plugin itself in Lite Mode as well, to opt-out of external executions management set the following environment variable to true:

export CYPRESS_SL_LITE_MODE_MANAGE_EXECUTIONS=true

Compatibility table

| | Browser Agent Version | Remote Agent Enabled | | :--------: | :-------------------: | :------------------: | | Compatible | NO | YES |

Debug Configuration

For debugging, we support dropping the generated footprints file so it will not be sent to Sealights. This is useful in case there are network issues of any kind or your pipeline is stuck for any reason not always related to Sealights — for example, running in a memory-limited Docker container.

export CYPRESS_SL_DROP_FOOTPRINTS=true # default: false

Additionally, extra logs can be enabled using the following environment variable:

export NODE_DEBUG=sl

The default log level with this var on is info. To obtain the debug logs you can set another variable:

export SL_LOG_LEVEL=debug

Moreover, you can enable the following environment variable, CYPRESS_SL_ENABLE_BROWSER_DEBUG, which allows the dumping of browser network traffic, unhandled exceptions, browser logs, and checks the fetch status of the browser agent. All of this will be exported in a folder called sealights-output, organized by spec file.

export CYPRESS_SL_ENABLE_BROWSER_DEBUG=true # default: false