explaingit

netflix/pollyjs

10,248JavaScriptAudience · developerComplexity · 2/5LicenseSetup · moderate

TLDR

Polly.JS is a JavaScript test utility by Netflix that records real HTTP requests the first time your tests run and replays the saved responses on every subsequent run, making tests faster and server-independent.

Mindmap

mindmap
  root((repo))
    What it does
      Record HTTP requests
      Replay recordings
      Request interception
      Passthrough mode
    Tech Stack
      JavaScript TypeScript
      Node.js and browser
      Pluggable adapters
    Use Cases
      Test speed up
      Error simulation
      CI reliability
    Audience
      Frontend developers
      Backend testers
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Speed up a slow test suite by recording HTTP responses once and replaying them without hitting real servers on future runs

USE CASE 2

Simulate API error states by intercepting requests and returning custom status codes without configuring a real server

USE CASE 3

Write reliable frontend or Node.js tests that pass even when external APIs are down or return different data

USE CASE 4

Capture and replay both fetch and XHR browser requests in automated tests without writing manual mocks

Tech stack

JavaScriptTypeScriptNode.js

Getting it running

Difficulty · moderate Time to first run · 30min

Storage persisters and request adapters are separate npm packages, you must install the right combination for your test environment and storage backend.

Free to use, modify, and distribute for any purpose including commercial, as long as you include the Apache 2.0 license notice.

In plain English

Polly.JS is a JavaScript testing tool built by Netflix that helps developers write faster and more reliable automated tests. The core problem it solves is that tests which make real network requests to servers are slow, unpredictable, and can fail for reasons unrelated to the code being tested. Polly.JS addresses this by recording those HTTP requests and their responses the first time a test runs, then replaying the saved recordings on every subsequent run. The workflow goes like this: you run your tests once while connected to real servers, and Polly.JS captures each request and response and saves them to disk or local storage. On future runs, the tests use those saved recordings instead of hitting the network. This makes the test suite run faster and produce consistent results regardless of whether the server is available or what data it currently holds. Beyond recording and replaying, the library lets you intercept individual requests and return whatever response you define, which is useful for simulating error states or loading conditions without needing to configure a real server to behave that way. You can also mark specific requests as pass-through, meaning they still hit the real network even when recording mode is off. Polly.JS works in both Node.js and the browser, which is less common among tools of this kind. It connects to the browser fetch and XHR request mechanisms, so it captures the full range of requests your app makes. Adapters for different request libraries and persisters for different storage backends are installed separately as packages, letting you use only what your project needs. The library works with any test framework and includes built-in helpers for Mocha and QUnit. The project is open source under the Apache 2.0 license and was created at Netflix. The README notes the project is in maintenance mode, with development focused on bug fixes rather than new features.

Copy-paste prompts

Prompt 1
I'm writing Jest tests for a React app that calls an external API. Show me how to set up Polly.JS to record the API responses to disk and replay them on subsequent runs.
Prompt 2
How do I use Polly.JS to make a specific API endpoint return a 503 error in my tests so I can verify my error handling code?
Prompt 3
Set up a Polly.JS configuration where requests to the auth service pass through to the real server but all other API calls use saved recordings.
Prompt 4
My Polly.JS recordings are stale because the API response format changed. How do I clear the old recordings so they get re-recorded on the next test run?
Open on GitHub → Explain another repo

← netflix on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.