chromedp

chromedp is a high-level Go client for the Chrome DevTools Protocol (CDP) that lets you drive headless or full Chrome instances directly from Go code, without shelling out to Selenium, WebDriver, or any browser binding library. It implements the CDP’s asynchronous protocol natively, exposing a composable set of Actions for navigation, DOM querying, form interaction, and screenshotting that can be chained into Run() calls against a browser context.

Under the hood, chromedp manages an ExecAllocator (or a RemoteAllocator for existing browser instances) that spins up and communicates with Chrome over WebSockets, exposing results through the companion cdproto package’s generated protocol bindings. It is widely used for web scraping, headless UI testing, PDF and screenshot generation, and automating any workflow that requires a real rendering engine rather than a static HTML parser.

What You Get

• An Action-based API (chromedp.Run(ctx, actions…)) for chaining browser operations like Navigate, Click, SendKeys, and WaitVisible
• An ExecAllocator that launches and manages headless (or headed) Chrome processes automatically, with no external driver binary required
• A RemoteAllocator for attaching to an already-running Chrome instance over its DevTools WebSocket endpoint
• Built-in screenshot and full-page PDF capture, plus DOM query helpers built on CSS/XPath/JS selectors
• Direct access to the full generated CDP protocol surface via the companion cdproto package for advanced use cases

Common Use Cases

• Scraping JavaScript-rendered pages that a plain HTTP client or HTML parser can’t execute
• Headless end-to-end browser testing of web applications in CI pipelines
• Generating full-page screenshots or PDFs of rendered web content
• Automating repetitive browser workflows like form submission or authenticated session scraping

Under The Hood

Architecture chromedp’s execution flow starts in chromedp.go, where a Context wraps an Allocator, Browser, and Target; NewContext creates a cancellable context tied to a browser, and Run() dispatches a list of Action values (functions closed over context.Context) executed against the Browser held by that Context. Allocation is abstracted behind the Allocator interface (allocate.go), with ExecAllocator managing local Chrome subprocess lifecycles — spawning via os/exec, reading the websocket debugger URL from stdout, and enforcing DefaultExecAllocatorOptions flags modeled on Puppeteer’s baseline — while RemoteAllocator attaches to an already-running browser over an existing DevTools websocket. target.go and browser.go maintain per-tab and per-browser state and event dispatch, while query.go implements a layered Query/Selector system that resolves CSS/XPath/JS/node-ID selectors into cdp.Node values before running After hooks to extract or mutate DOM state, all built atop the generated protocol types from the sibling cdproto module. Because Action, Allocator, and Selector are narrow interfaces and function types, the core abstraction most callers depend on is the Action closure signature that every high-level browser command implements — changing it would ripple through every Run() call site in every consumer.

Tech Stack Written in Go, chromedp carries almost no third-party runtime dependencies beyond its own sibling packages — cdproto for generated Chrome DevTools Protocol bindings and sysutil for OS helpers — plus a small, narrowly scoped set of libraries: gobwas/ws for the raw WebSocket client used to talk to Chrome’s debugger endpoint, go-json-experiment/json for JSON encoding, ledongthuc/pdf for PDF-related test verification, and orisano/pixelmatch for pixel-diff screenshot testing. There’s no web framework, ORM, or database in play — chromedp drives an external Chrome or Chromium binary as a subprocess via ExecAllocator, or attaches to one over the network via RemoteAllocator, communicating over the Chrome DevTools Protocol’s JSON-RPC-over-WebSocket wire format. CI runs the full test suite against multiple Go toolchain versions via GitHub Actions, plus a supplementary run against the official headless-shell Docker image.

Code Quality An extensive set of test files covers allocation, browser and target lifecycle, emulation, JS evaluation, event handling, input, navigation, polling, querying, and screenshotting, alongside runnable godoc examples that are checked by the test suite. Because the package’s core responsibility is driving a real browser, its tests exercise an actual Chrome session in CI rather than relying on mocks. Error handling is idiomatic Go: a small set of sentinel Error string constants are defined and checked explicitly rather than swallowed. Naming is consistent, and exported symbols carry thorough godoc comments explaining behavior and edge cases. No dedicated linter configuration was found, but the codebase reads as vet-clean and idiomatic, with CI enforcing green tests across Go toolchain versions.

API Design The public API centers on a single Run(ctx, actions…) entry point that accepts a list of composable Action values, letting callers chain high-level helpers — Navigate, Click, SendKeys, WaitVisible, Screenshot, and more — into a readable, declarative sequence without manually managing WebSocket frames or protocol message IDs; a Tasks alias lets a sequence be packaged into a single reusable value. Getting started requires little more than a context and a Run() call — no external driver binary, browser download step, or configuration file, since ExecAllocator locates or launches Chrome itself with sensible automation-friendly defaults modeled on Puppeteer’s flag set. Naming is consistent across the API (By-prefixed selector modes, With-prefixed context options, Err-prefixed sentinel errors), nearly every exported type carries detailed usage-oriented documentation, and the README’s FAQ section proactively addresses the most common pitfalls newcomers hit, such as headless-mode confusion and context-cancellation errors.