Skip to content

Commit

Permalink
docs(api.md): prefer async/await over Promise#then (#5089)
Browse files Browse the repository at this point in the history 
Fixes #5082.
  • Loading branch information
@randombenj @mathiasbynens
randombenj authored and mathiasbynens committed Oct 26, 2019
1 parent aaa904d commit 561c99d
Showing 1 changed file with 73 additions and 49 deletions.
122 changes: 73 additions & 49 deletions docs/api.md
View file
Expand Up @@ -428,12 +428,13 @@ The following is a typical example of using Puppeteer to drive automation:
```js
const puppeteer = require('puppeteer');

puppeteer.launch().then(async browser => {
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://www.google.com');
// other actions...
await browser.close();
});
})();
```

#### puppeteer.connect(options)
Expand Down Expand Up @@ -481,13 +482,14 @@ devices can be found in [lib/DeviceDescriptors.js](https://github.com/GoogleChro
const puppeteer = require('puppeteer');
const iPhone = puppeteer.devices['iPhone 6'];

puppeteer.launch().then(async browser => {
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.emulate(iPhone);
await page.goto('https://www.google.com');
// other actions...
await browser.close();
});
})();
```

> **NOTE** The old way (Puppeteer versions <= v1.14.0) devices can be obtained with `require('puppeteer/DeviceDescriptors')`.
Expand Down Expand Up @@ -630,18 +632,20 @@ An example of using a [Browser] to create a [Page]:
```js
const puppeteer = require('puppeteer');

puppeteer.launch().then(async browser => {
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
await browser.close();
});
})();
```

An example of disconnecting from and reconnecting to a [Browser]:
```js
const puppeteer = require('puppeteer');

puppeteer.launch().then(async browser => {
(async () => {
const browser = await puppeteer.launch();
// Store the endpoint to be able to reconnect to Chromium
const browserWSEndpoint = browser.wsEndpoint();
// Disconnect puppeteer from Chromium
Expand All @@ -651,7 +655,7 @@ puppeteer.launch().then(async browser => {
const browser2 = await puppeteer.connect({browserWSEndpoint});
// Close Chromium
await browser2.close();
});
})();
```
#### event: 'disconnected'
Emitted when Puppeteer gets disconnected from the Chromium instance. This might happen because of one of the following:
Expand Down Expand Up @@ -697,13 +701,15 @@ Closes Chromium and all of its pages (if any were opened). The [Browser] object
Creates a new incognito browser context. This won't share cookies/cache with other browser contexts.

```js
const browser = await puppeteer.launch();
// Create a new incognito browser context.
const context = await browser.createIncognitoBrowserContext();
// Create a new page in a pristine context.
const page = await context.newPage();
// Do stuff
await page.goto('https://example.com');
(async () => {
const browser = await puppeteer.launch();
// Create a new incognito browser context.
const context = await browser.createIncognitoBrowserContext();
// Create a new page in a pristine context.
const page = await context.newPage();
// Do stuff
await page.goto('https://example.com');
})();
```

#### browser.defaultBrowserContext()
Expand Down Expand Up @@ -918,12 +924,13 @@ This example creates a page, navigates it to a URL, and then saves a screenshot:
```js
const puppeteer = require('puppeteer');

puppeteer.launch().then(async browser => {
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
await page.screenshot({path: 'screenshot.png'});
await browser.close();
});
})();
```

The Page class emits various events (described below) which can be handled using any of Node's native [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter) methods, such as `on`, `once` or `removeListener`.
Expand Down Expand Up @@ -1269,13 +1276,14 @@ To aid emulation, puppeteer provides a list of device descriptors which can be o
const puppeteer = require('puppeteer');
const iPhone = puppeteer.devices['iPhone 6'];

puppeteer.launch().then(async browser => {
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.emulate(iPhone);
await page.goto('https://www.google.com');
// other actions...
await browser.close();
});
})();
```

List of all available devices is available in the source code: [DeviceDescriptors.js](https://github.com/GoogleChrome/puppeteer/blob/master/lib/DeviceDescriptors.js).
Expand Down Expand Up @@ -1452,7 +1460,8 @@ An example of adding an `md5` function into the page:
const puppeteer = require('puppeteer');
const crypto = require('crypto');

puppeteer.launch().then(async browser => {
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
page.on('console', msg => console.log(msg.text()));
await page.exposeFunction('md5', text =>
Expand All @@ -1465,7 +1474,7 @@ puppeteer.launch().then(async browser => {
console.log(`md5 of ${myString} is ${myHash}`);
});
await browser.close();
});
})();
```

An example of adding a `window.readfile` function into the page:
Expand All @@ -1474,7 +1483,8 @@ An example of adding a `window.readfile` function into the page:
const puppeteer = require('puppeteer');
const fs = require('fs');

puppeteer.launch().then(async browser => {
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
page.on('console', msg => console.log(msg.text()));
await page.exposeFunction('readfile', async filePath => {
Expand All @@ -1493,8 +1503,7 @@ puppeteer.launch().then(async browser => {
console.log(content);
});
await browser.close();
});

})();
```

#### page.focus(selector)
Expand Down Expand Up @@ -1862,7 +1871,8 @@ An example of a naïve request interceptor that aborts all image requests:
```js
const puppeteer = require('puppeteer');

puppeteer.launch().then(async browser => {
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.setRequestInterception(true);
page.on('request', interceptedRequest => {
Expand All @@ -1873,7 +1883,7 @@ puppeteer.launch().then(async browser => {
});
await page.goto('https://example.com');
await browser.close();
});
})();
```

> **NOTE** Enabling request interception disables page caching.
Expand Down Expand Up @@ -2036,13 +2046,14 @@ The `waitForFunction` can be used to observe viewport size change:
```js
const puppeteer = require('puppeteer');

puppeteer.launch().then(async browser => {
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
const watchDog = page.waitForFunction('window.innerWidth < 100');
await page.setViewport({width: 50, height: 50});
await watchDog;
await browser.close();
});
})();
```

To pass arguments from node.js to the predicate of `page.waitForFunction` function:
Expand Down Expand Up @@ -2118,16 +2129,18 @@ This method works across navigations:
```js
const puppeteer = require('puppeteer');

puppeteer.launch().then(async browser => {
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
let currentURL;
page
.waitForSelector('img')
.then(() => console.log('First URL with image: ' + currentURL));
for (currentURL of ['https://example.com', 'https://google.com', 'https://bbc.com'])
for (currentURL of ['https://example.com', 'https://google.com', 'https://bbc.com']) {
await page.goto(currentURL);
}
await browser.close();
});
})();
```
Shortcut for [page.mainFrame().waitForSelector(selector[, options])](#framewaitforselectorselector-options).

Expand All @@ -2147,16 +2160,18 @@ This method works across navigations:
```js
const puppeteer = require('puppeteer');

puppeteer.launch().then(async browser => {
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
let currentURL;
page
.waitForXPath('//img')
.then(() => console.log('First URL with image: ' + currentURL));
for (currentURL of ['https://example.com', 'https://google.com', 'https://bbc.com'])
for (currentURL of ['https://example.com', 'https://google.com', 'https://bbc.com']) {
await page.goto(currentURL);
}
await browser.close();
});
})();
```
Shortcut for [page.mainFrame().waitForXPath(xpath[, options])](#framewaitforxpathxpath-options).

Expand Down Expand Up @@ -2498,15 +2513,16 @@ An example of using `Dialog` class:
```js
const puppeteer = require('puppeteer');

puppeteer.launch().then(async browser => {
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
page.on('dialog', async dialog => {
console.log(dialog.message());
await dialog.dismiss();
await browser.close();
});
page.evaluate(() => alert('1'));
});
})();
```

#### dialog.accept([promptText])
Expand Down Expand Up @@ -2560,18 +2576,20 @@ An example of dumping frame tree:
```js
const puppeteer = require('puppeteer');

puppeteer.launch().then(async browser => {
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://www.google.com/chrome/browser/canary.html');
dumpFrameTree(page.mainFrame(), '');
await browser.close();

function dumpFrameTree(frame, indent) {
console.log(indent + frame.url());
for (let child of frame.childFrames())
for (const child of frame.childFrames()) {
dumpFrameTree(child, indent + ' ');
}
}
});
})();
```

An example of getting text from an iframe element:
Expand Down Expand Up @@ -2897,13 +2915,14 @@ The `waitForFunction` can be used to observe viewport size change:
```js
const puppeteer = require('puppeteer');

puppeteer.launch().then(async browser => {
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
const watchDog = page.mainFrame().waitForFunction('window.innerWidth < 100');
page.setViewport({width: 50, height: 50});
await watchDog;
await browser.close();
});
})();
```

To pass arguments from node.js to the predicate of `page.waitForFunction` function:
Expand Down Expand Up @@ -2952,16 +2971,18 @@ This method works across navigations:
```js
const puppeteer = require('puppeteer');

puppeteer.launch().then(async browser => {
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
let currentURL;
page.mainFrame()
.waitForSelector('img')
.then(() => console.log('First URL with image: ' + currentURL));
for (currentURL of ['https://example.com', 'https://google.com', 'https://bbc.com'])
for (currentURL of ['https://example.com', 'https://google.com', 'https://bbc.com']) {
await page.goto(currentURL);
}
await browser.close();
});
})();
```

#### frame.waitForXPath(xpath[, options])
Expand All @@ -2980,16 +3001,18 @@ This method works across navigations:
```js
const puppeteer = require('puppeteer');

puppeteer.launch().then(async browser => {
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
let currentURL;
page.mainFrame()
.waitForXPath('//img')
.then(() => console.log('First URL with image: ' + currentURL));
for (currentURL of ['https://example.com', 'https://google.com', 'https://bbc.com'])
for (currentURL of ['https://example.com', 'https://google.com', 'https://bbc.com']) {
await page.goto(currentURL);
}
await browser.close();
});
})();
```

### class: ExecutionContext
Expand Down Expand Up @@ -3179,13 +3202,14 @@ ElementHandle represents an in-page DOM element. ElementHandles can be created w
```js
const puppeteer = require('puppeteer');

puppeteer.launch().then(async browser => {
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
const hrefElement = await page.$('a');
await hrefElement.click();
// ...
});
})();
```

ElementHandle prevents DOM element from garbage collection unless the handle is [disposed](#elementhandledispose). ElementHandles are auto-disposed when their origin frame gets navigated.
Expand Down

0 comments on commit 561c99d

Please sign in to comment.