Registry / testing / playwright-network-cache

playwright-network-cache

library0.3.0jsnpmunverified

A Playwright test utility for caching network requests on the filesystem to speed up E2E tests. Version 0.3.0 is the latest stable release, with a focus on simplicity and transparency (cached responses stored as clear JSON files, not HAR). It supports automatic caching, TTL-based refresh, runtime response modification, and flexible path splitting. Unlike manual mocking or HAR-based tools, it requires no setup beyond a fixture and works transparently with real API calls. Release cadence is irregular; maintained by vitalets. Ships TypeScript types.

testing

npm install playwright-network-cache

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PLAYWRIGHT-NETWORK

playwright-network-cache

testingjavascriptv0.3.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CacheRoute

✓ import { CacheRoute } from 'playwright-network-cache'

✗ const CacheRoute = require('playwright-network-cache')

ESM-only package (type: module). CommonJS require() will fail.

CacheRouteOptions

✓ import type { CacheRouteOptions } from 'playwright-network-cache'

✗ type CacheRouteOptions = import('playwright-network-cache').CacheRouteOptions

Type import for TypeScript users. You can also inline the options interface.

default import

✓ import CacheRoute from 'playwright-network-cache'

✗ import cacheRoute from 'playwright-network-cache'

Package exports a default class CacheRoute. Named export `CacheRoute` is also available as a workaround.

Demonstrates setting up a CacheRoute fixture with TTL and using GET to cache an API call.

import { test as base, expect } from '@playwright/test'; import CacheRoute from 'playwright-network-cache'; const test = base.extend({ cacheRoute: async ({ page }, use) => { const cacheRoute = new CacheRoute(page, { ttlMinutes: 10 }); await use(cacheRoute); }, }); test('api caching', async ({ page, cacheRoute }) => { await cacheRoute.GET('https://api.example.com/users*'); await page.goto('https://example.com/users'); await expect(page.locator('text=User list')).toBeVisible(); });

Debug

Known issues

breakingPlaywright version 1.20+ required for route interception (page.route)

fix

Update Playwright to >=1.20 or use a compatible version of the library.

affects: <0.1.0

deprecatedThe `CacheRoute` constructor options `baseDirectory` is deprecated in favor of `baseDir`

fix

Use `baseDir` instead of `baseDirectory` in options.

affects: <0.3.0

gotchaCache files are not automatically cleaned; they persist across test runs. You must manually delete the .network-cache directory or rely on TTL

fix

Add a cleanup step in your test setup or CI, or set `ttlMinutes` to force refresh periodically.

affects: >=0.0.0

gotchaOnly HTTP methods GET, POST, PUT, PATCH, DELETE are supported by shorthand methods. For other methods, use `cacheRoute.route(method, url, options)`

fix

For HEAD, OPTIONS, etc., use the generic `route` method.

affects: >=0.0.0

gotchaThe cache is based on the full request URL (including query params). If query params vary unpredictably, cache hit ratio drops; use `splitByUrlParams` or `matchRequest` to normalize

fix

Use the `splitByUrlParams` option to group similar URLs, or implement custom `matchRequest` logic.

affects: >=0.0.0

gotchaThe package is ESM-only (type: module). If your project uses CommonJS, you must use dynamic import() or set type: module

fix

Set `"type": "module"` in package.json, or use `import('playwright-network-cache').then(mod => ...)`

affects: >=0.2.0

Errors

Common errors & fixes

TypeError: Class constructor CacheRoute cannot be invoked without 'new'

Using `CacheRoute(page, opts)` without `new` (valid JS, but TS strict mode may warn)

fix

Use `new CacheRoute(page, opts)` consistently.

Cannot find module 'playwright-network-cache'

Package not installed, or import path typo

fix

Run `npm i -D playwright-network-cache` and verify package.json has it as devDependency.

Error: page.route: Route is already handled

Calling cacheRoute.GET/POST/etc. twice on the same URL pattern without calling `page.unroute` first

fix

Ensure each pattern is only cached once per test, or use `cacheRoute.ALL` with `matchRequest` to handle multiple patterns.

TypeError: cacheRoute.GET is not a function

Importing wrong symbol or using default import incorrectly in TypeScript

fix

Use `import CacheRoute from 'playwright-network-cache'` and instantiate with `new`.

Upgrade

Version history

0.3.0latest on npm

Audit

Dependencies

playwrightrequiredPeer dependency — requires Playwright test runner for fixture integration

Agent activity

2 hits · last 30 days

node

Resources

githubgit://github.com/vitalets/playwright-network-cache ↗

packageplaywright-network-cache ↗

homepagehttps://github.com/vitalets/playwright-network-cache#readme ↗