Mode Management

Replay's mode system controls how HTTP requests are handled, providing four distinct operational modes for different testing scenarios.

Capabilities

Mode Property

Controls the operational mode of the replay system.

/**
 * Current operational mode
 * @type {'replay' | 'record' | 'cheat' | 'bloody'}
 */
Replay.mode: string;

Usage Examples:

const Replay = require('replay');

// Set to record mode to capture new responses
Replay.mode = 'record';

// Set to replay mode for tests (default)
Replay.mode = 'replay';

// Set to cheat mode for development
Replay.mode = 'cheat';

// Set to bloody mode to bypass all replay functionality
Replay.mode = 'bloody';

Environment Variable Configuration

The default mode can be set via environment variable:

/**
 * Environment variable for default mode
 * @type {'replay' | 'record' | 'cheat' | 'bloody'}
 */
process.env.REPLAY: string;

Usage Examples:

# Run tests in record mode
REPLAY=record npm test

# Run in cheat mode
REPLAY=cheat node app.js

# Run in bloody mode (live requests)
REPLAY=bloody npm test

Operational Modes

Replay Mode (Default)

The default mode for running tests. Only replay captured responses, no outbound network access.

Behavior:

• Replays recorded HTTP responses from fixtures
• Blocks all outbound HTTP requests
• Throws connection refused error for unmatched requests
• Ensures deterministic, repeatable tests

Use Cases:

• Running automated tests
• CI/CD pipelines
• Offline development

Record Mode

Captures new HTTP responses while replaying existing ones.

Behavior:

• Replays recorded responses when available
• Makes real HTTP requests for unmatched requests
• Saves new responses to fixture files
• Allows adding new test scenarios

Use Cases:

• Creating new tests
• Adding new API endpoints to existing tests
• Updating responses for changed APIs

Cheat Mode

Allows both replay and live requests without recording.

Behavior:

• Replays recorded responses when available
• Makes real HTTP requests for unmatched requests
• Does not save new responses
• Useful for unstable development scenarios

Use Cases:

• Development with new, changing code
• Testing against live APIs without committing responses
• Debugging network issues

Bloody Mode

Bypasses all replay functionality, all requests go live.

Behavior:

• All HTTP requests go to real servers
• No replay functionality
• No recording functionality
• Equivalent to not using Replay at all

Use Cases:

• Testing against live API changes
• Performance testing with real network conditions
• Validating recorded responses against current API behavior

Error Handling

Unsupported Mode Error

Thrown when an invalid mode is specified:

/**
 * Error thrown for invalid mode
 * @throws {Error} When mode is not one of the supported values
 */
new Error(`Unsupported mode '${mode}', must be one of ${MODES.join(', ')}.`);

Connection Refused Error

Thrown in replay mode when no matching fixture is found:

/**
 * Error thrown when request cannot be replayed
 * @throws {Error} When in replay mode and no fixture matches
 */
new Error(`Connection to ${url} refused: not recording and no network access`);

Usage Examples:

const Replay = require('replay');

try {
  Replay.mode = 'invalid-mode';
} catch (error) {
  console.log(error.message); // "Unsupported mode 'invalid-mode', must be one of bloody, cheat, record, replay."
}

// In replay mode with no matching fixture
Replay.mode = 'replay';
http.get('http://new-api.example.com/data', (response) => {
  // This will throw: Connection to http://new-api.example.com:80/data refused: not recording and no network access
});