chromedp

package module
v0.3.1-0...-d182e10 Latest Latest
Warning

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

 Go to latest Published: Jun 21, 2019 License: MIT Imports: 35 Imported by: 0

README

About chromedp GoDoc Build Status

Package chromedp is a faster, simpler way to drive browsers supporting the Chrome DevTools Protocol in Go using the without external dependencies (like Selenium or PhantomJS).

Installing

Install in the usual Go way:

go get -u github.com/seddonm1/chromedp

Examples

Refer to the GoDoc page for the documentation and examples. The examples repository contains more complex scenarios.

Frequently Asked Questions

I can't see any Chrome browser window

By default, it's run in headless mode. See DefaultExecAllocatorOptions, and an example to override said options.

I'm seeing "context canceled" errors

If the connection to the browser is dropped, the context will be cancelled, which can be an unexpected reason for this error. For example, if the browser is closed manually.

Chrome exits as soon as my Go program finishes

This is set up on Linux to avoid leaking resources. If you want Chrome to be a long-running process, start it separately and connect to it via RemoteAllocator.

Execute an action without Run results in "invalid context"

By default, a chromedp context doesn't have an executor set up. You can specify one; see issue #326.

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

Wrap it with an ActionFunc:

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

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.

Example (RetrieveHTML) 
package main

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

	"github.com/seddonm1/cdproto/network"
	"github.com/seddonm1/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()

	respBody := make(chan string)
	chromedp.ListenTarget(ctx, func(ev interface{}) {
		ev2, ok := ev.(*network.EventResponseReceived)
		if !ok {
			return
		}
		go func() {
			if err := chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {
				body, err := network.GetResponseBody(ev2.RequestID).Do(ctx)
				respBody <- string(body)
				return err
			})); err != nil {
				panic(err)
			}
		}()
	})

	var outerBefore, outerAfter string
	if err := chromedp.Run(ctx,
		network.Enable(),
		chromedp.Navigate(ts.URL),
		chromedp.OuterHTML("#content", &outerBefore),
		chromedp.Click("#content", chromedp.ByID),
		chromedp.OuterHTML("#content", &outerAfter),
	); err != nil {
		panic(err)
	}
	fmt.Println("Original response body:")
	fmt.Println(<-respBody)
	fmt.Println()
	fmt.Println("OuterHTML before clicking:")
	fmt.Println(outerBefore)
	fmt.Println("OuterHTML after clicking:")
	fmt.Println(outerAfter)

	// TODO: reenable once we fix the race with EventResponseReceived. The
	// code needs to wait for EventLoadingFinished.
	

Output:

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,TranslateUI,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 a query option to select a single element by their CSS #id.

func ByJSPath 

func ByJSPath(s *Selector)

ByJSPath is a query option to select elements by JS Path this allows selection of nodes within ShadowDOM nodes

func ByNodeID 

func ByNodeID(s *Selector)

ByNodeID is a query option to select elements by their NodeIDs.

func ByQuery 

func ByQuery(s *Selector)

ByQuery is a query option to select a single element using DOM.querySelector.

func ByQueryAll 

func ByQueryAll(s *Selector)

ByQueryAll is a query option to select elements by DOM.querySelectorAll.

func BySearch 

func BySearch(s *Selector)

BySearch is a query option via DOM.performSearch (works with both CSS and XPath queries).

func Cancel 

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.

Usually a "defer cancel()" will be enough for most use cases. This API is useful if you want to catch underlying cancel errors, such as when a temporary directory cannot be deleted.

func DisableGPU 

func DisableGPU(a *ExecAllocator)

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

func EvalAsValue 

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

EvalAsValue is a evaluate option that will cause the evaluated script 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 script 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.

Note: this should not be used with untrusted Javascript.

func Headless 

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 ListenBrowser 

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. 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.

func ListenTarget 

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. 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.

Example (AcceptAlert) 
package main

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

	"github.com/seddonm1/cdproto/page"
	"github.com/seddonm1/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 {
					panic(err)
				}
			}()
		}
	})

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

}

Output:

closing alert: alert text
Example (ConsoleLog) 
package main

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

	cdpruntime "github.com/seddonm1/cdproto/runtime"
	"github.com/seddonm1/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")
	var p = document.createElement("div");
	p.setAttribute("id", "jsFinished");
	document.body.appendChild(p);
</script>
</body>
	`))
	defer ts.Close()

	chromedp.ListenTarget(ctx, func(ev interface{}) {
		switch ev := ev.(type) {
		case *cdpruntime.EventConsoleAPICalled:
			fmt.Printf("console.%s call:\n", ev.Type)
			for _, arg := range ev.Args {
				fmt.Printf("%s - %s\n", arg.Type, arg.Value)
			}
		}
	})

	if err := chromedp.Run(ctx,
		chromedp.Navigate(ts.URL),
		chromedp.WaitVisible("#jsFinished", chromedp.ByID),
	); err != nil {
		panic(err)
	}

}

Output:

console.log call:
string - "hello js world"

func NewContext 

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.

Example (ManyTabs) 
package main

import (
	"context"
	"fmt"

	"github.com/seddonm1/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 {
		panic(err)
	}

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

	// ensure the second tab is created
	if err := chromedp.Run(ctx2); err != nil {
		panic(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

func NewExecAllocator 

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 

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.

func NoDefaultBrowserCheck 

func NoDefaultBrowserCheck(a *ExecAllocator)

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

func NoFirstRun 

func NoFirstRun(a *ExecAllocator)

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

func NoSandbox 

func NoSandbox(a *ExecAllocator)

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

func NodeEnabled 

func NodeEnabled(s *Selector)

NodeEnabled is a query option to wait until the element is enabled.

func NodeNotPresent 

func NodeNotPresent(s *Selector)

NodeNotPresent is a query option to wait until no elements are present matching the selector.

func NodeNotVisible 

func NodeNotVisible(s *Selector)

NodeNotVisible is a query option to wait until the element is not visible.

func NodeReady 

func NodeReady(s *Selector)

NodeReady is a query option to wait until the element is ready.

func NodeSelected 

func NodeSelected(s *Selector)

NodeSelected is a query option to wait until the element is selected.

func NodeVisible 

func NodeVisible(s *Selector)

NodeVisible is a query option to wait until the element is visible.

func Run 

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.

func Targets 

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

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

func WaitNewTarget 

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"
	"net/http"
	"net/http/httptest"
	"strings"

	"github.com/seddonm1/cdproto/target"
	"github.com/seddonm1/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 {
		panic(err)
	}
	newCtx, cancel := chromedp.NewContext(ctx, chromedp.WithTargetID(<-ch))
	defer cancel()

	var urlstr string
	if err := chromedp.Run(newCtx, chromedp.Location(&urlstr)); err != nil {
		panic(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 AttributeValue 

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

AttributeValue retrieves the element attribute value for the first node matching the selector.

func Attributes 

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

Attributes retrieves the element attributes for the first node matching the selector.

func AttributesAll 

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

AttributesAll retrieves the element attributes for all nodes matching the selector.

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

func Blur 

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

Blur unfocuses (blurs) the first node matching the selector.

func CaptureScreenshot 

func CaptureScreenshot(res *[]byte) Action

CaptureScreenshot captures takes a screenshot of the current viewport.

Note: this an alias for page.CaptureScreenshot.

func Clear 

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

Clear clears the values of any input/textarea nodes matching the selector.

func Click 

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

Click sends a mouse click event to the first node matching the selector.

func ComputedStyle 

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

ComputedStyle retrieves the computed style of the first node matching the selector.

func Dimensions 

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

Dimensions retrieves the box model dimensions for the first node matching the selector.

func DoubleClick 

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

DoubleClick sends a mouse double click event to the first node matching the selector.

func Evaluate 

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

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

When res is a type other than *[]byte, or **chromedp/cdproto/runtime.RemoteObject, then the result of the script evaluation will be returned "by value" (ie, JSON-encoded), and subsequently an attempt will be made to json.Unmarshal the script result to res.

Otherwise, when res is a *[]byte, the raw JSON-encoded value of the script result will be placed in res. Similarly, if res is a *runtime.RemoteObject, then res will be set to the low-level protocol type, and no attempt will be made to convert the result.

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

func EvaluateAsDevTools 

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

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.

Note: this should not be used with untrusted Javascript.

func Focus 

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

Focus focuses the first node matching the selector.

func InnerHTML 

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

InnerHTML retrieves the inner html of the first node matching the selector.

func JavascriptAttribute 

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

JavascriptAttribute retrieves the Javascript attribute for the first node matching the selector.

func KeyAction 

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

KeyAction will synthesize 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.

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

func KeyActionNode 

func KeyActionNode(n *cdp.Node, keys string, opts ...KeyOption) Action

KeyActionNode dispatches a key event on a node.

func Location 

func Location(urlstr *string) Action

Location retrieves the document location.

func MatchedStyle 

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

MatchedStyle retrieves the matched style information for the first node matching the selector.

func MouseAction 

func MouseAction(typ input.MouseType, x, y int64, opts ...MouseOption) Action

MouseAction is a mouse action.

func MouseClickNode 

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

MouseClickNode 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 int64, opts ...MouseOption) Action

MouseClickXY sends a left mouse button click (ie, mousePressed and mouseReleased event) at the X, Y location. 

func Navigate(urlstr string) Action

Navigate navigates the current frame. 

func NavigateBack() Action

NavigateBack navigates the current frame backwards in its history. 

func NavigateForward() Action

NavigateForward navigates the current frame forwards in its history. 

func NavigateToHistoryEntry(entryID int64) Action

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

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

NavigationEntries is an action to retrieve the page's navigation history entries.

func NodeIDs 

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

NodeIDs retrieves the node IDs matching the selector.

func Nodes 

func Nodes(sel interface{}, nodes *interface{}, opts ...QueryOption) Action

Nodes retrieves the document nodes matching the selector.

func OuterHTML 

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

OuterHTML retrieves the outer html of the first node matching the selector.

func Query 

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

Query is an action to query for document nodes match the specified sel and the supplied query options.

func QueryAfter 

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

QueryAfter is an action that will match the specified sel using the supplied query options, and after the visibility conditions of the query have been met, will execute f.

func Reload 

func Reload() Action

Reload reloads the current page.

func RemoveAttribute 

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

RemoveAttribute removes the element attribute with name from the first node matching the selector.

func Reset 

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

Reset is an action that resets the form of the first node matching the selector belongs to.

func Screenshot 

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

Screenshot takes a screenshot of the first node matching the selector.

func ScrollIntoView 

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

ScrollIntoView scrolls the window to the first node matching the selector.

func SendKeys 

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

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

Note: when selector 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) Action

SetAttributeValue sets the element attribute with name to value for the first node matching the selector.

func SetAttributes 

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

SetAttributes sets the element attributes for the first node matching the selector.

func SetJavascriptAttribute 

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

SetJavascriptAttribute sets the javascript attribute for the first node matching the selector.

func SetUploadFiles 

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

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

func SetValue 

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

SetValue sets the value of an element.

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 stops all navigation and pending resource retrieval.

func Submit 

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

Submit is an action that submits the form of the first node matching the selector belongs to.

func Text 

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

Text retrieves the visible text of the first node matching the selector.

func Title 

func Title(title *string) Action

Title retrieves the document title.

Example 
package main

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

	"github.com/seddonm1/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 {
		panic(err)
	}
	fmt.Println(title)

}

Output:

fancy website title

func Value 

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

Value retrieves the value of the first node matching the selector.

func WaitEnabled 

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

WaitEnabled waits until the selected element is enabled (does not have attribute 'disabled').

func WaitNotPresent 

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

WaitNotPresent waits until no elements match the specified selector.

func WaitNotVisible 

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

WaitNotVisible waits until the selected element is not visible.

func WaitReady 

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

WaitReady waits until the element is ready (ie, loaded by chromedp).

func WaitSelected 

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

WaitSelected waits until the element is selected (has attribute 'selected').

func WaitVisible 

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

WaitVisible waits until the selected element is visible.

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 

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 

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 

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 

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

type BrowserOption 

type BrowserOption func(*Browser)

BrowserOption is a browser option.

func WithBrowserDebugf 

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

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

func WithBrowserErrorf 

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

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

func WithBrowserLogf 

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 

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 Conn 

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

Conn implements Transport with a gobwas/ws websocket connection.

func DialContext 

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

DialContext dials the specified websocket URL using gobwas/ws.

func (*Conn) Close 

func (c *Conn) Close() error

Close satisfies the io.Closer interface.

func (*Conn) Read 

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

Read reads the next message.

func (*Conn) Write 

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

Write writes a message.

type Context 

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 

func FromContext(ctx context.Context) *Context

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

type ContextOption 

type ContextOption func(*Context)

ContextOption is a context option.

func WithBrowserOption 

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 

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 DialOption 

type DialOption func(*Conn)

DialOption is a dial option.

func WithConnDebugf 

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

WithConnDebugf is a dial option to set a protocol logger.

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"
)

Error types.

func (Error) Error 

func (err Error) Error() string

Error satisfies the error interface.

type EvaluateOption 

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

EvaluateOption is the type for script evaluation options.

func EvalObjectGroup 

func EvalObjectGroup(objectGroup string) EvaluateOption

EvalObjectGroup is a evaluate option to set the object group.

type ExecAllocator 

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/seddonm1/chromedp"
)

func main() {
	dir, err := ioutil.TempDir("", "chromedp-example")
	if err != nil {
		panic(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 {
		panic(err)
	}

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

}

Output:

DevToolsActivePort has 2 lines

func (*ExecAllocator) Allocate 

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

Allocate satisfies the Allocator interface.

func (*ExecAllocator) Wait 

func (a *ExecAllocator) Wait()

Wait satisfies the Allocator interface.

type ExecAllocatorOption 

type ExecAllocatorOption func(*ExecAllocator)

ExecAllocatorOption is a exec allocator option.

func CombinedOutput 

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 ExecPath 

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 

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 ProxyServer 

func ProxyServer(proxy string) ExecAllocatorOption

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

func UserAgent 

func UserAgent(userAgent string) ExecAllocatorOption

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

func UserDataDir 

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 WindowSize 

func WindowSize(width, height int) ExecAllocatorOption

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

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 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.ButtonType) 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 QueryOption 

type QueryOption func(*Selector)

QueryOption is a element query selector option.

func After 

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

After is a query option to set a func that will be executed after the wait has succeeded.

func AtLeast 

func AtLeast(n int) QueryOption

AtLeast is a query option to wait until at least n elements are returned from the query selector.

func ByFunc 

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

ByFunc is a query option to set the func used to select elements.

func WaitFunc 

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

WaitFunc is a query option to set a custom wait func.

type RemoteAllocator 

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 

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

Allocate satisfies the Allocator interface.

func (*RemoteAllocator) Wait 

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 query select action.

func (*Selector) Do 

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

Do satisfies the Action interface.

type Target 

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

Target manages a Chrome DevTools Protocol target.

func (*Target) Execute 

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

type TargetOption 

type TargetOption func(*Target)

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 

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.

Source Files

View all Source files

Directories

Path Synopsis
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.