chromiumoxide provides a high-level and async API to control Chrome or Chromium over the DevTools Protocol. It comes with support for all types of the Chrome DevTools Protocol and can launch headless or can be configured to run full (non-headless) Chrome or Chromium or connect to running instance.
⚠️ The API is still unstable, subject to change, untested and incomplete. However all message types, as defined in the protocol definition files (browserprotocol.pdl and jsprotocol.pdl) are supported. PRs, feature requests and issues are welcome.
```rust use futures::StreamExt;
use chromiumoxide::browser::{Browser, BrowserConfig};
async fn main() -> Result<(), Box
// create a Browser that spawns a chromium process running with UI (with_head(), headless is default)
// and the handler that drives the websocket etc.
let (browser, mut handler) =
Browser::launch(BrowserConfig::builder().with_head().build()?).await?;
// spawn the handle on its own task let handle = async_std::task::spawn(async move { loop { let _event = handler.next().await.unwrap(); } });
// create a new browser page and navigate to the url let page = browser.new_page("https://en.wikipedia.org").await?;
// find the search bar type into the search field and hit Enter,
// this triggers a new navigation to the search result page
page.findelement("input#searchInput")
.await?
.click()
.await?
.typestr("Rust programming language")
.await?
.press_key("Enter")
.await?;
// wait until the search result page is loaded and get the first hit let path = page .waitfornavigation() .await? .find_element("li.mw-search-result a") .await? .attribute("href") .await? .unwrap();
// navigate to the page and get its html content let html = page .goto(format!("https://en.wikipedia.org{}", path)) .await? .content() .await?;
handle.await;
Ok(())
} ```
The current API is still rather limited, but the Page::execute function allows sending all chromiumoxide_types::Command types (see Generated Code). Most Element and Page functions are basically just simplified command constructions and combinations, like Page::pdf:
rust
pub async fn pdf(&self, opts: PrintToPdfParams) -> Result<Vec<u8>> {
let res = self.execute(opts).await?;
Ok(base64::decode(&res.data)?)
}
If you need something else, the execute function allows for writing your own command wrappers. PRs are very welcome.
toml
chromiumoxide = { git = "https://github.com/mattsse/chromiumoxide" }
The chromiumoxide_pdl crate contains a PDL parser, which is a rust rewrite of a python script in the chromium source tree and a Generator that turns the parsed PDL files into rust code. The chromiumoxide_cdp crate only purpose is to integrate the generator during is build process and include the generated output before compiling the crate itself. This separation is done merely because the generated output is ~60K lines of rust code (not including all the Proc macro extensions). So expect the compilation to take some time.
The generator can be configured and used independently, see chromiumoxide_cdp/build.rs.
Every chrome pdl domain is put in its own rust module, the types for the page domain of the browserprotocol are in chromiumoxide_cdp::cdp::browser_protocol::page, the runtime domain of the jsprotocol in chromiumoxide_cdp::cdp::js_protocol::runtime and so on.
vanilla.aslushnikov.com/ is a great resource to browse all the types defined in the pdl files. This site displays Command types as defined in the pdl files as Method. chromiumoxid sticks to the Command nomenclature. So for everything that is defined as a command type in the pdl (=marked as Method on vanilla.aslushnikov.com/) chromiumoxide contains a type for command and a designated type for the return type. For every command there is a <name of command>Params type with builder support (<name of command>Params::builder()) and its corresponding return type: <name of command>Returns. All commands share an implementation of the chromiumoxide_types::Command trait.
All Events are bundled in single enum (CdpEvent)
export CDP_NO_EXPERIMENTAL=true). This is because the use of some experimental pdl types in the *.pdl files themselves are not marked as experimental.chromiumoxide requires an installed chromium application and may not be able to find it on its own. The option to download chromium certainly would be a handy feature.Q: A new chromium instance is being launched but then times out.
A: Check that your chromium language settings are set to English. chromiumoxide tries to parse the debugging port from the chromium process output and that is limited to english.
Licensed under either of these:
KeyDefinition and typing support is taken from.