To use Puppeteer in your project, you must first install it.
Installation
npm i puppeteer
# or "yarn add puppeteer"
When you install Puppeteer, it downloads a recent version of Chromium (~170MB Mac, ~282MB Linux, ~280MB Win) that is guaranteed to work with the API. To skip the download, download into another path, or download a different browser, see Environment variables.
puppeteer-core
Since version 1.7.0, we publish the puppeteer-core
package. This version of
Puppeteer 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 versus puppeteer-core.
Usage
Puppeteer follows the latest maintenance LTS version of Node.
Puppeteer is likely familiar to people using other browser testing frameworks.
You create an instance of Browser
, open pages, and then manipulate them with
Puppeteer's API.
Save a screenshot
For example, to navigate to https://example.com
and save a screenshot as
example.png
, save the following code to 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();
})();
Puppeteer sets an initial page size to 800×600px, which defines the screenshot size. The page size can be customized with Page.setViewport().
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.
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 Evaluate JavaScript for more
information on evaluate and related methods such as evaluateOnNewDocument
and
exposeFunction
.
Default runtime settings
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
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.
For more information:
- What's the Difference Between Chromium and Chrome? from How-To Geek.
- The Chromium Docs describes some differences for Linux users.
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.