Getting Started with Headless Chrome
TL;DR
Headless Chrome is a way to run the Chrome browser in a headless environment. Essentially, running Chrome without chrome! It brings all modern web platform features provided by Chromium and the Blink rendering engine to the command line.
Why is that useful?
A headless browser is a great tool for automated testing and server environments where you don't need a visible UI shell. For example, you may want to run some tests against a real web page, create a PDF of it, or just inspect how the browser renders an URL.
Note: Headless mode is available on Mac and Linux in Chrome 59. Windows support is coming soon!
Starting Headless (CLI)
The easiest way to get started with headless mode is to open the Chrome binary
from the command line. If you've got Chrome 59+ installed, start Chrome with the --headless flag:
chrome \
--headless \ # Runs Chrome in headless mode.
--disable-gpu \ # Temporarily needed for now.
--remote-debugging-port=9222 \
https://www.chromestatus.com # URL to open. Defaults to about:blank.
Note: Right now, you'll also want to include the --disable-gpu flag.
That will eventually go away.
chrome should point to your installation of Chrome. The exact location will
vary from platform to platform. Since I'm on Mac, I created convenient aliases
for each version of Chrome that I have installed:
alias chrome="/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome"
alias chrome-canary="/Applications/Google\ Chrome\ Canary.app/Contents/MacOS/Google\ Chrome\ Canary"
alias chromium="/Applications/Chromium.app/Contents/MacOS/Chromium"
Command line features
In some cases, you may not need to programmatically script Headless Chrome. There are some useful command line flags to perform common tasks.
Note: You may also need to include the --disable-gpu flag for now when
running these commands.
Printing the DOM
The --dump-dom flag prints document.body.innerHTML to stdout:
chrome --headless --dump-dom https://www.chromestatus.com/
Create a PDF
The --print-to-pdf flag creates a PDF of the page:
chrome --headless --print-to-pdf https://www.chromestatus.com/
Taking screenshots
To capture a screenshot of a page, use the --screenshot flag:
chrome --headless --screenshot https://www.chromestatus.com/
# Size of a standard letterhead.
chrome --headless --screenshot --window-size=1280,1696 https://www.chromestatus.com/
# Nexus 5x
chrome --headless --screenshot --window-size=412,732 https://www.chromestatus.com/
Running with --screenshot will produce a file named screenshot.png in the
current working directory. If you're looking for full page screenshots, things
are a tad more involved. There's a great blog
post from David Schnurr that has you covered. Check out Using headless Chrome as an automated screenshot tool
.
Debugging Chrome without a browser UI?
When you run Chrome with --remote-debugging-port=9222, it starts an instance
with the DevTools Protocol enabled. The
protocol is used to communicate with Chrome and drive the headless
browser instance. It's also what tools like Sublime, VS Code, and Node use for
remote debugging an application. #synergy
Since you don't have browser UI to see the page, navigate to http://localhost:9222
in another browser to check that everything is working. You'll see a list of
inspectable pages where you can click through and see what Headless is rendering:
From here, you can use the familiar DevTools features to inspect, debug, and tweak the page as you normally would. If you're using Headless programmatically, this page is also a powerful debugging tool for seeing all the raw DevTools protocol commands going across the wire, communicating with the browser.
Using programmatically (Node)
Launching Chrome
In the previous section, we started Chrome manually using --headless --remote-debugging-port=9222. However, to fully automate tests, you'll probably
want to spawn Chrome from your application.
One way is to use child_process:
const exec = require('child_process').exec;
function launchHeadlessChrome(url, callback) {
// Assuming MacOSx.
const CHROME = '/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome';
exec(`${CHROME} --headless --remote-debugging-port=9222 ${url}`, callback);
}
launchHeadlessChrome('https://www.chromestatus.com', (err, stdout, stderr) => {
...
});
But things get tricky if you want a portable solution that works across multiple platforms. Just look at that hard-coded path to Chrome :(
Using Lighthouse's ChromeLauncher
Lighthouse is a marvelous
tool for testing the quality of your web apps. One thing people don't realize
is that it ships with some really nice helper modules for working with Chrome.
One of those modules is ChromeLauncher. ChromeLauncher will find where
Chrome is installed, set up a debug instance, launch the browser, and kill it
when your program is done. Best part is that it works cross-platform thanks to
Node!
Note: The Lighthouse team is exploring a standalone package for ChromeLauncher with
an improved API. Let us know if you have feedback.
By default, ChromeLauncher will try to launch Chrome Canary (if it's
installed), but you can change that to manually select which Chrome to use. To
use it, first install Lighthouse from npm:
yarn add lighthouse
Example - using ChromeLauncher to launch Headless
const {ChromeLauncher} = require('lighthouse/lighthouse-cli/chrome-launcher');
/**
* Launches a debugging instance of Chrome on port 9222.
* @param {boolean=} headless True (default) to launch Chrome in headless mode.
* Set to false to launch Chrome normally.
* @return {Promise<ChromeLauncher>}
*/
function launchChrome(headless = true) {
const launcher = new ChromeLauncher({
port: 9222,
autoSelectChrome: true, // False to manually select which Chrome install.
additionalFlags: [headless ? '--headless' : '']
});
return launcher.run().then(() => launcher)
.catch(err => {
return launcher.kill().then(() => { // Kill Chrome if there's an error.
throw err;
}, console.error);
});
}
launchChrome(true).then(launcher => {
...
});
Running this script doesn't do much, but you should see an instance of
Chrome fire up in the task manager that loaded about:blank. Remember, there
won't be any browser UI. We're headless.
To control the browser, we need the DevTools protocol!
Retrieving information about the page
chrome-remote-interface is a great Node package that provides high-level APIs on top of the DevTools Protocol. You can use it to orchestrate Headless Chrome, navigate to pages, and fetch information about those pages.
Warning: The DevTools protocol can do a ton of interesting stuff, but it can be a bit
daunting at first. I recommend spending a bit of time browsing the DevTools Protocol API Viewer, first. Then, move on to the chrome-remote-interface API docs to
see how it wraps the raw protocol.
Let's install the library:
yarn add chrome-remote-interface
Examples
Example - print the user agent
launchChrome().then(launcher => {
chrome.Version().then(version => console.log(version['User-Agent']));
});
Results in something like: HeadlessChrome/60.0.3082.0
Example - check if the site has a web app manifest
const chrome = require('chrome-remote-interface');
function onPageLoad(Page) {
return Page.getAppManifest().then(response => {
if (!response.url) {
console.log('Site has no app manifest');
return;
}
console.log('Manifest: ' + response.url);
console.log(response.data);
});
}
launchChrome().then(launcher => {
chrome(protocol => {
// Extract the parts of the DevTools protocol we need for the task.
// See API docs: https://chromedevtools.github.io/debugger-protocol-viewer/
const {Page} = protocol;
// First, enable the Page domain we're going to use.
Page.enable().then(() => {
Page.navigate({url: 'https://www.chromestatus.com/'});
// Wait for window.onload before doing stuff.
Page.loadEventFired(() => {
onPageLoad(Page)).then(() => {
protocol.close();
launcher.kill(); // Kill Chrome.
});
});
});
}).on('error', err => {
throw Error('Cannot connect to Chrome:' + err);
});
});
Example - extract the <title> of the page using DOM APIs.
const chrome = require('chrome-remote-interface');
function onPageLoad(Runtime) {
const js = "document.querySelector('title').textContent";
// Evaluate the JS expression in the page.
return Runtime.evaluate({expression: js}).then(result => {
console.log('Title of page: ' + result.result.value);
});
}
launchChrome().then(launcher => {
chrome(protocol => {
// Extract the parts of the DevTools protocol we need for the task.
// See API docs: https://chromedevtools.github.io/debugger-protocol-viewer/
const {Page, Runtime} = protocol;
// First, need to enable the domains we're going to use.
Promise.all([
Page.enable(),
Runtime.enable()
]).then(() => {
Page.navigate({url: 'https://www.chromestatus.com/'});
// Wait for window.onload before doing stuff.
Page.loadEventFired(() => {
onPageLoad(Runtime).then(() => {
protocol.close();
launcher.kill(); // Kill Chrome.
});
});
});
}).on('error', err => {
throw Error('Cannot connect to Chrome:' + err);
});
});
Further resources
Here are some useful resources to get you started:
Docs
- DevTools Protocol - documentation on how to use the protocol
- DevTools Protocol Viewer - API reference docs
Tools
- chrome-remote-interface - node module that wraps the DevTools protocol
- Lighthouse - automated tool for testing the quality of web apps
Demos
- "The Headless Web" - Paul Kinlan's great blog post on using Headless with api.ai.
FAQ
How do I create a Docker container that runs Headless Chrome?
Check out lighthouse-ci. It has an example Dockerfile that uses Ubuntu as a base image, and installs + runs Lighthouse in an App Engine Flexible container.
How is this related to PhantomJS?
Headless Chrome is similar to tools like PhantomJS. Both can be used for automated testing in a headless environment. The main difference between the two is that Phantom uses an older version of WebKit as its rendering engine while Headless Chrome uses the latest version of Blink.
At the moment, Phantom also provides a higher level API than the DevTools Protocol.
Where do I report bugs?
For bugs against Headless Chrome, file them on crbug.com.
For bugs in the DevTools protocol, file them at github.com/ChromeDevTools/devtools-protocol.