sealights-cypress-plugin

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

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,
    setupNodeEvents(on, config) {
      registerSealightsTasks(on, 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 = (on, config) => {
  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

In order for the Sealights integration to work, three parameters have to be exported to the Cypress config.
This can be done using environment variables and exposing them to Cypress. The three environment variables are:

SL_BUILD_SESSION_ID
SL_LAB_ID // optional
SL_TOKEN
SL_TEST_STAGE

Additionally you can configure a proxy:

SL_PROXY=

For them to be available to Cypress, they have to be prefixed with CYPRESS_, for example:

export CYPRESS_SL_TOKEN={token}
export CYPRESS_SL_BUILD_SESSION_ID={buildSessionId}
export CYPRESS_SL_LAB_ID={labId}
export CYPRESS_SL_TEST_STAGE={your-test-stage}
export CYPRESS_SL_PROXY={your-proxy}

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

One additional change that has to be done in this case is in the Cypress config file:

// NOTE THE ADDITION OF `async` AND `await` - important when using Remote Agent mode
async setupNodeEvents(on, config) {
    await registerSealightsTasks(on, config);
}

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 sl-mapping part from the remote-agent and taking care of it instead.

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

Using the Plugins API (events) instead of Life Cycle hooks

Using the Plugins API for Cypress will use the following events instead of using Life cycle hooks:

Cypress event	Usage
before:run	Start the test session
after:run	End the test session

Be careful when enabling this mode, Cypress has an ongoing issues (https://github.com/cypress-io/cypress/issues/19809) which prevents plugins to register the same event. Meaning if a plugin before Sealights subscribed to the same events (the ones from the table above), our event handlers will not fire and vice-versa. If you still want to opt in for this mode and use multiple plugins registering the same events you will need to use the suggested module in the issue thread above: cypress-on-fix or similar fix.

export CYPRESS_SL_ENABLE_PLUGINS_API=true // default: false

Compatibility table

	Browser Agent Version	Remote Agent Enabled
Compatible	YES	YES

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
// Upload the coverage - if suitable
npx slnodejs nycFolderReport
// 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 X reason, not always related to Sealights - for example running in memory limited Docker container.

export CYPRESS_SL_DROP_FOOTPRINTS=true // default: false

Beside the above flag additional logs can be enabled using the following environment variable:

export NODE_DEBUG=sl