Skip to content
No description, website, or topics provided.
Rust HTML Other
Branch: master
Clone or download
Latest commit e4eeab6 Aug 23, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Use Fallible<T> instead of Result<T, Error> Jul 7, 2019
src Add get_title method to tab Aug 23, 2019
tests Add tab.getCookies() Aug 20, 2019
.gitignore Update gitignore Feb 17, 2019
.travis.yml Disable test for OS X Aug 20, 2019
CHANGELOG.md Update changelog, bump crate to 0.8.0 Aug 22, 2019
Cargo.toml Bump websocket dep and png dev-dep Aug 22, 2019
README.md Misc updates to readme [ci skip] Aug 22, 2019

README.md

Headless Chrome

Build Status Crate API Discord channel

A high-level API to control headless Chrome or Chromium over the DevTools Protocol. It is the Rust equivalent of Puppeteer, a Node library maintained by the Chrome DevTools team.

It is not 100% feature compatible with Puppeteer, but there's enough here to satisfy most browser testing / web crawling use cases, and there are several 'advanced' features such as:

Quick Start

use headless_chrome::{Browser, protocol::page::ScreenshotFormat};

fn browse_wikipedia() -> Result<(), failure::Error> {
    let browser = Browser::default()?;

    let tab = browser.wait_for_initial_tab()?;

    /// Navigate to wikipedia
    tab.navigate_to("https://www.wikipedia.org")?;

    /// Wait for network/javascript/dom to make the search-box available
    /// and click it.
    tab.wait_for_element("input#searchInput")?.click()?;

    /// Type in a query and press `Enter`
    tab.type_str("WebKit")?.press_key("Enter")?;

    /// We should end up on the WebKit-page once navigated
    tab.wait_for_element("#firstHeading")?;
    assert!(tab.get_url().ends_with("WebKit"));

    /// Take a screenshot of the entire browser window
    let _jpeg_data = tab.capture_screenshot(
                        ScreenshotFormat::JPEG(Some(75)),
                        None,
                        true)?;

    /// Take a screenshot of just the WebKit-Infobox
    let _png_data = tab
        .wait_for_element("#mw-content-text > div > table.infobox.vevent")?
        .capture_screenshot(ScreenshotFormat::PNG)?;
    Ok(())
}

assert!(browse_wikipedia().is_ok());

For fuller examples, take a look at tests/simple.rs and examples/real_world.rs.

What can't it do?

The Chrome DevTools Protocol is huge. Currently, Puppeteer supports way more of it than we do. Some of the missing features include:

  • Manipulating cookies (you can view them with tab.getCookies(), though)
  • Dealing with frames
  • Handling file picker / chooser interactions
  • Tapping touchscreens
  • Emulating different network conditions (DevTools can alter latency, throughput, offline status, 'connection type')
  • Viewing timing information about network requests
  • Reading the SSL certificate
  • Replaying XHRs
  • HTTP Basic Auth
  • Inspecting EventSources (aka server-sent events or SSEs)
  • WebSocket inspection

If you're interested in adding one of these features but would like some advice about how to start, please reach out by creating an issue or sending me an email at alistair@sunburnt.country.

Related crates

  • fantoccini uses WebDriver, so it works with browsers other than Chrome. It's also asynchronous and based on Tokio, unlike headless_chrome, which has a synchronous API and is just implemented using plain old threads. Fantoccini has also been around longer and is more battle-tested. It doesn't support Chrome DevTools-specific functionality like JS Coverage.

Testing

For debug output, set these environment variables before running cargo test:

RUST_BACKTRACE=1 RUST_LOG=headless_chrome=trace

Version numbers

Starting with v0.2.0, we're trying to follow SemVar strictly.

Troubleshooting

If you get errors related to timeouts, you likely need to enable sandboxing either in the kernel or as a setuid sandbox. Puppeteer has some information about how to do that here

By default, headless_chrome will download a compatible version of chrome to XDG_DATA_HOME (or equivalent on Windows/Mac). This behaviour can be optionally turned off, and you can use the system version of chrome (assuming you have chrome installed) by disabling the default feature in your Cargo.toml:

[dependencies.headless_chrome]
default-features = false

Contributing

Pull requests and issues are most welcome, even if they're just experience reports. If you find anything frustrating or confusing, let me know!

You can’t perform that action at this time.