Changing Debugging => DevTools

README.md

@@ -1,102 +1,18 @@
 # About chromedp [![Build Status][1]][2] [![Coverage Status][3]][4]
 
-Package chromedp is a faster, simpler way to drive browsers in Go using the
+Package chromedp is a faster, simpler way to drive browsers supporting the
-[Chrome Debugging Protocol][5] (for Chrome, Edge, Safari, etc) without external
+[Chrome DevTools Protocol][5] in Go using the without external dependencies
-dependencies (ie, Selenium, PhantomJS, etc).
+(ie, Selenium, PhantomJS, etc).
-
-**NOTE:** chromedp's API is currently unstable, and may change at a moments
-notice. There are likely extremely bad bugs lurking in this code. **CAVEAT USER**.
 
 ## Installing
 
-Install in the usual way:
+Install in the usual Go way:
 
 ```sh
 go get -u github.com/chromedp/chromedp
 ```
 
-## Using
+## Examples
-
-Below is a simple Google search performed using chromedp (taken from
-[examples/simple][6]):
-
-This example shows logic for a simple search for a known website, clicking on
-the right link, and then taking a screenshot of a specific element on the
-loaded page and saving that to a local file on disk.
-
-```go
-// Command simple is a chromedp example demonstrating how to do a simple google
-// search.
-package main
-
-import (
-	"context"
-	"fmt"
-	"io/ioutil"
-	"log"
-	"time"
-
-	"github.com/chromedp/cdproto/cdp"
-	"github.com/chromedp/chromedp"
-)
-
-func main() {
-	var err error
-
-	// create context
-	ctxt, cancel := context.WithCancel(context.Background())
-	defer cancel()
-
-	// create chrome instance
-	c, err := chromedp.New(ctxt, chromedp.WithLog(log.Printf))
-	if err != nil {
-		log.Fatal(err)
-	}
-
-	// run task list
-	var site, res string
-	err = c.Run(ctxt, googleSearch("site:brank.as", "Home", &site, &res))
-	if err != nil {
-		log.Fatal(err)
-	}
-
-	// shutdown chrome
-	err = c.Shutdown(ctxt)
-	if err != nil {
-		log.Fatal(err)
-	}
-
-	// wait for chrome to finish
-	err = c.Wait()
-	if err != nil {
-		log.Fatal(err)
-	}
-
-	log.Printf("saved screenshot from search result listing `%s` (%s)", res, site)
-}
-
-func googleSearch(q, text string, site, res *string) chromedp.Tasks {
-	var buf []byte
-	sel := fmt.Sprintf(`//a[text()[contains(., '%s')]]`, text)
-	return chromedp.Tasks{
-		chromedp.Navigate(`https://www.google.com`),
-		chromedp.WaitVisible(`#hplogo`, chromedp.ByID),
-		chromedp.SendKeys(`#lst-ib`, q+"\n", chromedp.ByID),
-		chromedp.WaitVisible(`#res`, chromedp.ByID),
-		chromedp.Text(sel, res),
-		chromedp.Click(sel),
-		chromedp.WaitNotVisible(`.preloader-content`, chromedp.ByQuery),
-		chromedp.WaitVisible(`a[href*="twitter"]`, chromedp.ByQuery),
-		chromedp.Location(site),
-		chromedp.ScrollIntoView(`.banner-section.third-section`, chromedp.ByQuery),
-		chromedp.Sleep(2 * time.Second), // wait for animation to finish
-		chromedp.Screenshot(`.banner-section.third-section`, &buf, chromedp.ByQuery),
-		chromedp.ActionFunc(func(context.Context, cdp.Executor) error {
-			return ioutil.WriteFile("screenshot.png", buf, 0644)
-		}),
-	}
-}
-```
 
 Please see the [examples][6] project for more examples. Please refer to the
 [GoDoc API listing][7] for a summary of the API and Actions.
@@ -104,11 +20,11 @@ Please see the [examples][6] project for more examples. Please refer to the
 ## Resources
 
 * [chromedp: A New Way to Drive the Web][8] - GopherCon SG 2017 talk
-* [Chrome DevTools Protocol][5] - Chrome Debugging Protocol Domain documentation
+* [Chrome DevTools Protocol][5] - Chrome DevTools Protocol Domain documentation
 * [chromedp examples][6] - various `chromedp` examples
 * [`github.com/chromedp/cdproto`][9] - GoDoc listing for the CDP domains used by `chromedp`
 * [`github.com/chromedp/cdproto-gen`][10] - tool used to generate `cdproto`
-* [`github.com/chromedp/chromedp-proxy`][11] - a simple CDP proxy for logging/debugging CDP clients and browser instances
+* [`github.com/chromedp/chromedp-proxy`][11] - a simple CDP proxy for logging CDP clients and browsers
 
 ## TODO
 

chromedp.go

@@ -1,9 +1,9 @@
-// Package chromedp is a high level Chrome Debugging Protocol domain manager
+// Package chromedp is a high level Chrome DevTools Protocol client that
-// that simplifies driving web browsers (Chrome, Safari, Edge, Android Web
+// simplifies driving browsers for scraping, unit testing, or profiling web
-// Views, and others) for scraping, unit testing, or profiling web pages.
+// pages using the CDP.
 //
-// chromedp requires no third-party dependencies (ie, Selenium), implementing
+// chromedp requires no third-party dependencies, implementing the async Chrome
-// the async Chrome Debugging Protocol natively.
+// DevTools Protocol entirely in Go.
 package chromedp
 
 import (
@@ -35,8 +35,9 @@ const (
 	DefaultPoolEndPort = 10000
 )
 
-// CDP contains information for managing a Chrome process runner, low level
+// CDP is the high-level Chrome DevTools Protocol browser manager, handling the
-// JSON and websocket client, and associated network, page, and DOM handling.
+// browser process runner, WebSocket clients, associated targets, and network,
+// page, and DOM events.
 type CDP struct {
 	// r is the chrome runner.
 	r *runner.Runner
@@ -339,7 +340,7 @@ func (c *CDP) Run(ctxt context.Context, a Action) error {
 	return a.Do(ctxt, cur)
 }
 
-// Option is a Chrome Debugging Protocol option.
+// Option is a Chrome DevTools Protocol option.
 type Option func(*CDP) error
 
 // WithRunner is a CDP option to specify the underlying Chrome runner to

client/client.go

@@ -1,5 +1,4 @@
-// Package client provides the low level Chrome Debugging Protocol JSON types
+// Package client provides the low level Chrome DevTools Protocol client.
-// and related funcs.
 package client
 
 //go:generate go run gen.go
@@ -45,7 +44,7 @@ const (
 	ErrUnsupportedProtocolVersion Error = "unsupported protocol version"
 )
 
-// Target is the common interface for a Chrome Debugging Protocol target.
+// Target is the common interface for a Chrome DevTools Protocol target.
 type Target interface {
 	String() string
 	GetID() string
@@ -54,7 +53,7 @@ type Target interface {
 	GetWebsocketURL() string
 }
 
-// Client is a Chrome Debugging Protocol client.
+// Client is a Chrome DevTools Protocol client.
 type Client struct {
 	url     string
 	check   time.Duration
@@ -64,7 +63,7 @@ type Client struct {
 	rw       sync.RWMutex
 }
 
-// New creates a new Chrome Debugging Protocol client.
+// New creates a new Chrome DevTools Protocol client.
 func New(opts ...Option) *Client {
 	c := &Client{
 		url:     DefaultEndpoint,
@@ -301,10 +300,11 @@ func (c *Client) WatchPageTargets(ctxt context.Context) <-chan Target {
 	return ch
 }
 
-// Option is a Chrome Debugging Protocol client option.
+// Option is a Chrome DevTools Protocol client option.
 type Option func(*Client)
 
-// URL is a client option to specify the remote Chrome instance to connect to.
+// URL is a client option to specify the remote Chrome DevTools Protocol
+// instance to connect to.
 func URL(urlstr string) Option {
 	return func(c *Client) {
 		// since chrome 66+, dev tools requires the host name to be either an

handler.go

@@ -24,7 +24,7 @@ import (
 	"github.com/chromedp/chromedp/client"
 )
 
-// TargetHandler manages a Chrome Debugging Protocol target.
+// TargetHandler manages a Chrome DevTools Protocol target.
 type TargetHandler struct {
 	conn client.Transport
 

runner/runner.go

@@ -297,7 +297,7 @@ func (r *Runner) Port() int {
 	return p
 }
 
-// Client returns a Chrome Debugging Protocol client for the running Chrome
+// Client returns a Chrome DevTools Protocol client for the running Chrome
 // process.
 func (r *Runner) Client(opts ...client.Option) *client.Client {
 	return client.New(append(opts,