Sealights WebdriverIO Plugin

Overview

Integrates SeaLights test intelligence with WebdriverIO (v5+), Mocha only. For WDIO+Cucumber, use sealights-cucumber-plugin.

Installation

npm install --save-dev sealights-webdriverio-plugin

Quick Start (Service)

Add the service to your config. WDIO resolves services by name only for packages named like wdio-<name>-service or @wdio/<name>-service. Since this package does not use that naming, pass the module directly.

CommonJS (wdio.conf.js)

// wdio.conf.js
const SealightsService = require('sealights-webdriverio-plugin');
const { launcher: SealightsLauncher } = require('sealights-webdriverio-plugin');
// OR
const {
  service: SealightsService,
  launcher: SealightsLauncher,
} = require('sealights-webdriverio-plugin');

exports.config = {
  framework: 'mocha',
  services: [
    // Pass the service class/module directly
    [SealightsService],
    // ...other services
  ],
  // Ensure the launcher runs to fetch exclusions before workers start
  onPrepare: async () => {
    await new SealightsLauncher().onPrepare();
  },
};

ESM (wdio.conf.mjs) or project with "type": "module"

// wdio.conf.mjs
import {
  service as SealightsService,
  launcher as SealightsLauncher,
} from 'sealights-webdriverio-plugin';

export const config = {
  framework: 'mocha',
  services: [[SealightsService]],
  onPrepare: async () => {
    await new SealightsLauncher().onPrepare();
  },
};

TypeScript (wdio.conf.ts)

// wdio.conf.ts
import type { Config } from '@wdio/types';
import {
  service as SealightsService,
  launcher as SealightsLauncher,
} from 'sealights-webdriverio-plugin';

export const config: Config = {
  framework: 'mocha',
  services: [[SealightsService]],
  onPrepare: async () => {
    await new SealightsLauncher().onPrepare();
  },
};

Alternative: Manual Hooks (no WDIO service)

If you prefer not to use WDIO services, import and attach the hooks directly:

const { registerSealightsWdioHooks } = require('sealights-webdriverio-plugin');

const hooks = registerSealightsWdioHooks();
exports.config = { framework: 'mocha', ...hooks };

Advanced: Referencing a built file path

You can reference the built entry file explicitly, though this is not recommended as it relies on internal package layout that might change:

const path = require('path');
exports.config = {
  framework: 'mocha',
  services: [
    [
      path.resolve(
        __dirname,
        './node_modules/sealights-webdriverio-plugin/tsOutputs/src/index.js',
      ),
    ],
  ],
};

Prefer passing the module directly as shown above.

Configuration (CLI and Environment)

SeaLights configuration can be provided via CLI arguments or environment variables (ENV takes precedence over CLI).

Command Line Parameters

All Sealights parameters use the --sl- prefix:

| Parameter | Description | Required | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | | --sl-token | Sealights authentication token | No (defaults to using tokenFile) | | --sl-tokenFile | Path to file containing the token | No (defaults to 'sltoken.txt') | | --sl-buildSessionId | Sealights build session ID | No (defaults to using buildSessionIdFile) | | --sl-buildSessionIdFile | Path to file containing build session ID | No (defaults to 'buildSessionId') | | --sl-testStage | Name of the test stage | Yes | | --sl-labId | Pre-defined Sealights lab ID | No | | --sl-proxy | Proxy server configuration | No | | --sl-enableRemoteAgent | Presence-only switch. When provided, WDIO disables the Browser Agent and collects component coverage via the remote agent (default: disabled) | No | | --sl-testProjectId | Test project ID differentiates between different test stages with the same test stage name of different teams/products/etc. | No | | --sl-targetTestProjectId | Test project ID to set for PR builds. The target test-project-id will be used to the statistical-model used for recommendations. | No |

Environment variable equivalents:

• Required:
  • SL_BUILDSESSIONID or SL_BUILDSESSIONIDFILE (defaults to buildSessionId as file)
  • SL_TOKEN or SL_TOKENFILE (defaults to sltoken.txt as file)
  • SL_TESTSTAGE
• Optional:
  • SL_PROXY, SL_LABID, SL_TESTPROJECTID, SL_TARGETTESTPROJECTID
  • SL_ENABLEREMOTEAGENT (define with any value to enable remote agent mode)

Remote Agent mode

• Default is disabled. When disabled, WDIO will not execute any commands in the browser to control the Sealights Browser Agent; coverage collection is expected to be handled by the Browser Agent as usual.
• When enabled (via --sl-enableRemoteAgent with no value, or by defining SL_ENABLEREMOTEAGENT):
  • Before each test, the plugin disables the Browser Agent within the AUT.
  • After each test, the plugin collects component coverage from the AUT window and sends it through the underlying remote agent.

How It Works

• Launcher (onPrepare): fetches excluded tests once and writes to .sl/.wdio-excluded-tests.json.
• Worker (before): starts execution and loads exclusions (falls back to fetching if file missing).
• Before each test: sends startTest.
• Optional remote-agent mode: when enabled, the service disables the Browser Agent in the AUT and later collects/sends component coverage.
• Automatic TIA-based skipping: if the current test is in the exclusions map, the plugin logs and skips it immediately while reporting it as skipped.
• After each test: sends endTest with result and duration. In remote-agent mode, component coverage (if present) is sent via the agent.
• After all: ends execution and stops agent.

Cucumber with WDIO

When framework: 'cucumber' is detected, this plugin no-ops and logs guidance. Use sealights-cucumber-plugin instead.

Exclusions File

• Path: .sl/.wdio-excluded-tests.json
• Produced by the launcher and consumed by workers. If missing, workers fall back to fetching from SeaLights.

Troubleshooting

• Service name not found: pass the module directly as shown above, or publish a wrapper named wdio-sealights-service.
• No coverage: ensure your app under test is instrumented with Sealights.
• Exclusions missing: verify .sl/.wdio-excluded-tests.json is produced; ensure launcher ran.
• Browser hangs during beforeEach: leave remote-agent mode disabled (default), or explicitly disable it by removing --sl-enableRemoteAgent/SL_ENABLEREMOTEAGENT.
• Cucumber events duplicated: remove the WDIO service and configure sealights-cucumber-plugin via cucumberOpts.require.

Debugging

• Enable additional logs: export NODE_DEBUG=sl (default level: info)
• Full debug level: export SL_LOG_LEVEL=debug