Struct headless_chrome::browser::Browser

pub struct Browser { /* fields omitted */ }

A handle to an instance of Chrome / Chromium, which wraps a WebSocket connection to its debugging port.

Most of your actual "driving" (e.g. clicking, typing, navigating) will be via instances of Tab, which are accessible via methods such as get_tabs.

A Browser can either manage its own Chrome process or connect to a remote one.

Browser::default().unwrap() will return a headless instance of whatever browser can be found using default_executable, which will search on your PATH for relevant binaries or use the path specified in the CHROME env var.

You can use LaunchOptions to automatically download a revision of Chromium that has a compatible API into your $XDG_DATA_DIR. Alternatively, you can specify your own path to a binary, or make use of the default_executable function to use your already-installed copy of Chrome.

Option 1: Managing a Chrome process

use headless_chrome::Browser;
let browser = Browser::default()?;
let first_tab = browser.wait_for_initial_tab()?;
assert_eq!("about:blank", first_tab.get_url());

Option 2: Connecting to a remote Chrome service

• see /examples/print_to_pdf.rs for a working example

While the Chrome DevTools Protocl (CDTP) does define some methods in a "Browser" domain (such as for resizing the window in non-headless mode), we currently don't implement those.

Methods

impl Browser

pub fn new(launch_options: LaunchOptions) -> Fallible<Self>

Launch a new Chrome browser.

The browser will have its user data (aka "profile") directory stored in a temporary directory. The browser process will be killed when this struct is dropped.

pub fn default() -> Fallible<Self>

Calls [new] with options to launch a headless browser using whatever Chrome / Chromium binary can be found on the system.

pub fn connect(debug_ws_url: String) -> Fallible<Self>

Allows you to drive an externally-launched Chrome process instead of launch one via [new].

pub fn get_process_id(&self) -> Option<u32>

pub fn get_tabs(&self) -> &Arc<Mutex<Vec<Arc<Tab>>>>

The tabs are behind an Arc and Mutex because they're accessible from multiple threads (including the one that handles incoming protocol events about new or changed tabs).

pub fn wait_for_initial_tab(&self) -> Fallible<Arc<Tab>>

Chrome always launches with at least one tab. The reason we have to 'wait' is because information about that tab isn't available immediately after starting the process. Tabs are behind Arcs because they each have their own thread which handles events and method responses directed to them.

pub fn new_tab(&self) -> Fallible<Arc<Tab>>

Create a new tab and return a handle to it.

If you want to specify its starting options, see new_tab_with_options.

let first_tab = browser.wait_for_initial_tab()?;
let new_tab = browser.new_tab()?;
let num_tabs = browser.get_tabs().lock().unwrap().len();
assert_eq!(2, num_tabs);

pub fn new_tab_with_options(
    &self,
    create_target_params: CreateTarget
) -> Fallible<Arc<Tab>>

Create a new tab with a starting url, height / width, context ID and 'frame control'

   let new_tab = browser.new_tab_with_options(CreateTarget {
   url: "chrome://version",
   width: Some(1024),
   height: Some(800),
   browser_context_id: None,
   enable_begin_frame_control: None,
   })?;

pub fn new_context(&self) -> Fallible<Context>

Creates the equivalent of a new incognito window, AKA a browser context

pub fn get_version(&self) -> Fallible<VersionInformationReturnObject>

Get version information

let version_info = browser.get_version()?;
println!("User-Agent is `{}`", version_info.user_agent);

Trait Implementations

impl Drop for Browser

fn drop(&mut self)

Executes the destructor for this type.