@watershed-labs/logger

Structured, levelled logger with mandatory PII scrubbing for the Watershed ecosystem.

Part of the Watershed testing ecosystem.

Overview

@watershed-labs/logger is the single logging interface for all Watershed templates. Every string that passes through it is scanned for PII patterns before reaching stdout or disk. This is not configurable — it is a hard guarantee that Watershed logs are safe to store in CI artefacts and send to external reporting services.

Installation

npm install @watershed-labs/logger

Usage

import { logger } from '@watershed-labs/logger';

logger.info('Navigating to checkout');
logger.warn('Slow response detected', { duration: 4200 });
logger.error('Assertion failed', { step: 'verify order total' });
logger.debug('Network request captured', { url: '/api/orders' });

Child logger with context

Use logger.child() inside the World to tag every log entry with its scenario and worker:

// inside WatershedWorld.init()
this.logger = logger.child({
    workerId:  this.workerId,
    scenario:  this.pickle.name,
});

this.logger.info('Session started');
// → { level: 'info', workerId: '2', scenario: 'User adds item to cart', message: 'Session started' }

PII Scrubbing

The following patterns are redacted from every log message and metadata object before output. Redaction is applied recursively to nested objects.

| Pattern | Replacement | |---|---| | Email addresses | [REDACTED_EMAIL] | | JSON Web Tokens (eyJ...) | [REDACTED_JWT] | | Credit / debit card numbers (Luhn-valid) | [REDACTED_CARD] | | IBANs | [REDACTED_IBAN] | | Phone numbers (UK and international formats) | [REDACTED_PHONE] | | AWS access keys (AKIA...) | [REDACTED_AWS_KEY] | | High-entropy strings matching secret patterns | [REDACTED_SECRET] |

API

| Method | Description | |---|---| | logger.info(msg, meta?) | Informational log entry. | | logger.warn(msg, meta?) | Warning — non-fatal unexpected state. | | logger.error(msg, meta?) | Error — test failure or unexpected exception. | | logger.debug(msg, meta?) | Debug — verbose output, suppressed unless LOG_LEVEL=debug. | | logger.child(context) | Returns a child logger that merges context into every entry. |

Parallel Safety

Safe with worker-scoped file output. Each worker writes to ./logs/worker-{CUCUMBER_WORKER_ID}.log. Writing all workers to a single log file produces interleaved, unreadable output. Use logger.child({ workerId }) inside the World to tag every entry with its originating worker.

Licence

MIT — part of the Watershed ecosystem.