sealights-webdriverio-plugin/README.md

WebdriverIO plugin for Sealights integration

# Sealights WebdriverIO Plugin

## Overview

Integrates SeaLights test intelligence with WebdriverIO (v5+), Mocha only. For WDIO+Cucumber,
use [sealights-cucumber-plugin](https://www.npmjs.com/package/sealights-cucumber-plugin).

## Installation

```bash
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`)

```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"`

```js
// 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`)

```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:

```js
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:

```js
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](https://www.npmjs.com/package/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`