thunderstrike/puppeteer
thunderstrike/puppeteer
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(api.md): prefer async/await over Promise#then (#5089)

Browse Source 
Fixes #5082.
This commit is contained in:
Benj Fassbind 2019-10-26 11:00:39 +02:00 committed by Mathias Bynens
parent aaa904d293
commit 561c99d52a
1 changed files with 73 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

122
docs/api.md
View File

@ -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)
@ -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')`.
@ -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
@ -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:
@ -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()
@ -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`.
@ -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).
@ -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 =>
@ -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:
@ -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 => {
@ -1493,8 +1503,7 @@ puppeteer.launch().then(async browser => {
console.log(content);
});
await browser.close();
});
})();
```
#### page.focus(selector)
@ -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 => {
@ -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.
@ -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:
@ -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).
@ -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).
@ -2498,7 +2513,8 @@ 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());
@ -2506,7 +2522,7 @@ puppeteer.launch().then(async browser => {
await browser.close();
});
page.evaluate(() => alert('1'));
});
})();
```
#### dialog.accept([promptText])
@ -2560,7 +2576,8 @@ 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(), '');
@ -2568,10 +2585,11 @@ puppeteer.launch().then(async browser => {
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:
@ -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:
@ -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])
@ -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
@ -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.