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

> An HTTP interaction recording and playback library by Netflix for deterministic testing of API-dependent code in Node.js and browsers.

## Install

Save in your project root:

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

## Quick Use
```bash
npm install @pollyjs/core @pollyjs/adapter-fetch @pollyjs/persister-fs
```
```javascript
import { Polly } from "@pollyjs/core";
import FetchAdapter from "@pollyjs/adapter-fetch";
import FSPersister from "@pollyjs/persister-fs";

Polly.register(FetchAdapter);
Polly.register(FSPersister);

const polly = new Polly("my-recording", {
  adapters: ["fetch"],
  persister: "fs",
});

// First run records; subsequent runs replay
const response = await fetch("https://api.example.com/data");
await polly.stop();
```

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-2ef78570
Author: AI Open Source