chromist

A Rust library for controlling Chrome and Chromium over the Chrome DevTools Protocol (CDP).

Overview

chromist drives a real Chromium browser from async Rust over CDP. It offers a Playwright-inspired locator and assertion API, type-safe bindings generated from the upstream protocol, and a concurrency model built around a single handler task with cheaply-cloneable handles. Scope is deliberately narrow: Tokio-only, CDP-only — no WebDriver, no Firefox.

Telemetry

chromist sends no telemetry, analytics, or crash reports — there is no background phone-home, update check, or remote logging anywhere in the codebase. No third-party endpoint is hard-coded.

Features

• Launch Chrome headless or with a visible window, or attach to a browser that's already running.
• Navigate to pages and wait for them to finish loading.
• Take screenshots and print pages to PDF.
• Run JavaScript on the page and get typed results back.
• Find elements, click, type, press keys, and scroll.
• Watch network requests, handle dialogs, and collect code coverage.
• Subscribe to browser events as async streams.
• Open isolated incognito sessions side by side.

See CAPABILITIES.md for the full inventory.

Usage

Add to Cargo.toml:

[dependencies]
chromist = "0.1"
tokio = { version = "1", features = ["full"] }

Requires Rust 1.95+. A Chrome or Chromium binary must be on the host; chromist auto-detects it, or set an explicit path via BrowserConfig.

Quickstart

use chromist::Browser;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let browser = Browser::launch_default().await?;

    let page = browser.new_page("https://example.com").await?;
    let png = page.screenshot().await?;
    std::fs::write("example.png", &png)?;
    println!("saved {} bytes", png.len());

    Ok(())
}

Builder for custom configuration (inside an async context):

use chromist::{Browser, BrowserConfig};

let config = BrowserConfig::builder().with_head().window_size(1920, 1080).build();
let browser = Browser::launch(config).await?;

Evaluate JavaScript

let result = page.evaluate("document.title").await?;
let title: String = result.into_value()?;
println!("title: {title}");

Query and interact with elements

let elements = page.dom().find_elements("a[href]").await?;
for el in elements {
    let text = el.inner_text().await?;
    println!("{text}");
}

Wait for navigation

use chromist::WaitUntil;

let waiter = page.navigation_waiter(WaitUntil::NetworkIdle);
page.goto("https://example.com").await?;
waiter.wait().await?;

Listen to events

use chromist::cdp::browser_protocol::network::ResponseReceivedEvent;
use futures::StreamExt;

let mut stream = page.event_listener::<ResponseReceivedEvent>();
while let Some(ev) = stream.next().await {
    println!("{}", ev.response.url);
}

Attach to a running browser

// Start Chrome with: google-chrome --remote-debugging-port=9222
let browser = Browser::connect("ws://localhost:9222/json").await?;

CDP Protocol Revision

Generated bindings are pinned to chromist-cdp::PROTOCOL_REVISION. To update, replace the PDL files under chromist-cdp/pdl/ and run:

cargo xtask codegen
cargo test -p chromist-cdp --test generate

Workspace Layout

crates/
  chromist-types/   # Wire types (MethodCall, Response, …) and core traits
  chromist-pdl/     # PDL parser and Rust code generator (build-time)
  chromist-cdp/     # Pre-generated CDP bindings, one module per domain
  chromist/         # High-level API: Browser, Page, Handler, Element, …

See ARCHITECTURE.md for design details.

Quality Report

Last graded: 2026-04-27 · Rubric: GRADING_GUIDE.md (5 universal + 4 context axes)

Workspace Dimensions

Overall: A

Per-Crate Grades

chromist-types — A+

chromist-pdl — A+

chromist-cdp — A+

chromist — A

Improvements

To reach A+ (close the only good rating — Correctness & Testing):

• Expand crates/chromist/tests/integration.rs:1 from ~12 to ~30 real-browser tests covering navigation races, frame-swap, websocket interception, download error paths, and route_from_har round-trips. The --features integration-tests plumbing is in place; the gap is breadth.
• Wire the existing soak harness (xtask/src/main.rs:53 — xtask soak 1000) into a nightly CI workflow that asserts ≤ +50 MiB RSS / 0 fd growth between baseline and final samples.

Not blocking A+ but worth closing:

• Add cargo audit and cargo +nightly miri test jobs to CI for the unsafe pipe-fd path.
• Add a CHANGELOG.md (keep-a-changelog format) and CONTRIBUTING.md (how to run tests, file layout) for governance hygiene.

License

Dual-licensed under MIT and Apache-2.0.