chore(docs): document HTTPRequest with TSDoc (#6146)

* chore(docs): document HTTPRequest with TSDoc

* doclint

* example

new-docs/puppeteer.continuerequestoverrides.headers.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [ContinueRequestOverrides](./puppeteer.continuerequestoverrides.md) &gt; [headers](./puppeteer.continuerequestoverrides.headers.md)
+
+## ContinueRequestOverrides.headers property
+
+<b>Signature:</b>
+
+```typescript
+headers?: Record<string, string>;
+```

new-docs/puppeteer.continuerequestoverrides.md

@@ -0,0 +1,22 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [ContinueRequestOverrides](./puppeteer.continuerequestoverrides.md)
+
+## ContinueRequestOverrides interface
+
+
+<b>Signature:</b>
+
+```typescript
+export interface ContinueRequestOverrides 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [headers](./puppeteer.continuerequestoverrides.headers.md) | Record&lt;string, string&gt; |  |
+|  [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. |
+

new-docs/puppeteer.continuerequestoverrides.method.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [ContinueRequestOverrides](./puppeteer.continuerequestoverrides.md) &gt; [method](./puppeteer.continuerequestoverrides.method.md)
+
+## ContinueRequestOverrides.method property
+
+<b>Signature:</b>
+
+```typescript
+method?: string;
+```

new-docs/puppeteer.continuerequestoverrides.postdata.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [ContinueRequestOverrides](./puppeteer.continuerequestoverrides.md) &gt; [postData](./puppeteer.continuerequestoverrides.postdata.md)
+
+## ContinueRequestOverrides.postData property
+
+<b>Signature:</b>
+
+```typescript
+postData?: string;
+```

new-docs/puppeteer.continuerequestoverrides.url.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [ContinueRequestOverrides](./puppeteer.continuerequestoverrides.md) &gt; [url](./puppeteer.continuerequestoverrides.url.md)
+
+## ContinueRequestOverrides.url property
+
+If set, the request URL will change. This is not a redirect.
+
+<b>Signature:</b>
+
+```typescript
+url?: string;
+```

new-docs/puppeteer.errorcode.md

@@ -0,0 +1,12 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [ErrorCode](./puppeteer.errorcode.md)
+
+## ErrorCode type
+
+
+<b>Signature:</b>
+
+```typescript
+export declare type ErrorCode = 'aborted' | 'accessdenied' | 'addressunreachable' | 'blockedbyclient' | 'blockedbyresponse' | 'connectionaborted' | 'connectionclosed' | 'connectionfailed' | 'connectionrefused' | 'connectionreset' | 'internetdisconnected' | 'namenotresolved' | 'timedout' | 'failed';
+```

new-docs/puppeteer.httprequest._constructor_.md

@@ -1,25 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [HTTPRequest](./puppeteer.httprequest.md) &gt; [(constructor)](./puppeteer.httprequest._constructor_.md)
-
-## HTTPRequest.(constructor)
-
-Constructs a new instance of the `HTTPRequest` class
-
-<b>Signature:</b>
-
-```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)<!-- -->\[\] |  |
-

new-docs/puppeteer.httprequest._failuretext.md

@@ -1,11 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [HTTPRequest](./puppeteer.httprequest.md) &gt; [\_failureText](./puppeteer.httprequest._failuretext.md)
-
-## HTTPRequest.\_failureText property
-
-<b>Signature:</b>
-
-```typescript
-_failureText: any;
-```

new-docs/puppeteer.httprequest._frommemorycache.md

@@ -1,11 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [HTTPRequest](./puppeteer.httprequest.md) &gt; [\_fromMemoryCache](./puppeteer.httprequest._frommemorycache.md)
-
-## HTTPRequest.\_fromMemoryCache property
-
-<b>Signature:</b>
-
-```typescript
-_fromMemoryCache: boolean;
-```

new-docs/puppeteer.httprequest._interceptionid.md

@@ -1,11 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [HTTPRequest](./puppeteer.httprequest.md) &gt; [\_interceptionId](./puppeteer.httprequest._interceptionid.md)
-
-## HTTPRequest.\_interceptionId property
-
-<b>Signature:</b>
-
-```typescript
-_interceptionId: string;
-```

new-docs/puppeteer.httprequest._redirectchain.md

@@ -1,11 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [HTTPRequest](./puppeteer.httprequest.md) &gt; [\_redirectChain](./puppeteer.httprequest._redirectchain.md)
-
-## HTTPRequest.\_redirectChain property
-
-<b>Signature:</b>
-
-```typescript
-_redirectChain: HTTPRequest[];
-```

new-docs/puppeteer.httprequest._requestid.md

@@ -1,11 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [HTTPRequest](./puppeteer.httprequest.md) &gt; [\_requestId](./puppeteer.httprequest._requestid.md)
-
-## HTTPRequest.\_requestId property
-
-<b>Signature:</b>
-
-```typescript
-_requestId: string;
-```

new-docs/puppeteer.httprequest._response.md

@@ -1,11 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [HTTPRequest](./puppeteer.httprequest.md) &gt; [\_response](./puppeteer.httprequest._response.md)
-
-## HTTPRequest.\_response property
-
-<b>Signature:</b>
-
-```typescript
-_response: HTTPResponse | null;
-```

new-docs/puppeteer.httprequest.abort.md

@@ -4,6 +4,8 @@
 
 ## HTTPRequest.abort() method
 
+Aborts a request.
+
 <b>Signature:</b>
 
 ```typescript
@@ -14,9 +16,13 @@ abort(errorCode?: ErrorCode): Promise<void>;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  errorCode | ErrorCode |  |
+|  errorCode | [ErrorCode](./puppeteer.errorcode.md) | optional error code to provide. |
 
 <b>Returns:</b>
 
 Promise&lt;void&gt;
 
+## 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.
+

new-docs/puppeteer.httprequest.continue.md

@@ -4,24 +4,43 @@
 
 ## HTTPRequest.continue() method
 
+Continues request with optional request overrides.
+
 <b>Signature:</b>
 
 ```typescript
-continue(overrides?: {
+continue(overrides?: ContinueRequestOverrides): Promise<void>;
-        url?: string;
-        method?: string;
-        postData?: string;
-        headers?: Record<string, string>;
-    }): Promise<void>;
 ```
 
 ## Parameters
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  overrides | { url?: string; method?: string; postData?: string; headers?: Record&lt;string, string&gt;; } |  |
+|  overrides | [ContinueRequestOverrides](./puppeteer.continuerequestoverrides.md) | optional overrides to apply to the request. |
 
 <b>Returns:</b>
 
 Promise&lt;void&gt;
 
+## 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});
+});
+
+```
+

new-docs/puppeteer.httprequest.failure.md

@@ -4,6 +4,8 @@
 
 ## HTTPRequest.failure() method
 
+Access information about the request's failure.
+
 <b>Signature:</b>
 
 ```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);
+});
+
+```
 

new-docs/puppeteer.httprequest.frame.md

@@ -13,3 +13,5 @@ frame(): Frame | null;
 
 [Frame](./puppeteer.frame.md) \| null
 
+the frame that initiated the request.
+

new-docs/puppeteer.httprequest.headers.md

@@ -13,3 +13,5 @@ headers(): Record<string, string>;
 
 Record&lt;string, string&gt;
 
+an object with HTTP headers associated with the request. All header names are lower-case.
+

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.
+

new-docs/puppeteer.httprequest.md

@@ -4,44 +4,49 @@
 
 ## HTTPRequest class
 
+Represents an HTTP request sent by a page.
+
 <b>Signature:</b>
 
 ```typescript
 export declare class HTTPRequest 
 ```
 
-## Constructors
+## Remarks
 
-|  Constructor | Modifiers | Description |
+Whenever the page sends a request, such as for a network resource, the following events are emitted by Puppeteer's `page`<!-- -->:
-|  --- | --- | --- |
-|  [(constructor)(client, frame, interceptionId, allowInterception, event, redirectChain)](./puppeteer.httprequest._constructor_.md) |  | Constructs a new instance of the <code>HTTPRequest</code> class |
 
-## 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 |
+If request fails at some point, then instead of `requestfinished` event the `requestfailed` event is emitted.
-|  --- | --- | --- | --- |
+
-|  [\_failureText](./puppeteer.httprequest._failuretext.md) |  | any |  |
+All of these events provide an instance of `HTTPRequest` representing the request that occurred:
-|  [\_fromMemoryCache](./puppeteer.httprequest._frommemorycache.md) |  | boolean |  |
+
-|  [\_interceptionId](./puppeteer.httprequest._interceptionid.md) |  | string |  |
+```
-|  [\_redirectChain](./puppeteer.httprequest._redirectchain.md) |  | [HTTPRequest](./puppeteer.httprequest.md)<!-- -->\[\] |  |
+page.on('request', request => ...)
-|  [\_requestId](./puppeteer.httprequest._requestid.md) |  | string |  |
+
-|  [\_response](./puppeteer.httprequest._response.md) |  | [HTTPResponse](./puppeteer.httpresponse.md) \| null |  |
+```
+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) |  |  |
+|  [abort(errorCode)](./puppeteer.httprequest.abort.md) |  | Aborts a request. |
-|  [continue(overrides)](./puppeteer.httprequest.continue.md) |  |  |
+|  [continue(overrides)](./puppeteer.httprequest.continue.md) |  | Continues request with optional request overrides. |
-|  [failure()](./puppeteer.httprequest.failure.md) |  |  |
+|  [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) |  |  |
+|  [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) |  |  |
+|  [respond(response)](./puppeteer.httprequest.respond.md) |  | Fulfills a request with the given response. |
 |  [response()](./puppeteer.httprequest.response.md) |  |  |
 |  [url()](./puppeteer.httprequest.url.md) |  |  |
 

new-docs/puppeteer.httprequest.method.md

@@ -13,3 +13,5 @@ method(): string;
 
 string
 
+the method used (`GET`<!-- -->, `POST`<!-- -->, etc.)
+

new-docs/puppeteer.httprequest.postdata.md

@@ -13,3 +13,5 @@ postData(): string | undefined;
 
 string \| undefined
 
+the request's post body, if any.
+

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
+
+```
+

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.
+
 <b>Signature:</b>
 
 ```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
+
+

new-docs/puppeteer.httprequest.respond.md

@@ -4,24 +4,44 @@
 
 ## HTTPRequest.respond() method
 
+Fulfills a request with the given response.
+
 <b>Signature:</b>
 
 ```typescript
-respond(response: {
+respond(response: ResponseForRequest): Promise<void>;
-        status: number;
-        headers: Record<string, string>;
-        contentType: string;
-        body: string | Buffer;
-    }): Promise<void>;
 ```
 
 ## Parameters
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  response | { status: number; headers: Record&lt;string, string&gt;; contentType: string; body: string \| Buffer; } |  |
+|  response | [ResponseForRequest](./puppeteer.responseforrequest.md) | the response to fulfill the request with. |
 
 <b>Returns:</b>
 
 Promise&lt;void&gt;
 
+## 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.
+

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.
+

new-docs/puppeteer.httprequest.url.md

@@ -13,3 +13,5 @@ url(): string;
 
 string
 
+the URL of the request
+

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) |  |

new-docs/puppeteer.responseforrequest.body.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [ResponseForRequest](./puppeteer.responseforrequest.md) &gt; [body](./puppeteer.responseforrequest.body.md)
+
+## ResponseForRequest.body property
+
+<b>Signature:</b>
+
+```typescript
+body: string | Buffer;
+```

new-docs/puppeteer.responseforrequest.contenttype.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [ResponseForRequest](./puppeteer.responseforrequest.md) &gt; [contentType](./puppeteer.responseforrequest.contenttype.md)
+
+## ResponseForRequest.contentType property
+
+<b>Signature:</b>
+
+```typescript
+contentType: string;
+```

new-docs/puppeteer.responseforrequest.headers.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [ResponseForRequest](./puppeteer.responseforrequest.md) &gt; [headers](./puppeteer.responseforrequest.headers.md)
+
+## ResponseForRequest.headers property
+
+<b>Signature:</b>
+
+```typescript
+headers: Record<string, string>;
+```

new-docs/puppeteer.responseforrequest.md

@@ -0,0 +1,23 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [ResponseForRequest](./puppeteer.responseforrequest.md)
+
+## ResponseForRequest interface
+
+Required response data to fulfill a request with.
+
+<b>Signature:</b>
+
+```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&lt;string, string&gt; |  |
+|  [status](./puppeteer.responseforrequest.status.md) | number |  |
+

new-docs/puppeteer.responseforrequest.status.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [ResponseForRequest](./puppeteer.responseforrequest.md) &gt; [status](./puppeteer.responseforrequest.status.md)
+
+## ResponseForRequest.status property
+
+<b>Signature:</b>
+
+```typescript
+status: number;
+```

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;
+ * @public
-  _interceptionId: string;
+ */
-  _failureText = null;
+export interface ContinueRequestOverrides {
-  _response: HTTPResponse | null = null;
+  /**
+   * If set, the request URL will change. This is not a redirect.
+   */
+  url?: string;
+  method?: string;
+  postData?: string;
+  headers?: Record<string, string>;
+}
 
+/**
+ * Required response data to fulfill a request with.
+ *
+ * @public
+ */
+export interface ResponseForRequest {
+  status: number;
+  headers: Record<string, string>;
+  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<string, string> = {};
   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<string, string> {
     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: {
+   * Continues request with optional request overrides.
-      url?: string;
+   *
-      method?: string;
+   * @remarks
-      postData?: string;
+   *
-      headers?: Record<string, string>;
+   * To use this, request
-    } = {}
+   * interception should be enabled with {@link Page.setRequestInterception}.
-  ): Promise<void> {
+   *
+   * 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<void> {
     // 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;
+   * Fulfills a request with the given response.
-    headers: Record<string, string>;
+   *
-    contentType: string;
+   * @remarks
-    body: string | Buffer;
+   *
-  }): Promise<void> {
+   * 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<void> {
     // 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<void> {
     // 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'

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);