Headless Chromium allows running Chromium in a headless/server environment. Expected use cases include loading web pages, extracting metadata (e.g., the DOM) and generating bitmaps from page contents -- using all the modern web platform features provided by Chromium and Blink.
There are two ways to use Headless Chromium:
--headlesscommand line flag (Linux-only for now):
$ chrome --headless --remote-debugging-port=9222 https://chromium.org
Currently you'll also need to use
--disable-gpu to avoid an error from a missing Mesa library.
http://localhost:9222in another browser to open the DevTools interface or use a tool such as Selenium to drive the headless browser.
Headless Chromium can be built as a library for embedding into a C++ application. This approach is otherwise similar to controlling the browser over a DevTools connection, but it provides more customization points, e.g., for networking and mojo services.
Headless Shell is a sample application which demonstrates the use of the headless C++ API. To run it, first initialize a headless build configuration:
$ mkdir -p out/Debug $ echo 'import("//build/args/headless.gn")' > out/Debug/args.gn $ gn gen out/Debug
Then build the shell:
$ ninja -C out/Debug headless_shell
After the build completes, Headless Shell can be run with the following command:
$ out/Debug/headless_shell https://www.google.com
To attach a DevTools debugger to the shell, start it with an argument specifying the debugging port:
$ out/Debug/headless_shell --remote-debugging-port=9222 https://youtube.com
Then navigate to
http://localhost:9222 with your browser.
The embedder API allows developers to integrate the headless library into their application. The API provides default implementations for low level adaptation points such as networking and the run loop.
The main embedder API classes are:
HeadlessBrowser::Options::Builder- Defines the embedding options, e.g.:
SetMessagePump- Replaces the default base message pump. See
SetProxyServer- Configures an HTTP/HTTPS proxy server to be used for accessing the network.
The headless client API is used to drive the browser and interact with loaded web pages. Its main classes are:
HeadlessBrowser- Represents the global headless browser instance.
HeadlessWebContents- Represents a single “tab” within the browser.
HeadlessDevToolsClient- Provides a C++ interface for inspecting and controlling a tab. The API functions corresponds to DevTools commands. See the client API documentation for more information.