headless/README.md

   1 # Headless Chromium
   2
   3 Headless Chromium allows running Chromium in a headless/server environment.
   4 Expected use cases include loading web pages, extracting metadata (e.g., the
   5 DOM) and generating bitmaps from page contents -- using all the modern web
   6 platform features provided by Chromium and Blink.
   7
   8 There are two ways to use Headless Chromium:
   9
  10 ## Usage via the DevTools remote debugging protocol
  11
  12 1. Start a normal Chrome binary with the `--headless` command line flag:
  13
  14 ```sh
  15 $ chrome --headless --remote-debugging-port=9222 https://chromium.org/
  16 ```
  17
  18 2. Navigate to `http://localhost:9222/` in another browser to open the
  19 [DevTools](https://developer.chrome.com/devtools) interface or use a tool such
  20 as [Selenium](http://www.seleniumhq.org/) to drive the headless browser.
  21
  22 ## Usage from Node.js
  23
  24 For example, the [chrome-remote-interface](https://github.com/cyrus-and/chrome-remote-interface)
  25 Node.js package can be used to extract a page's DOM like this:
  26
  27 ```js
  28 const CDP = require('chrome-remote-interface');
  29
  30 CDP((client) => {
  31   // Extract used DevTools domains.
  32   const {Page, Runtime} = client;
  33
  34   // Enable events on domains we are interested in.
  35   Promise.all([
  36     Page.enable()
  37   ]).then(() => {
  38     return Page.navigate({url: 'https://example.com'});
  39   });
  40
  41   // Evaluate outerHTML after page has loaded.
  42   Page.loadEventFired(() => {
  43     Runtime.evaluate({expression: 'document.body.outerHTML'}).then((result) => {
  44       console.log(result.result.value);
  45       client.close();
  46     });
  47   });
  48 }).on('error', (err) => {
  49   console.error('Cannot connect to browser:', err);
  50 });
  51 ```
  52
  53 ## Usage as a C++ library
  54
  55 Headless Chromium can be built as a library for embedding into a C++
  56 application. This approach is otherwise similar to controlling the browser over
  57 a DevTools connection, but it provides more customization points, e.g., for
  58 networking and [mojo services](https://docs.google.com/document/d/1Fr6_DJH6OK9rG3-ibMvRPTNnHsAXPk0VzxxiuJDSK3M/edit#heading=h.qh0udvlk963d).
  59
  60 [Headless Example](https://cs.chromium.org/chromium/src/headless/app/headless_example.cc)
  61 is a small sample application which demonstrates the use of the headless C++
  62 API. It loads a web page and outputs the resulting DOM. To run it, first
  63 initialize a headless build configuration:
  64
  65 ```sh
  66 $ mkdir -p out/Debug
  67 $ echo 'import("//build/args/headless.gn")' > out/Debug/args.gn
  68 $ gn gen out/Debug
  69 ```
  70
  71 Then build the example:
  72
  73 ```sh
  74 $ ninja -C out/Debug headless_example
  75 ```
  76
  77 After the build completes, the example can be run with the following command:
  78
  79 ```sh
  80 $ out/Debug/headless_example https://www.google.com/
  81 ```
  82
  83 [Headless Shell](https://cs.chromium.org/chromium/src/headless/app/headless_shell.cc)
  84 is a more capable headless application. For instance, it supports remote
  85 debugging with the [DevTools](https://developer.chrome.com/devtools) protocol.
  86 To do this, start the application with an argument specifying the debugging
  87 port:
  88
  89 ```sh
  90 $ ninja -C out/Debug headless_shell
  91 $ out/Debug/headless_shell --remote-debugging-port=9222 https://youtube.com/
  92 ```
  93
  94 Then navigate to `http://localhost:9222/` with your browser.
  95
  96 As of M118, precompiled `headless_shell` binaries are available for download
  97 under the name `chrome-headless-shell` via [Chrome for Testing
  98 infrastructure](https://googlechromelabs.github.io/chrome-for-testing/).
  99
 100 ## Embedder API
 101
 102 The embedder API allows developers to integrate the headless library into their
 103 application. The API provides default implementations for low level adaptation
 104 points such as networking and the run loop.
 105
 106 The main embedder API classes are:
 107
 108 - `HeadlessBrowser::Options::Builder` - Defines the embedding options, e.g.:
 109   - `SetMessagePump` - Replaces the default base message pump. See
 110     `base::MessagePump`.
 111   - `SetProxyServer` - Configures an HTTP/HTTPS proxy server to be used for
 112     accessing the network.
 113
 114 ## Client/DevTools API
 115
 116 The headless client API is used to drive the browser and interact with loaded
 117 web pages. Its main classes are:
 118
 119 - `HeadlessBrowser` - Represents the global headless browser instance.
 120 - `HeadlessWebContents` - Represents a single "tab" within the browser.
 121 - `HeadlessDevToolsClient` - Provides a C++ interface for inspecting and
 122   controlling a tab. The API functions corresponds to [DevTools commands](https://developer.chrome.com/devtools/docs/debugger-protocol).
 123   See the [client API documentation](https://docs.google.com/document/d/1rlqcp8nk-ZQvldNJWdbaMbwfDbJoOXvahPCDoPGOwhQ/edit#)
 124   for more information.
 125
 126 ## Resources and Documentation
 127
 128 Mailing list: [headless-dev@chromium.org](https://groups.google.com/a/chromium.org/forum/#!forum/headless-dev)
 129
 130 Bug tracker: [Internals>Headless](https://bugs.chromium.org/p/chromium/issues/list?can=2&q=component%3AInternals%3EHeadless)
 131
 132 [File a new bug](https://bugs.chromium.org/p/chromium/issues/entry?components=Internals%3EHeadless) ([bit.ly/2pP6SBb](https://bit.ly/2pP6SBb))
 133
 134 * [Runtime headless mode on Windows OS](https://docs.google.com/document/d/12c3bSEbmpeGevuyFHcvEKw9br6CkFJSS2saQynBjIzE)
 135 * [BeginFrame sequence numbers + acknowledgements](https://docs.google.com/document/d/1nxaunQ0cYWxhtS6Zzfwa99nae74F7gxanbuT5JRpI6Y/edit#)
 136 * [Deterministic page loading for Blink](https://docs.google.com/document/d/19s2g4fPP9p9qmMZvwPX8uDGbb-39rgR9k56B4B-ueG8/edit#)
 137 * [Crash dumps for Headless Chrome](https://docs.google.com/document/d/1l6AGOOBLk99PaAKoZQW_DVhM8FQ6Fut27lD938CRbTM/edit)
 138 * [Runtime headless mode for Chrome](https://docs.google.com/document/d/1aIJUzQr3eougZQp90bp4mqGr5gY6hdUice8UPa-Ys90/edit#)
 139 * [Virtual Time in
 140   Blink](https://docs.google.com/document/d/1y9KDT_ZEzT7pBeY6uzVt1dgKlwc1OB_vY4NZO1zBQmo/edit?usp=sharing)
 141 * [Headless Chrome architecture (Design Doc)](https://docs.google.com/document/d/11zIkKkLBocofGgoTeeyibB2TZ_k7nR78v7kNelCatUE)
 142 * [Headless Chrome C++ DevTools API](https://docs.google.com/document/d/1rlqcp8nk-ZQvldNJWdbaMbwfDbJoOXvahPCDoPGOwhQ/edit#heading=h.ng2bxb15li9a)
 143 * [Session isolation in Headless Chrome](https://docs.google.com/document/d/1XAKvrxtSEoe65vNghSWC5S3kJ--z2Zpt2UWW1Fi8GiM/edit)
 144 * [Headless Chrome mojo service](https://docs.google.com/document/d/1Fr6_DJH6OK9rG3-ibMvRPTNnHsAXPk0VzxxiuJDSK3M/edit#heading=h.qh0udvlk963d)
 145 * [Controlling BeginFrame through DevTools](https://docs.google.com/document/d/1LVMYDkfjrrX9PNkrD8pJH5-Np_XUTQHIuJ8IEOirQH4/edit?ts=57d96dbd#heading=h.ndv831lc9uf0)
 146 * [Viewport bounds and scale for screenshots](https://docs.google.com/document/d/1VTcYz4q_x0f1O5IVrvRX4u1DVd_K34IVUl1VULLTCWw/edit#heading=h.ndv831lc9uf0)
 147 * [BlinkOn 6 presentation slides](https://docs.google.com/presentation/d/1gqK9F4lGAY3TZudAtdcxzMQNEE7PcuQrGu83No3l0lw/edit#slide=id.p)