puppeteer-request-spy

With puppeteer-request-spy you can easily watch, fake or block requests from puppeteer matching patterns.

• allows you to write tests verifying specific resources getting requested as expected
• allows you to exclude unneeded requests from tests, speeding them up significantly
• allows you to alter a request's response with custom content and http status
• avoids conflicts resulting from already aborted / continued or responded requests

Install

npm install puppeteer-request-spy

Usage

Spying on requests with a KeywordMatcher

First create a new RequestInterceptor with a matcher function and an optional logger.

function KeywordMatcher(testee, keyword) {
    return testee.indexOf(keyword) > -1; 
}

let requestInterceptor = new RequestInterceptor(KeywordMatcher, console);

Next create a new RequestSpy with a pattern to be matched against all requests.

let imageSpy = new RequestSpy('/pictures');

The RequestSpy needs to be registered with the RequestInterceptor.

requestInterceptor.addSpy(imageSpy);

The RequestInterceptor must be registered with puppeteer.

page.on('request', requestInterceptor.intercept.bind(requestInterceptor));

After puppeteer's page object finished navigating to any page, you can query the RequestSpy.

await page.goto('https://www.example.com');
assert.ok(imageSpy.hasMatch() && imageSpy.getMatchCount() > 0);

Altering Responses

Note

When blocking or faking responses of requests, puppeteer's requestInterception flag must be set to true or puppeteer will throw an exception. For further information check the official puppeteer API. Since unhandled Promise rejections causes the node process to keep running after test failure, the RequestInterceptor will catch and log puppeteer's exception, if the requestInterception flag is not set.

Faking Responses

The response of intercepted requests can be replaced by adding a ResponseFaker to the RequestInterceptor. The fake response has to match the Response object as specified in the official puppeteer API.

let responseFaker = new ResponseFaker('/ajax/some-request', {
    status: 200,
    contentType: 'application/json',
    body: JSON.stringify({successful: false, payload: []})
});

requestInterceptor.addFaker(responseFaker);

For further details on how to replace different formats of data like images, text or html, please refer to the examples provided in the github repository.

Blocking requests

Optionally you can add patterns to block requests. Blocking requests speeds up page load since no data is loaded. Blocking requests takes precedence over faking responses, so any request blocked will not be replaced even when matching a ResponseFaker. Blocked or faked requests will still be counted by a RequestSpy with a matching pattern.

requestInterceptor.block(['scripts', 'track', '.png']);      
await page.setRequestInterception(true);

Minimatch

puppeteer-request-spy works great with minimatch, it can be passed as the matcher function.

const minimatch = require('minimatch');

let pngSpy = new RequestSpy('**/*.png');
let responseFaker = new ResponseFaker('**/*.jpg', someFakeResponse);
                                                        
let requestInterceptor = new RequestInterceptor(minimatch);  
responseFaker.addFaker(mock);
requestInterceptor.addSpy(pngSpy);   
requestInterceptor.block('!https://www.example.com');

await page.setRequestInterception(true);
page.on('request', requestInterceptor.intercept.bind(requestInterceptor));  
await page.goto('https://www.example.com');

assert.ok(pngSpy.hasMatch() && pngSpy.getMatchCount() > 0);

API

class: RequestInterceptor

The RequestInterceptor will match any intercepted request against the matcher function and notify all spies with a matching pattern and block requests matching any pattern in urlsToBlock.

RequestInterceptor constructor(matcher, logger?)

• matcher: <(url: string, pattern: string) => boolean>>
• logger?: <{log: (text: string) => void}>

The matcher will be called for every url, testing the url against patterns of any RequestSpy provided and also any url added to urlsToBlock.

The logger if provided will output any requested url with a 'loaded' or 'aborted' prefix and any exception caused by puppeteer's abort and continue functions.

RequestInterceptor.intercept(interceptedUrl)

• interceptedUrl: interceptedUrl provided by puppeteer's 'request' event

Function to be registered with puppeteer's request event.

RequestInterceptor.addSpy(requestSpy)

• requestSpy: <RequestSpy> spy to register

Register a spy with the RequestInterceptor.

RequestInterceptor.clearSpies()

Clears all registered spies.

RequestInterceptor.addFaker(requestFaker)

• responseFaker: <ResponseFaker> faker to register

RequestInterceptor.clearFakers()

Clears all registered fakers.

RequestInterceptor.block(urlsToBlock)

• urlsToBlock: <Array<string> | <string>> urls to be blocked if matched

block will always add urls to the list urlsToBlock. Passed arrays will be merged with urlsToBlock.

RequestInterceptor.setUrlsToBlock(urlsToBlock)

• urlsToBlock: <Array<string>> setter for urlsToBlock

RequestInterceptor.clearUrlsToBlock()

Clears all registered patterns in urlsToBlock.

class: RequestSpy

RequestSpy is used to count and verify intercepted requests matching a specific pattern.

RequestSpy constructor(pattern)

• pattern: <string|Array<string>>

pattern passed to the matcher function of the RequestInterceptor.

RequestSpy.hasMatch()

• returns: <boolean> returns whether any url matched the pattern

RequestSpy.getMatchedUrls()

• returns: <Array<string>> returns a list of urls that matched the pattern

RequestSpy.getMatchCount()

• returns: <number> number of urls that matched the pattern

RequestSpy.getPatterns()

• returns: <Array<string>> return the pattern list of the spy

RequestSpy.addMatchedUrl(matchedUrl)

• matchedUrl: <string> url that was matched

The RequestInterceptor calls this method when an interceptedUrl matches the pattern.

class: RequestFaker

RequestFaker is used to provide a fake response when matched to a specific pattern.

RequestSpy constructor(pattern, responseFake)

• pattern: <string|Array>
• responseFake: <Response> for details refer to puppeteer API

RequestFaker.getPatterns()

• returns: <Array<string>> return the pattern list of the faker

RequestFaker.getResponseFake()

• returns: <Response>\ return the fake response

The RequestInterceptor calls this method when an interceptedUrl matches the pattern.

Examples

There are some simple usage examples included in the github repository. Check them out to get started with writing a simple test with puppeteer and puppeteer-request-spy.

Related

• minimatch - For easily matching path-like strings to patterns.
• puppeteer - Control chrome in headless mode with puppeteer for automated testing.

License

MIT