diff --git a/new-docs/puppeteer.continuerequestoverrides.headers.md b/new-docs/puppeteer.continuerequestoverrides.headers.md new file mode 100644 index 00000000..1d39d8ee --- /dev/null +++ b/new-docs/puppeteer.continuerequestoverrides.headers.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [ContinueRequestOverrides](./puppeteer.continuerequestoverrides.md) > [headers](./puppeteer.continuerequestoverrides.headers.md) + +## ContinueRequestOverrides.headers property + +Signature: + +```typescript +headers?: Record; +``` diff --git a/new-docs/puppeteer.continuerequestoverrides.md b/new-docs/puppeteer.continuerequestoverrides.md new file mode 100644 index 00000000..18c7868f --- /dev/null +++ b/new-docs/puppeteer.continuerequestoverrides.md @@ -0,0 +1,22 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [ContinueRequestOverrides](./puppeteer.continuerequestoverrides.md) + +## ContinueRequestOverrides interface + + +Signature: + +```typescript +export interface ContinueRequestOverrides +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [headers](./puppeteer.continuerequestoverrides.headers.md) | Record<string, string> | | +| [method](./puppeteer.continuerequestoverrides.method.md) | string | | +| [postData](./puppeteer.continuerequestoverrides.postdata.md) | string | | +| [url](./puppeteer.continuerequestoverrides.url.md) | string | If set, the request URL will change. This is not a redirect. | + diff --git a/new-docs/puppeteer.continuerequestoverrides.method.md b/new-docs/puppeteer.continuerequestoverrides.method.md new file mode 100644 index 00000000..f68211f2 --- /dev/null +++ b/new-docs/puppeteer.continuerequestoverrides.method.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [ContinueRequestOverrides](./puppeteer.continuerequestoverrides.md) > [method](./puppeteer.continuerequestoverrides.method.md) + +## ContinueRequestOverrides.method property + +Signature: + +```typescript +method?: string; +``` diff --git a/new-docs/puppeteer.continuerequestoverrides.postdata.md b/new-docs/puppeteer.continuerequestoverrides.postdata.md new file mode 100644 index 00000000..69703a47 --- /dev/null +++ b/new-docs/puppeteer.continuerequestoverrides.postdata.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [ContinueRequestOverrides](./puppeteer.continuerequestoverrides.md) > [postData](./puppeteer.continuerequestoverrides.postdata.md) + +## ContinueRequestOverrides.postData property + +Signature: + +```typescript +postData?: string; +``` diff --git a/new-docs/puppeteer.continuerequestoverrides.url.md b/new-docs/puppeteer.continuerequestoverrides.url.md new file mode 100644 index 00000000..3cd0108a --- /dev/null +++ b/new-docs/puppeteer.continuerequestoverrides.url.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [ContinueRequestOverrides](./puppeteer.continuerequestoverrides.md) > [url](./puppeteer.continuerequestoverrides.url.md) + +## ContinueRequestOverrides.url property + +If set, the request URL will change. This is not a redirect. + +Signature: + +```typescript +url?: string; +``` diff --git a/new-docs/puppeteer.errorcode.md b/new-docs/puppeteer.errorcode.md new file mode 100644 index 00000000..7c209f0a --- /dev/null +++ b/new-docs/puppeteer.errorcode.md @@ -0,0 +1,12 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [ErrorCode](./puppeteer.errorcode.md) + +## ErrorCode type + + +Signature: + +```typescript +export declare type ErrorCode = 'aborted' | 'accessdenied' | 'addressunreachable' | 'blockedbyclient' | 'blockedbyresponse' | 'connectionaborted' | 'connectionclosed' | 'connectionfailed' | 'connectionrefused' | 'connectionreset' | 'internetdisconnected' | 'namenotresolved' | 'timedout' | 'failed'; +``` diff --git a/new-docs/puppeteer.httprequest._constructor_.md b/new-docs/puppeteer.httprequest._constructor_.md deleted file mode 100644 index 32a4b6df..00000000 --- a/new-docs/puppeteer.httprequest._constructor_.md +++ /dev/null @@ -1,25 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [HTTPRequest](./puppeteer.httprequest.md) > [(constructor)](./puppeteer.httprequest._constructor_.md) - -## HTTPRequest.(constructor) - -Constructs a new instance of the `HTTPRequest` class - -Signature: - -```typescript -constructor(client: CDPSession, frame: Frame, interceptionId: string, allowInterception: boolean, event: Protocol.Network.requestWillBeSentPayload, redirectChain: HTTPRequest[]); -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| client | [CDPSession](./puppeteer.cdpsession.md) | | -| frame | [Frame](./puppeteer.frame.md) | | -| interceptionId | string | | -| allowInterception | boolean | | -| event | Protocol.Network.requestWillBeSentPayload | | -| redirectChain | [HTTPRequest](./puppeteer.httprequest.md)\[\] | | - diff --git a/new-docs/puppeteer.httprequest._failuretext.md b/new-docs/puppeteer.httprequest._failuretext.md deleted file mode 100644 index e8a5894a..00000000 --- a/new-docs/puppeteer.httprequest._failuretext.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [HTTPRequest](./puppeteer.httprequest.md) > [\_failureText](./puppeteer.httprequest._failuretext.md) - -## HTTPRequest.\_failureText property - -Signature: - -```typescript -_failureText: any; -``` diff --git a/new-docs/puppeteer.httprequest._frommemorycache.md b/new-docs/puppeteer.httprequest._frommemorycache.md deleted file mode 100644 index 1a42bbe3..00000000 --- a/new-docs/puppeteer.httprequest._frommemorycache.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [HTTPRequest](./puppeteer.httprequest.md) > [\_fromMemoryCache](./puppeteer.httprequest._frommemorycache.md) - -## HTTPRequest.\_fromMemoryCache property - -Signature: - -```typescript -_fromMemoryCache: boolean; -``` diff --git a/new-docs/puppeteer.httprequest._interceptionid.md b/new-docs/puppeteer.httprequest._interceptionid.md deleted file mode 100644 index 2e2353e6..00000000 --- a/new-docs/puppeteer.httprequest._interceptionid.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [HTTPRequest](./puppeteer.httprequest.md) > [\_interceptionId](./puppeteer.httprequest._interceptionid.md) - -## HTTPRequest.\_interceptionId property - -Signature: - -```typescript -_interceptionId: string; -``` diff --git a/new-docs/puppeteer.httprequest._redirectchain.md b/new-docs/puppeteer.httprequest._redirectchain.md deleted file mode 100644 index 33e89365..00000000 --- a/new-docs/puppeteer.httprequest._redirectchain.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [HTTPRequest](./puppeteer.httprequest.md) > [\_redirectChain](./puppeteer.httprequest._redirectchain.md) - -## HTTPRequest.\_redirectChain property - -Signature: - -```typescript -_redirectChain: HTTPRequest[]; -``` diff --git a/new-docs/puppeteer.httprequest._requestid.md b/new-docs/puppeteer.httprequest._requestid.md deleted file mode 100644 index 57ecf2df..00000000 --- a/new-docs/puppeteer.httprequest._requestid.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [HTTPRequest](./puppeteer.httprequest.md) > [\_requestId](./puppeteer.httprequest._requestid.md) - -## HTTPRequest.\_requestId property - -Signature: - -```typescript -_requestId: string; -``` diff --git a/new-docs/puppeteer.httprequest._response.md b/new-docs/puppeteer.httprequest._response.md deleted file mode 100644 index 9168ce0d..00000000 --- a/new-docs/puppeteer.httprequest._response.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [HTTPRequest](./puppeteer.httprequest.md) > [\_response](./puppeteer.httprequest._response.md) - -## HTTPRequest.\_response property - -Signature: - -```typescript -_response: HTTPResponse | null; -``` diff --git a/new-docs/puppeteer.httprequest.abort.md b/new-docs/puppeteer.httprequest.abort.md index 34b92e4a..726984e2 100644 --- a/new-docs/puppeteer.httprequest.abort.md +++ b/new-docs/puppeteer.httprequest.abort.md @@ -4,6 +4,8 @@ ## HTTPRequest.abort() method +Aborts a request. + Signature: ```typescript @@ -14,9 +16,13 @@ abort(errorCode?: ErrorCode): Promise; | Parameter | Type | Description | | --- | --- | --- | -| errorCode | ErrorCode | | +| errorCode | [ErrorCode](./puppeteer.errorcode.md) | optional error code to provide. | Returns: Promise<void> +## Remarks + +To use this, request interception should be enabled with [Page.setRequestInterception()](./puppeteer.page.setrequestinterception.md). If it is not enabled, this method will throw an exception immediately. + diff --git a/new-docs/puppeteer.httprequest.continue.md b/new-docs/puppeteer.httprequest.continue.md index ec976786..cca32746 100644 --- a/new-docs/puppeteer.httprequest.continue.md +++ b/new-docs/puppeteer.httprequest.continue.md @@ -4,24 +4,43 @@ ## HTTPRequest.continue() method +Continues request with optional request overrides. + Signature: ```typescript -continue(overrides?: { - url?: string; - method?: string; - postData?: string; - headers?: Record; - }): Promise; +continue(overrides?: ContinueRequestOverrides): Promise; ``` ## Parameters | Parameter | Type | Description | | --- | --- | --- | -| overrides | { url?: string; method?: string; postData?: string; headers?: Record<string, string>; } | | +| overrides | [ContinueRequestOverrides](./puppeteer.continuerequestoverrides.md) | optional overrides to apply to the request. | Returns: Promise<void> +## Remarks + +To use this, request interception should be enabled with [Page.setRequestInterception()](./puppeteer.page.setrequestinterception.md). + +Exception is immediately thrown if the request interception is not enabled. + +## Example + + +```js +await page.setRequestInterception(true); +page.on('request', request => { + // Override headers + const headers = Object.assign({}, request.headers(), { + foo: 'bar', // set "foo" header + origin: undefined, // remove "origin" header + }); + request.continue({headers}); +}); + +``` + diff --git a/new-docs/puppeteer.httprequest.failure.md b/new-docs/puppeteer.httprequest.failure.md index 3cbf6433..562fdd18 100644 --- a/new-docs/puppeteer.httprequest.failure.md +++ b/new-docs/puppeteer.httprequest.failure.md @@ -4,6 +4,8 @@ ## HTTPRequest.failure() method +Access information about the request's failure. + Signature: ```typescript @@ -15,5 +17,19 @@ failure(): { { errorText: string; } \| null -{?{errorText: string}} +`null` unless the request failed. If the request fails this can return an object with `errorText` containing a human-readable error message, e.g. `net::ERR_FAILED`. It is not guaranteeded that there will be failure text if the request fails. + +## Remarks + + +## Example + +Example of logging all failed requests: + +```js +page.on('requestfailed', request => { + console.log(request.url() + ' ' + request.failure().errorText); +}); + +``` diff --git a/new-docs/puppeteer.httprequest.frame.md b/new-docs/puppeteer.httprequest.frame.md index 86571dbb..618fd9df 100644 --- a/new-docs/puppeteer.httprequest.frame.md +++ b/new-docs/puppeteer.httprequest.frame.md @@ -13,3 +13,5 @@ frame(): Frame | null; [Frame](./puppeteer.frame.md) \| null +the frame that initiated the request. + diff --git a/new-docs/puppeteer.httprequest.headers.md b/new-docs/puppeteer.httprequest.headers.md index 037ed9bb..102ad662 100644 --- a/new-docs/puppeteer.httprequest.headers.md +++ b/new-docs/puppeteer.httprequest.headers.md @@ -13,3 +13,5 @@ headers(): Record; Record<string, string> +an object with HTTP headers associated with the request. All header names are lower-case. + diff --git a/new-docs/puppeteer.httprequest.isnavigationrequest.md b/new-docs/puppeteer.httprequest.isnavigationrequest.md index 7dd64b32..3cd15e00 100644 --- a/new-docs/puppeteer.httprequest.isnavigationrequest.md +++ b/new-docs/puppeteer.httprequest.isnavigationrequest.md @@ -13,3 +13,5 @@ isNavigationRequest(): boolean; boolean +true if the request is the driver of the current frame's navigation. + diff --git a/new-docs/puppeteer.httprequest.md b/new-docs/puppeteer.httprequest.md index 9a2df058..b6e5f580 100644 --- a/new-docs/puppeteer.httprequest.md +++ b/new-docs/puppeteer.httprequest.md @@ -4,44 +4,49 @@ ## HTTPRequest class +Represents an HTTP request sent by a page. + Signature: ```typescript export declare class HTTPRequest ``` -## Constructors +## Remarks -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(client, frame, interceptionId, allowInterception, event, redirectChain)](./puppeteer.httprequest._constructor_.md) | | Constructs a new instance of the HTTPRequest class | +Whenever the page sends a request, such as for a network resource, the following events are emitted by Puppeteer's `page`: -## Properties +- `request`: emitted when the request is issued by the page. - `requestfinished` - emitted when the response body is downloaded and the request is complete. -| Property | Modifiers | Type | Description | -| --- | --- | --- | --- | -| [\_failureText](./puppeteer.httprequest._failuretext.md) | | any | | -| [\_fromMemoryCache](./puppeteer.httprequest._frommemorycache.md) | | boolean | | -| [\_interceptionId](./puppeteer.httprequest._interceptionid.md) | | string | | -| [\_redirectChain](./puppeteer.httprequest._redirectchain.md) | | [HTTPRequest](./puppeteer.httprequest.md)\[\] | | -| [\_requestId](./puppeteer.httprequest._requestid.md) | | string | | -| [\_response](./puppeteer.httprequest._response.md) | | [HTTPResponse](./puppeteer.httpresponse.md) \| null | | +If request fails at some point, then instead of `requestfinished` event the `requestfailed` event is emitted. + +All of these events provide an instance of `HTTPRequest` representing the request that occurred: + +``` +page.on('request', request => ...) + +``` +NOTE: HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request will complete with `requestfinished` event. + +If request gets a 'redirect' response, the request is successfully finished with the `requestfinished` event, and a new request is issued to a redirected url. + +The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `HTTPRequest` class. ## Methods | Method | Modifiers | Description | | --- | --- | --- | -| [abort(errorCode)](./puppeteer.httprequest.abort.md) | | | -| [continue(overrides)](./puppeteer.httprequest.continue.md) | | | -| [failure()](./puppeteer.httprequest.failure.md) | | | +| [abort(errorCode)](./puppeteer.httprequest.abort.md) | | Aborts a request. | +| [continue(overrides)](./puppeteer.httprequest.continue.md) | | Continues request with optional request overrides. | +| [failure()](./puppeteer.httprequest.failure.md) | | Access information about the request's failure. | | [frame()](./puppeteer.httprequest.frame.md) | | | | [headers()](./puppeteer.httprequest.headers.md) | | | | [isNavigationRequest()](./puppeteer.httprequest.isnavigationrequest.md) | | | | [method()](./puppeteer.httprequest.method.md) | | | | [postData()](./puppeteer.httprequest.postdata.md) | | | | [redirectChain()](./puppeteer.httprequest.redirectchain.md) | | | -| [resourceType()](./puppeteer.httprequest.resourcetype.md) | | | -| [respond(response)](./puppeteer.httprequest.respond.md) | | | +| [resourceType()](./puppeteer.httprequest.resourcetype.md) | | Contains the request's resource type as it was perceived by the rendering engine. | +| [respond(response)](./puppeteer.httprequest.respond.md) | | Fulfills a request with the given response. | | [response()](./puppeteer.httprequest.response.md) | | | | [url()](./puppeteer.httprequest.url.md) | | | diff --git a/new-docs/puppeteer.httprequest.method.md b/new-docs/puppeteer.httprequest.method.md index 876f2e8f..7917c50c 100644 --- a/new-docs/puppeteer.httprequest.method.md +++ b/new-docs/puppeteer.httprequest.method.md @@ -13,3 +13,5 @@ method(): string; string +the method used (`GET`, `POST`, etc.) + diff --git a/new-docs/puppeteer.httprequest.postdata.md b/new-docs/puppeteer.httprequest.postdata.md index 565a8d65..5848596a 100644 --- a/new-docs/puppeteer.httprequest.postdata.md +++ b/new-docs/puppeteer.httprequest.postdata.md @@ -13,3 +13,5 @@ postData(): string | undefined; string \| undefined +the request's post body, if any. + diff --git a/new-docs/puppeteer.httprequest.redirectchain.md b/new-docs/puppeteer.httprequest.redirectchain.md index 9d222287..1d758c37 100644 --- a/new-docs/puppeteer.httprequest.redirectchain.md +++ b/new-docs/puppeteer.httprequest.redirectchain.md @@ -13,3 +13,27 @@ redirectChain(): HTTPRequest[]; [HTTPRequest](./puppeteer.httprequest.md)\[\] +the chain of requests - if a server responds with at least a single redirect, this chain will contain all requests that were redirected. + +## Remarks + +`redirectChain` is shared between all the requests of the same chain. + +For example, if the website `http://example.com` has a single redirect to `https://example.com`, then the chain will contain one request: + +```js +const response = await page.goto('http://example.com'); +const chain = response.request().redirectChain(); +console.log(chain.length); // 1 +console.log(chain[0].url()); // 'http://example.com' + +``` +If the website `https://google.com` has no redirects, then the chain will be empty: + +```js +const response = await page.goto('https://google.com'); +const chain = response.request().redirectChain(); +console.log(chain.length); // 0 + +``` + diff --git a/new-docs/puppeteer.httprequest.resourcetype.md b/new-docs/puppeteer.httprequest.resourcetype.md index a286c9be..867b6a6a 100644 --- a/new-docs/puppeteer.httprequest.resourcetype.md +++ b/new-docs/puppeteer.httprequest.resourcetype.md @@ -4,6 +4,8 @@ ## HTTPRequest.resourceType() method +Contains the request's resource type as it was perceived by the rendering engine. + Signature: ```typescript @@ -13,3 +15,8 @@ resourceType(): string; string +one of the following: `document`, `stylesheet`, `image`, `media`, `font`, `script`, `texttrack`, `xhr`, `fetch`, `eventsource`, `websocket`, `manifest`, `other`. + +## Remarks + + diff --git a/new-docs/puppeteer.httprequest.respond.md b/new-docs/puppeteer.httprequest.respond.md index 1bd69c6d..d96d866c 100644 --- a/new-docs/puppeteer.httprequest.respond.md +++ b/new-docs/puppeteer.httprequest.respond.md @@ -4,24 +4,44 @@ ## HTTPRequest.respond() method +Fulfills a request with the given response. + Signature: ```typescript -respond(response: { - status: number; - headers: Record; - contentType: string; - body: string | Buffer; - }): Promise; +respond(response: ResponseForRequest): Promise; ``` ## Parameters | Parameter | Type | Description | | --- | --- | --- | -| response | { status: number; headers: Record<string, string>; contentType: string; body: string \| Buffer; } | | +| response | [ResponseForRequest](./puppeteer.responseforrequest.md) | the response to fulfill the request with. | Returns: Promise<void> +## Remarks + +To use this, request interception should be enabled with [Page.setRequestInterception()](./puppeteer.page.setrequestinterception.md). + +Exception is immediately thrown if the request interception is not enabled. + +## Example + +An example of fulfilling all requests with 404 responses: + +```js +await page.setRequestInterception(true); +page.on('request', request => { + request.respond({ + status: 404, + contentType: 'text/plain', + body: 'Not Found!' + }); +}); + +``` +NOTE: Mocking responses for dataURL requests is not supported. Calling `request.respond` for a dataURL request is a noop. + diff --git a/new-docs/puppeteer.httprequest.response.md b/new-docs/puppeteer.httprequest.response.md index b6d69cd7..61665b5c 100644 --- a/new-docs/puppeteer.httprequest.response.md +++ b/new-docs/puppeteer.httprequest.response.md @@ -13,3 +13,5 @@ response(): HTTPResponse | null; [HTTPResponse](./puppeteer.httpresponse.md) \| null +the response for this request, if a response has been received. + diff --git a/new-docs/puppeteer.httprequest.url.md b/new-docs/puppeteer.httprequest.url.md index fe38e906..080c53db 100644 --- a/new-docs/puppeteer.httprequest.url.md +++ b/new-docs/puppeteer.httprequest.url.md @@ -13,3 +13,5 @@ url(): string; string +the URL of the request + diff --git a/new-docs/puppeteer.md b/new-docs/puppeteer.md index 0961f47d..ad1da812 100644 --- a/new-docs/puppeteer.md +++ b/new-docs/puppeteer.md @@ -22,7 +22,7 @@ | [ExecutionContext](./puppeteer.executioncontext.md) | This class represents a context for JavaScript execution. A \[Page\] might have many execution contexts: - each [frame](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) has "default" execution context that is always created after frame is attached to DOM. This context is returned by the method. - [Extension](https://developer.chrome.com/extensions)'s content scripts create additional execution contexts.Besides pages, execution contexts can be found in [workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). | | [FileChooser](./puppeteer.filechooser.md) | File choosers let you react to the page requesting for a file. | | [Frame](./puppeteer.frame.md) | | -| [HTTPRequest](./puppeteer.httprequest.md) | | +| [HTTPRequest](./puppeteer.httprequest.md) | Represents an HTTP request sent by a page. | | [HTTPResponse](./puppeteer.httpresponse.md) | The HTTPResponse class represents responses which are received by the [Page](./puppeteer.page.md) class. | | [JSHandle](./puppeteer.jshandle.md) | Represents an in-page JavaScript object. JSHandles can be created with the [page.evaluateHandle](./puppeteer.page.evaluatehandle.md) method. | | [Keyboard](./puppeteer.keyboard.md) | Keyboard provides an api for managing a virtual keyboard. The high level api is [Keyboard.type()](./puppeteer.keyboard.type.md), which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page. | @@ -54,6 +54,7 @@ | [ChromeArgOptions](./puppeteer.chromeargoptions.md) | Launcher options that only apply to Chrome. | | [ClickOptions](./puppeteer.clickoptions.md) | | | [ConsoleMessageLocation](./puppeteer.consolemessagelocation.md) | | +| [ContinueRequestOverrides](./puppeteer.continuerequestoverrides.md) | | | [CoverageEntry](./puppeteer.coverageentry.md) | The CoverageEntry class represents one entry of the coverage report. | | [Credentials](./puppeteer.credentials.md) | | | [CSSCoverageOptions](./puppeteer.csscoverageoptions.md) | Set of configurable options for CSS coverage. | @@ -66,6 +67,7 @@ | [PressOptions](./puppeteer.pressoptions.md) | | | [ProductLauncher](./puppeteer.productlauncher.md) | Describes a launcher - a class that is able to create and launch a browser instance. | | [RemoteAddress](./puppeteer.remoteaddress.md) | | +| [ResponseForRequest](./puppeteer.responseforrequest.md) | Required response data to fulfill a request with. | | [SerializedAXNode](./puppeteer.serializedaxnode.md) | Represents a Node and the properties of it that are relevant to Accessibility. | | [SnapshotOptions](./puppeteer.snapshotoptions.md) | | | [TracingOptions](./puppeteer.tracingoptions.md) | | @@ -88,6 +90,7 @@ | --- | --- | | [ConsoleMessageType](./puppeteer.consolemessagetype.md) | The supported types for console messages. | | [DevicesMap](./puppeteer.devicesmap.md) | | +| [ErrorCode](./puppeteer.errorcode.md) | | | [EvaluateFn](./puppeteer.evaluatefn.md) | | | [EvaluateFnReturnType](./puppeteer.evaluatefnreturntype.md) | | | [EvaluateHandleFn](./puppeteer.evaluatehandlefn.md) | | diff --git a/new-docs/puppeteer.responseforrequest.body.md b/new-docs/puppeteer.responseforrequest.body.md new file mode 100644 index 00000000..a7d2b789 --- /dev/null +++ b/new-docs/puppeteer.responseforrequest.body.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [ResponseForRequest](./puppeteer.responseforrequest.md) > [body](./puppeteer.responseforrequest.body.md) + +## ResponseForRequest.body property + +Signature: + +```typescript +body: string | Buffer; +``` diff --git a/new-docs/puppeteer.responseforrequest.contenttype.md b/new-docs/puppeteer.responseforrequest.contenttype.md new file mode 100644 index 00000000..bcf864d6 --- /dev/null +++ b/new-docs/puppeteer.responseforrequest.contenttype.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [ResponseForRequest](./puppeteer.responseforrequest.md) > [contentType](./puppeteer.responseforrequest.contenttype.md) + +## ResponseForRequest.contentType property + +Signature: + +```typescript +contentType: string; +``` diff --git a/new-docs/puppeteer.responseforrequest.headers.md b/new-docs/puppeteer.responseforrequest.headers.md new file mode 100644 index 00000000..b8fadb3d --- /dev/null +++ b/new-docs/puppeteer.responseforrequest.headers.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [ResponseForRequest](./puppeteer.responseforrequest.md) > [headers](./puppeteer.responseforrequest.headers.md) + +## ResponseForRequest.headers property + +Signature: + +```typescript +headers: Record; +``` diff --git a/new-docs/puppeteer.responseforrequest.md b/new-docs/puppeteer.responseforrequest.md new file mode 100644 index 00000000..dd628c9a --- /dev/null +++ b/new-docs/puppeteer.responseforrequest.md @@ -0,0 +1,23 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [ResponseForRequest](./puppeteer.responseforrequest.md) + +## ResponseForRequest interface + +Required response data to fulfill a request with. + +Signature: + +```typescript +export interface ResponseForRequest +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [body](./puppeteer.responseforrequest.body.md) | string \| Buffer | | +| [contentType](./puppeteer.responseforrequest.contenttype.md) | string | | +| [headers](./puppeteer.responseforrequest.headers.md) | Record<string, string> | | +| [status](./puppeteer.responseforrequest.status.md) | number | | + diff --git a/new-docs/puppeteer.responseforrequest.status.md b/new-docs/puppeteer.responseforrequest.status.md new file mode 100644 index 00000000..a8174c08 --- /dev/null +++ b/new-docs/puppeteer.responseforrequest.status.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [ResponseForRequest](./puppeteer.responseforrequest.md) > [status](./puppeteer.responseforrequest.status.md) + +## ResponseForRequest.status property + +Signature: + +```typescript +status: number; +``` diff --git a/src/common/HTTPRequest.ts b/src/common/HTTPRequest.ts index 04ff725f..d2a4548b 100644 --- a/src/common/HTTPRequest.ts +++ b/src/common/HTTPRequest.ts @@ -20,13 +20,87 @@ import { assert } from './assert'; import { helper, debugError } from './helper'; import Protocol from '../protocol'; -export class HTTPRequest { - _requestId: string; - _interceptionId: string; - _failureText = null; - _response: HTTPResponse | null = null; +/** + * @public + */ +export interface ContinueRequestOverrides { + /** + * If set, the request URL will change. This is not a redirect. + */ + url?: string; + method?: string; + postData?: string; + headers?: Record; +} +/** + * Required response data to fulfill a request with. + * + * @public + */ +export interface ResponseForRequest { + status: number; + headers: Record; + contentType: string; + body: string | Buffer; +} + +/** + * + * Represents an HTTP request sent by a page. + * @remarks + * + * Whenever the page sends a request, such as for a network resource, the + * following events are emitted by Puppeteer's `page`: + * + * - `request`: emitted when the request is issued by the page. + * - `requestfinished` - emitted when the response body is downloaded and the + * request is complete. + * + * If request fails at some point, then instead of `requestfinished` event the + * `requestfailed` event is emitted. + * + * All of these events provide an instance of `HTTPRequest` representing the + * request that occurred: + * + * ``` + * page.on('request', request => ...) + * ``` + * + * NOTE: HTTP Error responses, such as 404 or 503, are still successful + * responses from HTTP standpoint, so request will complete with + * `requestfinished` event. + * + * If request gets a 'redirect' response, the request is successfully finished + * with the `requestfinished` event, and a new request is issued to a + * redirected url. + * + * @public + */ +export class HTTPRequest { + /** + * @internal + */ + _requestId: string; + /** + * @internal + */ + _interceptionId: string; + /** + * @internal + */ + _failureText = null; + /** + * @internal + */ + _response: HTTPResponse | null = null; + /** + * @internal + */ _fromMemoryCache = false; + /** + * @internal + */ _redirectChain: HTTPRequest[]; private _client: CDPSession; @@ -41,6 +115,9 @@ export class HTTPRequest { private _headers: Record = {}; private _frame: Frame; + /** + * @internal + */ constructor( client: CDPSession, frame: Frame, @@ -66,44 +143,122 @@ export class HTTPRequest { this._headers[key.toLowerCase()] = event.request.headers[key]; } + /** + * @returns the URL of the request + */ url(): string { return this._url; } + /** + * Contains the request's resource type as it was perceived by the rendering + * engine. + * @remarks + * @returns one of the following: `document`, `stylesheet`, `image`, `media`, + * `font`, `script`, `texttrack`, `xhr`, `fetch`, `eventsource`, `websocket`, + * `manifest`, `other`. + */ resourceType(): string { + // TODO (@jackfranklin): protocol.d.ts has a type for this, but all the + // string values are uppercase. The Puppeteer docs explicitly say the + // potential values are all lower case, and the constructor takes the event + // type and calls toLowerCase() on it, so we can't reuse the type from the + // protocol.d.ts. Why do we lower case? return this._resourceType; } + /** + * @returns the method used (`GET`, `POST`, etc.) + */ method(): string { return this._method; } + /** + * @returns the request's post body, if any. + */ postData(): string | undefined { return this._postData; } + /** + * @returns an object with HTTP headers associated with the request. All + * header names are lower-case. + */ headers(): Record { return this._headers; } + /** + * @returns the response for this request, if a response has been received. + */ response(): HTTPResponse | null { return this._response; } + /** + * @returns the frame that initiated the request. + */ frame(): Frame | null { return this._frame; } + /** + * @returns true if the request is the driver of the current frame's navigation. + */ isNavigationRequest(): boolean { return this._isNavigationRequest; } + /** + * @remarks + * + * `redirectChain` is shared between all the requests of the same chain. + * + * For example, if the website `http://example.com` has a single redirect to + * `https://example.com`, then the chain will contain one request: + * + * ```js + * const response = await page.goto('http://example.com'); + * const chain = response.request().redirectChain(); + * console.log(chain.length); // 1 + * console.log(chain[0].url()); // 'http://example.com' + * ``` + * + * If the website `https://google.com` has no redirects, then the chain will be empty: + * + * ```js + * const response = await page.goto('https://google.com'); + * const chain = response.request().redirectChain(); + * console.log(chain.length); // 0 + * ``` + * + * @returns the chain of requests - if a server responds with at least a + * single redirect, this chain will contain all requests that were redirected. + */ redirectChain(): HTTPRequest[] { return this._redirectChain.slice(); } /** - * @returns {?{errorText: string}} + * Access information about the request's failure. + * + * @remarks + * + * @example + * + * Example of logging all failed requests: + * + * ```js + * page.on('requestfailed', request => { + * console.log(request.url() + ' ' + request.failure().errorText); + * }); + * ``` + * + * @returns `null` unless the request failed. If the request fails this can + * return an object with `errorText` containing a human-readable error + * message, e.g. `net::ERR_FAILED`. It is not guaranteeded that there will be + * failure text if the request fails. */ failure(): { errorText: string } | null { if (!this._failureText) return null; @@ -112,14 +267,32 @@ export class HTTPRequest { }; } - async continue( - overrides: { - url?: string; - method?: string; - postData?: string; - headers?: Record; - } = {} - ): Promise { + /** + * Continues request with optional request overrides. + * + * @remarks + * + * To use this, request + * interception should be enabled with {@link Page.setRequestInterception}. + * + * Exception is immediately thrown if the request interception is not enabled. + * + * @example + * ```js + * await page.setRequestInterception(true); + * page.on('request', request => { + * // Override headers + * const headers = Object.assign({}, request.headers(), { + * foo: 'bar', // set "foo" header + * origin: undefined, // remove "origin" header + * }); + * request.continue({headers}); + * }); + * ``` + * + * @param overrides - optional overrides to apply to the request. + */ + async continue(overrides: ContinueRequestOverrides = {}): Promise { // Request interception is not supported for data: urls. if (this._url.startsWith('data:')) return; assert(this._allowInterception, 'Request Interception is not enabled!'); @@ -142,12 +315,35 @@ export class HTTPRequest { }); } - async respond(response: { - status: number; - headers: Record; - contentType: string; - body: string | Buffer; - }): Promise { + /** + * Fulfills a request with the given response. + * + * @remarks + * + * To use this, request + * interception should be enabled with {@link Page.setRequestInterception}. + * + * Exception is immediately thrown if the request interception is not enabled. + * + * @example + * An example of fulfilling all requests with 404 responses: + * ```js + * await page.setRequestInterception(true); + * page.on('request', request => { + * request.respond({ + * status: 404, + * contentType: 'text/plain', + * body: 'Not Found!' + * }); + * }); + * ``` + * + * NOTE: Mocking responses for dataURL requests is not supported. + * Calling `request.respond` for a dataURL request is a noop. + * + * @param response - the response to fulfill the request with. + */ + async respond(response: ResponseForRequest): Promise { // Mocking responses for dataURL requests is not currently supported. if (this._url.startsWith('data:')) return; assert(this._allowInterception, 'Request Interception is not enabled!'); @@ -187,6 +383,16 @@ export class HTTPRequest { }); } + /** + * Aborts a request. + * + * @remarks + * To use this, request interception should be enabled with + * {@link Page.setRequestInterception}. If it is not enabled, this method will + * throw an exception immediately. + * + * @param errorCode - optional error code to provide. + */ async abort(errorCode: ErrorCode = 'failed'): Promise { // Request interception is not supported for data: urls. if (this._url.startsWith('data:')) return; @@ -209,7 +415,10 @@ export class HTTPRequest { } } -type ErrorCode = +/** + * @public + */ +export type ErrorCode = | 'aborted' | 'accessdenied' | 'addressunreachable' diff --git a/utils/doclint/check_public_api/index.js b/utils/doclint/check_public_api/index.js index d6d04a91..83dc1c5b 100644 --- a/utils/doclint/check_public_api/index.js +++ b/utils/doclint/check_public_api/index.js @@ -749,6 +749,20 @@ function compareDocumentations(actual, expected) { expectedName: 'MouseButton', }, ], + [ + 'Method HTTPRequest.continue() overrides', + { + actualName: 'Object', + expectedName: 'ContinueRequestOverrides', + }, + ], + [ + 'Method HTTPRequest.respond() response', + { + actualName: 'Object', + expectedName: 'ResponseForRequest', + }, + ], ]); const expectedForSource = expectedNamingMismatches.get(source);