Getting Started
Installation
To use Puppeteer in your project, run:
npm i puppeteer
# or "yarn add puppeteer"
puppeteer-core
Since version 1.7.0 we publish the puppeteer-core
package,
a version of Puppeteer that doesn't download any browser by default.
npm i puppeteer-core
# or "yarn add puppeteer-core"
puppeteer-core
is intended to be a lightweight version of Puppeteer for launching an existing browser installation or for connecting to a remote one. Be sure that the version of puppeteer-core you install is compatible with the
browser you intend to connect to.
See puppeteer vs puppeteer-core.
Usage
Puppeteer follows the latest maintenance LTS version of Node.
Puppeteer will be familiar to people using other browser testing frameworks. You create an instance
of Browser
, open pages, and then manipulate them with Puppeteer's API.
Example - navigating to https://example.com and saving a screenshot as example.png:
Save file as example.js
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
await page.screenshot({ path: 'example.png' });
await browser.close();
})();
Execute script on the command line
node example.js
Puppeteer sets an initial page size to 800×600px, which defines the screenshot size. The page size can be customized with Page.setViewport()
.
Example - create a PDF.
Save file as hn.js
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://news.ycombinator.com', {
waitUntil: 'networkidle2',
});
await page.pdf({ path: 'hn.pdf', format: 'a4' });
await browser.close();
})();
Execute script on the command line
node hn.js
See Page.pdf()
for more information about creating pdfs.
Example - evaluate script in the context of the page
Save file as get-dimensions.js
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
// Get the "viewport" of the page, as reported by the page.
const dimensions = await page.evaluate(() => {
return {
width: document.documentElement.clientWidth,
height: document.documentElement.clientHeight,
deviceScaleFactor: window.devicePixelRatio,
};
});
console.log('Dimensions:', dimensions);
await browser.close();
})();
Execute script on the command line
node get-dimensions.js
See Page.evaluate()
for more information on evaluate
and related methods like evaluateOnNewDocument
and exposeFunction
.
Default runtime settings
1. Uses Headless mode
Puppeteer launches Chromium in headless mode. To launch a full version of Chromium, set the headless
option when launching a browser:
const browser = await puppeteer.launch({ headless: false }); // default is true
2. Runs a bundled version of Chromium
By default, Puppeteer downloads and uses a specific version of Chromium so its API
is guaranteed to work out of the box. To use Puppeteer with a different version of Chrome or Chromium,
pass in the executable's path when creating a Browser
instance:
const browser = await puppeteer.launch({ executablePath: '/path/to/Chrome' });
You can also use Puppeteer with Firefox Nightly (experimental support). See Puppeteer.launch()
for more information.
See this article
for a description of the differences between Chromium and Chrome. This article
describes some differences for Linux users.
3. Creates a fresh user profile
Puppeteer creates its own browser user profile which it cleans up on every run.
Next steps
- Learn more about headless Chrome
- Look over the examples.