@watershed-labs/world

Cucumber World base class and lifecycle contract for the Watershed ecosystem.

Part of the Watershed testing ecosystem.

Overview

@watershed-labs/world is the foundation every Watershed template builds on. It provides the WatershedWorld base class that all Cucumber Worlds extend, enforcing a consistent lifecycle contract across every template: session initialisation, cleanup handler registry, and guaranteed teardown.

Every template calls super.init() and super.teardown(). The base class handles the rest — worker ID resolution, cleanup handler ordering, and reporter attachment.

Installation

npm install @watershed-labs/world

Usage

import { WatershedWorld } from '@watershed-labs/world';
import { setWorldConstructor } from '@cucumber/cucumber';

class OtterWorld extends WatershedWorld {
    async init() {
        await super.init();         // always call first
        this.driver = await ...;    // template-specific setup
    }
}

setWorldConstructor(OtterWorld);

API

| Method | Description | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | init() | Called by the Before hook. Override in each template for session setup. Always call super.init() first. | | updateContext(updates) | Merges values into the scenario context store via Object.assign (mutates in place). This preserves the object reference so BaseHelper and BasePage always see the current values without re-reading the store. Use to expose the driver after creation: this.updateContext({ driver: this.driver }). | | teardown() | Calls all registered cleanup handlers in reverse registration order, then resets internal state. Called automatically by @watershed-labs/hooks after every scenario. | | registerCleanup(fn) | Registers an async cleanup function. Called during teardown() in reverse order. Use this for BiDi subscriptions, network intercepts, and any resource that must be released per-scenario. | | attach(data, mediaType) | Wraps Cucumber's native attach. Use for screenshots, logs, and arbitrary report attachments. | | workerId | String. Set from CUCUMBER_WORKER_ID during init(). Available to all subclasses. Defaults to '0' in non-parallel runs. |

Lifecycle Contract

Before scenario
  → init()                  override in template, call super.init() first

During scenario
  → registerCleanup(fn)     register cleanup handles as resources are created

After scenario (automatic via @watershed-labs/hooks)
  → teardown()              cleanup handlers called in reverse order
                            capturedErrors reset
                            internal state cleared

Parallel Safety

Safe. Cucumber instantiates a fresh World per scenario per worker. workerId is set automatically from CUCUMBER_WORKER_ID and is available to all subclasses.

Licence

MIT — part of the Watershed ecosystem.