playwright-network-cache

Speed up Playwright tests by caching network requests on the filesystem.

✨ Features

Automatically cache network requests during test execution
Save responses to the filesystem in a clear, organized structure
Modify cached responses dynamically during runtime
Reuse cached data across multiple test runs
Configure TTL to automatically refresh the cache and keep responses up-to-date
View response bodies in a pretty formatted JSON
No need for manual mocks management
No mess with the HAR format — see motivation

Example of cache structure:

.network-cache
└── example.com
    └── api-cats
        └── GET
            ├── headers.json
            └── body.json

Index

Click to expand

Index
Installation
Basic usage
Examples
API
Debug
Motivation
Alternatives
Changelog
Feedback
License

Installation

Install from npm:

npm i -D playwright-network-cache

Basic usage

1. Setup `cacheRoute` fixture

Extend Playwright's test instance with cacheRoute fixture:

// fixtures.ts
import { test as base } from '@playwright/test';
import { CacheRoute } from 'playwright-network-cache';

type Fixtures = {
  cacheRoute: CacheRoute;
};

export const test = base.extend<Fixtures>({
  cacheRoute: async ({ page }, use) => {
    const cacheRoute = new CacheRoute(page, { /* cache options */ });
    await use(cacheRoute);
  },
});

2. Use `cacheRoute` inside a test

For example, to cache a GET request to https://example.com/api/cats:

// test.ts
test('test', async ({ page, cacheRoute }) => {
  await cacheRoute.GET('https://example.com/api/cats*');
  // ... perform usual test actions
});

On the first run, the test will hit real API and store the response on the filesystem:

.network-cache
└── example.com
    └── api-cats
        └── GET
            ├── headers.json
            └── body.json

All subsequent test runs will re-use cached response and execute much faster. You can invalidate that cache by manually deleting the files. Or provide ttlMinutes option to hit real API once in some period of time.

To catch requests targeting your own app APIs, you can omit hostname in url:

test('test', async ({ page, cacheRoute }) => {
  await cacheRoute.GET('/api/cats*');
  // ...
});

Default cache path is:

{baseDir}/{hostname}/{pathname}/{httpMethod}/{extraDir}/{httpStatus}

See more examples below or check configuration options.

Examples

Invalidate cache

Click to expand

To keep response data up-to-date, you can automatically invalidate cache after configured time period. Set ttlMinutes option to desired value in minutes:

test('test', async ({ page, cacheRoute }) => {
  await cacheRoute.GET('/api/cats', {
    ttlMinutes: 60 // hit real API once in a hour
  });
  // ...
});

Currently, HTTP cache headers are not used by playwright-network-cache. See #4 for more details.

Modify cached response

Click to expand

You can modify the cached response by setting the modify option to a custom function. In this function, you retrieve the response data, make your changes, and then call route.fulfill with the updated data.

test('test', async ({ page, cacheRoute }) => {
  await cacheRoute.GET('/api/cats', {
    modify: async (route, response) => {
      const json = await response.json();
      json[0].name = 'Kitty-1';
      await route.fulfill({ json });
    }
  });
  // ...
});

For modifying JSON responses, there is a helper option modifyJSON:

test('test', async ({ page, cacheRoute }) => {
  await cacheRoute.GET('/api/cats', {
    modifyJSON: (json) => {
      json[0].name = 'Kitty';
    },
  });
  // ...
});

modifyJSON can modify response json in-place (like above) or return some result, which will overwrite the original data.

Disable cache

Click to expand

To disable cache in a single test, set cacheRoute.options.noCache to true:

test('test', async ({ page, cacheRoute }) => {
  cacheRoute.options.noCache = true;
  await cacheRoute.GET('/api/cats'); // <- this will not cache the request
  // ...
});

To disable cache in all tests, set the noCache option to true in the fixture:

export const test = base.extend<{ cacheRoute: CacheRoute }>({
  cacheRoute: async ({ page }, use, testInfo) => {
    await use(new CacheRoute(page, {
      noCache: true
    }));
  }
});

Note: When cache is disabled, modify functions still run

Force cache update

Click to expand

To force updating cache files for a single test, set cacheRoute.options.forceUpdate to true:

test('test', async ({ page, cacheRoute }) => {
  cacheRoute.options.forceUpdate = true;
  await cacheRoute.GET('/api/cats');
  // ...
});

To force updating cache files for all tests, set the forceUpdate option to true in the fixture:

export const test = base.extend<{ cacheRoute: CacheRoute }>({
  cacheRoute: async ({ page }, use, testInfo) => {
    await use(new CacheRoute(page, {
      forceUpdate: true
    }));
  }
});

Auto-cache request for all tests

Click to expand

You can setup caching of some request for all tests. Define cacheRoute as auto fixture and setup cached routes:

export const test = base.extend<{ cacheRoute: CacheRoute }>({
  cacheRoute: [async ({ page }, use) => {
    const cacheRoute = new CacheRoute(page);
    await cacheRoute.GET('/api/cats');
    await use(cacheRoute);
  }, { auto: true }]
});

Auto-cache static assets

Click to expand

You can cache static assets to run tests faster. Define cacheRoute as auto fixture and setup cache rules:

export const test = base.extend<{ cacheRoute: CacheRoute }>({
  cacheRoute: [async ({ page }, use) => {
    const cacheRoute = new CacheRoute(page);
    await cacheRoute.GET('**/*.png', { // <-- cache all *.png images
      ttlMinutes: 24 * 60
    });
    await use(cacheRoute);
  }, { auto: true }]
});

Additional match by HTTP status

Click to expand

By default, only responses with 2xx status are considered valid and stored in cache. To test error responses, provide additional httpStatus option to cache route:

test('test', async ({ page, cacheRoute }) => {
  await cacheRoute.GET('/api/cats', { 
    httpStatus: 500 
  });
  // ...
});

Now error response will be cached in the following structure:

.network-cache
└── example.com
    └── api-cats
        └── GET
            └── 500
                ├── headers.json
                └── body.json

Additional match by request fields

Click to expand

By default, requests are matched by:

HTTP method + URL pattern + (optionally) HTTP status

If you need to match by other request fields, provide custom function to match option. Example of matching GET requests with query param /api/cats?foo=bar:

test('test', async ({ page, cacheRoute }) => {
  await cacheRoute.GET('/api/cats*', { 
    match: req => new URL(req.url()).searchParams.get('foo') === 'bar'
  });
  // ...
});

Notice * in /api/cats* to match query params

Split cache by test title

Click to expand

By default, cached responses are stored in a shared directory and re-used across tests. If you want to isolate cache files for a particular test, utilize cacheRoute.options.extraDir - an array of extra directories to be inserted into the cache path:

test('test', async ({ page, cacheRoute }) => {
  cacheRoute.options.extraDir.push('custom-test');
  await cacheRoute.GET('/api/cats');
  // ...
});

Generated cache structure:

.network-cache
└── example.com
    └── api-cats
        └── GET
            └── custom-test       # <- extra directory
                ├── headers.json
                └── body.json

You can freely transform extraDir during the test and create nested directories if needed.

To automatically store cache files in a separate directories for each test, you can set extraDir option in a fixture setup:

export const test = base.extend<{ cacheRoute: CacheRoute }>({
  cacheRoute: async ({ page }, use, testInfo) => {
    await use(new CacheRoute(page, {
      extraDir: testInfo.title  // <- use testInfo.title as a unique extraDir
    }));
  }
});

After running two tests with titles custom test 1 and custom test 2, the generated structure is:

.network-cache
└── example.com
    └── api-cats
        └── GET
            ├── custom-test-1
            │   ├── headers.json
            │   └── body.json
            └── custom-test-2
                ├── headers.json
                └── body.json

Split cache by request URL params

Click to expand

To split cache by request query params, you can set extraDir to a function. It accepts request as a first argument and gives access to any prop of the request:

test('test', async ({ page, cacheRoute }) => {
  await cacheRoute.GET('/api/cats*', {
    extraDir: req => new URL(req.url()).searchParams.toString()
  });
  // ...
});

Notice * in /api/cats* to match query params

Given the following requests:

GET /api/cats?foo=1
GET /api/cats?foo=2

Cache structure will be:

.network-cache
└── example.com
    └── api-cats
        └── GET
            ├── foo=1
            │   ├── headers.json
            │   └── body.json
            └── foo=2
                ├── headers.json
                └── body.json

Split cache by request body

Click to expand

To split cache by request body, you can set extraDir to a function. It accepts request as a first argument and gives access to any prop of the request:

test('test', async ({ page, cacheRoute }) => {
  await cacheRoute.GET('/api/cats', {
    extraDir: req => req.postDataJSON().email
  });
  // ...
});

Having the following requests:

POST -d '{"email":"[email protected]"}' /api/cats
POST -d '{"email":"[email protected]"}' /api/cats

Cache structure will be:

.network-cache
└── example.com
    └── api-cats
        └── POST
            ├── [email protected]
            │   ├── headers.json
            │   └── body.json
            └── [email protected]
                ├── headers.json
                └── body.json

Change base dir

Click to expand

By default, cache files are stored in .network-cache base directory. To change this location, set baseDir option:

export const test = base.extend<{ cacheRoute: CacheRoute }>({
  cacheRoute: async ({ page }, use, testInfo) => {
    await use(new CacheRoute(page, {
      baseDir: `test/.network-cache`
    }));
  }
});

Moreover, you can set separate baseDir for each Playwright project or each test:

export const test = base.extend<{ cacheRoute: CacheRoute }>({
  cacheRoute: async ({ page }, use, testInfo) => {
    await use(new CacheRoute(page, {
      baseDir: `test/.network-cache/${testInfo.project.name}`
    }));
  }
});

Example of generated structure

.network-cache
├── project-one
│   └── example.com
│       └── api-cats
│           └── GET
│               ├── headers.json
│               └── body.json
└── project-two
    └── example.com
        └── api-cats
            └── GET
                ├── headers.json
                └── body.json

In that example, you get more isolation, but less cache re-use. It's a trade-off, as always 🤷‍♂️

Multi-step cache in complex scenarios

Click to expand

For complex scenarios, you may want to have different cached responses for the same API. Example: adding a new todo item into the todo list.

With caching in mind, the plan for such test can be the following:

Set cache for GET request to load original todo items
Open the todo items page
Set cache for POST request to create new todo item
Set cache for GET request to load updated todo items
Enter todo text and click "Add" button
Assert todo list is updated

The implementation utilizes extraDir option to dynamically change cache path in the test:

test('adding todo', async ({ page, cacheRoute }) => {
  // set cache for GET request to load todo items
  await cacheRoute.GET('/api/todo');

  // ...load page

  // CHECKPOINT: change cache dir, all subsequent requests will be cached in `after-add` dir
  cacheRoute.options.extraDir.push('after-add');

  // set cache for POST request to create a todo item
  await cacheRoute.POST('/api/todo');
  
  // ...add todo item
  // ...reload page
  // ...assert todo list is updated
});

Generated cache structure:

.network-cache
└── example.com
    └── api-todo
        ├── GET
        │   ├── headers.json
        │   ├── body.json
        │   └── after-add
        │       ├── headers.json
        │       └── body.json
        └── POST
            └── after-add
                ├── headers.json
                └── body.json

You may still modify cached responses to match test expectation. But it's better to make it as replacement modifications, not changing the structure of the response body. Keeping response structure unchanged is more "end-2-end" approach.

API

The CacheRoute class manages caching of routes for a Playwright Page or BrowserContext. It simplifies setting up HTTP method handlers for specific routes with caching options.

Constructor

const cacheRoute = new CacheRoute(page, options?)

page: The Playwright Page or BrowserContext to manage routes.
options: Optional configuration to control caching behavior.

Methods

These methods enable caching for specific HTTP routes:

cacheRoute.GET(url, optionsOrFn?)
cacheRoute.POST(url, optionsOrFn?)
cacheRoute.PUT(url, optionsOrFn?)
cacheRoute.PATCH(url, optionsOrFn?)
cacheRoute.DELETE(url, optionsOrFn?)
cacheRoute.HEAD(url, optionsOrFn?)
cacheRoute.ALL(url, optionsOrFn?)

Params

url: Url pattern
optionsOrFn: Caching options or a function to modify the response

Options

You can provide options to CacheRoute constructor or modify them dynamically via cacheRoute.options. All values are optional.

baseDir

string

Base directory for cache files.

extraDir

string | string[] | ((req: Request) => string | string[])

Additional directory for cache files. Can be a string, array of strings, or a function that accepts a request and returns a string or an array of strings.

match

(req: Request) => boolean

Function to add additional matching logic for requests. Returns true to cache, or false to skip.

httpStatus

number

Cache responses with the specified HTTP status code.

ttlMinutes

number

Time to live for cached responses, in minutes.

overrides

RequestOverrides | ((req: Request) => RequestOverrides)

Object or function that provides request overrides (e.g., headers, body) when making real calls.

modify

(route: Route, response: APIResponse) => Promise<unknown>

Function to modify the response before caching. This is called for each route.

modifyJSON

(json: any) => any

Helper function to modify JSON responses before caching.

noCache

boolean

If true, disables caching and always makes requests to the server.

forceUpdate

boolean

If true, always requests from the server and updates the cached files.

buildCacheDir

(ctx: BuildCacheDirArg) => string[]

Function to build a custom cache directory, providing fine-grained control over the cache file location. Default implementation.

Debug

To debug caching, run Playwright with the following DEBUG environment variable:

DEBUG=playwright-network-cache npx playwright test

Motivation

Playwright has built-in support for HAR format to record and replay network requests. But when you need more fine-grained control of network, it becomes messy. Check out these issues where people struggle with HAR:

This library intentionally does not use HAR. Instead, it generates file-based cache structure, giving you full control of what and how is cached.

Alternatives

Alternatively, you can check the following packages:

playwright-intercept - uses Cypress-influenced API
playwright-advanced-har - uses HAR format
playwright-request-mocker uses HAR format, looks abandoned

Changelog

See CHANGELOG.md.

Feedback

Feel free to share your feedback and suggestions in issues.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 143 Commits
.github/workflows		.github/workflows
example		example
scripts		scripts
src		src
test		test
.gitignore		.gitignore
.prettierignore		.prettierignore
.release-it.ts		.release-it.ts
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
eslint.config.mjs		eslint.config.mjs
lint-staged.config.mjs		lint-staged.config.mjs
package-lock.json		package-lock.json
package.json		package.json
playwright.config.ts		playwright.config.ts
prettier.config.mjs		prettier.config.mjs
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json

Uh oh!

License

vitalets/playwright-network-cache

Folders and files

Latest commit

History

Repository files navigation

playwright-network-cache

✨ Features

Index

Installation

Basic usage

1. Setup cacheRoute fixture

2. Use cacheRoute inside a test

Examples

Invalidate cache

Modify cached response

Disable cache

Force cache update

Auto-cache request for all tests

Auto-cache static assets

Additional match by HTTP status

Additional match by request fields

Split cache by test title

Split cache by request URL params

Split cache by request body

Change base dir

Multi-step cache in complex scenarios

API

Constructor

Methods

Params

Options

baseDir

extraDir

match

httpStatus

ttlMinutes

overrides

modify

modifyJSON

noCache

forceUpdate

buildCacheDir

Debug

Motivation

Alternatives

Changelog

Feedback

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Languages

1. Setup `cacheRoute` fixture

2. Use `cacheRoute` inside a test

Packages