- Notifications
You must be signed in to change notification settings - Fork45
Package cdp provides type-safe bindings for the Chrome DevTools Protocol (CDP), written in the Go programming language.
License
mafredri/cdp
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Packagecdp provides type-safe bindings for theChrome DevTools Protocol (CDP), written in the Go programming language. The bindings are generated (bycdpgen) from the latesttip-of-tree (tot) protocol definitions and are mainly intended for use with Google Chrome or Chromium, however, they can be used with any debug target (Node.js,Edge DevTools Protocol,Safari, etc.) that implement the protocol.
This package can be used for any kind of browser automation, scripting or debugging via the Chrome DevTools Protocol.
A big motivation forcdp is to expose the full functionality of the Chrome DevTools Protocol and provide it in a discoverable and self-documenting manner.
Providing high-level browser automation is a non-goal for this project. That being said,cdp hopes to improve the ergonomics of working with the protocol by providing primitives better suited for Go and automating repetitive tasks.
- Discoverable API for the Chrome DevTools Protocol (GoDoc, autocomplete friendly)
- Contexts as a first-class citizen (for timeouts and cancellation)
- Simple and synchronous event handling (no callbacks)
- Concurrently safe
- No silent or hidden errors
- Do what the user expects
- Match CDP types to Go types wherever possible
- Separation of concerns (avoid mixing CDP and RPC)
$go get -u github.com/mafredri/cdpSeeAPI documentation for package, API descriptions and examples. Examples can also be found in this repository, see thesimple,advanced,logging andincognito examples.
The main packages arecdp andrpcc, the former provides the CDP bindings and the latter handles the RPC communication with the debugging target.
To connect to a debug target, a WebSocket debugger URL is needed. For example, if Chrome is running with--remote-debugging-port=9222 the debugger URL can be found atlocalhost:9222/json. Thedevtool package can also be used to query the DevTools JSON API (see example below).
Here is an example of usingcdp:
package mainimport ("bufio""context""fmt""io/ioutil""log""os""time""github.com/mafredri/cdp""github.com/mafredri/cdp/devtool""github.com/mafredri/cdp/protocol/dom""github.com/mafredri/cdp/protocol/page""github.com/mafredri/cdp/rpcc")funcmain() {err:=run(5*time.Second)iferr!=nil {log.Fatal(err)}}funcrun(timeout time.Duration)error {ctx,cancel:=context.WithTimeout(context.Background(),timeout)defercancel()// Use the DevTools HTTP/JSON API to manage targets (e.g. pages, webworkers).devt:=devtool.New("http://127.0.0.1:9222")pt,err:=devt.Get(ctx,devtool.Page)iferr!=nil {pt,err=devt.Create(ctx)iferr!=nil {returnerr}}// Initiate a new RPC connection to the Chrome DevTools Protocol target.conn,err:=rpcc.DialContext(ctx,pt.WebSocketDebuggerURL)iferr!=nil {returnerr}deferconn.Close()// Leaving connections open will leak memory.c:=cdp.NewClient(conn)// Open a DOMContentEventFired client to buffer this event.domContent,err:=c.Page.DOMContentEventFired(ctx)iferr!=nil {returnerr}deferdomContent.Close()// Enable events on the Page domain, it's often preferrable to create// event clients before enabling events so that we don't miss any.iferr=c.Page.Enable(ctx);err!=nil {returnerr}// Create the Navigate arguments with the optional Referrer field set.navArgs:=page.NewNavigateArgs("https://www.google.com").SetReferrer("https://duckduckgo.com")nav,err:=c.Page.Navigate(ctx,navArgs)iferr!=nil {returnerr}// Wait until we have a DOMContentEventFired event.if_,err=domContent.Recv();err!=nil {returnerr}fmt.Printf("Page loaded with frame ID: %s\n",nav.FrameID)// Fetch the document root node. We can pass nil here// since this method only takes optional arguments.doc,err:=c.DOM.GetDocument(ctx,nil)iferr!=nil {returnerr}// Get the outer HTML for the page.result,err:=c.DOM.GetOuterHTML(ctx,&dom.GetOuterHTMLArgs{NodeID:&doc.Root.NodeID,})iferr!=nil {returnerr}fmt.Printf("HTML: %s\n",result.OuterHTML)// Capture a screenshot of the current page.screenshotName:="screenshot.jpg"screenshotArgs:=page.NewCaptureScreenshotArgs().SetFormat("jpeg").SetQuality(80)screenshot,err:=c.Page.CaptureScreenshot(ctx,screenshotArgs)iferr!=nil {returnerr}iferr=ioutil.WriteFile(screenshotName,screenshot.Data,0o644);err!=nil {returnerr}fmt.Printf("Saved screenshot: %s\n",screenshotName)pdfName:="page.pdf"f,err:=os.Create(pdfName)iferr!=nil {returnerr}pdfArgs:=page.NewPrintToPDFArgs().SetTransferMode("ReturnAsStream")// Request stream.pdfData,err:=c.Page.PrintToPDF(ctx,pdfArgs)iferr!=nil {returnerr}sr:=c.NewIOStreamReader(ctx,*pdfData.Stream)r:=bufio.NewReader(sr)// Write to file in ~r.Size() chunks._,err=r.WriteTo(f)iferr!=nil {returnerr}err=f.Close()iferr!=nil {returnerr}fmt.Printf("Saved PDF: %s\n",pdfName)returnnil}
For more information, consult thedocumentation.
The Go implementation of gRPC (grpc-go) has been a source of inspiration for some of the design decisions made in thecdp andrpcc packages. Some ideas have also been borrowed from thenet/rpc package from the standard library.
- Chrome DevTools Protocol
- Viewer (latest tip-of-tree) official protocol API docs
- Repository (GitHub) pleasefile issues at this repo if you have concerns or problems with the Chrome DevTools Protocol
- Mailing list
- Getting Started with Headless Chrome
- Awesome chrome-devtools: Chrome DevTools Protocol
- RemoteDebug is an initiative to bring remote debugging (e.g. CDP) to all modern browsers
About
Package cdp provides type-safe bindings for the Chrome DevTools Protocol (CDP), written in the Go programming language.