• Index
• Installation
• Basic usage
• 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
  • Options
• Debug
• Motivation
• Alternatives
• Changelog
• Feedback
• License

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 })=>{awaitcacheRoute.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.

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 })=>{awaitcacheRoute.GET('/api/cats',{modify: async(route,response)=>{constjson=awaitresponse.json();json[0].name='Kitty-1';awaitroute.fulfill({ json });}});// ...});

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

test('test',async({ page, cacheRoute })=>{awaitcacheRoute.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.

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

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

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

exportconsttest=base.extend<{cacheRoute: CacheRoute}>({cacheRoute: async({ page },use,testInfo)=>{awaituse(newCacheRoute(page,{noCache: true}));}});

Note: When cache is disabled, modify functions still run

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

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

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

exportconsttest=base.extend<{cacheRoute: CacheRoute}>({cacheRoute: async({ page },use,testInfo)=>{awaituse(newCacheRoute(page,{forceUpdate: true}));}});

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

exportconsttest=base.extend<{cacheRoute: CacheRoute}>({cacheRoute: [async({ page },use)=>{constcacheRoute=newCacheRoute(page);awaitcacheRoute.GET('/api/cats');awaituse(cacheRoute);},{auto: true}]});

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

exportconsttest=base.extend<{cacheRoute: CacheRoute}>({cacheRoute: [async({ page },use)=>{constcacheRoute=newCacheRoute(page);awaitcacheRoute.GET('**/*.png',{// <-- cache all *.png imagesttlMinutes: 24*60});awaituse(cacheRoute);},{auto: true}]});

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 })=>{awaitcacheRoute.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 

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 })=>{awaitcacheRoute.GET('/api/cats*',{match: req=>newURL(req.url()).searchParams.get('foo')==='bar'});// ...});

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

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');awaitcacheRoute.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:

exportconsttest=base.extend<{cacheRoute: CacheRoute}>({cacheRoute: async({ page },use,testInfo)=>{awaituse(newCacheRoute(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 

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 })=>{awaitcacheRoute.GET('/api/cats*',{extraDir: req=>newURL(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 

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 })=>{awaitcacheRoute.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 

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

exportconsttest=base.extend<{cacheRoute: CacheRoute}>({cacheRoute: async({ page },use,testInfo)=>{awaituse(newCacheRoute(page,{baseDir: `test/.network-cache`}));}});

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

exportconsttest=base.extend<{cacheRoute: CacheRoute}>({cacheRoute: async({ page },use,testInfo)=>{awaituse(newCacheRoute(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 🤷‍♂️

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:

1. Set cache for GET request to load original todo items
2. Open the todo items page
3. Set cache for POST request to create new todo item
4. Set cache for GET request to load updated todo items
5. Enter todo text and click "Add" button
6. 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 itemsawaitcacheRoute.GET('/api/todo');// ...load page// CHECKPOINT: change cache dir, all subsequent requests will be cached in `after-add` dircacheRoute.options.extraDir.push('after-add');// set cache for POST request to create a todo itemawaitcacheRoute.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.