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 (Linux-only for now):
  14
  15 ```
  16 $ chrome --headless --remote-debugging-port=9222 https://chromium.org
  17 ```
  18
  19 Currently you'll also need to use `--disable-gpu` to avoid an error from a
  20 missing Mesa library.
  21
  22 2. Navigate to `http://localhost:9222` in another browser to open the
  23 [DevTools](https://developer.chrome.com/devtools) interface or use a tool such
  24 as [Selenium](http://www.seleniumhq.org/) to drive the headless browser.
  25
  26 ## Usage from Node.js
  27
  28 For example, the [chrome-remote-interface](https://github.com/cyrus-and/chrome-remote-interface)
  29 Node.js package can be used to extract a page's DOM like this:
  30
  31 ```
  32 const CDP = require('chrome-remote-interface');
  33
  34 CDP((client) => {
  35   // Extract used DevTools domains.
  36   const {Page, Runtime} = client;
  37
  38   // Enable events on domains we are interested in.
  39   Promise.all([
  40     Page.enable()
  41   ]).then(() => {
  42     return Page.navigate({url: 'https://example.com'});
  43   });
  44
  45   // Evaluate outerHTML after page has loaded.
  46   Page.loadEventFired(() => {
  47     Runtime.evaluate({expression: 'document.body.outerHTML'}).then((result) => {
  48       console.log(result.result.value);
  49       client.close();
  50     });
  51   });
  52 }).on('error', (err) => {
  53   console.error('Cannot connect to browser:', err);
  54 });
  55 ```
  56
  57 ## Usage as a C++ library
  58
  59 Headless Chromium can be built as a library for embedding into a C++
  60 application. This approach is otherwise similar to controlling the browser over
  61 a DevTools connection, but it provides more customization points, e.g., for
  62 networking and [mojo services](https://docs.google.com/document/d/1Fr6_DJH6OK9rG3-ibMvRPTNnHsAXPk0VzxxiuJDSK3M/edit#heading=h.qh0udvlk963d).
  63
  64 [Headless Example](https://cs.chromium.org/chromium/src/headless/app/headless_example.cc)
  65 is a small sample application which demonstrates the use of the headless C++
  66 API. It loads a web page and outputs the resulting DOM. To run it, first
  67 initialize a headless build configuration:
  68
  69 ```
  70 $ mkdir -p out/Debug
  71 $ echo 'import("//build/args/headless.gn")' > out/Debug/args.gn
  72 $ gn gen out/Debug
  73 ```
  74
  75 Then build the example:
  76
  77 ```
  78 $ ninja -C out/Debug headless_example
  79 ```
  80
  81 After the build completes, the example can be run with the following command:
  82
  83 ```
  84 $ out/Debug/headless_example https://www.google.com
  85 ```
  86
  87 [Headless Shell](https://cs.chromium.org/chromium/src/headless/app/headless_shell.cc)
  88 is a more capable headless application. For instance, it supports remote
  89 debugging with the [DevTools](https://developer.chrome.com/devtools) protocol.
  90 To do this, start the application with an argument specifying the debugging
  91 port:
  92
  93 ```
  94 $ ninja -C out/Debug headless_shell
  95 $ out/Debug/headless_shell --remote-debugging-port=9222 https://youtube.com
  96 ```
  97
  98 Then navigate to `http://localhost:9222` with your browser.
  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](https://docs.google.com/document/d/11zIkKkLBocofGgoTeeyibB2TZ_k7nR78v7kNelCatUE/edit)
 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)
 148 * [Architecture design doc](https://docs.google.com/document/d/11zIkKkLBocofGgoTeeyibB2TZ_k7nR78v7kNelCatUE)