sealights-cucumber-plugin

This is the SeaLights plugin for Cucumber.js. This plugin is specifically designed for JavaScript/Node.js projects using Cucumber.js and should not be confused with SeaLights plugins for Java (Maven/Gradle).

Install

npm install sealights-cucumber-plugin

Usage

Pass path-to-plugin as require option of cucumber command:

npx cucumber-js ./features ... --require <path-to-plugin>

Or alternatively, set it in the cucumber.js config file:

// cucumber.js
module.exports = {
  default: {
    ...
    require: [
      './features/support/*',
      '<path-to-plugin>',
    ]
  }
};

Note: Using the --require option overrides the default path to step definitions. Make sure to explicitly include your step definitions path:

npx cucumber-js ./features --require ./src/steps/*.steps.ts --require <path-to-plugin>

Resolve path to plugin

CommonJs

const pathToPlugin = require.resolve('sealights-cucumber-plugin');

ESM

import url from 'node:url';

const pluginUrl = import.meta.resolve('sealights-cucumber-plugin');
const pathToPlugin = url.fileURLToPath(new URL(pluginUrl));

Resolve in CLI

You can resolve the path in CLI if Node.js is available on your machine:

Unix:

SL_PACKAGE=$(node -p "require.resolve('sealights-cucumber-plugin')")

PowerShell:

$Env:SL_PACKAGE = node -p "require.resolve('sealights-cucumber-plugin')"

If these options don't work, you can use the static path to the plugin: ./node_modules/sealights-cucumber-plugin/tsOutputs/lib/cucumber-integration.js (Note: Using static path is not recommended as it may change in future versions)

Usage in protractor.conf or wdio.conf

Add the plugin path to the cucumber options:

cucumberOpts: {
    require: [
      './src/steps/*.steps.ts',
      '<path-to-plugin>'
    ]
  },

Configuration

Using configuration file (Recommended)

Create a file named sl.conf and provide the configuration in JSON format:

{
  "tokenFile": "path/to/token-file",
  "buildSessionIdFile": "path/to/buildSessionId-file",
  "testStage": "e2e"
}

Using CLI parameters (Legacy support)

⚠️ Not recommended: This method won't work in the latest versions of Cucumber.js. Use the configuration file instead.

From the command line, add SeaLights parameters with --sl- prefix:

npx cucumber-js ./features --sl-tokenFile <path/to/token-file> --sl-buildSessionIdFile <path/to/buildSessionId-file> --sl-testStage e2e

Configuration Parameters

• token - SeaLights token
• tokenFile - Path to file containing the SeaLights token
• buildSessionId - SeaLights build session ID
• buildSessionIdFile - Path to file containing the SeaLights build session ID
• testStage - Test stage that current tests relate to
• labId - Pre-defined SeaLights lab-id (optional)
• proxy - Proxy server (optional)
• testProjectId - Test project ID differentiates between different test stages with the same test stage name of different teams/products/etc.
• targetTestProjectId - Test project ID to set for PR builds. The target test-project-id will be used to the statistical-model used for recommendations.

Note: All configuration parameters are case-insensitive as they are converted to lowercase internally.

Troubleshooting

If you encounter configuration issues:

1. Ensure your sl.conf contains valid JSON
2. Verify all file paths are correct and accessible
3. Check that token and buildSessionId files exist and contain valid values
4. If you see a "Failed to load cucumber version" message, this is typically informational and not an error, it means that the plugin is trying to load the latest version of Cucumber.js. If you see a message "Failed to load cucumber" followed by an error, this is an actual error and the plugin failed to load.

Author

SeaLights