@watershed-labs/driver-factory

Browser and device session factory for the Watershed ecosystem.

Part of the Watershed testing ecosystem.

Overview

@watershed-labs/driver-factory handles browser and device session creation for every Watershed template that interacts with a browser. It abstracts Chrome, Firefox, Edge, Safari, and Brave initialisation — including WebDriver BiDi capability enabling, post-launch Brave detection, and correct session teardown.

Keeping session creation here means BiDi upgrades, Brave patches, and new browser support land in one place and propagate to all affected templates automatically.

Installation

npm install @watershed-labs/driver-factory

Usage

import { BrowserFactory } from '@watershed-labs/driver-factory';
import { config } from '@watershed-labs/config';

const driver = await BrowserFactory.create({
    browser:  config.get('browser'),   // chrome | firefox | edge | safari
    headless: config.get('headless'),
    bidi:     true,                    // WebDriver BiDi enabled by default
});

await driver.detectBrave();            // post-launch Brave probe

API

| Method | Description | |---|---| | BrowserFactory.create(options) | Creates a new WebDriver session with BiDi enabled by default. Returns an augmented Driver instance. | | driver.detectBrave() | Post-launch Brave detection via navigator.brave JS probe. Caches result on instance. Call once after session creation. | | driver.initBiDi() | Upgrades the session to a BiDi WebSocket connection. Called automatically if bidi: true. | | driver.isBrave | Boolean. Available after detectBrave() is called. Use to gate Brave-specific behaviour. | | driver.quit() | Cleanly terminates the WebDriver session and closes the BiDi WebSocket connection. |

Options

| Option | Type | Default | Description | |---|---|---|---| | browser | string | 'chrome' | Browser target: chrome, firefox, edge, safari | | headless | boolean | true | Run in headless mode | | bidi | boolean | true | Enable WebDriver BiDi via webSocketUrl capability | | debugPort | number | auto | CDP debug port. Auto-derived from CUCUMBER_WORKER_ID in parallel runs. | | browserVersion | string | 'stable' | Browser channel. Always use 'stable' in CI. |

Brave Detection

Brave reports itself to WebDriver as Chrome. Detection must be done post-launch via a JavaScript probe. Do not check browserName === 'brave' — it will never be true.

await driver.detectBrave();

if (driver.isBrave) {
    // Skip canvas-dependent assertions
    // CDP device emulation results may not be pixel-perfect
}

Parallel Safety

Safe. Each worker owns an independent session. The factory automatically derives a unique CDP debug port from CUCUMBER_WORKER_ID using 9222 + parseInt(workerId) to prevent port collisions. Never pass a fixed --remote-debugging-port argument when running in parallel.

Licence

MIT — part of the Watershed ecosystem.