Polly.js — Record, Replay, and Stub HTTP Interactions by Netflix

Introduction

Polly.js by Netflix records HTTP interactions during test runs and replays them on subsequent executions. This eliminates flaky tests caused by network variability while keeping tests realistic by using actual API responses as fixtures.

What Polly.js Does

• Records HTTP requests and responses to persistent storage (filesystem, REST API, or localStorage)
• Replays recorded interactions on subsequent test runs for deterministic results
• Intercepts and stubs requests that match configurable rules
• Supports request matching by URL, method, headers, and body
• Provides timing simulation to mirror real-world latency

Architecture Overview

Polly.js uses an adapter layer to intercept HTTP calls (fetch, XHR, or Node.js http) and a persister layer to store recordings as HAR-like JSON files. On replay, incoming requests are matched against recordings using a configurable matching strategy. Unmatched requests can passthrough, record, or throw depending on the mode.

Self-Hosting & Configuration

• Install the core package plus your chosen adapter and persister
• Register adapters and persisters before creating a Polly instance
• Set recordIfMissing to control behavior for unrecorded requests
• Configure request matching strictness via matchRequestsBy options
• Use expiresIn to auto-expire recordings and force re-recording

Key Features

• Three modes: record, replay, and passthrough for flexible test workflows
• HAR-compatible recording format for interoperability
• Request interception with custom response handlers
• Timing simulation preserving original response latency
• Built-in adapters for fetch, XHR, and Node.js http

Comparison with Similar Tools

• MSW (Mock Service Worker) — Mocks at the service worker level; Polly.js records real interactions
• Nock — Node.js-only HTTP mocking; Polly.js works in both Node.js and browsers
• VCR (Ruby) — Ruby HTTP recording; Polly.js brings the same pattern to JavaScript
• WireMock — Java-based mock server; Polly.js runs in-process without a separate server
• Mirage.js — Client-side mock server; Polly.js focuses on recording real responses

FAQ

Q: Can I use Polly.js with Jest? A: Yes. Use the @pollyjs/core setup/teardown in beforeEach/afterEach hooks.

Q: How do I handle sensitive data in recordings? A: Use the recordFailedRequests option and custom serializers to redact headers or body fields.

Q: Does it support GraphQL? A: Yes. Configure matchRequestsBy to include the request body so different queries are recorded separately.

Q: Can recordings be shared across CI environments? A: Yes. Commit recordings to your repository or use the REST persister to store them centrally.

Sources

• https://github.com/Netflix/pollyjs
• https://netflix.github.io/pollyjs/