Cypress framework

The 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, including coverage reporting, test results, and test optimization.

It’s a non-intrusive setup — no changes to your Cypress configuration files are required. Install the plugin, export your environment variables, and run your Cypress tests using the SeaLights Cypress Runner.

For advanced details, you can also refer to https://www.npmjs.com/package/sealights-cypress-plugin

Configuration

1

Install the Plugin

To install the Sealights Cypress plugin, follow the instructions below.

npm install --save-dev sealights-cypress-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. The required environment variables must start with a CYPRESS_ prefix:

Linux

export CYPRESS_SL_TOKEN=<your_token>            # from CI secret or vault
export CYPRESS_SL_ENABLE_REMOTE_AGENT=true
export CYPRESS_SL_TEST_STAGE="Cypress E2E Tests"
#export CYPRESS_SL_BUILD_SESSION_ID=<your_bsid>  # unique per app build/version
export CYPRESS_SL_LAB_ID=<your_labid>  # unique per testing environment

PowerShell

3

Execute your Cypress tests with SeaLights

Execute your Cypress command through the Sealights runner:

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

The plugin used as a runner automatically integrates SeaLights with your Cypress project:

• Backs up your existing Cypress configuration & support files,

• Injects the required Sealights hooks (registerSealightsTasks and the support file import)

• Validates that the mandatory environment variables are present and that the Sealights endpoint is reachable before the test run starts.

• Executes tests with coverage collection

• Restores original files afterward

When the command and Cypress 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.

Additional Runner Usages

You can invoke the runner in two ways:

1. Using npx (recommended):

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

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

Logging and Debugging

Additional logging 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

Using the variable CYPRESS_SL_ENABLE_BROWSER_DEBUG, you can enable the dumping of browser network traffic, unhandled exceptions, browser logs, and check 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

Sample Script

Bash

# 1. Install dependencies
npm ci

# 2. Install SeaLights Cypress plugin
npm install --save-dev sealights-cypress-plugin

# 3. Set environment variables 
export CYPRESS_SL_TEST_STAGE="cypress e2e" 
export CYPRESS_SL_TOKEN={token}    ## From Secrets/Vault
#export CYPRESS_SL_BUILD_SESSION_ID={bsid}
export CYPRESS_SL_LAB_ID=integ_app_uat1
# export CYPRESS_SL_PROXY="http://proxyuser:[email protected]:8080"
#export NODE_DEBUG=sl
#export SL_LOG_LEVEL=debug

# 4. Run tests with SeaLights
npx sealights-cypress-plugin npx cypress run --spec 'cypress/e2e/**/*spec.cy'

PowerShell

GitHub Actions

✅ Coverage data and test results are uploaded automatically to your SeaLights dashboard.

Advanced Configuration and Developer Options

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

• Manual configuration for Cypress v9 and v10+ (without the runner)

• Lite Mode configuration

Common Plugin Parameters

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

Environment Variable Equivalent	Required	Description
CYPRESS_SL_TEST_STAGE	✅	Name of the test stage (“Cypress”, “E2E”, etc.)
CYPRESS_SL_TOKEN	✅	Authentication token
CYPRESS_SL_LAB_ID	✅	Test Environment ID shared with the Instrumented AUT (Application Under Test). Optional if the BUILD_SESSION_ID is provided.
CYPRESS_SL_BUILD_SESSION_ID	Optional	Sealights Build Session ID. Mandatory if LAB_ID is not defined.
CYPRESS_SL_PROXY	Optional	Proxy configuration (host:port or URL)
CYPRESS_SL_TEST_PROJECT_ID	Optional	Identifier for the current test project
CYPRESS_SL_TARGET_TEST_PROJECT_ID	Optional	Target test-project ID (for PR builds / TGA model)
CYPRESS_SL_ENABLE_REMOTE_AGENT	Optional	Reduce load and test execution times, by skipping download of browser agent and using a remote-agent implementation. Default is true
CYPRESS_SL_COLLECTOR_URL	Optional	HTTP Collector URL
CYPRESS_SL_TIA_DISABLED	Optional	Disable TIA and enforce a full run. (Default: false.)
CYPRESS_SL_OPTIMIZE_COVERAGE_COLLECTION	Optional	Reduce large coverage data transfers. Default is false