Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
setupPolly
✓ import { setupPolly } from 'setup-polly-jest';
✗ const { setupPolly } = require('setup-polly-jest');
Primary function for configuring PollyJS within tests. Requires a modern Jest setup or transpilation for ESM syntax.
Jest Environment (Node)
✓ /** @jest-environment setup-polly-jest/jest-environment-node */
Special comment for per-file environment configuration when using jest-circus. Can also be set globally in jest.config.js.
Jest Environment (JSDOM)
✓ /** @jest-environment setup-polly-jest/jest-environment-jsdom */
Special comment for per-file environment configuration, particularly useful for browser-like environments with jest-circus. Can also be set globally.
Demonstrates setting up PollyJS in a Jest test using `setupPolly`, configuring basic interception, and verifying recorded or intercepted HTTP responses.
/** @jest-environment setup-polly-jest/jest-environment-node */
import { setupPolly } from 'setup-polly-jest';
describe('HTTP Recording with PollyJS', () => {
const context = setupPolly({
logLevel: 'info' // Example configuration option
});
beforeEach(() => {
// Intercept a specific request before the test runs
context.polly.server
.get('/api/data')
.intercept((req, res) => res.json({ message: 'Intercepted Data' }));
});
test('should be able to fetch data and use Polly', async () => {
context.polly.configure({ recordIfMissing: true });
// Simulate a network request (e.g., using node-fetch or similar)
// For a real test, you'd use your actual HTTP client (fetch, axios, etc.)
const response = await fetch('http://example.com/api/data');
const data = await response.json();
expect(response.status).toBe(200);
expect(data.message).toBe('Intercepted Data');
// The recording name is automatically generated based on suite/test names.
// Polly will stop and save the recording automatically after the test.
});
afterEach(() => {
// Optional: perform actions after Polly has done its cleanup
// For example, flushing pending requests if not handled by default stop()
context.polly.flush();
});
});
Debug
Known issues
breakingWhen upgrading Jest to version 27 or higher, which uses the `jest-circus` runner by default, you must explicitly configure a custom test environment provided by `setup-polly-jest` to ensure proper integration. Failing to do so will result in tests not correctly utilizing PollyJS.fixAdd `/** @jest-environment setup-polly-jest/jest-environment-node */` (or `jsdom`) at the top of relevant test files, or configure `testEnvironment: 'setup-polly-jest/jest-environment-jsdom'` in `jest.config.js` for global application.
affects: >=0.10.0 (with Jest >=27)
gotchaDirect access to `context.polly` outside of test hooks (`beforeEach`, `it`/`test`, `afterEach`) will result in an error because the Polly instance is managed by the helper's lifecycle and may not yet be initialized or might already be cleaned up.fixEnsure all interactions with `context.polly` or `context.polly.server` occur within `beforeEach`, `test`/`it`, or `afterEach` blocks.
affects: >=0.1.0
gotchaThe library's integration with Jasmine environments (used by Jest) relies on overwriting Jasmine methods. While thoroughly tested, significant changes in Jest's or Jasmine's internal test runner implementation could potentially break functionality without prior warning.fixRegularly check the project's GitHub issues and changelog when updating Jest or related testing frameworks. Report any unexpected behavior immediately.
affects: >=0.1.0
gotchaThis library has a peer dependency on `@pollyjs/core`. If `@pollyjs/core` is not installed or its version is incompatible, `setup-polly-jest` may not function correctly.fixEnsure `@pollyjs/core` is installed as a dev dependency (e.g., `npm install --save-dev @pollyjs/core`) and its version is compatible with `setup-polly-jest`.
affects: >=0.1.0
Errors
Common errors & fixes
You are trying to access an instance of Polly that is not yet available.
Attempting to access `context.polly` outside of a test hook (beforeEach, test, afterEach).
fixMove the code accessing `context.polly` into a `beforeEach`, `test`/`it`, or `afterEach` block to align with Polly's lifecycle.
ReferenceError: fetch is not defined
Running browser-dependent code (like `fetch` or DOM manipulation) in a Node.js test environment without a polyfill or appropriate test environment.
fixIf testing browser-side code, ensure you're using `jest-environment-jsdom` (or `setup-polly-jest/jest-environment-jsdom`) in your Jest config or test file. If using Node.js `fetch`, ensure a polyfill like `node-fetch` is imported and used.
Audit
Dependencies
@pollyjs/corerequiredCore PollyJS library, required for all functionality.