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>'
    ]
  },

Playwright Integration (Browser Footprints)

When using Cucumber.js with Playwright, the plugin can automatically send browser footprints (coverage data) to SeaLights after each test scenario. This ensures that code coverage collected by the SeaLights Browser Agent is flushed before the test ends.

How It Works

After each test, the plugin checks if a Playwright page object is available on the Cucumber World (this). If found, it calls $SealightsAgent.sendAllFootprints() in the browser context before reporting the test end event.

Setup

For this to work, you need to attach your Playwright page object to the Cucumber World in your hooks file. The following is a simplified example — do not copy-paste it directly. Adapt it to match your existing project configuration (e.g. browser launch options, context settings, base URL, etc.):

// tests/utils/common/hooks.ts (or your hooks file)
import { Before, After, setWorldConstructor } from '@cucumber/cucumber';
import { chromium, Browser, Page, BrowserContext } from '@playwright/test';

class CustomWorld {
  browser: Browser;
  context: BrowserContext;
  page: Page;
}

setWorldConstructor(CustomWorld);

Before(async function () {
  this.browser = await chromium.launch();
  this.context = await this.browser.newContext();
  this.page = await this.context.newPage();
});

After(async function () {
  // this.page is accessible here
});

The key requirement is that this.page is set on the Cucumber World and is a valid Playwright Page object with an evaluate method.

Custom Page Property Name

By default, the plugin looks for the page object on this.page. If your World uses a different property name (e.g. this.playwrightPage), set the SL_CUCUMBER_PAGE_PROPERTY environment variable:

SL_CUCUMBER_PAGE_PROPERTY=playwrightPage cucumber-js --config=cucumber.js test

Notes

• If no page object is found on the World, the plugin silently continues without sending browser footprints. This keeps the plugin backward compatible with non-browser test setups.
• If the browser agent is not loaded on the page, the footprint sending is safely skipped.
• The After hook has a 30 second timeout to accommodate the footprint sending.

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.
• prID - Identifies PR pipeline executions, allowing them to be distinguished from eachother and from other executions of the same test-stage.

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