@watershed-labs/network

BiDi-first network interception, mocking, and security header assertion for the Watershed ecosystem.

Part of the Watershed testing ecosystem.

Overview

@watershed-labs/network provides the complete network layer for Watershed templates. It uses WebDriver BiDi as the primary protocol for cross-browser interception, falling back to CDP for Chromium-exclusive capabilities. The full mockResponse() implementation — including the network.provideResponse handler — lives here. Templates never implement their own network layer.

Installation

npm install @watershed-labs/network

Usage

import { NetworkInterceptor } from '@watershed-labs/network';

// Instantiate per session inside the World
const network = new NetworkInterceptor(driver);

// Mock a response
await network.mockResponse('/api/checkout', {
    status: 503,
    body: { error: 'Service temporarily unavailable' },
    headers: { 'Content-Type': 'application/json' },
});

// Capture requests for later assertion
await network.captureRequests('/api/orders');
// ... run scenario ...
const requests = network.getCapturedRequests('/api/orders');

// Assert security headers on the current page
await network.assertSecurityHeaders({
    'Content-Security-Policy':   true,
    'Strict-Transport-Security': true,
    'X-Content-Type-Options':    'nosniff',
    'Referrer-Policy':           true,
    'Permissions-Policy':        true,
});

// Cleanup is handled automatically by @watershed-labs/world teardown

API

| Method | Description | |---|---| | mockResponse(urlPattern, response) | Intercepts matching requests and responds with the provided mock. Registers a cleanup handle automatically. | | removeIntercept(handle) | Removes a specific intercept before teardown. Called automatically during teardown(). | | captureRequests(urlPattern) | Records all matching requests for later assertion. | | getCapturedRequests(urlPattern) | Returns captured requests matching the given pattern. | | assertSecurityHeaders(headers?) | Asserts presence and correctness of OWASP-recommended security headers on the current response. | | sanitiseLogs(entries) | Pipes network entries through @watershed-labs/logger PII scrubber before assertion or reporting. |

Protocol Strategy

| Capability | Protocol | |---|---| | Request interception | BiDi — all browsers | | Response mocking | BiDi — all browsers | | Security header assertion | BiDi — all browsers | | Response body injection | CDP — Chromium only |

Teardown

All intercepts registered via mockResponse() are automatically removed during teardown(). Do not manually manage intercept cleanup unless you need to remove an intercept mid-scenario. Intercepts that are not removed between scenarios cause cross-test pollution — this is the most common source of flakiness in network-heavy test suites.

Parallel Safety

Safe. Intercepts are registered on a specific BiDi WebSocket session and are fully isolated to that session. Teardown clears all intercepts before the session closes, ensuring no intercept bleeds into the next scenario even within the same worker.

Licence

MIT — part of the Watershed ecosystem.