Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
chore(docs): document HTTPRequest with TSDoc (#6146)
* chore(docs): document HTTPRequest with TSDoc

* doclint

* example
  • Loading branch information
jackfranklin committed Jul 3, 2020
1 parent 4ebf117 commit f7857d2
Show file tree
Hide file tree
Showing 35 changed files with 536 additions and 143 deletions.
11 changes: 11 additions & 0 deletions 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>;
```
22 changes: 22 additions & 0 deletions 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. |

11 changes: 11 additions & 0 deletions 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;
```
11 changes: 11 additions & 0 deletions 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;
```
13 changes: 13 additions & 0 deletions 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;
```
12 changes: 12 additions & 0 deletions 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';
```
25 changes: 0 additions & 25 deletions new-docs/puppeteer.httprequest._constructor_.md

This file was deleted.

11 changes: 0 additions & 11 deletions new-docs/puppeteer.httprequest._failuretext.md

This file was deleted.

11 changes: 0 additions & 11 deletions new-docs/puppeteer.httprequest._frommemorycache.md

This file was deleted.

11 changes: 0 additions & 11 deletions new-docs/puppeteer.httprequest._interceptionid.md

This file was deleted.

11 changes: 0 additions & 11 deletions new-docs/puppeteer.httprequest._redirectchain.md

This file was deleted.

11 changes: 0 additions & 11 deletions new-docs/puppeteer.httprequest._requestid.md

This file was deleted.

11 changes: 0 additions & 11 deletions new-docs/puppeteer.httprequest._response.md

This file was deleted.

8 changes: 7 additions & 1 deletion new-docs/puppeteer.httprequest.abort.md
Expand Up @@ -4,6 +4,8 @@

## HTTPRequest.abort() method

Aborts a request.

<b>Signature:</b>

```typescript
Expand All @@ -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 changes: 26 additions & 7 deletions new-docs/puppeteer.httprequest.continue.md
Expand Up @@ -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 changes: 17 additions & 1 deletion new-docs/puppeteer.httprequest.failure.md
Expand Up @@ -4,6 +4,8 @@

## HTTPRequest.failure() method

Access information about the request's failure.

<b>Signature:</b>

```typescript
Expand All @@ -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 changes: 2 additions & 0 deletions new-docs/puppeteer.httprequest.frame.md
Expand Up @@ -13,3 +13,5 @@ frame(): Frame | null;

[Frame](./puppeteer.frame.md) \| null

the frame that initiated the request.

2 changes: 2 additions & 0 deletions new-docs/puppeteer.httprequest.headers.md
Expand Up @@ -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 changes: 2 additions & 0 deletions new-docs/puppeteer.httprequest.isnavigationrequest.md
Expand Up @@ -13,3 +13,5 @@ isNavigationRequest(): boolean;

boolean

true if the request is the driver of the current frame's navigation.

41 changes: 23 additions & 18 deletions new-docs/puppeteer.httprequest.md
Expand Up @@ -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`<!-- -->:

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

## Properties
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.

| 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 | |
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 changes: 2 additions & 0 deletions new-docs/puppeteer.httprequest.method.md
Expand Up @@ -13,3 +13,5 @@ method(): string;

string

the method used (`GET`<!-- -->, `POST`<!-- -->, etc.)

2 changes: 2 additions & 0 deletions new-docs/puppeteer.httprequest.postdata.md
Expand Up @@ -13,3 +13,5 @@ postData(): string | undefined;

string \| undefined

the request's post body, if any.

0 comments on commit f7857d2

Please sign in to comment.