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');
const sealightsLauncher = new SealightsLauncher();

exports.config = {
  framework: 'mocha',
  services: [
    // Pass the service class/module directly
    [SealightsService],
    // ...other services
  ],
  // Retain one launcher: it owns the execution across both lifecycle hooks.
  onPrepare: async () => {
    await sealightsLauncher.onPrepare();
  },
  onComplete: async () => {
    await sealightsLauncher.onComplete();
  },
};

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

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

const sealightsLauncher = new SealightsLauncher();

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

TypeScript (wdio.conf.ts)

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

const sealightsLauncher = new SealightsLauncher();

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

The launcher is required because it owns the single SeaLights execution. It opens that execution before fetching exclusions, persists the shared state for workers to reuse, and closes the same execution in onComplete. Always retain one launcher instance for both lifecycle hooks.

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

registerSealightsWdioHooks() returns the complete lifecycle: launcher onPrepare/onComplete hooks and worker before/beforeTest/afterTest/after hooks. One launcher instance is shared by its two hooks, and one service instance is shared by all worker 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-prID | Identifies PR pipeline executions, allowing them to be distinguished from eachother and from other executions of the same test-stage. | 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_PRID
  • 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): opens the single execution, writes it to .sl/.wdio-execution.json, then fetches excluded tests once and writes them to .sl/.wdio-excluded-tests.json.
• Worker (before): reuses the launcher-owned execution from the state file and loads exclusions. If execution state is missing or invalid, SeaLights is strictly disabled for that worker; the worker does not start a replacement execution or fetch exclusions.
• 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.
• Worker (after): stops only its worker-local agent.
• Launcher (onComplete): explicitly ends the single execution, then stops the launcher agent and removes shared state. If execution closure fails, the launcher logs the error, stops the agent, and still removes local state files.

Cucumber with WDIO

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

Shared State Files

• Execution path: .sl/.wdio-execution.json
• Exclusions path: .sl/.wdio-excluded-tests.json
• Both files are produced by the launcher after the execution opens and consumed by workers. Missing or invalid execution state strictly disables SeaLights in that worker so workers cannot create duplicate executions. The launcher removes both files during teardown after attempting to end the execution.

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.
• Shared state missing: verify .sl/.wdio-execution.json and .sl/.wdio-excluded-tests.json are produced; ensure the same retained launcher instance is wired to both onPrepare and onComplete.
• 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