github/puppeteer
0
0
Fork 0
mirror of https://github.com/puppeteer/puppeteer synced 2024-06-14 14:02:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
* chore(docs): document HTTPRequest with TSDoc

* doclint

* example
This commit is contained in:
Jack Franklin 2020-07-03 14:28:45 +01:00 committed by GitHub
parent 4ebf117116
commit f7857d27c4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
35 changed files with 540 additions and 147 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
new-docs/puppeteer.continuerequestoverrides.headers.md Normal file
View File

@ -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>;
```

22
new-docs/puppeteer.continuerequestoverrides.md Normal file
View File

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

11
new-docs/puppeteer.continuerequestoverrides.method.md Normal file
View File

@ -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;
```

11
new-docs/puppeteer.continuerequestoverrides.postdata.md Normal file
View File

@ -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;
```

13
new-docs/puppeteer.continuerequestoverrides.url.md Normal file
View File

@ -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;
```

12
new-docs/puppeteer.errorcode.md Normal file
View File

@ -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';
```

25
new-docs/puppeteer.httprequest._constructor_.md
View File

@ -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)<!-- -->\[\] | |

11
new-docs/puppeteer.httprequest._failuretext.md
View File

@ -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;
```

11
new-docs/puppeteer.httprequest._frommemorycache.md
View File

@ -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;
```

11
new-docs/puppeteer.httprequest._interceptionid.md
View File

@ -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;
```

11
new-docs/puppeteer.httprequest._redirectchain.md
View File

@ -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[];
```

11
new-docs/puppeteer.httprequest._requestid.md
View File

@ -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;
```

11
new-docs/puppeteer.httprequest._response.md
View File

@ -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;
```

8
new-docs/puppeteer.httprequest.abort.md
View File

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

33
new-docs/puppeteer.httprequest.continue.md
View File

@ -4,24 +4,43 @@
## HTTPRequest.continue() method
Continues request with optional request overrides.
<b>Signature:</b>
```typescript
continue(overrides?: {
url?: string;
method?: string;
postData?: string;
headers?: Record<string, string>;
}): Promise<void>;
continue(overrides?: ContinueRequestOverrides): 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});
});
```

18
new-docs/puppeteer.httprequest.failure.md
View File

@ -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);
});
```

2
new-docs/puppeteer.httprequest.frame.md
View File

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

2
new-docs/puppeteer.httprequest.headers.md
View File

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

2
new-docs/puppeteer.httprequest.isnavigationrequest.md
View File

@ -13,3 +13,5 @@ isNavigationRequest(): boolean;
boolean
true if the request is the driver of the current frame's navigation.

41
new-docs/puppeteer.httprequest.md
View File

@ -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 |
| --- | --- | --- |
| [(constructor)(client, frame, interceptionId, allowInterception, event, redirectChain)](./puppeteer.httprequest._constructor_.md) | | Constructs a new instance of the <code>HTTPRequest</code> 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) | | |

2
new-docs/puppeteer.httprequest.method.md
View File

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

2
new-docs/puppeteer.httprequest.postdata.md
View File

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

24
new-docs/puppeteer.httprequest.redirectchain.md
View File

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

7
new-docs/puppeteer.httprequest.resourcetype.md
View File

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

34
new-docs/puppeteer.httprequest.respond.md
View File

@ -4,24 +4,44 @@
## HTTPRequest.respond() method
Fulfills a request with the given response.
<b>Signature:</b>
```typescript
respond(response: {
status: number;
headers: Record<string, string>;
contentType: string;
body: string | Buffer;
}): Promise<void>;
respond(response: ResponseForRequest): 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.

2
new-docs/puppeteer.httprequest.response.md
View File

@ -13,3 +13,5 @@ response(): HTTPResponse | null;
[HTTPResponse](./puppeteer.httpresponse.md) \| null
the response for this request, if a response has been received.

2
new-docs/puppeteer.httprequest.url.md
View File

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

5
new-docs/puppeteer.md
View File

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

11
new-docs/puppeteer.responseforrequest.body.md Normal file
View File

@ -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;
```

11
new-docs/puppeteer.responseforrequest.contenttype.md Normal file
View File

@ -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;
```

11
new-docs/puppeteer.responseforrequest.headers.md Normal file
View File

@ -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>;
```

23
new-docs/puppeteer.responseforrequest.md Normal file
View File

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

11
new-docs/puppeteer.responseforrequest.status.md Normal file
View File

@ -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;
```

251
src/common/HTTPRequest.ts
View File

@ -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<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: {
url?: string;
method?: string;
postData?: string;
headers?: Record<string, string>;
} = {}
): Promise<void> {
/**
* 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<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;
headers: Record<string, string>;
contentType: string;
body: string | Buffer;
}): Promise<void> {
/**
* 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<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'

14
utils/doclint/check_public_api/index.js
View File

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