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 and test skipping as well.

Supported Node / Cypress versions

• Node >= 12
• Cypress >= 9

⚠️ Usage with other plugins

If you're using the Sealights plugin with other plugins, please read the following carefully!

This plugin will register multiple types of life-cycle event handlers. However, only a single event handler can exist for each type of event (due to a limitation in Cypress). Thus, if you attempt to define any of the same handlers, your handler will either be overriden by this plugin or you will override this plugin's handler. Either way, one of the plugins will stop functioning as expected.

There's an (multiple actually) open issue at Cypress tracking this limitation.

These are the events this plugin will subscribe to:

• before:run
• after:run

For example, if you specify a handler for before:run and override this plugin's handler, then no test events will be sent to Sealights.

For a workaround and ability to use multiple plugins please refer to: cypress-on-fix, or the original issue linked above.

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 from GitHub/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

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 // this or labId
SL_LAB_ID // this or buildSessionId
SL_TOKEN
SL_TEST_STAGE

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}

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