chromedp

package module
v0.8.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 30, 2022 License: MIT Imports: 44 Imported by: 1,343

README

About chromedp

Package chromedp is a faster, simpler way to drive browsers supporting the Chrome DevTools Protocol in Go without external dependencies.

Unit Tests Go Reference Releases

Installing

Install in the usual Go way:

$ go get -u github.com/chromedp/chromedp

Examples

Refer to the Go reference for the documentation and examples. Additionally, the examples repository contains more examples on complex actions, and other common high-level tasks such as taking full page screenshots.

Frequently Asked Questions

I can't see any Chrome browser window

By default, Chrome is run in headless mode. See DefaultExecAllocatorOptions, and an example to override the default options.

I'm seeing "context canceled" errors

When the connection to the browser is lost, chromedp cancels the context, and it may result in this error. This occurs, for example, if the browser is closed manually, or if the browser process has been killed or otherwise terminated.

Chrome exits as soon as my Go program finishes

On Linux, chromedp is configured to avoid leaking resources by force-killing any started Chrome child processes. If you need to launch a long-running Chrome instance, manually start Chrome and connect using RemoteAllocator.

Executing an action without Run results in "invalid context"

By default, a chromedp context does not have an executor, however one can be specified manually if necessary; see issue #326 for an example.

I can't use an Action with Run because it returns many values

Wrap it with an ActionFunc:

ctx, cancel := chromedp.NewContext(context.Background())
defer cancel()
chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {
	_, err := domain.SomeAction().Do(ctx)
	return err
}))

I want to use chromedp on a headless environment

The simplest way is to run the Go program that uses chromedp inside the chromedp/headless-shell image. That image contains headless-shell, a smaller headless build of Chrome, which chromedp is able to find out of the box.

Resources

Documentation

Overview

Package chromedp is a high level Chrome DevTools Protocol client that simplifies driving browsers for scraping, unit testing, or profiling web pages using the CDP.

chromedp requires no third-party dependencies, implementing the async Chrome DevTools Protocol entirely in Go.

This package includes a number of simple examples. Additionally, https://github.com/chromedp/examples contains more complex examples.

Example (DocumentDump) 
package main

import (
	"context"
	"fmt"
	"io"
	"log"
	"net/http"
	"net/http/httptest"
	"strings"

	"github.com/chromedp/cdproto/cdp"
	"github.com/chromedp/cdproto/runtime"
	"github.com/chromedp/chromedp"
)

func writeHTML(content string) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "text/html")
		io.WriteString(w, strings.TrimSpace(content))
	})
}

func main() {
	ctx, cancel := chromedp.NewContext(context.Background())
	defer cancel()

	ts := httptest.NewServer(writeHTML(`<!doctype html>
<html>
<body>
  <div id="content">the content</div>
</body>
</html>`))
	defer ts.Close()

	const expr = `(function(d, id, v) {
		var b = d.querySelector('body');
		var el = d.createElement('div');
		el.id = id;
		el.innerText = v;
		b.insertBefore(el, b.childNodes[0]);
	})(document, %q, %q);`

	var nodes []*cdp.Node
	if err := chromedp.Run(ctx,
		chromedp.Navigate(ts.URL),
		chromedp.Nodes(`document`, &nodes, chromedp.ByJSPath),
		chromedp.WaitVisible(`#content`),
		chromedp.ActionFunc(func(ctx context.Context) error {
			s := fmt.Sprintf(expr, "thing", "a new thing!")
			_, exp, err := runtime.Evaluate(s).Do(ctx)
			if err != nil {
				return err
			}
			if exp != nil {
				return exp
			}
			return nil
		}),
		chromedp.WaitVisible(`#thing`),
	); err != nil {
		log.Fatal(err)
	}

	fmt.Println("Document tree:")
	fmt.Print(nodes[0].Dump("  ", "  ", false))

}

Output:

Document tree:
  #document <Document>
    html <DocumentType>
    html
      head
      body
        div#thing
          #text "a new thing!"
        div#content
          #text "the content"
Example (RetrieveHTML) 
package main

import (
	"context"
	"fmt"
	"io"
	"log"
	"net/http"
	"net/http/httptest"
	"strings"

	"github.com/chromedp/chromedp"
)

func writeHTML(content string) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "text/html")
		io.WriteString(w, strings.TrimSpace(content))
	})
}

func main() {
	ctx, cancel := chromedp.NewContext(context.Background())
	defer cancel()

	ts := httptest.NewServer(writeHTML(`
<body>
<p id="content" onclick="changeText()">Original content.</p>
<script>
function changeText() {
	document.getElementById("content").textContent = "New content!"
}
</script>
</body>
	`))
	defer ts.Close()

	var outerBefore, outerAfter string
	if err := chromedp.Run(ctx,
		chromedp.Navigate(ts.URL),
		chromedp.OuterHTML("#content", &outerBefore, chromedp.ByQuery),
		chromedp.Click("#content", chromedp.ByQuery),
		chromedp.OuterHTML("#content", &outerAfter, chromedp.ByQuery),
	); err != nil {
		log.Fatal(err)
	}
	fmt.Println("OuterHTML before clicking:")
	fmt.Println(outerBefore)
	fmt.Println("OuterHTML after clicking:")
	fmt.Println(outerAfter)

}

Output:

OuterHTML before clicking:
<p id="content" onclick="changeText()">Original content.</p>
OuterHTML after clicking:
<p id="content" onclick="changeText()">New content!</p>

Index

Examples

Constants

This section is empty.

Variables

View Source 
var DefaultExecAllocatorOptions = [...]ExecAllocatorOption{
	NoFirstRun,
	NoDefaultBrowserCheck,
	Headless,

	Flag("disable-background-networking", true),
	Flag("enable-features", "NetworkService,NetworkServiceInProcess"),
	Flag("disable-background-timer-throttling", true),
	Flag("disable-backgrounding-occluded-windows", true),
	Flag("disable-breakpad", true),
	Flag("disable-client-side-phishing-detection", true),
	Flag("disable-default-apps", true),
	Flag("disable-dev-shm-usage", true),
	Flag("disable-extensions", true),
	Flag("disable-features", "site-per-process,Translate,BlinkGenPropertyTrees"),
	Flag("disable-hang-monitor", true),
	Flag("disable-ipc-flooding-protection", true),
	Flag("disable-popup-blocking", true),
	Flag("disable-prompt-on-repost", true),
	Flag("disable-renderer-backgrounding", true),
	Flag("disable-sync", true),
	Flag("force-color-profile", "srgb"),
	Flag("metrics-recording-only", true),
	Flag("safebrowsing-disable-auto-update", true),
	Flag("enable-automation", true),
	Flag("password-store", "basic"),
	Flag("use-mock-keychain", true),
}

DefaultExecAllocatorOptions are the ExecAllocator options used by NewContext if the given parent context doesn't have an allocator set up. Do not modify this global; instead, use NewExecAllocator. See ExampleExecAllocator.

Functions

func ButtonLeft 

func ButtonLeft(p *input.DispatchMouseEventParams) *input.DispatchMouseEventParams

ButtonLeft is a mouse action option to set the button clicked as the left mouse button.

func ButtonMiddle 

func ButtonMiddle(p *input.DispatchMouseEventParams) *input.DispatchMouseEventParams

ButtonMiddle is a mouse action option to set the button clicked as the middle mouse button.

func ButtonNone 

func ButtonNone(p *input.DispatchMouseEventParams) *input.DispatchMouseEventParams

ButtonNone is a mouse action option to set the button clicked as none (used for mouse movements).

func ButtonRight 

func ButtonRight(p *input.DispatchMouseEventParams) *input.DispatchMouseEventParams

ButtonRight is a mouse action option to set the button clicked as the right mouse button.

func ByID 

func ByID(s *Selector)

ByID is an element query option to select a single element by its CSS #id.

Similar to calling document.querySelector('#' + ID) in the browser.

func ByJSPath added in v0.4.0 

func ByJSPath(s *Selector)

ByJSPath is an element query option to select elements by the "JS Path" value (as shown in the Chrome DevTools UI).

Allows for the direct querying of DOM elements that otherwise cannot be retrieved using the other By* funcs, such as ShadowDOM elements.

Note: Do not use with an untrusted selector value, as any defined selector will be passed to runtime.Evaluate.

Example 
package main

import (
	"context"
	"fmt"
	"io"
	"log"
	"net/http"
	"net/http/httptest"
	"strings"

	"github.com/chromedp/cdproto/cdp"
	"github.com/chromedp/cdproto/dom"
	"github.com/chromedp/chromedp"
)

func writeHTML(content string) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "text/html")
		io.WriteString(w, strings.TrimSpace(content))
	})
}

func main() {
	ctx, cancel := chromedp.NewContext(context.Background())
	defer cancel()

	ts := httptest.NewServer(writeHTML(`
<body>
	<div id="content">cool content</div>
</body>
	`))
	defer ts.Close()

	var ids []cdp.NodeID
	var html string
	if err := chromedp.Run(ctx,
		chromedp.Navigate(ts.URL),
		chromedp.NodeIDs(`document`, &ids, chromedp.ByJSPath),
		chromedp.ActionFunc(func(ctx context.Context) error {
			var err error
			html, err = dom.GetOuterHTML().WithNodeID(ids[0]).Do(ctx)
			return err
		}),
	); err != nil {
		log.Fatal(err)
	}

	fmt.Println("Outer HTML:")
	fmt.Println(html)

}

Output:

Outer HTML:
<html><head></head><body>
	<div id="content">cool content</div>
</body></html>

func ByNodeID 

func ByNodeID(s *Selector)

ByNodeID is an element query option to select elements by their node IDs.

Uses DOM.requestChildNodes to retrieve elements with specific node IDs.

Note: must be used with []cdp.NodeID.

func ByQuery 

func ByQuery(s *Selector)

ByQuery is an element query action option to select a single element by the DOM.querySelector command.

Similar to calling document.querySelector() in the browser.

func ByQueryAll 

func ByQueryAll(s *Selector)

ByQueryAll is an element query action option to select elements by the DOM.querySelectorAll command.

Similar to calling document.querySelectorAll() in the browser.

func BySearch 

func BySearch(s *Selector)

BySearch is an element query option to select elements by the DOM.performSearch command. It matches nodes by plain text, CSS selector or XPath query.

func Cancel added in v0.2.0 

func Cancel(ctx context.Context) error

Cancel cancels a chromedp context, waits for its resources to be cleaned up, and returns any error encountered during that process.

If the context allocated a browser, the browser will be closed gracefully by Cancel. A timeout can be attached to this context to determine how long to wait for the browser to close itself: 

tctx, tcancel := context.WithTimeout(ctx, 10 * time.Second)
defer tcancel()
chromedp.Cancel(tctx)

Usually a "defer cancel()" will be enough for most use cases. However, Cancel is the better option if one wants to gracefully close a browser, or catch underlying errors happening during cancellation.

func DisableGPU added in v0.2.0 

func DisableGPU(a *ExecAllocator)

DisableGPU is the command line option to disable the GPU process.

The --disable-gpu option is a temporary workaround for a few bugs in headless mode. According to the references below, it's no longer required: - https://bugs.chromium.org/p/chromium/issues/detail?id=737678 - https://github.com/puppeteer/puppeteer/pull/2908 - https://github.com/puppeteer/puppeteer/pull/4523 But according to this reported issue, it's still required in some cases: - https://github.com/chromedp/chromedp/issues/904

func EmulateLandscape added in v0.4.0 

func EmulateLandscape(p1 *emulation.SetDeviceMetricsOverrideParams, p2 *emulation.SetTouchEmulationEnabledParams)

EmulateLandscape is an emulate viewport option to set the device viewport screen orientation in landscape primary mode and an angle of 90.

func EmulateMobile added in v0.4.0 

func EmulateMobile(p1 *emulation.SetDeviceMetricsOverrideParams, p2 *emulation.SetTouchEmulationEnabledParams)

EmulateMobile is an emulate viewport option to toggle the device viewport to display as a mobile device.

func EmulatePortrait added in v0.4.0 

func EmulatePortrait(p1 *emulation.SetDeviceMetricsOverrideParams, p2 *emulation.SetTouchEmulationEnabledParams)

EmulatePortrait is an emulate viewport option to set the device viewport screen orientation in portrait primary mode and an angle of 0.

func EmulateTouch added in v0.4.0 

func EmulateTouch(p1 *emulation.SetDeviceMetricsOverrideParams, p2 *emulation.SetTouchEmulationEnabledParams)

EmulateTouch is an emulate viewport option to enable touch emulation.

func EvalAsValue 

func EvalAsValue(p *runtime.EvaluateParams) *runtime.EvaluateParams

EvalAsValue is a evaluate option that will cause the evaluated Javascript expression to encode the result of the expression as a JSON-encoded value.

func EvalIgnoreExceptions 

func EvalIgnoreExceptions(p *runtime.EvaluateParams) *runtime.EvaluateParams

EvalIgnoreExceptions is a evaluate option that will cause Javascript evaluation to ignore exceptions.

func EvalWithCommandLineAPI 

func EvalWithCommandLineAPI(p *runtime.EvaluateParams) *runtime.EvaluateParams

EvalWithCommandLineAPI is an evaluate option to make the DevTools Command Line API available to the evaluated script.

See Evaluate for more information on how evaluate actions work.

Note: this should not be used with untrusted Javascript.

func Headless added in v0.2.0 

func Headless(a *ExecAllocator)

Headless is the command line option to run in headless mode. On top of setting the headless flag, it also hides scrollbars and mutes audio.

func IgnoreCertErrors added in v0.7.4 

func IgnoreCertErrors(a *ExecAllocator)

IgnoreCertErrors is the command line option to ignore certificate-related errors. This options is useful when you need to access an HTTPS website through a proxy.

func ListenBrowser added in v0.3.0 

func ListenBrowser(ctx context.Context, fn func(ev interface{}))

ListenBrowser adds a function which will be called whenever a browser event is received on the chromedp context. Note that this only includes browser events; command responses and target events are not included. Cancelling ctx stops the listener from receiving any more events.

Note that the function is called synchronously when handling events. The function should avoid blocking at all costs. For example, any Actions must be run via a separate goroutine (otherwise, it could result in a deadlock if the action sends CDP messages).

func ListenTarget added in v0.3.0 

func ListenTarget(ctx context.Context, fn func(ev interface{}))

ListenTarget adds a function which will be called whenever a target event is received on the chromedp context. Cancelling ctx stops the listener from receiving any more events.

Note that the function is called synchronously when handling events. The function should avoid blocking at all costs. For example, any Actions must be run via a separate goroutine (otherwise, it could result in a deadlock if the action sends CDP messages).

Example (AcceptAlert) 
package main

import (
	"context"
	"fmt"
	"io"
	"log"
	"net/http"
	"net/http/httptest"
	"strings"

	"github.com/chromedp/cdproto/page"
	"github.com/chromedp/chromedp"
)

func writeHTML(content string) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "text/html")
		io.WriteString(w, strings.TrimSpace(content))
	})
}

func main() {
	ctx, cancel := chromedp.NewContext(context.Background())
	defer cancel()

	mux := http.NewServeMux()
	mux.Handle("/second", writeHTML(``))
	ts := httptest.NewServer(writeHTML(`
<input id='alert' type='button' value='alert' onclick='alert("alert text");'/>
	`))
	defer ts.Close()

	chromedp.ListenTarget(ctx, func(ev interface{}) {
		if ev, ok := ev.(*page.EventJavascriptDialogOpening); ok {
			fmt.Println("closing alert:", ev.Message)
			go func() {
				if err := chromedp.Run(ctx,
					page.HandleJavaScriptDialog(true),
				); err != nil {
					log.Fatal(err)
				}
			}()
		}
	})

	if err := chromedp.Run(ctx,
		chromedp.Navigate(ts.URL),
		chromedp.Click("#alert", chromedp.ByID),
	); err != nil {
		log.Fatal(err)
	}

}

Output:

closing alert: alert text
Example (ConsoleLog) 
package main

import (
	"context"
	"fmt"
	"io"
	"log"
	"net/http"
	"net/http/httptest"
	"strings"

	"github.com/chromedp/cdproto/runtime"
	"github.com/chromedp/chromedp"
)

func writeHTML(content string) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "text/html")
		io.WriteString(w, strings.TrimSpace(content))
	})
}

func main() {
	ctx, cancel := chromedp.NewContext(context.Background())
	defer cancel()

	ts := httptest.NewServer(writeHTML(`
<body>
<script>
	console.log("hello js world")
	console.warn("scary warning", 123)
	null.throwsException
</script>
</body>
	`))
	defer ts.Close()

	gotException := make(chan bool, 1)
	chromedp.ListenTarget(ctx, func(ev interface{}) {
		switch ev := ev.(type) {
		case *runtime.EventConsoleAPICalled:
			fmt.Printf("* console.%s call:\n", ev.Type)
			for _, arg := range ev.Args {
				fmt.Printf("%s - %s\n", arg.Type, arg.Value)
			}
		case *runtime.EventExceptionThrown:
			// Since ts.URL uses a random port, replace it.
			s := ev.ExceptionDetails.Error()
			s = strings.ReplaceAll(s, ts.URL, "<server>")
			// V8 has changed the error messages for property access on null/undefined in version 9.3.310.
			// see: https://chromium.googlesource.com/v8/v8/+/c0fd89c3c089e888c4f4e8582e56db7066fa779b
			//      https://github.com/chromium/chromium/commit/1735cbf94c98c70ff7554a1e9e01bb9a4f91beb6
			// The message is normalized to make it compatible with the versions before this change.
			s = strings.ReplaceAll(s, "Cannot read property 'throwsException' of null", "Cannot read properties of null (reading 'throwsException')")
			fmt.Printf("* %s\n", s)
			gotException <- true
		}
	})

	if err := chromedp.Run(ctx, chromedp.Navigate(ts.URL)); err != nil {
		log.Fatal(err)
	}
	<-gotException

}

Output:

* console.log call:
string - "hello js world"
* console.warning call:
string - "scary warning"
number - 123
* exception "Uncaught" (4:6): TypeError: Cannot read properties of null (reading 'throwsException')
    at <server>/:5:7

func NewContext added in v0.2.0 

func NewContext(parent context.Context, opts ...ContextOption) (context.Context, context.CancelFunc)

NewContext creates a chromedp context from the parent context. The parent context's Allocator is inherited, defaulting to an ExecAllocator with DefaultExecAllocatorOptions.

If the parent context contains an allocated Browser, the child context inherits it, and its first Run creates a new tab on that browser. Otherwise, its first Run will allocate a new browser.

Cancelling the returned context will close a tab or an entire browser, depending on the logic described above. To cancel a context while checking for errors, see Cancel.

Note that NewContext doesn't allocate nor start a browser; that happens the first time Run is used on the context.

Example (ManyTabs) 
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/chromedp/chromedp"
)

func main() {
	// new browser, first tab
	ctx1, cancel := chromedp.NewContext(context.Background())
	defer cancel()

	// ensure the first tab is created
	if err := chromedp.Run(ctx1); err != nil {
		log.Fatal(err)
	}

	// same browser, second tab
	ctx2, _ := chromedp.NewContext(ctx1)

	// ensure the second tab is created
	if err := chromedp.Run(ctx2); err != nil {
		log.Fatal(err)
	}

	c1 := chromedp.FromContext(ctx1)
	c2 := chromedp.FromContext(ctx2)

	fmt.Printf("Same browser: %t\n", c1.Browser == c2.Browser)
	fmt.Printf("Same tab: %t\n", c1.Target == c2.Target)

}

Output:

Same browser: true
Same tab: false
Example (ReuseBrowser) 
package main

import (
	"context"
	"fmt"
	"io"
	"log"
	"net/http"
	"net/http/httptest"
	"strings"
	"time"

	"github.com/chromedp/chromedp"
)

func writeHTML(content string) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "text/html")
		io.WriteString(w, strings.TrimSpace(content))
	})
}

func main() {
	ts := httptest.NewServer(writeHTML(`
<body>
<script>
	// Show the current cookies.
	var p = document.createElement("p")
	p.innerText = document.cookie
	p.setAttribute("id", "cookies")
	document.body.appendChild(p)

	// Override the cookies.
	document.cookie = "foo=bar"
</script>
</body>
	`))
	defer ts.Close()

	// create a new browser
	ctx, cancel := chromedp.NewContext(context.Background())
	defer cancel()

	// start the browser without a timeout
	if err := chromedp.Run(ctx); err != nil {
		log.Fatal(err)
	}

	for i := 0; i < 2; i++ {
		func() {
			ctx, cancel := context.WithTimeout(ctx, time.Second)
			defer cancel()
			ctx, cancel = chromedp.NewContext(ctx)
			defer cancel()
			var cookies string
			if err := chromedp.Run(ctx,
				chromedp.Navigate(ts.URL),
				chromedp.Text("#cookies", &cookies),
			); err != nil {
				log.Fatal(err)
			}
			fmt.Printf("Cookies at i=%d: %q\n", i, cookies)
		}()
	}

}

Output:

Cookies at i=0: ""
Cookies at i=1: "foo=bar"

func NewExecAllocator added in v0.2.0 

func NewExecAllocator(parent context.Context, opts ...ExecAllocatorOption) (context.Context, context.CancelFunc)

NewExecAllocator creates a new context set up with an ExecAllocator, suitable for use with NewContext.

func NewRemoteAllocator added in v0.2.0 

func NewRemoteAllocator(parent context.Context, url string) (context.Context, context.CancelFunc)

NewRemoteAllocator creates a new context set up with a RemoteAllocator, suitable for use with NewContext. The url should point to the browser's websocket address, such as "ws://127.0.0.1:$PORT/devtools/browser/...". If the url does not contain "/devtools/browser/", it will try to detect the correct one by sending a request to "http://$HOST:$PORT/json/version".

The url with the following formats are accepted: * ws://127.0.0.1:9222/ * http://127.0.0.1:9222/

But "ws://127.0.0.1:9222/devtools/browser/" are not accepted. Because it contains "/devtools/browser/" and will be considered as a valid websocket debugger URL.

func NoDefaultBrowserCheck added in v0.2.0 

func NoDefaultBrowserCheck(a *ExecAllocator)

NoDefaultBrowserCheck is the Chrome command line option to disable the default browser check.

func NoFirstRun added in v0.2.0 

func NoFirstRun(a *ExecAllocator)

NoFirstRun is the Chrome command line option to disable the first run dialog.

func NoSandbox added in v0.2.0 

func NoSandbox(a *ExecAllocator)

NoSandbox is the Chrome command line option to disable the sandbox.

func NodeEnabled 

func NodeEnabled(s *Selector)

NodeEnabled is an element query option to wait until all queried element nodes have been sent by the browser and are enabled (ie, do not have a 'disabled' attribute).

func NodeNotPresent 

func NodeNotPresent(s *Selector)

NodeNotPresent is an element query option to wait until no elements are present that match the query.

Note: forces the expected number of element nodes to be 0.

func NodeNotVisible 

func NodeNotVisible(s *Selector)

NodeNotVisible is an element query option to wait until all queried element nodes have been sent by the browser and are not visible.

func NodeReady 

func NodeReady(s *Selector)

NodeReady is an element query option to wait until all queried element nodes have been sent by the browser.

func NodeSelected 

func NodeSelected(s *Selector)

NodeSelected is an element query option to wait until all queried element nodes have been sent by the browser and are selected (ie, has 'selected' attribute).

func NodeVisible 

func NodeVisible(s *Selector)

NodeVisible is an element query option to wait until all queried element nodes have been sent by the browser and are visible.

func Run added in v0.2.0 

func Run(ctx context.Context, actions ...Action) error

Run runs an action against context. The provided context must be a valid chromedp context, typically created via NewContext.

Note that the first time Run is called on a context, a browser will be allocated via Allocator. Thus, it's generally a bad idea to use a context timeout on the first Run call, as it will stop the entire browser.

func RunResponse added in v0.5.4 

func RunResponse(ctx context.Context, actions ...Action) (*network.Response, error)

RunResponse is an alternative to Run which can be used with a list of actions that trigger a page navigation, such as clicking on a link or button.

RunResponse will run the actions and block until a page loads, returning the HTTP response information for its HTML document. This can be useful to wait for the page to be ready, or to catch 404 status codes, for example.

Note that if the actions trigger multiple navigations, only the first is used. And if the actions trigger no navigations at all, RunResponse will block until the context is cancelled.

Example 
package main

import (
	"context"
	"fmt"
	"log"
	"net/http"
	"net/http/httptest"

	"github.com/chromedp/chromedp"
)

func main() {
	ctx, cancel := chromedp.NewContext(context.Background())
	defer cancel()

	// This server simply shows the URL path as the page title, and contains
	// a link that points to /foo.
	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "text/html")
		fmt.Fprintf(w, `
			<head><title>%s</title></head>
			<body><a id="foo" href="/foo">foo</a></body>
		`, r.URL.Path)
	}))
	defer ts.Close()

	// The Navigate action already waits until a page loads, so Title runs
	// once the page is ready.
	var firstTitle string
	if err := chromedp.Run(ctx,
		chromedp.Navigate(ts.URL),
		chromedp.Title(&firstTitle),
	); err != nil {
		log.Fatal(err)
	}
	fmt.Println("first title:", firstTitle)

	// However, actions like Click don't always trigger a page navigation,
	// so they don't wait for a page load directly. Wrapping them with
	// RunResponse does that waiting, and also obtains the HTTP response.
	resp, err := chromedp.RunResponse(ctx, chromedp.Click("#foo", chromedp.ByID))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("second status code:", resp.Status)

	// Grabbing the title again should work, as the page has finished
	// loading once more.
	var secondTitle string
	if err := chromedp.Run(ctx, chromedp.Title(&secondTitle)); err != nil {
		log.Fatal(err)
	}
	fmt.Println("second title:", secondTitle)

	// Finally, it's always possible to wrap Navigate with RunResponse, if
	// one wants the response information for that case too.
	resp, err = chromedp.RunResponse(ctx, chromedp.Navigate(ts.URL+"/bar"))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("third status code:", resp.Status)

}

Output:

first title: /
second status code: 200
second title: /foo
third status code: 200

func Targets added in v0.2.0 

func Targets(ctx context.Context) ([]*target.Info, error)

Targets lists all the targets in the browser attached to the given context.

func WaitNewTarget added in v0.4.0 

func WaitNewTarget(ctx context.Context, fn func(*target.Info) bool) <-chan target.ID

WaitNewTarget can be used to wait for the current target to open a new target. Once fn matches a new unattached target, its target ID is sent via the returned channel.

Example 
package main

import (
	"context"
	"fmt"
	"io"
	"log"
	"net/http"
	"net/http/httptest"
	"strings"

	"github.com/chromedp/cdproto/target"
	"github.com/chromedp/chromedp"
)

func writeHTML(content string) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "text/html")
		io.WriteString(w, strings.TrimSpace(content))
	})
}

func main() {
	ctx, cancel := chromedp.NewContext(context.Background())
	defer cancel()

	mux := http.NewServeMux()
	mux.Handle("/first", writeHTML(`
<input id='newtab' type='button' value='open' onclick='window.open("/second", "_blank");'/>
	`))
	mux.Handle("/second", writeHTML(``))
	ts := httptest.NewServer(mux)
	defer ts.Close()

	// Grab the first spawned tab that isn't blank.
	ch := chromedp.WaitNewTarget(ctx, func(info *target.Info) bool {
		return info.URL != ""
	})
	if err := chromedp.Run(ctx,
		chromedp.Navigate(ts.URL+"/first"),
		chromedp.Click("#newtab", chromedp.ByID),
	); err != nil {
		log.Fatal(err)
	}
	newCtx, cancel := chromedp.NewContext(ctx, chromedp.WithTargetID(<-ch))
	defer cancel()

	var urlstr string
	if err := chromedp.Run(newCtx, chromedp.Location(&urlstr)); err != nil {
		log.Fatal(err)
	}
	fmt.Println("new tab's path:", strings.TrimPrefix(urlstr, ts.URL))

}

Output:

new tab's path: /second

Types

type Action 

type Action interface {
	// Do executes the action using the provided context and frame handler.
	Do(context.Context) error
}

Action is the common interface for an action that will be executed against a context and frame handler.

func CaptureScreenshot 

func CaptureScreenshot(res *[]byte) Action

CaptureScreenshot is an action that captures/takes a screenshot of the current browser viewport.

It's supposed to act the same as the command "Capture screenshot" in Chrome. See the behavior notes of Screenshot for more information.

See the Screenshot action to take a screenshot of a specific element.

See the 'screenshot' example in the https://github.com/chromedp/examples project for an example of taking a screenshot of the entire page.

func Location 

func Location(urlstr *string) Action

Location is an action that retrieves the document location. 

func NavigationEntries(currentIndex *int64, entries *[]*page.NavigationEntry) Action

NavigationEntries is an action that retrieves the page's navigation history entries.

func Sleep 

func Sleep(d time.Duration) Action

Sleep is an empty action that calls time.Sleep with the specified duration.

Note: this is a temporary action definition for convenience, and will likely be marked for deprecation in the future, after the remaining Actions have been able to be written/tested.

func Stop 

func Stop() Action

Stop is an action that stops all navigation and pending resource retrieval.

func Title 

func Title(title *string) Action

Title is an action that retrieves the document title.

Example 
package main

import (
	"context"
	"fmt"
	"io"
	"log"
	"net/http"
	"net/http/httptest"
	"strings"

	"github.com/chromedp/chromedp"
)

func writeHTML(content string) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "text/html")
		io.WriteString(w, strings.TrimSpace(content))
	})
}

func main() {
	ctx, cancel := chromedp.NewContext(context.Background())
	defer cancel()

	ts := httptest.NewServer(writeHTML(`
<head>
	<title>fancy website title</title>
</head>
<body>
	<div id="content"></div>
</body>
	`))
	defer ts.Close()

	var title string
	if err := chromedp.Run(ctx,
		chromedp.Navigate(ts.URL),
		chromedp.Title(&title),
	); err != nil {
		log.Fatal(err)
	}
	fmt.Println(title)

}

Output:

fancy website title

type ActionFunc 

type ActionFunc func(context.Context) error

ActionFunc is a adapter to allow the use of ordinary func's as an Action.

func (ActionFunc) Do 

func (f ActionFunc) Do(ctx context.Context) error

Do executes the func f using the provided context and frame handler.

type Allocator added in v0.2.0 

type Allocator interface {
	// Allocate creates a new browser. It can be cancelled via the provided
	// context, at which point all the resources used by the browser (such
	// as temporary directories) will be freed.
	Allocate(context.Context, ...BrowserOption) (*Browser, error)

	// Wait blocks until an allocator has freed all of its resources.
	// Cancelling the allocator context will already perform this operation,
	// so normally there's no need to call Wait directly.
	Wait()
}

An Allocator is responsible for creating and managing a number of browsers.

This interface abstracts away how the browser process is actually run. For example, an Allocator implementation may reuse browser processes, or connect to already-running browsers on remote machines.

type Browser added in v0.2.0 

type Browser struct {

	// LostConnection is closed when the websocket connection to Chrome is
	// dropped. This can be useful to make sure that Browser's context is
	// cancelled (and the handler stopped) once the connection has failed.
	LostConnection chan struct{}
	// contains filtered or unexported fields
}

Browser is the high-level Chrome DevTools Protocol browser manager, handling the browser process runner, WebSocket clients, associated targets, and network, page, and DOM events.

func NewBrowser added in v0.2.0 

func NewBrowser(ctx context.Context, urlstr string, opts ...BrowserOption) (*Browser, error)

NewBrowser creates a new browser. Typically, this function wouldn't be called directly, as the Allocator interface takes care of it.

func (*Browser) Execute added in v0.2.0 

func (b *Browser) Execute(ctx context.Context, method string, params easyjson.Marshaler, res easyjson.Unmarshaler) error

func (*Browser) Process added in v0.7.2 

func (b *Browser) Process() *os.Process

Process returns the process object of the browser.

It could be nil when the browser is allocated with RemoteAllocator. It could be useful for a monitoring system to collect process metrics of the browser process. (see https://pkg.go.dev/github.com/prometheus/client_golang/prometheus#NewProcessCollector for an example)

Example: 

if process := chromedp.FromContext(ctx).Browser.Process(); process != nil {
    fmt.Printf("Browser PID: %v", process.Pid)
}

type BrowserOption added in v0.2.0 

type BrowserOption = func(*Browser)

BrowserOption is a browser option.

func WithBrowserDebugf added in v0.2.0 

func WithBrowserDebugf(f func(string, ...interface{})) BrowserOption

WithBrowserDebugf is a browser option to specify a func to log actual websocket messages.

func WithBrowserErrorf added in v0.2.0 

func WithBrowserErrorf(f func(string, ...interface{})) BrowserOption

WithBrowserErrorf is a browser option to specify a func to receive error logging.

func WithBrowserLogf added in v0.2.0 

func WithBrowserLogf(f func(string, ...interface{})) BrowserOption

WithBrowserLogf is a browser option to specify a func to receive general logging.

func WithConsolef 

func WithConsolef(f func(string, ...interface{})) BrowserOption

WithConsolef is a browser option to specify a func to receive chrome log events.

Note: NOT YET IMPLEMENTED.

func WithDialTimeout added in v0.3.0 

func WithDialTimeout(d time.Duration) BrowserOption

WithDialTimeout is a browser option to specify the timeout when dialing a browser's websocket address. The default is ten seconds; use a zero duration to not use a timeout.

type CallAction added in v0.7.4 

type CallAction Action

CallAction are actions that calls a Javascript function using runtime.CallFunctionOn.

func CallFunctionOn added in v0.7.4 

func CallFunctionOn(functionDeclaration string, res interface{}, opt CallOption, args ...interface{}) CallAction

CallFunctionOn is an action to call a Javascript function, unmarshaling the result of the function to res.

The handling of res is the same as that of Evaluate.

Do not call the following methods on runtime.CallFunctionOnParams: - WithReturnByValue: it will be set depending on the type of res; - WithArguments: pass the arguments with args instead.

Note: any exception encountered will be returned as an error.

type CallOption added in v0.7.4 

type CallOption = func(params *runtime.CallFunctionOnParams) *runtime.CallFunctionOnParams

CallOption is a function to modify the runtime.CallFunctionOnParams to provide more information.

type Conn added in v0.2.0 

type Conn struct {
	// contains filtered or unexported fields
}

Conn implements Transport with a gobwas/ws websocket connection.

func DialContext added in v0.2.0 

func DialContext(ctx context.Context, urlstr string, opts ...DialOption) (*Conn, error)

DialContext dials the specified websocket URL using gobwas/ws.

func (*Conn) Close added in v0.2.0 

func (c *Conn) Close() error

Close satisfies the io.Closer interface.

func (*Conn) Read added in v0.2.0 

func (c *Conn) Read(_ context.Context, msg *cdproto.Message) error

Read reads the next message.

func (*Conn) Write added in v0.2.0 

func (c *Conn) Write(_ context.Context, msg *cdproto.Message) error

Write writes a message.

type Context added in v0.2.0 

type Context struct {
	// Allocator is used to create new browsers. It is inherited from the
	// parent context when using NewContext.
	Allocator Allocator

	// Browser is the browser being used in the context. It is inherited
	// from the parent context when using NewContext.
	Browser *Browser

	// Target is the target to run actions (commands) against. It is not
	// inherited from the parent context, and typically each context will
	// have its own unique Target pointing to a separate browser tab (page).
	Target *Target
	// contains filtered or unexported fields
}

Context is attached to any context.Context which is valid for use with Run.

func FromContext added in v0.2.0 

func FromContext(ctx context.Context) *Context

FromContext extracts the Context data stored inside a context.Context.

type ContextOption added in v0.2.0 

type ContextOption = func(*Context)

ContextOption is a context option.

func WithBrowserOption added in v0.2.0 

func WithBrowserOption(opts ...BrowserOption) ContextOption

WithBrowserOption allows passing a number of browser options to the allocator when allocating a new browser. As such, this context option can only be used when NewContext is allocating a new browser.

func WithDebugf 

func WithDebugf(f func(string, ...interface{})) ContextOption

WithDebugf is a shortcut for WithBrowserOption(WithBrowserDebugf(f)).

func WithErrorf 

func WithErrorf(f func(string, ...interface{})) ContextOption

WithErrorf is a shortcut for WithBrowserOption(WithBrowserErrorf(f)).

func WithLogf 

func WithLogf(f func(string, ...interface{})) ContextOption

WithLogf is a shortcut for WithBrowserOption(WithBrowserLogf(f)).

func WithTargetID added in v0.3.0 

func WithTargetID(id target.ID) ContextOption

WithTargetID sets up a context to be attached to an existing target, instead of creating a new one.

type Device added in v0.4.0 

type Device interface {
	// Device returns the device info.
	Device() device.Info
}

Device is the shared interface for known device types.

See: github.com/chromedp/chromedp/device for a set of off-the-shelf devices and modes.

type DialOption added in v0.2.0 

type DialOption = func(*Conn)

DialOption is a dial option.

func WithConnDebugf added in v0.2.0 

func WithConnDebugf(f func(string, ...interface{})) DialOption

WithConnDebugf is a dial option to set a protocol logger.

type EmulateAction added in v0.4.0 

type EmulateAction Action

EmulateAction are actions that change the emulation settings for the browser.

func Emulate added in v0.4.0 

func Emulate(device Device) EmulateAction

Emulate is an action to emulate a specific device.

See: github.com/chromedp/chromedp/device for a set of off-the-shelf devices and modes.

Example 
package main

import (
	"context"
	"io/ioutil"
	"log"

	"github.com/chromedp/chromedp"
	"github.com/chromedp/chromedp/device"
)

func main() {
	ctx, cancel := chromedp.NewContext(context.Background())
	defer cancel()

	var buf []byte
	if err := chromedp.Run(ctx,
		chromedp.Emulate(device.IPhone7),
		chromedp.Navigate(`https://duckduckgo.com/`),
		chromedp.SendKeys(`input[name=q]`, "what's my user agent?\n"),
		chromedp.WaitVisible(`#zci-answer`, chromedp.ByID),
		chromedp.CaptureScreenshot(&buf),
	); err != nil {
		log.Fatal(err)
	}

	if err := ioutil.WriteFile("iphone7-ua.png", buf, 0o644); err != nil {
		log.Fatal(err)
	}

}

Output:

func EmulateReset added in v0.4.0 

func EmulateReset() EmulateAction

EmulateReset is an action to reset the device emulation.

Resets the browser's viewport, screen orientation, user-agent, and mobile/touch emulation settings to the original values the browser was started with.

func EmulateViewport added in v0.4.0 

func EmulateViewport(width, height int64, opts ...EmulateViewportOption) EmulateAction

EmulateViewport is an action to change the browser viewport.

Wraps calls to emulation.SetDeviceMetricsOverride and emulation.SetTouchEmulationEnabled.

Note: this has the effect of setting/forcing the screen orientation to landscape, and will disable mobile and touch emulation by default. If this is not the desired behavior, use the emulate viewport options EmulateOrientation (or EmulateLandscape/EmulatePortrait), EmulateMobile, and EmulateTouch, respectively.

func FullScreenshot added in v0.7.0 

func FullScreenshot(res *[]byte, quality int) EmulateAction

FullScreenshot takes a full screenshot with the specified image quality of the entire browser viewport.

It's supposed to act the same as the command "Capture full size screenshot" in Chrome. See the behavior notes of Screenshot for more information.

The valid range of the compression quality is [0..100]. When this value is 100, the image format is png; otherwise, the image format is jpeg.

Example 
package main

import (
	"context"
	"fmt"
	"io/ioutil"
	"log"

	"github.com/chromedp/chromedp"
)

func main() {
	ctx, cancel := chromedp.NewContext(context.Background())
	defer cancel()

	var buf []byte
	if err := chromedp.Run(ctx,
		chromedp.Navigate(`https://google.com`),
		chromedp.FullScreenshot(&buf, 90),
	); err != nil {
		log.Fatal(err)
	}

	if err := ioutil.WriteFile("fullScreenshot.jpeg", buf, 0644); err != nil {
		log.Fatal(err)
	}
	fmt.Println("wrote fullScreenshot.jpeg")
}

Output:

wrote fullScreenshot.jpeg

func ResetViewport added in v0.4.0 

func ResetViewport() EmulateAction

ResetViewport is an action to reset the browser viewport to the default values the browser was started with.

Note: does not modify / change the browser's emulated User-Agent, if any.

type EmulateViewportOption added in v0.4.0 

type EmulateViewportOption = func(*emulation.SetDeviceMetricsOverrideParams, *emulation.SetTouchEmulationEnabledParams)

EmulateViewportOption is the type for emulate viewport options.

func EmulateOrientation added in v0.4.0 

func EmulateOrientation(orientation emulation.OrientationType, angle int64) EmulateViewportOption

EmulateOrientation is an emulate viewport option to set the device viewport screen orientation.

func EmulateScale added in v0.4.0 

func EmulateScale(scale float64) EmulateViewportOption

EmulateScale is an emulate viewport option to set the device viewport scaling factor.

type Error 

type Error string

Error is a chromedp error. 

const (
	// ErrInvalidWebsocketMessage is the invalid websocket message.
	ErrInvalidWebsocketMessage Error = "invalid websocket message"

	// ErrInvalidDimensions is the invalid dimensions error.
	ErrInvalidDimensions Error = "invalid dimensions"

	// ErrNoResults is the no results error.
	ErrNoResults Error = "no results"

	// ErrHasResults is the has results error.
	ErrHasResults Error = "has results"

	// ErrNotVisible is the not visible error.
	ErrNotVisible Error = "not visible"

	// ErrVisible is the visible error.
	ErrVisible Error = "visible"

	// ErrDisabled is the disabled error.
	ErrDisabled Error = "disabled"

	// ErrNotSelected is the not selected error.
	ErrNotSelected Error = "not selected"

	// ErrInvalidBoxModel is the invalid box model error.
	ErrInvalidBoxModel Error = "invalid box model"

	// ErrChannelClosed is the channel closed error.
	ErrChannelClosed Error = "channel closed"

	// ErrInvalidTarget is the invalid target error.
	ErrInvalidTarget Error = "invalid target"

	// ErrInvalidContext is the invalid context error.
	ErrInvalidContext Error = "invalid context"

	// ErrPollingTimeout is the error that the timeout reached before the pageFunction returns a truthy value.
	ErrPollingTimeout Error = "waiting for function failed: timeout"
)

Error types.

func (Error) Error 

func (err Error) Error() string

Error satisfies the error interface.

type EvaluateAction added in v0.4.0 

type EvaluateAction Action

EvaluateAction are actions that evaluate Javascript expressions using runtime.Evaluate.

func Evaluate 

func Evaluate(expression string, res interface{}, opts ...EvaluateOption) EvaluateAction

Evaluate is an action to evaluate the Javascript expression, unmarshaling the result of the script evaluation to res.

When res is nil, the script result will be ignored.

When res is a *[]byte, the raw JSON-encoded value of the script result will be placed in res.

When res is a **runtime.RemoteObject, res will be set to the low-level protocol type, and no attempt will be made to convert the result. Original objects are maintained in memory until the page navigated or closed, unless they are either explicitly released or are released along with the other objects in their object group. runtime.ReleaseObject or runtime.ReleaseObjectGroup can be used to ask the browser to release original objects.

For all other cases, the result of the script will be returned "by value" (ie, JSON-encoded), and subsequently an attempt will be made to json.Unmarshal the script result to res. It returns an error if the script result is "undefined" in this case.

Note: any exception encountered will be returned as an error.

func EvaluateAsDevTools 

func EvaluateAsDevTools(expression string, res interface{}, opts ...EvaluateOption) EvaluateAction

EvaluateAsDevTools is an action that evaluates a Javascript expression as Chrome DevTools would, evaluating the expression in the "console" context, and making the Command Line API available to the script.

See Evaluate for more information on how script expressions are evaluated.

Note: this should not be used with untrusted Javascript.

type EvaluateOption 

type EvaluateOption = func(*runtime.EvaluateParams) *runtime.EvaluateParams

EvaluateOption is the type for Javascript evaluation options.

func EvalObjectGroup 

func EvalObjectGroup(objectGroup string) EvaluateOption

EvalObjectGroup is a evaluate option to set the object group.

type ExecAllocator added in v0.2.0 

type ExecAllocator struct {
	// contains filtered or unexported fields
}

ExecAllocator is an Allocator which starts new browser processes on the host machine.

Example 
package main

import (
	"bytes"
	"context"
	"fmt"
	"io/ioutil"
	"log"
	"os"
	"path/filepath"

	"github.com/chromedp/chromedp"
)

func main() {
	dir, err := ioutil.TempDir("", "chromedp-example")
	if err != nil {
		log.Fatal(err)
	}
	defer os.RemoveAll(dir)

	opts := append(chromedp.DefaultExecAllocatorOptions[:],
		chromedp.DisableGPU,
		chromedp.UserDataDir(dir),
	)

	allocCtx, cancel := chromedp.NewExecAllocator(context.Background(), opts...)
	defer cancel()

	// also set up a custom logger
	taskCtx, cancel := chromedp.NewContext(allocCtx, chromedp.WithLogf(log.Printf))
	defer cancel()

	// ensure that the browser process is started
	if err := chromedp.Run(taskCtx); err != nil {
		log.Fatal(err)
	}

	path := filepath.Join(dir, "DevToolsActivePort")
	bs, err := ioutil.ReadFile(path)
	if err != nil {
		log.Fatal(err)
	}
	lines := bytes.Split(bs, []byte("\n"))
	fmt.Printf("DevToolsActivePort has %d lines\n", len(lines))

}

Output:

DevToolsActivePort has 2 lines

func (*ExecAllocator) Allocate added in v0.2.0 

func (a *ExecAllocator) Allocate(ctx context.Context, opts ...BrowserOption) (*Browser, error)

Allocate satisfies the Allocator interface.

func (*ExecAllocator) Wait added in v0.2.0 

func (a *ExecAllocator) Wait()

Wait satisfies the Allocator interface.

type ExecAllocatorOption added in v0.2.0 

type ExecAllocatorOption = func(*ExecAllocator)

ExecAllocatorOption is a exec allocator option.

func CombinedOutput added in v0.4.0 

func CombinedOutput(w io.Writer) ExecAllocatorOption

CombinedOutput is used to set an io.Writer where stdout and stderr from the browser will be sent

func Env added in v0.4.1 

func Env(vars ...string) ExecAllocatorOption

Env is a list of generic environment variables in the form NAME=value to pass into the new Chrome process. These will be appended to the environment of the golang process as retrieved by os.Environ.

func ExecPath added in v0.2.0 

func ExecPath(path string) ExecAllocatorOption

ExecPath returns an ExecAllocatorOption which uses the given path to execute browser processes. The given path can be an absolute path to a binary, or just the name of the program to find via exec.LookPath.

func Flag added in v0.2.0 

func Flag(name string, value interface{}) ExecAllocatorOption

Flag is a generic command line option to pass a flag to Chrome. If the value is a string, it will be passed as --name=value. If it's a boolean, it will be passed as --name if value is true.

func ModifyCmdFunc added in v0.7.3 

func ModifyCmdFunc(f func(cmd *exec.Cmd)) ExecAllocatorOption

ModifyCmdFunc allows for running an arbitrary function on the browser exec.Cmd object. This overrides the default version of the command which sends SIGKILL to any open browsers when the Go program exits.

func ProxyServer added in v0.2.0 

func ProxyServer(proxy string) ExecAllocatorOption

ProxyServer is the command line option to set the outbound proxy server.

func UserAgent added in v0.2.0 

func UserAgent(userAgent string) ExecAllocatorOption

UserAgent is the command line option to set the default User-Agent header.

func UserDataDir added in v0.2.0 

func UserDataDir(dir string) ExecAllocatorOption

UserDataDir is the command line option to set the user data dir.

Note: set this option to manually set the profile directory used by Chrome. When this is not set, then a default path will be created in the /tmp directory.

func WSURLReadTimeout added in v0.8.4 

func WSURLReadTimeout(t time.Duration) ExecAllocatorOption

WSURLReadTimeout sets the waiting time for reading the WebSocket URL. The default value is 20 seconds.

func WindowSize added in v0.2.0 

func WindowSize(width, height int) ExecAllocatorOption

WindowSize is the command line option to set the initial window size.

type KeyAction 

type KeyAction Action

KeyAction are keyboard (key) input event actions.

func KeyEvent added in v0.4.0 

func KeyEvent(keys string, opts ...KeyOption) KeyAction

KeyEvent is a key action that synthesizes a keyDown, char, and keyUp event for each rune contained in keys along with any supplied key options.

Only well-known, "printable" characters will have char events synthesized.

See the SendKeys action to synthesize key events for a specific element node.

See the chromedp/kb package for implementation details and list of well-known keys.

func KeyEventNode added in v0.4.0 

func KeyEventNode(n *cdp.Node, keys string, opts ...KeyOption) KeyAction

KeyEventNode is a key action that dispatches a key event on a element node.

type KeyOption 

type KeyOption = func(*input.DispatchKeyEventParams) *input.DispatchKeyEventParams

KeyOption is a key action option.

func KeyModifiers 

func KeyModifiers(modifiers ...input.Modifier) KeyOption

KeyModifiers is a key action option to add additional modifiers on the key press.

type MouseAction 

type MouseAction Action

MouseAction are mouse input event actions

func MouseClickNode 

func MouseClickNode(n *cdp.Node, opts ...MouseOption) MouseAction

MouseClickNode is an action that dispatches a mouse left button click event at the center of a specified node.

Note that the window will be scrolled if the node is not within the window's viewport.

func MouseClickXY 

func MouseClickXY(x, y float64, opts ...MouseOption) MouseAction

MouseClickXY is an action that sends a left mouse button click (ie, mousePressed and mouseReleased event) to the X, Y location.

func MouseEvent added in v0.4.0 

func MouseEvent(typ input.MouseType, x, y float64, opts ...MouseOption) MouseAction

MouseEvent is a mouse event action to dispatch the specified mouse event type at coordinates x, y.

type MouseOption 

type MouseOption = func(*input.DispatchMouseEventParams) *input.DispatchMouseEventParams

MouseOption is a mouse action option.

func Button 

func Button(btn string) MouseOption

Button is a mouse action option to set the button to click from a string.

func ButtonModifiers 

func ButtonModifiers(modifiers ...input.Modifier) MouseOption

ButtonModifiers is a mouse action option to add additional input modifiers for a button click.

func ButtonType 

func ButtonType(button input.MouseButton) MouseOption

ButtonType is a mouse action option to set the button to click.

func ClickCount 

func ClickCount(n int) MouseOption

ClickCount is a mouse action option to set the click count. 

type NavigateAction Action

NavigateAction are actions which always trigger a page navigation, waiting for the page to load.

Note that these actions don't collect HTTP response information; for that, see RunResponse. 

func Navigate(urlstr string) NavigateAction

Navigate is an action that navigates the current frame. 

func NavigateBack() NavigateAction

NavigateBack is an action that navigates the current frame backwards in its history. 

func NavigateForward() NavigateAction

NavigateForward is an action that navigates the current frame forwards in its history. 

func NavigateToHistoryEntry(entryID int64) NavigateAction

NavigateToHistoryEntry is an action to navigate to the specified navigation entry.

func Reload 

func Reload() NavigateAction

Reload is an action that reloads the current page.

type PollAction added in v0.6.11 

type PollAction Action

PollAction are actions that will wait for a general Javascript predicate.

See Poll for details on building poll tasks.

func Poll added in v0.6.11 

func Poll(expression string, res interface{}, opts ...PollOption) PollAction

Poll is a poll action that will wait for a general Javascript predicate. It builds the predicate from a Javascript expression.

This is a copy of puppeteer's page.waitForFunction. see https://github.com/puppeteer/puppeteer/blob/v8.0.0/docs/api.md#pagewaitforfunctionpagefunction-options-args. It's named Poll intentionally to avoid messing up with the Wait* query actions. The behavior is not guaranteed to be compatible. For example, our implementation makes the poll task not survive from a navigation, and an error is raised in this case (see unit test TestPoll/NotSurviveNavigation).

Polling Options

The default polling mode is "raf", to constantly execute pageFunction in requestAnimationFrame callback. This is the tightest polling mode which is suitable to observe styling changes. The WithPollingInterval option makes it to poll the predicate with a specified interval. The WithPollingMutation option makes it to poll the predicate on every DOM mutation.

The WithPollingTimeout option specifies the maximum time to wait for the predicate returns truthy value. It defaults to 30 seconds. Pass 0 to disable timeout.

The WithPollingInFrame option specifies the frame in which to evaluate the predicate. If not specified, it will be evaluated in the root page of the current tab.

The WithPollingArgs option provides extra arguments to pass to the predicate. Only apply this option when the predicate is built from a function. See PollFunction.

func PollFunction added in v0.6.11 

func PollFunction(pageFunction string, res interface{}, opts ...PollOption) PollAction

PollFunction is a poll action that will wait for a general Javascript predicate. It builds the predicate from a Javascript function.

See Poll for details on building poll tasks.

type PollOption added in v0.6.11 

type PollOption = func(task *pollTask)

PollOption is an poll task option.

func WithPollingArgs added in v0.6.11 

func WithPollingArgs(args ...interface{}) PollOption

WithPollingArgs provides extra arguments to pass to the predicate.

func WithPollingInFrame added in v0.6.11 

func WithPollingInFrame(frame *cdp.Node) PollOption

WithPollingInFrame specifies the frame in which to evaluate the predicate. If not specified, it will be evaluated in the root page of the current tab.

func WithPollingInterval added in v0.6.11 

func WithPollingInterval(interval time.Duration) PollOption

WithPollingInterval makes it to poll the predicate with the specified interval.

func WithPollingMutation added in v0.6.11 

func WithPollingMutation() PollOption

WithPollingMutation makes it to poll the predicate on every DOM mutation.

func WithPollingTimeout added in v0.6.11 

func WithPollingTimeout(timeout time.Duration) PollOption

WithPollingTimeout specifies the maximum time to wait for the predicate returns truthy value. It defaults to 30 seconds. Pass 0 to disable timeout.

type QueryAction added in v0.4.0 

type QueryAction Action

QueryAction are element query actions that select node elements from the browser's DOM for retrieval or manipulation.

See Query for details on building element query selectors.

func AttributeValue 

func AttributeValue(sel interface{}, name string, value *string, ok *bool, opts ...QueryOption) QueryAction

AttributeValue is an element query action that retrieves the element attribute value for the first element node matching the selector.

func Attributes 

func Attributes(sel interface{}, attributes *map[string]string, opts ...QueryOption) QueryAction

Attributes is an element query action that retrieves the element attributes for the first element node matching the selector.

func AttributesAll 

func AttributesAll(sel interface{}, attributes *[]map[string]string, opts ...QueryOption) QueryAction

AttributesAll is an element query action that retrieves the element attributes for all element nodes matching the selector.

Note: this should be used with the ByQueryAll query option.

func Blur 

func Blur(sel interface{}, opts ...QueryOption) QueryAction

Blur is an element query action that unfocuses (blurs) the first element node matching the selector.

func Clear 

func Clear(sel interface{}, opts ...QueryOption) QueryAction

Clear is an element query action that clears the values of any input/textarea element nodes matching the selector.

func Click 

func Click(sel interface{}, opts ...QueryOption) QueryAction

Click is an element query action that sends a mouse click event to the first element node matching the selector.

func ComputedStyle 

func ComputedStyle(sel interface{}, style *[]*css.ComputedStyleProperty, opts ...QueryOption) QueryAction

ComputedStyle is an element query action that retrieves the computed style of the first element node matching the selector.

func Dimensions 

func Dimensions(sel interface{}, model **dom.BoxModel, opts ...QueryOption) QueryAction

Dimensions is an element query action that retrieves the box model dimensions for the first element node matching the selector.

func DoubleClick 

func DoubleClick(sel interface{}, opts ...QueryOption) QueryAction

DoubleClick is an element query action that sends a mouse double click event to the first element node matching the selector.

func Focus 

func Focus(sel interface{}, opts ...QueryOption) QueryAction

Focus is an element query action that focuses the first element node matching the selector.

func InnerHTML 

func InnerHTML(sel interface{}, html *string, opts ...QueryOption) QueryAction

InnerHTML is an element query action that retrieves the inner html of the first element node matching the selector.

func JavascriptAttribute 

func JavascriptAttribute(sel interface{}, name string, res interface{}, opts ...QueryOption) QueryAction

JavascriptAttribute is an element query action that retrieves the Javascript attribute for the first element node matching the selector.

func MatchedStyle 

func MatchedStyle(sel interface{}, style **css.GetMatchedStylesForNodeReturns, opts ...QueryOption) QueryAction

MatchedStyle is an element query action that retrieves the matched style information for the first element node matching the selector.

func NodeIDs 

func NodeIDs(sel interface{}, ids *[]cdp.NodeID, opts ...QueryOption) QueryAction

NodeIDs is an element query action that retrieves the element node IDs matching the selector.

func Nodes 

func Nodes(sel interface{}, nodes *[]*cdp.Node, opts ...QueryOption) QueryAction

Nodes is an element query action that retrieves the document element nodes matching the selector.

func OuterHTML 

func OuterHTML(sel interface{}, html *string, opts ...QueryOption) QueryAction

OuterHTML is an element query action that retrieves the outer html of the first element node matching the selector.

func Query 

func Query(sel interface{}, opts ...QueryOption) QueryAction

Query is a query action that queries the browser for specific element node(s) matching the criteria.

Query actions that target a browser DOM element node (or nodes) make use of Query, in conjunction with the After option (see below) to retrieve data or to modify the element(s) selected by the query.

For example: 

chromedp.Run(ctx, chromedp.SendKeys(`thing`, chromedp.ByID))

The above will perform a "SendKeys" action on the first element matching a browser CSS query for "#thing".

Element selection queries work in conjunction with specific actions and form the primary way of automating Tasks in the browser. They are typically written in the following form: 

Action(selector[, parameter1, ...parameterN][,result][, queryOptions...])

Where: 

Action         - the action to perform
selector       - element query selection (typically a string), that any matching node(s) will have the action applied
parameter[1-N] - parameter(s) needed for the individual action (if any)
result         - pointer to a result (if any)
queryOptions   - changes how queries are executed, or how nodes are waited for (see below)

Query Options

By* options specify the type of element query used By the browser to perform the selection query. When not specified, element queries will use BySearch (a wrapper for DOM.performSearch).

Node* options specify node conditions that cause the query to wait until the specified condition is true. When not specified, queries will use the NodeReady wait condition.

The AtLeast option alters the minimum number of nodes that must be returned by the element query. If not specified, the default value is 1.

The After option is used to specify a func that will be executed when element query has returned one or more elements, and after the node condition is true.

By Options

The BySearch (default) option enables querying for elements by plain text, CSS selector or XPath query, wrapping DOM.performSearch.

The ByID option enables querying for a single element with the matching CSS ID, wrapping DOM.querySelector. ByID is similar to calling document.querySelector('#' + ID) from within the browser.

The ByQuery option enables querying for a single element using a CSS selector, wrapping DOM.querySelector. ByQuery is similar to calling document.querySelector() from within the browser.

The ByQueryAll option enables querying for elements using a CSS selector, wrapping DOM.querySelectorAll. ByQueryAll is similar to calling document.querySelectorAll() from within the browser.

The ByJSPath option enables querying for a single element using its "JS Path" value, wrapping Runtime.evaluate. ByJSPath is similar to executing a Javascript snippet that returns a element from within the browser. ByJSPath should be used only with trusted element queries, as it is passed directly to Runtime.evaluate, and no attempt is made to sanitize the query. Useful for querying DOM elements that cannot be retrieved using other By* funcs, such as ShadowDOM elements.

Node Options

The NodeReady (default) option causes the query to wait until all element nodes matching the selector have been retrieved from the browser.

The NodeVisible option causes the query to wait until all element nodes matching the selector have been retrieved from the browser, and are visible.

The NodeNotVisible option causes the query to wait until all element nodes matching the selector have been retrieved from the browser, and are not visible.

The NodeEnabled option causes the query to wait until all element nodes matching the selector have been retrieved from the browser, and are enabled (ie, do not have a 'disabled' attribute).

The NodeSelected option causes the query to wait until all element nodes matching the selector have been retrieved from the browser, and are are selected (ie, has a 'selected' attribute).

The NodeNotPresent option causes the query to wait until there are no element nodes matching the selector.

func QueryAfter 

func QueryAfter(sel interface{}, f func(context.Context, runtime.ExecutionContextID, ...*cdp.Node) error, opts ...QueryOption) QueryAction

QueryAfter is an element query action that queries the browser for selector sel. Waits until the visibility conditions of the query have been met, after which executes f.

func RemoveAttribute 

func RemoveAttribute(sel interface{}, name string, opts ...QueryOption) QueryAction

RemoveAttribute is an element query action that removes the element attribute with name from the first element node matching the selector.

func Reset 

func Reset(sel interface{}, opts ...QueryOption) QueryAction

Reset is an element query action that resets the parent form of the first element node matching the selector.

func Screenshot 

func Screenshot(sel interface{}, picbuf *[]byte, opts ...QueryOption) QueryAction

Screenshot is an element query action that takes a screenshot of the first element node matching the selector.

It's supposed to act the same as the command "Capture node screenshot" in Chrome.

Behavior notes: the Protocol Monitor shows that the command sends the following CDP commands too:

  • Emulation.clearDeviceMetricsOverride
  • Network.setUserAgentOverride with {"userAgent": ""}
  • Overlay.setShowViewportSizeOnResize with {"show": false}

These CDP commands are not sent by chromedp. If it does not work as expected, you can try to send those commands yourself.

See CaptureScreenshot for capturing a screenshot of the browser viewport.

See the 'screenshot' example in the https://github.com/chromedp/examples project for an example of taking a screenshot of the entire page.

func ScrollIntoView 

func ScrollIntoView(sel interface{}, opts ...QueryOption) QueryAction

ScrollIntoView is an element query action that scrolls the window to the first element node matching the selector.

func SendKeys 

func SendKeys(sel interface{}, v string, opts ...QueryOption) QueryAction

SendKeys is an element query action that synthesizes the key up, char, and down events as needed for the runes in v, sending them to the first element node matching the selector.

For a complete example on how to use SendKeys, see https://github.com/chromedp/examples/tree/master/keys.

Note: when the element query matches a input[type="file"] node, then dom.SetFileInputFiles is used to set the upload path of the input node to v.

func SetAttributeValue 

func SetAttributeValue(sel interface{}, name, value string, opts ...QueryOption) QueryAction

SetAttributeValue is an element query action that sets the element attribute with name to value for the first element node matching the selector.

func SetAttributes 

func SetAttributes(sel interface{}, attributes map[string]string, opts ...QueryOption) QueryAction

SetAttributes is an element query action that sets the element attributes for the first element node matching the selector.

func SetJavascriptAttribute 

func SetJavascriptAttribute(sel interface{}, name, value string, opts ...QueryOption) QueryAction

SetJavascriptAttribute is an element query action that sets the Javascript attribute for the first element node matching the selector.

func SetUploadFiles 

func SetUploadFiles(sel interface{}, files []string, opts ...QueryOption) QueryAction

SetUploadFiles is an element query action that sets the files to upload (ie, for a input[type="file"] node) for the first element node matching the selector.

func SetValue 

func SetValue(sel interface{}, value string, opts ...QueryOption) QueryAction

SetValue is an element query action that sets the Javascript value of the first element node matching the selector.

Useful for setting an element's Javascript value, namely form, input, textarea, select, or other element with a '.value' field.

func Submit 

func Submit(sel interface{}, opts ...QueryOption) QueryAction

Submit is an element query action that submits the parent form of the first element node matching the selector.

func Text 

func Text(sel interface{}, text *string, opts ...QueryOption) QueryAction

Text is an element query action that retrieves the visible text of the first element node matching the selector.

func TextContent added in v0.4.1 

func TextContent(sel interface{}, text *string, opts ...QueryOption) QueryAction

TextContent is an element query action that retrieves the text content of the first element node matching the selector.

func Value 

func Value(sel interface{}, value *string, opts ...QueryOption) QueryAction

Value is an element query action that retrieves the Javascript value field of the first element node matching the selector.

Useful for retrieving an element's Javascript value, namely form, input, textarea, select, or any other element with a '.value' field.

func WaitEnabled 

func WaitEnabled(sel interface{}, opts ...QueryOption) QueryAction

WaitEnabled is an element query action that waits until the element matching the selector is enabled (ie, does not have attribute 'disabled').

func WaitNotPresent 

func WaitNotPresent(sel interface{}, opts ...QueryOption) QueryAction

WaitNotPresent is an element query action that waits until no elements are present matching the selector.

func WaitNotVisible 

func WaitNotVisible(sel interface{}, opts ...QueryOption) QueryAction

WaitNotVisible is an element query action that waits until the element matching the selector is not visible.

func WaitReady 

func WaitReady(sel interface{}, opts ...QueryOption) QueryAction

WaitReady is an element query action that waits until the element matching the selector is ready (ie, has been "loaded").

func WaitSelected 

func WaitSelected(sel interface{}, opts ...QueryOption) QueryAction

WaitSelected is an element query action that waits until the element matching the selector is selected (ie, has attribute 'selected').

func WaitVisible 

func WaitVisible(sel interface{}, opts ...QueryOption) QueryAction

WaitVisible is an element query action that waits until the element matching the selector is visible.

type QueryOption 

type QueryOption = func(*Selector)

QueryOption is an element query action option.

func After 

func After(f func(context.Context, runtime.ExecutionContextID, ...*cdp.Node) error) QueryOption

After is an element query option that sets a func to execute after the matched nodes have been returned by the browser, and after the node condition is true.

func AtLeast 

func AtLeast(n int) QueryOption

AtLeast is an element query option to set a minimum number of elements that must be returned by the query.

By default, a query will have a value of 1.

func ByFunc 

func ByFunc(f func(context.Context, *cdp.Node) ([]cdp.NodeID, error)) QueryOption

ByFunc is an element query action option to set the func used to select elements.

func FromNode added in v0.5.4 

func FromNode(node *cdp.Node) QueryOption

FromNode is an element query action option where a query will be run. That is, the query will only look at the node's element sub-tree. By default, or when passed nil, the document's root element will be used.

Note that, at present, BySearch and ByJSPath do not support FromNode; this option is mainly useful for ByQuery selectors.

Example 
package main

import (
	"context"
	"fmt"
	"io"
	"log"
	"net/http"
	"net/http/httptest"
	"strings"

	"github.com/chromedp/cdproto/cdp"
	"github.com/chromedp/chromedp"
)

func writeHTML(content string) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "text/html")
		io.WriteString(w, strings.TrimSpace(content))
	})
}

func main() {
	ctx, cancel := chromedp.NewContext(context.Background())
	defer cancel()

	ts := httptest.NewServer(writeHTML(`
<body>
	<p class="content">outer content</p>
	<div id="section"><p class="content">inner content</p></div>
</body>
	`))
	defer ts.Close()

	var nodes []*cdp.Node
	if err := chromedp.Run(ctx,
		chromedp.Navigate(ts.URL),
		chromedp.Nodes("#section", &nodes, chromedp.ByQuery),
	); err != nil {
		log.Fatal(err)
	}
	sectionNode := nodes[0]

	var queryRoot, queryFromNode, queryNestedSelector string
	if err := chromedp.Run(ctx,
		// Queries run from the document root by default, so Text will
		// pick the first node it finds.
		chromedp.Text(".content", &queryRoot, chromedp.ByQuery),

		// We can specify a different node to run the query from; in
		// this case, we can tailor the search within #section.
		chromedp.Text(".content", &queryFromNode, chromedp.ByQuery, chromedp.FromNode(sectionNode)),

		// A CSS selector like "#section > .content" achieves the same
		// here, but FromNode allows us to use a node obtained by an
		// entirely separate step, allowing for custom logic.
		chromedp.Text("#section > .content", &queryNestedSelector, chromedp.ByQuery),
	); err != nil {
		log.Fatal(err)
	}
	fmt.Println("Simple query from the document root:", queryRoot)
	fmt.Println("Simple query from the section node:", queryFromNode)
	fmt.Println("Nested query from the document root:", queryNestedSelector)

}

Output:

Simple query from the document root: outer content
Simple query from the section node: inner content
Nested query from the document root: inner content

func RetryInterval added in v0.8.6 

func RetryInterval(interval time.Duration) QueryOption

RetryInterval is an element query action option to set the retry interval to specify how often it should retry when it failed to select the target element(s).

The default value is 5ms.

func WaitFunc 

func WaitFunc(wait func(context.Context, *cdp.Frame, runtime.ExecutionContextID, ...cdp.NodeID) ([]*cdp.Node, error)) QueryOption

WaitFunc is an element query option to set a custom node condition wait.

type RemoteAllocator added in v0.2.0 

type RemoteAllocator struct {
	// contains filtered or unexported fields
}

RemoteAllocator is an Allocator which connects to an already running Chrome process via a websocket URL.

func (*RemoteAllocator) Allocate added in v0.2.0 

func (a *RemoteAllocator) Allocate(ctx context.Context, opts ...BrowserOption) (*Browser, error)

Allocate satisfies the Allocator interface.

func (*RemoteAllocator) Wait added in v0.2.0 

func (a *RemoteAllocator) Wait()

Wait satisfies the Allocator interface.

type Selector 

type Selector struct {
	// contains filtered or unexported fields
}

Selector holds information pertaining to an element selection query.

See Query for information on building an element selector and relevant options.

func (*Selector) Do 

func (s *Selector) Do(ctx context.Context) error

Do executes the selector, only finishing if the selector's by, wait, and after funcs succeed, or if the context is cancelled.

type Target added in v0.2.0 

type Target struct {
	SessionID target.SessionID
	TargetID  target.ID
	// contains filtered or unexported fields
}

Target manages a Chrome DevTools Protocol target.

func (*Target) Execute added in v0.2.0 

func (t *Target) Execute(ctx context.Context, method string, params easyjson.Marshaler, res easyjson.Unmarshaler) error

type Tasks 

type Tasks []Action

Tasks is a sequential list of Actions that can be used as a single Action.

func (Tasks) Do 

func (t Tasks) Do(ctx context.Context) error

Do executes the list of Actions sequentially, using the provided context and frame handler.

type Transport added in v0.2.0 

type Transport interface {
	Read(context.Context, *cdproto.Message) error
	Write(context.Context, *cdproto.Message) error
	io.Closer
}

Transport is the common interface to send/receive messages to a target.

This interface is currently used internally by Browser, but it is exposed as it will be useful as part of the public API in the future.

Source Files

View all Source files

Directories

Path Synopsis
Package device contains device emulation definitions for use with chromedp's Emulate action.
 Package device contains device emulation definitions for use with chromedp's Emulate action.
Package kb provides keyboard mappings for Chrome DOM Keys for use with input events.
 Package kb provides keyboard mappings for Chrome DOM Keys for use with input events.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.