Help us shape the future of Go! Take the 2026 Go Developer Survey

wand

package module
v0.1.0-rc.4 Latest Latest
Warning

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

 Go to latest Published: Oct 19, 2026 License: MIT Imports: 35 Imported by: 0

README

wand

OpenSSF Scorecard

A Chrome DevTools Protocol driver for browser automation and web scraping in Go.

wand descends from a snapshot of go-rod (commit 393ac0d, 2024-12-07) and is maintained independently by headlesslab. See NOTICE for attribution.

Moving an existing go-rod program over is an import swap and a short list of behaviour changes; the migration guide has both, with a Known limitations section.

中文说明

Install

go get github.com/headlesslab/wand

wand needs no driver binary. It drives a browser over the DevTools Protocol, and it finds the Chrome you already have before it downloads anything; see Browsers.

package main

import (
	"fmt"

	"github.com/headlesslab/wand"
)

func main() {
	browser := wand.New().MustConnect()
	defer browser.MustClose()

	page := browser.MustPage("https://go.dev").MustWaitStable()

	fmt.Println(page.MustElement("h1").MustText())
}

Two commands go with the library:

go install github.com/headlesslab/wand/cmd/wand-manager@latest        # launch browsers on another machine
go install github.com/headlesslab/wand/cmd/wand-fetch-browser@latest  # download the browser ahead of time

The runnable examples in examples_test.go drive pages of this repository served on a loopback port, so go test -run Example needs no network. lib/examples holds standalone programs, several of which drive live websites.

Browsers

wand is aligned to one Chrome stable at a time, the Target Chrome: the protocol layer is generated for it and the Managed browser download is pinned to it. A Companion Chromium trunk build is the second Managed browser, for deployments that cannot accept Google Chrome's terms. ✅ marks the platforms where a Managed browser archive exists; on the others wand uses a browser already installed. Every number in the table moves with each Roll, once per Chrome stable milestone.

Managed browser Linux x64 Linux arm64 macOS x64 macOS arm64 Windows x86 Windows x64
Chrome 155.0.8059.84 (Chrome for Testing) ✅ ✅ ✅ ✅ ✅ ✅
chrome-headless-shell 155.0.8059.84 ✅ ✅ ✅ ✅ ✅ ✅
Chromium 1697040 (trunk build) ✅ ❌ ✅ ✅ ✅ ✅

Protocol: devtools-protocol r1696802. Support window: Chrome 152 to 155, the Target Chrome and the three stable milestones before it.

The Target Chrome is what CI tests; the three milestones before it are best-effort. Nothing is enforced in code: a browser of another major version is launched anyway, with one line through the browser's logger naming both versions.

Browser resolution

Launch takes the first browser it finds, and downloads one only when it finds none:

  1. Launcher.Bin() in code
  2. the -wand=bin=<path> flag (lib/defaults)
  3. WAND_BROWSER_BIN
  4. a System browser: Google Chrome, Chromium or Microsoft Edge at the paths LookPath searches on this OS
  5. the Managed browser already in the cache
  6. a download of the Managed browser, hash-verified against lib/launcher/pins, from Google's buckets or npmmirror, whichever answers first

Switch the download off with WAND_BROWSER_DOWNLOAD=0 or Launcher.Download(false); then, and on a platform with nothing to download, the launch fails with launcher.ErrNoBrowser and an error listing every step tried.

Variable Values In code
WAND_BROWSER_BIN path of the browser to launch Launcher.Bin(); the flag is -wand=bin=
WAND_BROWSER_CACHE the browser cache directory Browser.RootDir
WAND_BROWSER_HOSTS URL templates separated by commas Launcher.Hosts()
WAND_BROWSER_DOWNLOAD 0 switches the download off Launcher.Download()
WAND_BROWSER_SOURCE chrome (default) or chromium Launcher.Source()
WAND_BROWSER_BINARY chrome (default) or chrome-headless-shell Launcher.Binary()

Precedence is the option set in code, then the flag, then the variable, then discovery. The cache is wand/browser under the user cache directory ($XDG_CACHE_HOME or ~/.cache on Linux, ~/Library/Caches on macOS, %LocalAppData% on Windows). The launcher's README has the whole story.

Domestic browsers are not in the discovery list: none of lbrowser, 奇安信可信浏览器, 360 安全浏览器信创版, UOS 浏览器 or 红莲花 is documented as accepting --remote-debugging-port. If yours does, name it yourself with WAND_BROWSER_BIN or Launcher.Bin(). On UOS and Kylin, browsers installed from the app store live under /opt/apps/<app id>/files/; on Loongnix, dpkg -L lbrowser names lbrowser's executable.

Platforms

Support tier What wand promises Platforms
Tier 1 built and tested with a real browser in CI, with -race, on every pull request and every push to main linux/amd64, linux/arm64, windows/amd64, darwin/arm64
Tier 2 built and vetted in CI, never tested with a browser; runtime best-effort darwin/amd64, windows/arm64, linux/loong64
Tier 3 no promise everything else

The Go floor is go 1.21, with no toolchain directive, and it is anchored to the newest Go the current openEuler LTS ships natively on every architecture it supports (ADR-0003). It moves only when a new LTS raises it.

That makes the Domestic platform build paths:

  • openEuler 24.03 LTS, on x86_64, aarch64 and loongarch64, builds wand with its own packaged Go — 1.21.4 on GA through SP2, 1.24.6 on SP3 and SP4 — and needs no toolchain download.

  • openEuler 22.03 LTS (Go 1.17.3), Kylin V10 (Go 1.13–1.15) and UOS 20 are below the floor. Either cross-compile from a machine with Go 1.21 or later, or install a Go tarball from golang.google.cn, which serves every architecture below.

    GOOS=linux GOARCH=loong64 go build ./...

  • linux/loong64 means new-world (ABI 2.0) distributions only: openEuler 22.03 LTS and 24.03 LTS SP1 and later. Kylin V10 and UOS 20 loong64 builds are old-world, are not targets, and an official Go binary crashes on them before main. Official Go has shipped linux/loong64 binaries since Go 1.21.

No Managed browser archive exists for windows/arm64, linux/loong64 or musl systems such as Alpine, so wand never downloads there; point WAND_BROWSER_BIN at a browser you installed.

Container image

ghcr.io/headlesslab/wand is ubuntu:noble with the Target Chrome inside it and wand-manager, the remote-launch server, as its entrypoint, for linux/amd64 and linux/arm64 in one manifest. The browser it carries is the pinned one above, downloaded and hash-verified at build time, so a container runs the browser wand is tested on. Its tags are published by a release and are not there yet; until then, build it from a checkout:

docker build -t ghcr.io/headlesslab/wand -f docker/Dockerfile .
docker run --rm -p 7317:7317 ghcr.io/headlesslab/wand

A wand program anywhere then launches its browsers in that container:

l := launcher.MustNewManaged("ws://127.0.0.1:7317")
browser := wand.New().Client(l.MustClient()).MustConnect()

See lib/examples/launch-managed for the whole program.

docker run --rm ghcr.io/headlesslab/wand chrome --version prints the Chrome inside, and xvfb-run is there for a visible browser.

Every published manifest carries a build-provenance attestation and an SPDX SBOM attestation in Sigstore's public log:

gh attestation verify oci://ghcr.io/headlesslab/wand:v0.1.0 -R headlesslab/wand

go run ./internal/tools/docker builds that image and the :dev one on top of it, which adds the Go and Node toolchains, and checks both the way the image Gate does; nothing is pushed. Add -suite to run wand's whole suite inside the :dev image, where utils.InContainer holds and the launcher passes --no-sandbox.

Behind a restricted network, a Go module proxy and an Ubuntu mirror are build arguments:

docker build -t ghcr.io/headlesslab/wand -f docker/Dockerfile \
  --build-arg goproxy=https://goproxy.cn,direct \
  --build-arg apt_mirror=https://your-mirror.example/ubuntu .

Releases

One release per Chrome stable milestone, cut after the Roll that moves the pins, with bug-fix patches in between. versions.json takes one row per release — the wand version beside the Target Chrome, Protocol roll and Companion Chromium it carried — appended by the release workflow, so you can match a browser fleet to a wand version. It is empty until the first release.

Until 1.0 a minor may break and a patch never does, so go get -u=patch is always safe (ADR-0008).

Roadmap

  • Baseline release: the go-rod snapshot renamed to github.com/headlesslab/wand, built and tested against current Chrome, with the protocol layer, browser acquisition and dependency chain brought current. In progress.
  • API modernization: planned. It will change the API in a later minor.
  • Stealth: planned. wand ships no evasion code today.

No dates and no ordering promises.

Documentation

Overview

Package wand is a high-level driver directly based on DevTools Protocol.

Example (Basic)

This example opens a search page, searches for "git", and then gets the element that gives the description for Git.

The page is one of this repository's own, under fixtures/examples, served on a loopback port: every example here drives a local page rather than a live website, so the whole set runs offline. Where an example calls fixtureURL, pass the address of the site you automate instead. 

// Launch a new browser with default options, and connect to it.
browser := wand.New().MustConnect()

// Even you forget to close, wand will close it after main process ends.
defer browser.MustClose()

// Create a new page
page := browser.MustPage(fixtureURL("search.html")).MustWaitStable()

// Trigger the search input with hotkey "/"
page.Keyboard.MustType(input.Slash)

// We use css selector to get the search input element and input "git"
page.MustElement("#query").MustInput("git").MustType(input.Enter)

// Wait until css selector get the element then get the text content of it.
text := page.MustElementR("span", "most widely used").MustText()

fmt.Println(text)

// Get all input elements. wand supports query elements by css selector, xpath, and regex.
// For more detailed usage, check the query_test.go file.
fmt.Println("Found", len(page.MustElements("input")), "input elements")

// Eval js on the page
page.MustEval(`() => console.log("hello world")`)

// Pass parameters as json objects to the js function. This MustEval will result 3
fmt.Println("1 + 2 =", page.MustEval(`(a, b) => a + b`, 1, 2).Int())

// When eval on an element, "this" in the js is the current DOM element.
fmt.Println(page.MustElement("title").MustEval(`() => this.innerText`).String())

Output:
Git is the most widely used version control system.
Found 3 input elements
1 + 2 = 3
git - wand search
Example (Context_and_EachEvent) 
browser := wand.New().MustConnect()
defer browser.MustClose()

page := browser.MustPage(fixtureURL("search.html")).MustWaitLoad()

page, cancel := page.WithCancel()

go func() {
	time.Sleep(time.Second)
	cancel()
}()

// It's a blocking method, it will wait until the context is cancelled
page.EachEvent(func(_ *proto.PageLifecycleEvent) {})()

if page.GetContext().Err() == context.Canceled {
	fmt.Println("cancelled")
}

Output:
cancelled
Example (Context_and_timeout)

wand use https://golang.org/pkg/context to handle cancellations for IO blocking operations, most times it's timeout. Context will be recursively passed to all sub-methods. For example, methods like Page.Context(ctx) will return a clone of the page with the ctx, all the methods of the returned page will use the ctx if they have IO blocking operations. Page.Timeout or Page.WithCancel is just a shortcut for Page.Context. Of course, Browser or Element works the same way. 

browser := wand.New().MustConnect()
defer browser.MustClose()

page := browser.MustPage(fixtureURL("search.html"))

title := page.
	// Set a 5-second timeout for all chained methods
	Timeout(5 * time.Second).

	// The total time for MustWaitLoad and MustElement must be less than 5 seconds
	MustWaitLoad().
	MustElement("title").

	// Methods after CancelTimeout won't be affected by the 5-second timeout
	CancelTimeout().

	// Set a 10-second timeout for all chained methods
	Timeout(10 * time.Second).

	// Panics if it takes more than 10 seconds
	MustText()

fmt.Println(title)

// The two code blocks below are basically the same:
{
	page.Timeout(5 * time.Second).MustElement("a").CancelTimeout()
}
{
	// Use this way you can customize your own way to cancel long-running task
	page, cancel := page.WithCancel()

	cancelled := make(chan struct{})
	go func() {
		defer close(cancelled)
		time.Sleep(time.Second) // cancel it a second from now
		cancel()
	}()

	page.MustElement("a")

	<-cancelled
}

Output:
wand search
Example (Customize_browser_launch)

Shows how we can further customize the browser with the launcher library. Usually you use launcher lib to set the browser's command line flags (switches). Doc for flags: https://peter.sh/experiments/chromium-command-line-switches

This example has no output comment, so it is compiled but never run: it goes through a proxy of your own, which this repository does not ship. 

package main

import (
	"fmt"

	"github.com/headlesslab/wand"
	"github.com/headlesslab/wand/lib/launcher"
)

func main() {
	// The address of a proxy you run yourself, such as the one the CLI tool
	// "mitmproxy --proxyauth user:pass" listens on. An example of this
	// repository names no port of its own, so fill this in before you run it.
	var proxyAddress string

	url := launcher.New().
		Proxy(proxyAddress).         // set flag "--proxy-server=<proxyAddress>"
		Delete("use-mock-keychain"). // delete flag "--use-mock-keychain"
		MustLaunch()

	browser := wand.New().ControlURL(url).MustConnect()
	defer browser.MustClose()

	// So that we don't have to self issue certs for MITM
	browser.MustIgnoreCertErrors(true)

	// Adding authentication to the proxy, for the next auth request.
	go browser.MustHandleAuth("user", "pass")()

	fmt.Println(browser.MustPage("https://mdn.dev/").MustElement("title").MustText())
}
Example (Customize_retry_strategy)

Shows how to change the retry/polling options that is used to query elements. This is useful when you want to customize the element query retry logic. 

browser := wand.New().MustConnect()
defer browser.MustClose()

page := browser.MustPage(fixtureURL("search.html"))

// sleep for 0.5 seconds before every retry
sleeper := func() utils.Sleeper {
	return func(context.Context) error {
		time.Sleep(time.Second / 2)
		return nil
	}
}
el, _ := page.Sleeper(sleeper).Element("input")
fmt.Println(el.MustProperty("name"))

// If sleeper is nil page.ElementE will query without retrying.
// If nothing found it will return an error.
el, err := page.Sleeper(wand.NotFoundSleeper).Element("input")
if errors.Is(err, &wand.ElementNotFoundError{}) {
	fmt.Println("element not found")
} else if err != nil {
	panic(err)
}

fmt.Println(el.MustProperty("name"))

Output:
q
q
Example (Direct_cdp)

When wand doesn't have a feature that you need. You can easily call the cdp to achieve it. List of cdp API: https://github.com/headlesslab/wand/tree/main/lib/proto 

package main

import (
	"context"
	"fmt"

	"github.com/headlesslab/wand"
	"github.com/headlesslab/wand/lib/proto"
)

func main() {
	browser := wand.New().MustConnect()
	defer browser.MustClose()

	page := browser.MustPage()

	// wand doesn't have a method to enable AD blocking,
	// but you can call cdp interface directly to achieve it.

	// The two code blocks below are equal to enable AD blocking

	{
		_ = proto.PageSetAdBlockingEnabled{
			Enabled: true,
		}.Call(page)
	}

	{
		// Interact with the cdp JSON API directly
		_, _ = page.Call(context.TODO(), "", "Page.setAdBlockingEnabled", map[string]bool{
			"enabled": true,
		})
	}

	fmt.Println("done")

}

Output:
done
Example (Disable_headless_to_debug)

Shows how to disable headless mode and debug. wand provides a lot of debug options, you can set them with setter methods or use environment variables. Doc for environment variables: https://pkg.go.dev/github.com/headlesslab/wand/lib/defaults

This example has no output comment, so it is compiled but never run: it puts a browser window on the screen and then blocks in utils.Pause, which needs a display and a person in front of it. 

// Headless runs the browser on foreground, you can also use flag "-wand=show"
// Devtools opens the tab in each new tab opened automatically
l := launcher.New().
	Headless(false).
	Devtools(true)

defer l.Cleanup()

url := l.MustLaunch()

// Trace shows verbose debug information for each action executed
// SlowMotion is a debug related function that waits 2 seconds between
// each action, making it easier to inspect what your code is doing.
browser := wand.New().
	ControlURL(url).
	Trace(true).
	SlowMotion(2 * time.Second).
	MustConnect()

// ServeMonitor plays screenshots of each tab. This feature is extremely
// useful when debugging with headless mode.
// You can also enable it with flag "-wand=monitor"
launcher.Open(browser.ServeMonitor(""))

defer browser.MustClose()

page := browser.MustPage(fixtureURL("search.html"))

page.MustElement("#query").MustInput("git").MustType(input.Enter)

text := page.MustElementR("span", "most widely used").MustText()

fmt.Println(text)

utils.Pause() // pause goroutine
Example (Download_file) 
browser := wand.New().MustConnect()
defer browser.MustClose()

page := browser.MustPage(fixtureURL("download.html"))

wait := browser.MustWaitDownload()

page.MustElementR("a", "DOWNLOAD THE SAMPLE FILE").MustClick()

data := wait()

_ = utils.OutputFile(outFile("note.txt"), data)

fmt.Println(string(data))

Output:
A sample file for the download example.
Example (Error_handling)

We use "Must" prefixed functions to write example code. But in production you may want to use the no-prefix version of them. About why we use "Must" as the prefix, it's similar to https://golang.org/pkg/regexp/#MustCompile 

browser := wand.New().MustConnect()
defer browser.MustClose()

page := browser.MustPage(fixtureURL("search.html"))

// We use Go's standard way to check error types, no magic.
check := func(err error) {
	var evalErr *wand.EvalError
	if errors.Is(err, context.DeadlineExceeded) { // timeout error
		fmt.Println("timeout err")
	} else if errors.As(err, &evalErr) { // eval error
		fmt.Println(evalErr.LineNumber)
	} else if err != nil {
		fmt.Println("can't handle", err)
	}
}

// The two code blocks below are doing the same thing in two styles:

// The block below is better for debugging or quick scripting. We use panic to short-circuit logics.
// So that we can take advantage of fluent interface (https://en.wikipedia.org/wiki/Fluent_interface)
// and fail-fast (https://en.wikipedia.org/wiki/Fail-fast).
// This style will reduce code, but it may also catch extra errors (less consistent and precise).
{
	err := wand.Try(func() {
		fmt.Println(page.MustElement("a").MustHTML()) // use "Must" prefixed functions
	})
	check(err)
}

// The block below is better for production code. It's the standard way to handle errors.
// Usually, this style is more consistent and precise.
{
	el, err := page.Element("a")
	if err != nil {
		check(err)
		return
	}
	html, err := el.HTML()
	if err != nil {
		check(err)
		return
	}
	fmt.Println(html)
}

Output:
<a href="./about.html">About</a>
<a href="./about.html">About</a>
Example (Eval_reuse_remote_object)

Shows how to share a remote object reference between two Eval. 

package main

import (
	"fmt"

	"github.com/headlesslab/wand"
)

func main() {
	browser := wand.New().MustConnect()
	defer browser.MustClose()

	page := browser.MustPage()

	// ByObject keeps the function in the browser and hands back a reference to
	// it, instead of copying its return value into Go.
	fn := page.MustEvaluate(wand.Eval(`() => n => n * 2`).ByObject())

	// Pass the reference to another Eval, which calls it in the browser.
	res := page.MustEval(`(f, n) => f(n)`, fn, 21)

	fmt.Println(res.Int())

}

Output:
42
Example (Handle_events)

Shows how to listen for events. 

browser := wand.New().MustConnect()
defer browser.MustClose()

page := browser.MustPage()

done := make(chan struct{})

// Listen for all events of console output.
go page.EachEvent(func(e *proto.RuntimeConsoleAPICalled) {
	if e.Type == proto.RuntimeConsoleAPICalledTypeLog {
		fmt.Println(page.MustObjectsToJSON(e.Args))
		close(done)
	}
})()

wait := page.WaitEvent(&proto.PageLoadEventFired{})
page.MustNavigate(fixtureURL("search.html"))
wait()

// EachEvent allows us to achieve the same functionality as above.
if false {
	// Subscribe events before they happen, run the "wait()" to start consuming
	// the events. We can return an optional stop signal to unsubscribe events.
	wait := page.EachEvent(func(_ *proto.PageLoadEventFired) (stop bool) {
		return true
	})
	page.MustNavigate(fixtureURL("search.html"))
	wait()
}

// Or the for-loop style to handle events to do the same thing above.
if false {
	page.MustNavigate(fixtureURL("search.html"))

	for msg := range page.Event() {
		e := proto.PageLoadEventFired{}
		if msg.Load(&e) {
			break
		}
	}
}

page.MustEval(`() => console.log("hello", "world")`)

<-done

Output:
[hello world]
Example (Hijack_requests)

Shows how to intercept requests and modify both the request and the response. The entire process of hijacking one request: 

browser --req-> wand ---> server ---> wand --res-> browser

The --req-> and --res-> are the parts that can be modified. 

browser := wand.New().MustConnect()
defer browser.MustClose()

router := browser.HijackRequests()
defer router.MustStop()

router.MustAdd("*.js", func(ctx *wand.Hijack) {
	// Here we update the request's header. wand gives functionality to
	// change or update all parts of the request. Refer to the documentation
	// for more information.
	ctx.Request.Req().Header.Set("My-Header", "test")

	// LoadResponse runs the default request to the destination of the request.
	// Not calling this will require you to mock the entire response.
	// This can be done with the SetXxx (Status, Header, Body) functions on the
	// ctx.Response struct.
	_ = ctx.LoadResponse(http.DefaultClient, true)

	// Here we append some code to every js file.
	// The code will update the document title to "hi"
	ctx.Response.SetBody(ctx.Response.Body() + "\n document.title = 'hi' ")
})

go router.Run()

browser.MustPage(fixtureURL("hijack.html")).MustWait(`() => document.title === 'hi'`)

fmt.Println("done")

Output:
done
Example (Load_extension)

This example has no output comment, so it is compiled but never run: an extension needs a browser with a window on screen, and a run has no display. Reason: https://bugs.chromium.org/p/chromium/issues/detail?id=706008#c5 You can use XVFB to get rid of it: https://github.com/headlesslab/wand/blob/main/lib/examples/launch-managed/main.go 

extPath, _ := filepath.Abs("fixtures/chrome-extension")

u := launcher.New().
	// Must use abs path for an extension
	Set("load-extension", extPath).
	Headless(false).
	MustLaunch()

browser := wand.New().ControlURL(u).MustConnect()
defer browser.MustClose()

page := browser.MustPage(fixtureURL("search.html"))

page.MustWait(`() => document.title === 'test-extension'`)

fmt.Println("ok")
Example (Log_cdp_traffic) 
l := launcher.New()
defer l.Cleanup()

client := cdp.New().
	// Here we can customize how to log the requests, responses, and events transferred between wand and the browser.
	// This one reports the navigations only, so that the example's output is the same on every run.
	Logger(utils.Log(func(args ...interface{}) {
		switch v := args[0].(type) {
		case *cdp.Request:
			if v.Method == "Page.navigate" {
				fmt.Printf("request: %s\n", v.Method)
			}
		}
	})).
	Start(cdp.MustConnectWS(l.MustLaunch()))

browser := wand.New().Client(client).MustConnect()
defer browser.MustClose()

browser.MustPage(fixtureURL("search.html"))

Output:
request: Page.navigate
Example (Page_pdf) 
browser := wand.New().MustConnect()
defer browser.MustClose()

page := browser.MustPage(fixtureURL("tall.html")).MustWaitLoad()

// simple version
page.MustPDF(outFile("my.pdf"))

// customized version
pdf, _ := page.PDF(&proto.PagePrintToPDF{
	PaperWidth:  lazyjson.Num(8.5),
	PaperHeight: lazyjson.Num(11),
	PageRanges:  "1-3",
})
_ = utils.OutputFile(outFile("custom.pdf"), pdf)

fmt.Println("done")

Output:
done
Example (Page_screenshot) 
browser := wand.New().MustConnect()
defer browser.MustClose()

page := browser.MustPage(fixtureURL("search.html")).MustWaitLoad()

// simple version
page.MustScreenshot(outFile("my.png"))

// customization version
img, _ := page.Screenshot(true, &proto.PageCaptureScreenshot{
	Format:  proto.PageCaptureScreenshotFormatJpeg,
	Quality: lazyjson.Int(90),
	Clip: &proto.PageViewport{
		X:      0,
		Y:      0,
		Width:  300,
		Height: 200,
		Scale:  1,
	},
	FromSurface: true,
})
_ = utils.OutputFile(outFile("my.jpg"), img)

fmt.Println("done")

Output:
done
Example (Page_scroll_screenshot) 
browser := wand.New().MustConnect()
defer browser.MustClose()

// capture entire browser viewport, returning jpg with quality=90
img, err := browser.MustPage(fixtureURL("tall.html")).MustWaitStable().ScrollScreenshot(&wand.ScrollScreenshotOptions{
	Format:  proto.PageCaptureScreenshotFormatJpeg,
	Quality: lazyjson.Int(90),
})
if err != nil {
	panic(err)
}

_ = utils.OutputFile(outFile("scroll.jpg"), img)

fmt.Println("done")

Output:
done
Example (Race_selectors)

Show how to handle multiple results of an action. Such as when you login a page, the result can be success or wrong password. 

// The login fixture takes any username, and "wand" as the password.
const username = "gopher"
const password = "wand"

browser := wand.New().MustConnect()
defer browser.MustClose()

page := browser.MustPage(fixtureURL("login.html"))

page.MustElement("#id_login").MustInput(username)
page.MustElement("#id_password").MustInput(password).MustType(input.Enter)

// It will keep retrying until one selector has found a match
elm := page.Race().Element(".nav-user-icon-base").MustHandle(func(e *wand.Element) {
	// print the username after successful login
	fmt.Println(*e.MustAttribute("title"))
}).Element("[data-cy=sign-in-error]").MustDo()

if elm.MustMatches("[data-cy=sign-in-error]") {
	// when wrong username or password
	panic(elm.MustText())
}

Output:
gopher
Example (States)

Shows how to update the state of the current page. In this example we enable the network domain. 

package main

import (
	"fmt"

	"github.com/headlesslab/wand"
	"github.com/headlesslab/wand/lib/proto"
)

func main() {
	browser := wand.New().MustConnect()
	defer browser.MustClose()

	page := browser.MustPage()

	// LoadState detects whether the network domain is enabled or not.
	fmt.Println(page.LoadState(&proto.NetworkEnable{}))

	_ = proto.NetworkEnable{}.Call(page)

	// Check if the network domain is successfully enabled.
	fmt.Println(page.LoadState(&proto.NetworkEnable{}))

}

Output:
false
true
Example (Wait_for_animation)

wand uses mouse cursor to simulate clicks, so if a button is moving because of animation, the click may not work as expected. We usually use WaitStable to make sure the target isn't changing anymore. 

browser := wand.New().MustConnect()
defer browser.MustClose()

page := browser.MustPage(fixtureURL("modal.html"))

page.MustWaitLoad().MustElement("[data-target='#dialog']").MustClick()

saveBtn := page.MustElementR("#dialog button", "Close")

// Here, WaitStable will wait until the button's position and size become stable.
saveBtn.MustWaitStable().MustClick().MustWaitInvisible()

fmt.Println("done")

Output:
done
Example (Wait_for_request)

When you want to wait for an ajax request to complete, this example will be useful. 

browser := wand.New().MustConnect()
defer browser.MustClose()

page := browser.MustPage(fixtureURL("suggestions.html")).MustWaitLoad()

// Start to analyze request events
wait := page.MustWaitRequestIdle()

// This will trigger the search ajax request
page.MustElement("#search-input").MustClick().MustInput("lisp")

// Wait until there's no active requests
wait()

// We want to make sure that after waiting, there are some autocomplete
// suggestions available.
fmt.Println(len(page.MustElements(".suggestion-link")) > 0)

Output:
true

Index

Examples

Constants

This section is empty.

Variables

View Source 
var DefaultLogger = log.New(os.Stdout, "[wand] ", log.LstdFlags)

DefaultLogger for wand.

View Source 
var DefaultSleeper = func() utils.Sleeper {
	return utils.BackoffSleeper(100*time.Millisecond, time.Second, nil)
}

DefaultSleeper generates the default sleeper for retry, it uses backoff to grow the interval. The growth looks like: 

A(0) = 100ms, A(n) = A(n-1) * random[1.9, 2.1), A(n) < 1s

Why the default is not RequestAnimationFrame or DOM change events is because of if a retry never ends it can easily flood the program. But you can always easily config it into what you want.

View Source 
var ErrPoolCleanedUp = errors.New("pool has been cleaned up")

ErrPoolCleanedUp is what [Pool[T].Get] returns after [Pool[T].Cleanup].

Functions

func NotFoundSleeper 

func NotFoundSleeper() utils.Sleeper

NotFoundSleeper returns ErrElementNotFound on the first call.

func Try 

func Try(fn func()) (err error)

Try try fn with recover, return the panic as wand.ErrTry.

Types

type Browser 

type Browser struct {
	// BrowserContextID is the id for incognito window
	BrowserContextID proto.BrowserBrowserContextID
	// contains filtered or unexported fields
}

Browser represents the browser. It doesn't depends on file system, it should work with remote browser seamlessly. To check the env var you can use to quickly enable options from CLI, check here: https://pkg.go.dev/github.com/headlesslab/wand/lib/defaults

Example (Pool)

We can use wand.BrowserPool to concurrently control and reuse browsers. 

// Create a new browser pool with a limit of 3
pool := wand.NewBrowserPool(3)

// Create a function that returns a new browser instance
create := func() *wand.Browser {
	browser := wand.New().MustConnect()
	return browser
}

// Use the browser instances in separate goroutines
var wg sync.WaitGroup
for i := 0; i < 3; i++ {
	wg.Add(1)
	go func() {
		defer wg.Done()

		// Get a browser instance from the pool
		browser := pool.MustGet(create)

		// Put the instance back to the pool after we're done,
		// so the instance can be reused by other goroutines.
		defer pool.Put(browser)

		// Use the browser instance
		page := browser.MustPage(fixtureURL("search.html")).MustWaitLoad()
		fmt.Println(page.MustInfo().Title)
	}()
}

// Wait for all the goroutines to finish
wg.Wait()

// Cleanup the pool by closing all the browser instances
pool.Cleanup(func(p *wand.Browser) {
	p.MustClose()
})

Output:
wand search
wand search
wand search

func New 

func New() *Browser

New creates a controller. DefaultDevice to emulate is set to devices.LaptopWithMDPIScreen.Landscape(), it will change the default user-agent and can make the actual view area smaller than the browser window on headful mode, you can use Browser.NoDefaultDevice to disable it.

func (*Browser) Call 

func (b *Browser) Call(ctx context.Context, sessionID, methodName string, params interface{}) (res []byte, err error)

Call implements the proto.Client to call raw cdp interface directly.

func (*Browser) CancelTimeout 

func (b *Browser) CancelTimeout() *Browser

CancelTimeout cancels the current timeout context and returns a clone with the parent context.

func (*Browser) Client 

func (b *Browser) Client(c CDPClient) *Browser

Client set the cdp client.

func (*Browser) Close 

func (b *Browser) Close() error

Close the browser. A browser Browser.Connect launched itself is wand's own: Close also waits for its process to exit and removes its temporary user data directory, so nothing is left behind; one that does not take the close is killed at once, one that takes it and does not exit within the launcher's bound is killed then (launcher.Launcher.Cleanup).

func (*Browser) Connect 

func (b *Browser) Connect() error

Connect to the browser and start to control it. Without a client or a control URL it launches a browser through launcher.New, whose Browser resolution takes an explicit path, then a System browser, then a Managed browser, downloaded only as a last resort. Once connected, a browser of another major version than the Target Chrome's gets one line through the logger, and no refusal.

func (*Browser) Context 

func (b *Browser) Context(ctx context.Context) *Browser

Context returns a clone with the specified ctx for chained sub-operations.

func (*Browser) ControlURL 

func (b *Browser) ControlURL(url string) *Browser

ControlURL set the url to remote control browser.

func (*Browser) DefaultDevice 

func (b *Browser) DefaultDevice(d devices.Device) *Browser

DefaultDevice sets the default device for new page to emulate in the future. Default is devices.LaptopWithMDPIScreen. Set it to devices.Clear to disable it.

func (*Browser) DisableDomain 

func (b *Browser) DisableDomain(sessionID proto.TargetSessionID, req proto.Request) (restore func())

DisableDomain and returns a restore function to restore previous state.

func (*Browser) EachEvent 

func (b *Browser) EachEvent(callbacks ...interface{}) (wait func())

EachEvent is similar to Page.EachEvent, but catches events of the entire browser.

func (*Browser) EnableDomain 

func (b *Browser) EnableDomain(sessionID proto.TargetSessionID, req proto.Request) (restore func())

EnableDomain and returns a restore function to restore previous state.

func (*Browser) Event 

func (b *Browser) Event() <-chan *Message

Event of the browser.

func (*Browser) GetContext 

func (b *Browser) GetContext() context.Context

GetContext of current instance.

func (*Browser) GetCookies 

func (b *Browser) GetCookies() ([]*proto.NetworkCookie, error)

GetCookies from the browser.

func (*Browser) HandleAuth 

func (b *Browser) HandleAuth(username, password string) func() error

HandleAuth for the next basic HTTP authentication. It will prevent the popup that requires user to input user name and password. Ref: https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication

func (*Browser) HijackRequests 

func (b *Browser) HijackRequests() *HijackRouter

HijackRequests same as Page.HijackRequests, but can intercept requests of the entire browser.

func (*Browser) IgnoreCertErrors 

func (b *Browser) IgnoreCertErrors(enable bool) error

IgnoreCertErrors switch. If enabled, all certificate errors will be ignored.

func (*Browser) Incognito 

func (b *Browser) Incognito() (*Browser, error)

Incognito creates a new incognito browser.

func (*Browser) LoadState 

func (b *Browser) LoadState(sessionID proto.TargetSessionID, method proto.Request) (has bool)

LoadState into the method, sessionID can be empty.

func (*Browser) Logger 

func (b *Browser) Logger(l utils.Logger) *Browser

Logger overrides the default log functions for tracing.

func (*Browser) Monitor 

func (b *Browser) Monitor(url string) *Browser

Monitor address to listen if not empty. Shortcut for Browser.ServeMonitor.

func (*Browser) MustClose 

func (b *Browser) MustClose()

MustClose is similar to Browser.Close.

func (*Browser) MustConnect 

func (b *Browser) MustConnect() *Browser

MustConnect is similar to Browser.Connect.

func (*Browser) MustGetCookies 

func (b *Browser) MustGetCookies() []*proto.NetworkCookie

MustGetCookies is similar to Browser.GetCookies.

func (*Browser) MustHandleAuth 

func (b *Browser) MustHandleAuth(username, password string) (wait func())

MustHandleAuth is similar to Browser.HandleAuth.

func (*Browser) MustIgnoreCertErrors 

func (b *Browser) MustIgnoreCertErrors(enable bool) *Browser

MustIgnoreCertErrors is similar to Browser.IgnoreCertErrors.

func (*Browser) MustIncognito 

func (b *Browser) MustIncognito() *Browser

MustIncognito is similar to Browser.Incognito.

func (*Browser) MustPage 

func (b *Browser) MustPage(url ...string) *Page

MustPage is similar to Browser.Page. The url list will be joined by "/".

func (*Browser) MustPageFromTargetID 

func (b *Browser) MustPageFromTargetID(targetID proto.TargetTargetID) *Page

MustPageFromTargetID is similar to [Browser.PageFromTargetID].

func (*Browser) MustPages 

func (b *Browser) MustPages() Pages

MustPages is similar to Browser.Pages.

func (*Browser) MustSetCookies 

func (b *Browser) MustSetCookies(cookies ...*proto.NetworkCookie) *Browser

MustSetCookies is similar to Browser.SetCookies. If the len(cookies) is 0 it will clear all the cookies.

func (*Browser) MustVersion 

func (b *Browser) MustVersion() *proto.BrowserGetVersionResult

MustVersion is similar to Browser.Version.

func (*Browser) MustWaitDownload 

func (b *Browser) MustWaitDownload() func() []byte

MustWaitDownload is similar to Browser.WaitDownload. It will read the file into bytes then remove the file.

func (*Browser) NoDefaultDevice 

func (b *Browser) NoDefaultDevice() *Browser

NoDefaultDevice is the same as Browser.DefaultDevice(devices.Clear).

func (*Browser) Page 

func (b *Browser) Page(opts proto.TargetCreateTarget) (p *Page, err error)

Page creates a new browser tab. If opts.URL is empty, the default target will be "about:blank". With a URL, it returns once the document has committed, as Page.Navigate does.

func (*Browser) PageFromSession 

func (b *Browser) PageFromSession(sessionID proto.TargetSessionID) *Page

PageFromSession is used for low-level debugging.

func (*Browser) PageFromTarget 

func (b *Browser) PageFromTarget(targetID proto.TargetTargetID) (*Page, error)

PageFromTarget gets or creates a Page instance.

func (*Browser) Pages 

func (b *Browser) Pages() (Pages, error)

Pages retrieves all visible pages.

func (*Browser) RemoveState 

func (b *Browser) RemoveState(key interface{})

RemoveState a state.

func (*Browser) ServeMonitor 

func (b *Browser) ServeMonitor(host string) string

ServeMonitor starts the monitor server. The reason why not to use "chrome://inspect/#devices" is one target cannot be driven by multiple controllers.

func (*Browser) SetCookies 

func (b *Browser) SetCookies(cookies []*proto.NetworkCookieParam) error

SetCookies to the browser. If the cookies is nil it will clear all the cookies.

func (*Browser) Sleeper 

func (b *Browser) Sleeper(sleeper func() utils.Sleeper) *Browser

Sleeper returns a clone with the specified sleeper for chained sub-operations.

func (*Browser) SlowMotion 

func (b *Browser) SlowMotion(delay time.Duration) *Browser

SlowMotion set the delay for each control action, such as the simulation of the human inputs.

func (*Browser) Timeout 

func (b *Browser) Timeout(d time.Duration) *Browser

Timeout returns a clone with the specified total timeout of all chained sub-operations.

func (*Browser) Trace 

func (b *Browser) Trace(enable bool) *Browser

Trace enables/disables the visual tracing of the input actions on the page.

func (*Browser) Version 

func (b *Browser) Version() (*proto.BrowserGetVersionResult, error)

Version info of the browser.

func (*Browser) WaitDownload 

func (b *Browser) WaitDownload(dir string) func() (info *proto.PageDownloadWillBegin)

WaitDownload returns a helper to get the next download file. The file path will be: 

filepath.Join(dir, info.GUID)

Page.downloadWillBegin and Page.downloadProgress are deprecated in the protocol and still fire; moving to their Browser domain successors is API modernization, so the deprecation is silenced below.

func (*Browser) WaitEvent 

func (b *Browser) WaitEvent(e proto.Event) (wait func())

WaitEvent waits for the next event for one time. It will also load the data into the event object.

func (*Browser) WithCancel 

func (b *Browser) WithCancel() (*Browser, func())

WithCancel returns a clone with a context cancel function.

func (*Browser) WithPanic 

func (b *Browser) WithPanic(fail func(interface{})) *Browser

WithPanic returns a browser clone with the specified panic function. The fail must stop the current goroutine's execution immediately, such as use runtime.Goexit or panic inside it.

type CDPClient 

type CDPClient interface {
	Event() <-chan *cdp.Event
	Call(ctx context.Context, sessionID, method string, params interface{}) ([]byte, error)
}

CDPClient is usually used to make wand side-effect free. Such as proxy all IO of wand.

type CoveredError 

type CoveredError struct {
	*Element
}

CoveredError error.

func (*CoveredError) Error 

func (e *CoveredError) Error() string

Error ...

func (*CoveredError) Is 

func (e *CoveredError) Is(err error) bool

Is interface.

func (*CoveredError) Unwrap 

func (e *CoveredError) Unwrap() error

Unwrap ...

type Element 

type Element struct {
	Object *proto.RuntimeRemoteObject
	// contains filtered or unexported fields
}

Element represents the DOM element.

func (*Element) Attribute 

func (el *Element) Attribute(name string) (*string, error)

Attribute of the DOM object. Attribute vs Property: https://stackoverflow.com/questions/6003819/what-is-the-difference-between-properties-and-attributes-in-html

func (*Element) BackgroundImage 

func (el *Element) BackgroundImage() ([]byte, error)

BackgroundImage returns the css background-image of the element.

func (*Element) Blur 

func (el *Element) Blur() error

Blur removes focus from the element.

func (*Element) Call 

func (el *Element) Call(ctx context.Context, sessionID, methodName string, params interface{}) (res []byte, err error)

Call implements the proto.Client.

func (*Element) CancelTimeout 

func (el *Element) CancelTimeout() *Element

CancelTimeout cancels the current timeout context and returns a clone with the parent context.

func (*Element) CanvasToImage 

func (el *Element) CanvasToImage(format string, quality float64) ([]byte, error)

CanvasToImage get image data of a canvas. The default format is image/png. The default quality is 0.92. doc: https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toDataURL

func (*Element) Click 

func (el *Element) Click(button proto.InputMouseButton, clickCount int) error

Click will press then release the button just like a human. Before the action, it will try to scroll to the element, hover the mouse over it, wait until the it's interactable and enabled.

func (*Element) ContainsElement 

func (el *Element) ContainsElement(target *Element) (bool, error)

ContainsElement check if the target is equal or inside the element.

func (*Element) Context 

func (el *Element) Context(ctx context.Context) *Element

Context returns a clone with the specified ctx for chained sub-operations.

func (*Element) Describe 

func (el *Element) Describe(depth int, pierce bool) (*proto.DOMNode, error)

Describe the current element. The depth is the maximum depth at which children should be retrieved, defaults to 1, use -1 for the entire subtree or provide an integer larger than 0. The pierce decides whether or not iframes and shadow roots should be traversed when returning the subtree. The returned proto.DOMNode.NodeID will always be empty, because NodeID is not stable (when proto.DOMDocumentUpdated is fired all NodeID on the page will be reassigned to another value) we don't recommend using the NodeID, instead, use the proto.DOMBackendNodeID to identify the element.

func (*Element) Disabled 

func (el *Element) Disabled() (bool, error)

Disabled checks if the element is disabled.

func (*Element) Element 

func (el *Element) Element(selector string) (*Element, error)

Element returns the first child that matches the css selector.

func (*Element) ElementByJS 

func (el *Element) ElementByJS(opts *EvalOptions) (*Element, error)

ElementByJS returns the element from the return value of the js.

func (*Element) ElementR 

func (el *Element) ElementR(selector, jsRegex string) (*Element, error)

ElementR returns the first child element that matches the css selector and its text matches the jsRegex.

func (*Element) ElementX 

func (el *Element) ElementX(xPath string) (*Element, error)

ElementX returns the first child that matches the XPath selector.

func (*Element) Elements 

func (el *Element) Elements(selector string) (Elements, error)

Elements returns all elements that match the css selector.

func (*Element) ElementsByJS 

func (el *Element) ElementsByJS(opts *EvalOptions) (Elements, error)

ElementsByJS returns the elements from the return value of the js.

func (*Element) ElementsX 

func (el *Element) ElementsX(xpath string) (Elements, error)

ElementsX returns all elements that match the XPath selector.

func (*Element) Equal 

func (el *Element) Equal(elm *Element) (bool, error)

Equal checks if the two elements are equal.

func (*Element) Eval 

func (el *Element) Eval(js string, params ...interface{}) (*proto.RuntimeRemoteObject, error)

Eval is a shortcut for Element.Evaluate with AwaitPromise, ByValue and AutoExp set to true.

func (*Element) Evaluate 

func (el *Element) Evaluate(opts *EvalOptions) (*proto.RuntimeRemoteObject, error)

Evaluate is just a shortcut of Page.Evaluate with This set to current element.

func (*Element) Focus 

func (el *Element) Focus() error

Focus sets focus on the specified element. Before the action, it will try to scroll to the element.

func (*Element) Frame 

func (el *Element) Frame() (*Page, error)

Frame creates a page instance that represents the iframe.

func (*Element) GetContext 

func (el *Element) GetContext() context.Context

GetContext of current instance.

func (*Element) GetSessionID 

func (el *Element) GetSessionID() proto.TargetSessionID

GetSessionID interface.

func (*Element) GetXPath 

func (el *Element) GetXPath(optimized bool) (string, error)

GetXPath returns the xpath of the element.

func (*Element) HTML 

func (el *Element) HTML() (string, error)

HTML of the element.

func (*Element) Has 

func (el *Element) Has(selector string) (bool, *Element, error)

Has an element that matches the css selector.

func (*Element) HasR 

func (el *Element) HasR(selector, jsRegex string) (bool, *Element, error)

HasR returns true if a child element that matches the css selector and its text matches the jsRegex.

func (*Element) HasX 

func (el *Element) HasX(selector string) (bool, *Element, error)

HasX an element that matches the XPath selector.

func (*Element) Hover 

func (el *Element) Hover() error

Hover the mouse over the center of the element. Before the action, it will try to scroll to the element and wait until it's interactable.

func (*Element) Input 

func (el *Element) Input(text string) error

Input focuses on the element and input text to it. Before the action, it will scroll to the element, wait until it's visible, enabled and writable. To empty the input you can use something like 

el.SelectAllText().MustInput("")

func (*Element) InputColor 

func (el *Element) InputColor(color string) error

InputColor focuses on the element and inputs a color string to it. Before the action, it will scroll to the element, wait until it's visible, enabled and writable.

func (*Element) InputTime 

func (el *Element) InputTime(t time.Time) error

InputTime focuses on the element and input time to it. Before the action, it will scroll to the element, wait until it's visible, enabled and writable. It will wait until the element is visible, enabled and writable.

func (*Element) Interactable 

func (el *Element) Interactable() (pt *proto.Point, err error)

Interactable checks if the element is interactable with cursor. The cursor can be mouse, finger, stylus, etc. If not interactable err will be ErrNotInteractable, such as when covered by a modal,.

func (*Element) KeyActions 

func (el *Element) KeyActions() (*KeyActions, error)

KeyActions is similar with Page.KeyActions. Before the action, it will try to scroll to the element and focus on it.

func (*Element) Matches 

func (el *Element) Matches(selector string) (bool, error)

Matches checks if the element can be selected by the css selector.

func (*Element) MoveMouseOut 

func (el *Element) MoveMouseOut() error

MoveMouseOut of the current element.

func (*Element) MustAttribute 

func (el *Element) MustAttribute(name string) *string

MustAttribute is similar to Element.Attribute.

func (*Element) MustBackgroundImage 

func (el *Element) MustBackgroundImage() []byte

MustBackgroundImage is similar to Element.BackgroundImage.

func (*Element) MustBlur 

func (el *Element) MustBlur() *Element

MustBlur is similar to Element.Blur.

func (*Element) MustCanvasToImage 

func (el *Element) MustCanvasToImage() []byte

MustCanvasToImage is similar to Element.CanvasToImage.

func (*Element) MustClick 

func (el *Element) MustClick() *Element

MustClick is similar to Element.Click.

func (*Element) MustContainsElement 

func (el *Element) MustContainsElement(target *Element) bool

MustContainsElement is similar to Element.ContainsElement.

func (*Element) MustDescribe 

func (el *Element) MustDescribe() *proto.DOMNode

MustDescribe is similar to Element.Describe.

func (*Element) MustDisabled 

func (el *Element) MustDisabled() bool

MustDisabled is similar to Element.Disabled.

func (*Element) MustDoubleClick 

func (el *Element) MustDoubleClick() *Element

MustDoubleClick is similar to Element.Click.

func (*Element) MustElement 

func (el *Element) MustElement(selector string) *Element

MustElement is similar to Element.Element.

func (*Element) MustElementByJS 

func (el *Element) MustElementByJS(js string, params ...interface{}) *Element

MustElementByJS is similar to Element.ElementByJS.

func (*Element) MustElementR 

func (el *Element) MustElementR(selector, regex string) *Element

MustElementR is similar to Element.ElementR.

func (*Element) MustElementX 

func (el *Element) MustElementX(xpath string) *Element

MustElementX is similar to Element.ElementX.

func (*Element) MustElements 

func (el *Element) MustElements(selector string) Elements

MustElements is similar to Element.Elements.

func (*Element) MustElementsByJS 

func (el *Element) MustElementsByJS(js string, params ...interface{}) Elements

MustElementsByJS is similar to Element.ElementsByJS.

func (*Element) MustElementsX 

func (el *Element) MustElementsX(xpath string) Elements

MustElementsX is similar to Element.ElementsX.

func (*Element) MustEqual 

func (el *Element) MustEqual(elm *Element) bool

MustEqual is similar to Element.Equal.

func (*Element) MustEval 

func (el *Element) MustEval(js string, params ...interface{}) lazyjson.JSON

MustEval is similar to Element.Eval.

func (*Element) MustFocus 

func (el *Element) MustFocus() *Element

MustFocus is similar to Element.Focus.

func (*Element) MustFrame 

func (el *Element) MustFrame() *Page

MustFrame is similar to Element.Frame.

func (*Element) MustGetXPath 

func (el *Element) MustGetXPath(optimized bool) string

MustGetXPath is similar to Element.GetXPath.

func (*Element) MustHTML 

func (el *Element) MustHTML() string

MustHTML is similar to Element.HTML.

func (*Element) MustHas 

func (el *Element) MustHas(selector string) bool

MustHas is similar to Element.Has.

func (*Element) MustHasR 

func (el *Element) MustHasR(selector, regex string) bool

MustHasR is similar to Element.HasR.

func (*Element) MustHasX 

func (el *Element) MustHasX(selector string) bool

MustHasX is similar to Element.HasX.

func (*Element) MustHover 

func (el *Element) MustHover() *Element

MustHover is similar to Element.Hover.

func (*Element) MustInput 

func (el *Element) MustInput(text string) *Element

MustInput is similar to Element.Input.

func (*Element) MustInputColor 

func (el *Element) MustInputColor(color string) *Element

MustInputColor is similar to Element.InputColor.

func (*Element) MustInputTime 

func (el *Element) MustInputTime(t time.Time) *Element

MustInputTime is similar to Element.Input.

func (*Element) MustInteractable 

func (el *Element) MustInteractable() bool

MustInteractable is similar to Element.Interactable.

func (*Element) MustKeyActions 

func (el *Element) MustKeyActions() *KeyActions

MustKeyActions is similar to Element.KeyActions.

func (*Element) MustMatches 

func (el *Element) MustMatches(selector string) bool

MustMatches is similar to Element.Matches.

func (*Element) MustMoveMouseOut 

func (el *Element) MustMoveMouseOut() *Element

MustMoveMouseOut is similar to Element.MoveMouseOut.

func (*Element) MustNext 

func (el *Element) MustNext() *Element

MustNext is similar to Element.Next.

func (*Element) MustParent 

func (el *Element) MustParent() *Element

MustParent is similar to Element.Parent.

func (*Element) MustParents 

func (el *Element) MustParents(selector string) Elements

MustParents is similar to Element.Parents.

func (*Element) MustPrevious 

func (el *Element) MustPrevious() *Element

MustPrevious is similar to Element.Previous.

func (*Element) MustProperty 

func (el *Element) MustProperty(name string) lazyjson.JSON

MustProperty is similar to Element.Property.

func (*Element) MustRelease 

func (el *Element) MustRelease()

MustRelease is similar to Element.Release.

func (*Element) MustRemove 

func (el *Element) MustRemove()

MustRemove is similar to Element.Remove.

func (*Element) MustResource 

func (el *Element) MustResource() []byte

MustResource is similar to Element.Resource.

func (*Element) MustScreenshot 

func (el *Element) MustScreenshot(toFile ...string) []byte

MustScreenshot is similar to Element.Screenshot.

func (*Element) MustScrollIntoView 

func (el *Element) MustScrollIntoView() *Element

MustScrollIntoView is similar to Element.ScrollIntoView.

func (*Element) MustSelect 

func (el *Element) MustSelect(selectors ...string) *Element

MustSelect is similar to Element.Select.

func (*Element) MustSelectAllText 

func (el *Element) MustSelectAllText() *Element

MustSelectAllText is similar to Element.SelectAllText.

func (*Element) MustSelectText 

func (el *Element) MustSelectText(regex string) *Element

MustSelectText is similar to Element.SelectText.

func (*Element) MustSetFiles 

func (el *Element) MustSetFiles(paths ...string) *Element

MustSetFiles is similar to Element.SetFiles.

func (*Element) MustShadowRoot 

func (el *Element) MustShadowRoot() *Element

MustShadowRoot is similar to Element.ShadowRoot.

func (*Element) MustShape 

func (el *Element) MustShape() *proto.DOMGetContentQuadsResult

MustShape is similar to Element.Shape.

func (*Element) MustTap 

func (el *Element) MustTap() *Element

MustTap is similar to Element.Tap.

func (*Element) MustText 

func (el *Element) MustText() string

MustText is similar to Element.Text.

func (*Element) MustType 

func (el *Element) MustType(keys ...input.Key) *Element

MustType is similar to Element.Type.

func (*Element) MustVisible 

func (el *Element) MustVisible() bool

MustVisible is similar to Element.Visible.

func (*Element) MustWait 

func (el *Element) MustWait(js string, params ...interface{}) *Element

MustWait is similar to Element.Wait.

func (*Element) MustWaitEnabled 

func (el *Element) MustWaitEnabled() *Element

MustWaitEnabled is similar to Element.WaitEnabled.

func (*Element) MustWaitInteractable 

func (el *Element) MustWaitInteractable() *Element

MustWaitInteractable is similar to Element.WaitInteractable.

func (*Element) MustWaitInvisible 

func (el *Element) MustWaitInvisible() *Element

MustWaitInvisible is similar to Element.WaitInvisible..

func (*Element) MustWaitLoad 

func (el *Element) MustWaitLoad() *Element

MustWaitLoad is similar to Element.WaitLoad.

func (*Element) MustWaitStable 

func (el *Element) MustWaitStable() *Element

MustWaitStable is similar to Element.WaitStable.

func (*Element) MustWaitVisible 

func (el *Element) MustWaitVisible() *Element

MustWaitVisible is similar to Element.WaitVisible.

func (*Element) MustWaitWritable 

func (el *Element) MustWaitWritable() *Element

MustWaitWritable is similar to Element.WaitWritable.

func (*Element) Next 

func (el *Element) Next() (*Element, error)

Next returns the next sibling element in the DOM tree.

func (*Element) Overlay 

func (el *Element) Overlay(msg string) (removeOverlay func())

Overlay msg on the element.

func (*Element) Page 

func (el *Element) Page() *Page

Page of the element.

func (*Element) Parent 

func (el *Element) Parent() (*Element, error)

Parent returns the parent element in the DOM tree.

func (*Element) Parents 

func (el *Element) Parents(selector string) (Elements, error)

Parents that match the selector.

func (*Element) Previous 

func (el *Element) Previous() (*Element, error)

Previous returns the previous sibling element in the DOM tree.

func (*Element) Property 

func (el *Element) Property(name string) (lazyjson.JSON, error)

Property of the DOM object. Property vs Attribute: https://stackoverflow.com/questions/6003819/what-is-the-difference-between-properties-and-attributes-in-html

func (*Element) Release 

func (el *Element) Release() error

Release is a shortcut for Page.Release current element.

func (*Element) Remove 

func (el *Element) Remove() error

Remove the element from the page.

func (*Element) Resource 

func (el *Element) Resource() ([]byte, error)

Resource returns the "src" content of current element. Such as the jpg of <img src="a.jpg">.

func (*Element) Screenshot 

func (el *Element) Screenshot(format proto.PageCaptureScreenshotFormat, quality int) ([]byte, error)

Screenshot of the area of the element.

func (*Element) ScrollIntoView 

func (el *Element) ScrollIntoView() error

ScrollIntoView scrolls the current element into the visible area of the browser window if it's not already within the visible area.

func (*Element) Select 

func (el *Element) Select(selectors []string, selected bool, t SelectorType) error

Select the children option elements that match the selectors. Before the action, it will scroll to the element, wait until it's visible. If no option matches the selectors, it will return [ErrElementNotFound].

func (*Element) SelectAllText 

func (el *Element) SelectAllText() error

SelectAllText selects all text Before the action, it will try to scroll to the element and focus on it.

func (*Element) SelectText 

func (el *Element) SelectText(regex string) error

SelectText selects the text that matches the regular expression. Before the action, it will try to scroll to the element and focus on it.

func (*Element) SetFiles 

func (el *Element) SetFiles(paths []string) error

SetFiles of the current file input element.

func (*Element) ShadowRoot 

func (el *Element) ShadowRoot() (*Element, error)

ShadowRoot returns the shadow root of this element.

func (*Element) Shape 

func (el *Element) Shape() (*proto.DOMGetContentQuadsResult, error)

Shape of the DOM element content. The shape is a group of 4-sides polygons. A 4-sides polygon is not necessary a rectangle. 4-sides polygons can be apart from each other. For example, we use 2 4-sides polygons to describe the shape below: 

  ____________          ____________
 /        ___/    =    /___________/    +     _________
/________/                                   /________/

func (*Element) Sleeper 

func (el *Element) Sleeper(sleeper func() utils.Sleeper) *Element

Sleeper returns a clone with the specified sleeper for chained sub-operations.

func (*Element) String 

func (el *Element) String() string

String interface.

func (*Element) Tap 

func (el *Element) Tap() error

Tap will scroll to the button and tap it just like a human. Before the action, it will try to scroll to the element and wait until it's interactable and enabled.

func (*Element) Text 

func (el *Element) Text() (string, error)

Text that the element displays.

func (*Element) Timeout 

func (el *Element) Timeout(d time.Duration) *Element

Timeout returns a clone with the specified total timeout of all chained sub-operations.

func (*Element) Type 

func (el *Element) Type(keys ...input.Key) error

Type is similar with Keyboard.Type. Before the action, it will try to scroll to the element and focus on it.

func (*Element) Visible 

func (el *Element) Visible() (bool, error)

Visible returns true if the element is visible on the page.

func (*Element) Wait 

func (el *Element) Wait(opts *EvalOptions) error

Wait until the js returns true.

func (*Element) WaitEnabled 

func (el *Element) WaitEnabled() error

WaitEnabled until the element is not disabled. Doc for disabled: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/disabled

func (*Element) WaitInteractable 

func (el *Element) WaitInteractable() (pt *proto.Point, err error)

WaitInteractable waits for the element to be interactable. It will try to scroll to the element on each try.

func (*Element) WaitInvisible 

func (el *Element) WaitInvisible() error

WaitInvisible until the element invisible.

func (*Element) WaitLoad 

func (el *Element) WaitLoad() error

WaitLoad for element like <img>.

func (*Element) WaitStable 

func (el *Element) WaitStable(d time.Duration) error

WaitStable waits until no shape or position change for d duration. Be careful, d is not the max wait timeout, it's the least stable time. If you want to set a timeout you can use the Element.Timeout function.

func (*Element) WaitStableRAF 

func (el *Element) WaitStableRAF() error

WaitStableRAF waits until no shape or position change for 2 consecutive animation frames. If you want to wait animation that is triggered by JS not CSS, you'd better use Element.WaitStable. About animation frame: https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame

func (*Element) WaitVisible 

func (el *Element) WaitVisible() error

WaitVisible until the element is visible.

func (*Element) WaitWritable 

func (el *Element) WaitWritable() error

WaitWritable until the element is not readonly. Doc for readonly: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/readonly

func (*Element) WithCancel 

func (el *Element) WithCancel() (*Element, func())

WithCancel returns a clone with a context cancel function.

func (*Element) WithPanic 

func (el *Element) WithPanic(fail func(interface{})) *Element

WithPanic returns an element clone with the specified panic function. The fail must stop the current goroutine's execution immediately, such as use runtime.Goexit or panic inside it.

type ElementNotFoundError 

type ElementNotFoundError struct{}

ElementNotFoundError error.

func (*ElementNotFoundError) Error 

func (e *ElementNotFoundError) Error() string

type Elements 

type Elements []*Element

Elements provides some helpers to deal with element list.

func (Elements) Empty 

func (els Elements) Empty() bool

Empty returns true if the list is empty.

func (Elements) First 

func (els Elements) First() *Element

First returns the first element, if the list is empty returns nil.

func (Elements) Last 

func (els Elements) Last() *Element

Last returns the last element, if the list is empty returns nil.

type EvalError 

type EvalError struct {
	*proto.RuntimeExceptionDetails
}

EvalError error.

func (*EvalError) Error 

func (e *EvalError) Error() string

func (*EvalError) Is 

func (e *EvalError) Is(err error) bool

Is interface.

type EvalOptions 

type EvalOptions struct {
	// If enabled the eval result will be a plain JSON value.
	// If disabled the eval result will be a reference of a remote js object.
	ByValue bool

	AwaitPromise bool

	// ThisObj represents the "this" object in the JS
	ThisObj *proto.RuntimeRemoteObject

	// JS function definition to execute.
	JS string

	// JSArgs represents the arguments that will be passed to JS.
	// If an argument is [*proto.RuntimeRemoteObject] type, the corresponding remote object will be used.
	// Or it will be passed as a plain JSON value.
	// When an arg in the args is a *js.Function, the arg will be cached on the page's js context.
	// When the arg.Name exists in the page's cache, it reuse the cache without sending
	// the definition to the browser again.
	// Useful when you need to eval a huge js expression many times.
	JSArgs []interface{}

	// Whether execution should be treated as initiated by user in the UI.
	UserGesture bool
}

EvalOptions for Page.Evaluate.

func Eval 

func Eval(js string, args ...interface{}) *EvalOptions

Eval creates a EvalOptions with ByValue set to true.

func (*EvalOptions) ByObject 

func (e *EvalOptions) ByObject() *EvalOptions

ByObject disables ByValue.

func (*EvalOptions) ByPromise 

func (e *EvalOptions) ByPromise() *EvalOptions

ByPromise enables AwaitPromise.

func (*EvalOptions) ByUser 

func (e *EvalOptions) ByUser() *EvalOptions

ByUser enables UserGesture.

func (*EvalOptions) String 

func (e *EvalOptions) String() string

String interface.

func (*EvalOptions) This 

func (e *EvalOptions) This(obj *proto.RuntimeRemoteObject) *EvalOptions

This set the obj as ThisObj.

type ExpectElementError 

type ExpectElementError struct {
	*proto.RuntimeRemoteObject
}

ExpectElementError error.

func (*ExpectElementError) Error 

func (e *ExpectElementError) Error() string

func (*ExpectElementError) Is 

func (e *ExpectElementError) Is(err error) bool

Is interface.

type ExpectElementsError 

type ExpectElementsError struct {
	*proto.RuntimeRemoteObject
}

ExpectElementsError error.

func (*ExpectElementsError) Error 

func (e *ExpectElementsError) Error() string

func (*ExpectElementsError) Is 

func (e *ExpectElementsError) Is(err error) bool

Is interface.

type Hijack 

type Hijack struct {
	Request  *HijackRequest
	Response *HijackResponse
	OnError  func(error)

	// Skip to next handler
	Skip bool

	// CustomState is used to store things for this context
	CustomState interface{}
	// contains filtered or unexported fields
}

Hijack context.

func (*Hijack) ContinueRequest 

func (h *Hijack) ContinueRequest(cq *proto.FetchContinueRequest)

ContinueRequest without hijacking. The RequestID will be set by the router, you don't have to set it.

func (*Hijack) LoadResponse 

func (h *Hijack) LoadResponse(client *http.Client, loadBody bool) error

LoadResponse will send request to the real destination and load the response as default response to override. The request body goes out with its length and can be sent more than once: by the client on a 307 or 308 redirect and on an HTTP/2 stream the server refused, and by a later LoadResponse.

func (*Hijack) MustLoadResponse 

func (h *Hijack) MustLoadResponse()

MustLoadResponse is similar to Hijack.LoadResponse.

type HijackRequest 

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

HijackRequest context.

func (*HijackRequest) Body 

func (ctx *HijackRequest) Body() string

Body of the request, devtools API doesn't support binary data yet, only string can be captured.

func (*HijackRequest) Header 

func (ctx *HijackRequest) Header(key string) string

Header via a key.

func (*HijackRequest) Headers 

func (ctx *HijackRequest) Headers() proto.NetworkHeaders

Headers of request.

func (*HijackRequest) IsNavigation 

func (ctx *HijackRequest) IsNavigation() bool

IsNavigation determines whether the request is a navigation request.

func (*HijackRequest) JSONBody 

func (ctx *HijackRequest) JSONBody() lazyjson.JSON

JSONBody of the request.

func (*HijackRequest) Method 

func (ctx *HijackRequest) Method() string

Method of the request.

func (*HijackRequest) Req 

func (ctx *HijackRequest) Req() *http.Request

Req returns the underlying http.Request instance that will be used to send the request.

func (*HijackRequest) SetBody 

func (ctx *HijackRequest) SetBody(obj interface{}) *HijackRequest

SetBody of the request, if obj is []byte or string, raw body will be used, else it will be encoded as json.

func (*HijackRequest) SetContext 

func (ctx *HijackRequest) SetContext(c context.Context) *HijackRequest

SetContext of the underlying http.Request instance.

func (*HijackRequest) Type 

func (ctx *HijackRequest) Type() proto.NetworkResourceType

Type of the resource.

func (*HijackRequest) URL 

func (ctx *HijackRequest) URL() *url.URL

URL of the request.

type HijackResponse 

type HijackResponse struct {
	RawResponse *http.Response
	// contains filtered or unexported fields
}

HijackResponse context.

func (*HijackResponse) AddHeader 

func (ctx *HijackResponse) AddHeader(pairs ...string) *HijackResponse

AddHeader appends key-value pairs to the end of the response headers. Duplicate keys will be preserved.

func (*HijackResponse) Body 

func (ctx *HijackResponse) Body() string

Body of the payload.

func (*HijackResponse) Fail 

func (ctx *HijackResponse) Fail(reason proto.NetworkErrorReason) *HijackResponse

Fail request.

func (*HijackResponse) Headers 

func (ctx *HijackResponse) Headers() http.Header

Headers returns the clone of response headers. If you want to modify the response headers use HijackResponse.SetHeader .

func (*HijackResponse) Payload 

func (ctx *HijackResponse) Payload() *proto.FetchFulfillRequest

Payload to respond the request from the browser.

func (*HijackResponse) SetBody 

func (ctx *HijackResponse) SetBody(obj interface{}) *HijackResponse

SetBody of the payload, if obj is []byte or string, raw body will be used, else it will be encoded as json.

func (*HijackResponse) SetHeader 

func (ctx *HijackResponse) SetHeader(pairs ...string) *HijackResponse

SetHeader of the payload via key-value pairs.

type HijackRouter 

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

HijackRouter context.

func (*HijackRouter) Add 

func (r *HijackRouter) Add(pattern string, resourceType proto.NetworkResourceType, handler func(*Hijack)) error

Add a hijack handler to router, the doc of the pattern is the same as "proto.FetchRequestPattern.URLPattern". A pattern the regexp package refuses, one that is not valid UTF-8, is an error and enables nothing.

func (*HijackRouter) MustAdd 

func (r *HijackRouter) MustAdd(pattern string, handler func(*Hijack)) *HijackRouter

MustAdd is similar to HijackRouter.Add.

func (*HijackRouter) MustRemove 

func (r *HijackRouter) MustRemove(pattern string) *HijackRouter

MustRemove is similar to HijackRouter.Remove.

func (*HijackRouter) MustStop 

func (r *HijackRouter) MustStop()

MustStop is similar to HijackRouter.Stop.

func (*HijackRouter) Remove 

func (r *HijackRouter) Remove(pattern string) error

Remove handler via the pattern.

func (*HijackRouter) Run 

func (r *HijackRouter) Run()

Run the router, after you call it, you shouldn't add new handler to it.

func (*HijackRouter) Stop 

func (r *HijackRouter) Stop() error

Stop the router.

type InvisibleShapeError 

type InvisibleShapeError struct {
	*Element
}

InvisibleShapeError error.

func (*InvisibleShapeError) Error 

func (e *InvisibleShapeError) Error() string

Error ...

func (*InvisibleShapeError) Is 

func (e *InvisibleShapeError) Is(err error) bool

Is interface.

func (*InvisibleShapeError) Unwrap 

func (e *InvisibleShapeError) Unwrap() error

Unwrap ...

type KeyAction 

type KeyAction struct {
	Type KeyActionType
	Key  input.Key
}

KeyAction to perform.

type KeyActionType 

type KeyActionType int

KeyActionType enum. 

const (
	KeyActionPress KeyActionType = iota
	KeyActionRelease
	KeyActionTypeKey
)

KeyActionTypes.

type KeyActions 

type KeyActions struct {
	Actions []KeyAction
	// contains filtered or unexported fields
}

KeyActions to simulate.

func (*KeyActions) Do 

func (ka *KeyActions) Do() (err error)

Do the actions.

func (*KeyActions) MustDo 

func (ka *KeyActions) MustDo()

MustDo is similar to KeyActions.Do.

func (*KeyActions) Press 

func (ka *KeyActions) Press(keys ...input.Key) *KeyActions

Press keys is guaranteed to have a release at the end of actions.

func (*KeyActions) Release 

func (ka *KeyActions) Release(keys ...input.Key) *KeyActions

Release keys.

func (*KeyActions) Type 

func (ka *KeyActions) Type(keys ...input.Key) *KeyActions

Type will release the key immediately after the pressing.

type Keyboard 

type Keyboard struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Keyboard represents the keyboard on a page, it's always related the main frame.

func (*Keyboard) MustType 

func (k *Keyboard) MustType(key ...input.Key) *Keyboard

MustType is similar to Keyboard.Type.

func (*Keyboard) Press 

func (k *Keyboard) Press(key input.Key) error

Press the key down. To input characters that are not on the keyboard, such as Chinese or Japanese, you should use method like Page.InsertText.

func (*Keyboard) Release 

func (k *Keyboard) Release(key input.Key) error

Release the key.

func (*Keyboard) Type 

func (k *Keyboard) Type(keys ...input.Key) (err error)

Type releases the key after the press.

type Message 

type Message struct {
	SessionID proto.TargetSessionID
	Method    string
	// contains filtered or unexported fields
}

Message represents a cdp.Event.

func (*Message) Load 

func (msg *Message) Load(e proto.Event) bool

Load data into e, returns true if e matches the event type.

type Mouse 

type Mouse struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Mouse represents the mouse on a page, it's always related the main frame.

func (*Mouse) Click 

func (m *Mouse) Click(button proto.InputMouseButton, clickCount int) error

Click the button. It's the combination of Mouse.Down and Mouse.Up.

func (*Mouse) Down 

func (m *Mouse) Down(button proto.InputMouseButton, clickCount int) error

Down holds the button down.

func (*Mouse) MoveAlong 

func (m *Mouse) MoveAlong(guide func() (proto.Point, bool)) error

MoveAlong the guide function. Every time the guide function is called it should return the next mouse position, return true to stop. Read the source code of Mouse.MoveLinear as an example to use this method.

func (*Mouse) MoveLinear 

func (m *Mouse) MoveLinear(to proto.Point, steps int) error

MoveLinear to the absolute position with the given steps. Such as move from (0,0) to (6,6) with 3 steps, the mouse will first move to (2,2) then (4,4) then (6,6).

func (*Mouse) MoveTo 

func (m *Mouse) MoveTo(p proto.Point) error

MoveTo the absolute position.

func (*Mouse) MustClick 

func (m *Mouse) MustClick(button proto.InputMouseButton) *Mouse

MustClick is similar to Mouse.Click.

func (*Mouse) MustDown 

func (m *Mouse) MustDown(button proto.InputMouseButton) *Mouse

MustDown is similar to Mouse.Down.

func (*Mouse) MustMoveTo 

func (m *Mouse) MustMoveTo(x, y float64) *Mouse

MustMoveTo is similar to [Mouse.Move].

func (*Mouse) MustScroll 

func (m *Mouse) MustScroll(x, y float64) *Mouse

MustScroll is similar to Mouse.Scroll.

func (*Mouse) MustUp 

func (m *Mouse) MustUp(button proto.InputMouseButton) *Mouse

MustUp is similar to Mouse.Up.

func (*Mouse) Position 

func (m *Mouse) Position() proto.Point

Position of current cursor.

func (*Mouse) Scroll 

func (m *Mouse) Scroll(offsetX, offsetY float64, steps int) error

Scroll the relative offset with specified steps.

func (*Mouse) Up 

func (m *Mouse) Up(button proto.InputMouseButton, clickCount int) error

Up releases the button. 

type NavigationError struct {
	Reason string
}

NavigationError error. 

func (e *NavigationError) Error() string
func (e *NavigationError) Is(err error) bool

Is interface.

type NoPointerEventsError 

type NoPointerEventsError struct {
	*Element
}

NoPointerEventsError error.

func (*NoPointerEventsError) Error 

func (e *NoPointerEventsError) Error() string

Error ...

func (*NoPointerEventsError) Is 

func (e *NoPointerEventsError) Is(err error) bool

Is interface.

func (*NoPointerEventsError) Unwrap 

func (e *NoPointerEventsError) Unwrap() error

Unwrap ...

type NoShadowRootError 

type NoShadowRootError struct {
	*Element
}

NoShadowRootError error.

func (*NoShadowRootError) Error 

func (e *NoShadowRootError) Error() string

Error ...

func (*NoShadowRootError) Is 

func (e *NoShadowRootError) Is(err error) bool

Is interface.

type NotInteractableError 

type NotInteractableError struct{}

NotInteractableError error. Check the doc of Element.Interactable for details.

func (*NotInteractableError) Error 

func (e *NotInteractableError) Error() string

type ObjectNotFoundError 

type ObjectNotFoundError struct {
	*proto.RuntimeRemoteObject
}

ObjectNotFoundError error.

func (*ObjectNotFoundError) Error 

func (e *ObjectNotFoundError) Error() string

func (*ObjectNotFoundError) Is 

func (e *ObjectNotFoundError) Is(err error) bool

Is interface.

type Page 

type Page struct {
	// TargetID is a unique ID for a remote page.
	// It's usually used in events sent from the browser to tell which page an event belongs to.
	TargetID proto.TargetTargetID

	// FrameID is a unique ID for a browsing context.
	// Usually, different FrameID means different javascript execution context.
	// Such as an iframe and the page it belongs to will have the same TargetID but different FrameIDs.
	FrameID proto.PageFrameID

	// SessionID is a unique ID for a page attachment to a controller.
	// It's usually used in transport layer to tell which page to send the control signal.
	// A page can attached to multiple controllers, the browser uses it distinguish controllers.
	SessionID proto.TargetSessionID

	// devices
	Mouse    *Mouse
	Keyboard *Keyboard
	Touch    *Touch
	// contains filtered or unexported fields
}

Page represents the webpage. We try to hold as less states as possible. When a page is closed by wand or not all the ongoing operations an events on it will abort.

Example (Pool)

We can use wand.PagePool to concurrently control and reuse pages. 

browser := wand.New().MustConnect()
defer browser.MustClose()

// We create a pool that will hold at most 3 pages which means the max concurrency is 3
pool := wand.NewPagePool(3)

// Create a page if needed
create := func() *wand.Page {
	// We use MustIncognito to isolate pages with each other
	return browser.MustIncognito().MustPage()
}

yourJob := func() {
	page := pool.MustGet(create)

	// Put the instance back to the pool after we're done,
	// so the instance can be reused by other goroutines.
	defer pool.Put(page)

	page.MustNavigate(fixtureURL("search.html")).MustWaitLoad()
	fmt.Println(page.MustInfo().Title)
}

// Run jobs concurrently
wg := sync.WaitGroup{}
for range "...." {
	wg.Add(1)
	go func() {
		defer wg.Done()
		yourJob()
	}()
}
wg.Wait()

// cleanup pool
pool.Cleanup(func(p *wand.Page) { p.MustClose() })

Output:
wand search
wand search
wand search
wand search

func (*Page) Activate 

func (p *Page) Activate() (*Page, error)

Activate (focuses) the page.

func (*Page) AddScriptTag 

func (p *Page) AddScriptTag(url, content string) error

AddScriptTag to page. If url is empty, content will be used.

func (*Page) AddStyleTag 

func (p *Page) AddStyleTag(url, content string) error

AddStyleTag to page. If url is empty, content will be used.

func (*Page) Browser 

func (p *Page) Browser() *Browser

Browser of the page.

func (*Page) Call 

func (p *Page) Call(ctx context.Context, sessionID, methodName string, params interface{}) (res []byte, err error)

Call implements the proto.Client.

func (*Page) CancelTimeout 

func (p *Page) CancelTimeout() *Page

CancelTimeout cancels the current timeout context and returns a clone with the parent context.

func (*Page) CaptureDOMSnapshot 

func (p *Page) CaptureDOMSnapshot() (domSnapshot *proto.DOMSnapshotCaptureSnapshotResult, err error)

CaptureDOMSnapshot Returns a document snapshot, including the full DOM tree of the root node (including iframes, template contents, and imported documents) in a flattened array, as well as layout and white-listed computed style information for the nodes. Shadow DOM in the returned DOM tree is flattened. `Documents` The nodes in the DOM tree. The DOMNode at index 0 corresponds to the root document. `Strings` Shared string table that all string properties refer to with indexes. Normally use `Strings` is enough.

func (*Page) Close 

func (p *Page) Close() error

Close tries to close page, running its beforeunload hooks, if has any.

func (*Page) Context 

func (p *Page) Context(ctx context.Context) *Page

Context returns a clone with the specified ctx for chained sub-operations.

func (*Page) Cookies 

func (p *Page) Cookies(urls []string) ([]*proto.NetworkCookie, error)

Cookies returns the page cookies. By default it will return the cookies for current page. The urls is the list of URLs for which applicable cookies will be fetched.

func (*Page) DisableDomain 

func (p *Page) DisableDomain(method proto.Request) (restore func())

DisableDomain and returns a restore function to restore previous state.

func (*Page) EachEvent 

func (p *Page) EachEvent(callbacks ...interface{}) (wait func())

EachEvent of the specified event types, if any callback returns true the wait function will resolve, The type of each callback is (? means optional): 

func(proto.Event, proto.TargetSessionID?) bool?

You can listen to multiple event types at the same time like: 

browser.EachEvent(func(a *proto.A) {}, func(b *proto.B) {})

Such as subscribe the events to know when the navigation is complete or when the page is rendered. Here's an example to dismiss all dialogs/alerts on the page: 

go page.EachEvent(func(e *proto.PageJavascriptDialogOpening) {
    _ = proto.PageHandleJavaScriptDialog{ Accept: false, PromptText: ""}.Call(page)
})()

func (*Page) Element 

func (p *Page) Element(selector string) (*Element, error)

Element retries until an element in the page that matches the CSS selector, then returns the matched element.

func (*Page) ElementByJS 

func (p *Page) ElementByJS(opts *EvalOptions) (*Element, error)

ElementByJS returns the element from the return value of the js function. If sleeper is nil, no retry will be performed. By default, it will retry until the js function doesn't return null. To customize the retry logic, check the examples of Page.Sleeper.

func (*Page) ElementFromNode 

func (p *Page) ElementFromNode(node *proto.DOMNode) (*Element, error)

ElementFromNode creates an Element from the node, proto.DOMNodeID or proto.DOMBackendNodeID must be specified.

func (*Page) ElementFromObject 

func (p *Page) ElementFromObject(obj *proto.RuntimeRemoteObject) (*Element, error)

ElementFromObject creates an Element from the remote object id.

func (*Page) ElementFromPoint 

func (p *Page) ElementFromPoint(x, y int) (*Element, error)

ElementFromPoint creates an Element from the absolute point on the page. The point should include the window scroll offset.

func (*Page) ElementR 

func (p *Page) ElementR(selector, jsRegex string) (*Element, error)

ElementR retries until an element in the page that matches the css selector and it's text matches the jsRegex, then returns the matched element.

func (*Page) ElementX 

func (p *Page) ElementX(xPath string) (*Element, error)

ElementX retries until an element in the page that matches one of the XPath selectors, then returns the matched element.

func (*Page) Elements 

func (p *Page) Elements(selector string) (Elements, error)

Elements returns all elements that match the css selector.

func (*Page) ElementsByJS 

func (p *Page) ElementsByJS(opts *EvalOptions) (Elements, error)

ElementsByJS returns the elements from the return value of the js.

func (*Page) ElementsX 

func (p *Page) ElementsX(xpath string) (Elements, error)

ElementsX returns all elements that match the XPath selector.

func (*Page) Emulate 

func (p *Page) Emulate(device devices.Device) error

Emulate the device, such as iPhone9. If device is devices.Clear, it will clear the override.

func (*Page) EnableDomain 

func (p *Page) EnableDomain(method proto.Request) (restore func())

EnableDomain and returns a restore function to restore previous state.

func (*Page) Eval 

func (p *Page) Eval(js string, args ...interface{}) (*proto.RuntimeRemoteObject, error)

Eval is a shortcut for Page.Evaluate with AwaitPromise, ByValue set to true.

func (*Page) EvalOnNewDocument 

func (p *Page) EvalOnNewDocument(js string) (remove func() error, err error)

EvalOnNewDocument Evaluates given script in every frame upon creation (before loading frame's scripts).

func (*Page) Evaluate 

func (p *Page) Evaluate(opts *EvalOptions) (res *proto.RuntimeRemoteObject, err error)

Evaluate js on the page.

func (*Page) Event 

func (p *Page) Event() <-chan *Message

Event of the page.

func (*Page) Expose 

func (p *Page) Expose(name string, fn func(lazyjson.JSON) (interface{}, error)) (stop func() error, err error)

Expose fn to the page's window object with the name. The exposure survives reloads. Call stop to unbind the fn.

func (*Page) ExposeHelpers 

func (p *Page) ExposeHelpers(list ...*js.Function)

ExposeHelpers helper functions to page's js context so that we can use the Devtools' console to debug them.

func (*Page) GetContext 

func (p *Page) GetContext() context.Context

GetContext of current instance.

func (*Page) GetNavigationHistory 

func (p *Page) GetNavigationHistory() (*proto.PageGetNavigationHistoryResult, error)

GetNavigationHistory get navigation history.

func (*Page) GetResource 

func (p *Page) GetResource(url string) ([]byte, error)

GetResource content by the url. Such as image, css, html, etc. Use the proto.PageGetResourceTree to list all the resources.

func (*Page) GetSessionID 

func (p *Page) GetSessionID() proto.TargetSessionID

GetSessionID interface.

func (*Page) GetWindow 

func (p *Page) GetWindow() (*proto.BrowserBounds, error)

GetWindow position and size info.

func (*Page) HTML 

func (p *Page) HTML() (string, error)

HTML of the page.

func (*Page) HandleDialog 

func (p *Page) HandleDialog() (
	wait func() *proto.PageJavascriptDialogOpening,
	handle func(*proto.PageHandleJavaScriptDialog) error,
)

HandleDialog accepts or dismisses next JavaScript initiated dialog (alert, confirm, prompt, or onbeforeunload). Because modal dialog will block js, usually you have to trigger the dialog in another goroutine. For example: 

wait, handle := page.MustHandleDialog()
go page.MustElement("button").MustClick()
wait()
handle(true, "")

func (*Page) HandleFileDialog 

func (p *Page) HandleFileDialog() (func([]string) error, error)

HandleFileDialog return a functions that waits for the next file chooser dialog pops up and returns the element for the event.

func (*Page) Has 

func (p *Page) Has(selector string) (bool, *Element, error)

Has an element that matches the css selector.

func (*Page) HasR 

func (p *Page) HasR(selector, jsRegex string) (bool, *Element, error)

HasR an element that matches the css selector and its display text matches the jsRegex.

func (*Page) HasX 

func (p *Page) HasX(selector string) (bool, *Element, error)

HasX an element that matches the XPath selector.

func (*Page) HijackRequests 

func (p *Page) HijackRequests() *HijackRouter

HijackRequests creates a new router instance for requests hijacking. When use Fetch domain outside the router should be stopped. Enabling hijacking disables page caching, but such as 304 Not Modified will still work as expected. The entire process of hijacking one request: 

browser --req-> wand ---> server ---> wand --res-> browser

The --req-> and --res-> are the parts that can be modified.

func (*Page) Info 

func (p *Page) Info() (*proto.TargetTargetInfo, error)

Info of the page, such as the URL or title of the page.

func (*Page) InsertText 

func (p *Page) InsertText(text string) error

InsertText is like pasting text into the page.

func (*Page) IsIframe 

func (p *Page) IsIframe() bool

IsIframe tells if it's iframe.

func (*Page) KeyActions 

func (p *Page) KeyActions() *KeyActions

KeyActions simulates the type actions on a physical keyboard. Useful when input shortcuts like ctrl+enter .

func (*Page) LoadState 

func (p *Page) LoadState(method proto.Request) (has bool)

LoadState into the method.

func (*Page) MustActivate 

func (p *Page) MustActivate() *Page

MustActivate is similar to Page.Activate.

func (*Page) MustAddScriptTag 

func (p *Page) MustAddScriptTag(url string) *Page

MustAddScriptTag is similar to Page.AddScriptTag.

func (*Page) MustAddStyleTag 

func (p *Page) MustAddStyleTag(url string) *Page

MustAddStyleTag is similar to Page.AddStyleTag.

func (*Page) MustCaptureDOMSnapshot 

func (p *Page) MustCaptureDOMSnapshot() (domSnapshot *proto.DOMSnapshotCaptureSnapshotResult)

MustCaptureDOMSnapshot is similar to Page.CaptureDOMSnapshot.

func (*Page) MustClose 

func (p *Page) MustClose()

MustClose is similar to Page.Close.

func (*Page) MustCookies 

func (p *Page) MustCookies(urls ...string) []*proto.NetworkCookie

MustCookies is similar to Page.Cookies.

func (*Page) MustElement 

func (p *Page) MustElement(selector string) *Element

MustElement is similar to Page.Element.

func (*Page) MustElementByJS 

func (p *Page) MustElementByJS(js string, params ...interface{}) *Element

MustElementByJS is similar to Page.ElementByJS.

func (*Page) MustElementFromNode 

func (p *Page) MustElementFromNode(node *proto.DOMNode) *Element

MustElementFromNode is similar to Page.ElementFromNode.

func (*Page) MustElementFromPoint 

func (p *Page) MustElementFromPoint(left, top int) *Element

MustElementFromPoint is similar to Page.ElementFromPoint.

func (*Page) MustElementR 

func (p *Page) MustElementR(selector, jsRegex string) *Element

MustElementR is similar to Page.ElementR.

func (*Page) MustElementX 

func (p *Page) MustElementX(xPath string) *Element

MustElementX is similar to Page.ElementX.

func (*Page) MustElements 

func (p *Page) MustElements(selector string) Elements

MustElements is similar to Page.Elements.

func (*Page) MustElementsByJS 

func (p *Page) MustElementsByJS(js string, params ...interface{}) Elements

MustElementsByJS is similar to Page.ElementsByJS.

func (*Page) MustElementsX 

func (p *Page) MustElementsX(xpath string) Elements

MustElementsX is similar to Page.ElementsX.

func (*Page) MustEmulate 

func (p *Page) MustEmulate(device devices.Device) *Page

MustEmulate is similar to Page.Emulate.

func (*Page) MustEval 

func (p *Page) MustEval(js string, params ...interface{}) lazyjson.JSON

MustEval is similar to Page.Eval.

func (*Page) MustEvalOnNewDocument 

func (p *Page) MustEvalOnNewDocument(js string)

MustEvalOnNewDocument is similar to Page.EvalOnNewDocument.

func (*Page) MustEvaluate 

func (p *Page) MustEvaluate(opts *EvalOptions) *proto.RuntimeRemoteObject

MustEvaluate is similar to Page.Evaluate.

func (*Page) MustExpose 

func (p *Page) MustExpose(name string, fn func(lazyjson.JSON) (interface{}, error)) (stop func())

MustExpose is similar to Page.Expose.

func (*Page) MustGetWindow 

func (p *Page) MustGetWindow() *proto.BrowserBounds

MustGetWindow is similar to Page.GetWindow.

func (*Page) MustHTML 

func (p *Page) MustHTML() string

MustHTML is similar to Page.HTML.

func (*Page) MustHandleDialog 

func (p *Page) MustHandleDialog() (wait func() *proto.PageJavascriptDialogOpening, handle func(bool, string))

MustHandleDialog is similar to Page.HandleDialog.

func (*Page) MustHandleFileDialog 

func (p *Page) MustHandleFileDialog() func(...string)

MustHandleFileDialog is similar to Page.HandleFileDialog.

func (*Page) MustHas 

func (p *Page) MustHas(selector string) bool

MustHas is similar to Page.Has.

func (*Page) MustHasR 

func (p *Page) MustHasR(selector, regex string) bool

MustHasR is similar to Page.HasR.

func (*Page) MustHasX 

func (p *Page) MustHasX(selector string) bool

MustHasX is similar to Page.HasX.

func (*Page) MustInfo 

func (p *Page) MustInfo() *proto.TargetTargetInfo

MustInfo is similar to Page.Info.

func (*Page) MustInsertText 

func (p *Page) MustInsertText(text string) *Page

MustInsertText is similar to Page.InsertText.

func (*Page) MustNavigate 

func (p *Page) MustNavigate(url string) *Page

MustNavigate is similar to Page.Navigate.

func (*Page) MustNavigateBack 

func (p *Page) MustNavigateBack() *Page

MustNavigateBack is similar to Page.NavigateBack.

func (*Page) MustNavigateForward 

func (p *Page) MustNavigateForward() *Page

MustNavigateForward is similar to Page.NavigateForward.

func (*Page) MustObjectToJSON 

func (p *Page) MustObjectToJSON(obj *proto.RuntimeRemoteObject) lazyjson.JSON

MustObjectToJSON is similar to Page.ObjectToJSON.

func (*Page) MustObjectsToJSON 

func (p *Page) MustObjectsToJSON(list []*proto.RuntimeRemoteObject) lazyjson.JSON

MustObjectsToJSON is similar to [Page.ObjectsToJSON].

func (*Page) MustPDF 

func (p *Page) MustPDF(toFile ...string) []byte

MustPDF is similar to Page.PDF. If the toFile is "", it Page.will save output to "tmp/pdf" folder, time as the file name.

func (*Page) MustRelease 

func (p *Page) MustRelease(obj *proto.RuntimeRemoteObject) *Page

MustRelease is similar to Page.Release.

func (*Page) MustReload 

func (p *Page) MustReload() *Page

MustReload is similar to Page.Reload.

func (*Page) MustResetNavigationHistory 

func (p *Page) MustResetNavigationHistory() *Page

MustResetNavigationHistory is similar to Page.ResetNavigationHistory.

func (*Page) MustScreenshot 

func (p *Page) MustScreenshot(toFile ...string) []byte

MustScreenshot is similar to Page.Screenshot. If the toFile is "", it Page.will save output to "tmp/screenshots" folder, time as the file name.

func (*Page) MustScreenshotFullPage 

func (p *Page) MustScreenshotFullPage(toFile ...string) []byte

MustScreenshotFullPage is similar to [Page.ScreenshotFullPage]. If the toFile is "", it Page.will save output to "tmp/screenshots" folder, time as the file name.

func (*Page) MustScrollScreenshot 

func (p *Page) MustScrollScreenshot(toFile ...string) []byte

MustScrollScreenshot is similar to Page.ScrollScreenshot. If the toFile is "", it Page.will save output to "tmp/screenshots" folder, time as the file name.

func (*Page) MustSearch 

func (p *Page) MustSearch(query string) *Element

MustSearch is similar to Page.Search. It only returns the first element in the search result.

func (*Page) MustSetBlockedURLs 

func (p *Page) MustSetBlockedURLs(urls ...string) *Page

MustSetBlockedURLs is similar to Page.SetBlockedURLs.

func (*Page) MustSetCookies 

func (p *Page) MustSetCookies(cookies ...*proto.NetworkCookieParam) *Page

MustSetCookies is similar to Page.SetCookies. If the len(cookies) is 0 it will clear all the cookies.

func (*Page) MustSetDocumentContent 

func (p *Page) MustSetDocumentContent(html string) *Page

MustSetDocumentContent is similar to Page.SetDocumentContent.

func (*Page) MustSetExtraHeaders 

func (p *Page) MustSetExtraHeaders(dict ...string) (cleanup func())

MustSetExtraHeaders is similar to Page.SetExtraHeaders.

func (*Page) MustSetUserAgent 

func (p *Page) MustSetUserAgent(req *proto.NetworkSetUserAgentOverride) *Page

MustSetUserAgent is similar to Page.SetUserAgent.

func (*Page) MustSetViewport 

func (p *Page) MustSetViewport(width, height int, deviceScaleFactor float64, mobile bool) *Page

MustSetViewport is similar to Page.SetViewport.

func (*Page) MustSetWindow 

func (p *Page) MustSetWindow(left, top, width, height int) *Page

MustSetWindow is similar to Page.SetWindow.

func (*Page) MustStopLoading 

func (p *Page) MustStopLoading() *Page

MustStopLoading is similar to Page.StopLoading.

func (*Page) MustTriggerFavicon 

func (p *Page) MustTriggerFavicon() *Page

MustTriggerFavicon is similar to [PageTriggerFavicon].

func (*Page) MustWait 

func (p *Page) MustWait(js string, params ...interface{}) *Page

MustWait is similar to Page.Wait.

func (*Page) MustWaitDOMStable 

func (p *Page) MustWaitDOMStable() *Page

MustWaitDOMStable is similar to Page.WaitDOMStable.

func (*Page) MustWaitElementsMoreThan 

func (p *Page) MustWaitElementsMoreThan(selector string, num int) *Page

MustWaitElementsMoreThan is similar to Page.WaitElementsMoreThan.

func (*Page) MustWaitIdle 

func (p *Page) MustWaitIdle() *Page

MustWaitIdle is similar to Page.WaitIdle.

func (*Page) MustWaitLoad 

func (p *Page) MustWaitLoad() *Page

MustWaitLoad is similar to Page.WaitLoad.

func (*Page) MustWaitNavigation 

func (p *Page) MustWaitNavigation() func()

MustWaitNavigation is similar to Page.WaitNavigation.

func (*Page) MustWaitOpen 

func (p *Page) MustWaitOpen() (wait func() (newPage *Page))

MustWaitOpen is similar to Page.WaitOpen.

func (*Page) MustWaitRequestIdle 

func (p *Page) MustWaitRequestIdle(excludes ...string) (wait func())

MustWaitRequestIdle is similar to Page.WaitRequestIdle.

func (*Page) MustWaitStable 

func (p *Page) MustWaitStable() *Page

MustWaitStable is similar to Page.WaitStable.

func (*Page) MustWindowFullscreen 

func (p *Page) MustWindowFullscreen() *Page

MustWindowFullscreen is similar to [Page.WindowFullscreen].

func (*Page) MustWindowMaximize 

func (p *Page) MustWindowMaximize() *Page

MustWindowMaximize is similar to [Page.WindowMaximize].

func (*Page) MustWindowMinimize 

func (p *Page) MustWindowMinimize() *Page

MustWindowMinimize is similar to [Page.WindowMinimize].

func (*Page) MustWindowNormal 

func (p *Page) MustWindowNormal() *Page

MustWindowNormal is similar to [Page.WindowNormal].

func (*Page) Navigate 

func (p *Page) Navigate(url string) error

Navigate to the url. If the url is empty, "about:blank" will be used. It returns once the navigation has committed, the point from which the page's commands reach the document it loaded: Chrome answers Page.navigate as soon as the navigation is ready to commit, before the renderer has committed the document, and a command bound for the renderer that arrives in between is held by the browser until the commit, where it can be lost with no answer at all (#120). A navigation that turns into a download commits nothing and is a NavigationError.

func (*Page) NavigateBack 

func (p *Page) NavigateBack() error

NavigateBack history. It returns once the entry has committed, as Page.Navigate does, and at once where there is no entry to go back to.

func (*Page) NavigateForward 

func (p *Page) NavigateForward() error

NavigateForward history. It returns once the entry has committed, as Page.Navigate does, and at once where there is no entry to go forward to.

func (*Page) ObjectToJSON 

func (p *Page) ObjectToJSON(obj *proto.RuntimeRemoteObject) (lazyjson.JSON, error)

ObjectToJSON by object id.

func (*Page) Overlay 

func (p *Page) Overlay(left, top, width, height float64, msg string) (remove func())

Overlay a rectangle on the main frame with specified message.

func (*Page) PDF 

func (p *Page) PDF(req *proto.PagePrintToPDF) (*StreamReader, error)

PDF prints page as PDF.

func (*Page) Race 

func (p *Page) Race() *RaceContext

Race creates a context to race selectors.

func (*Page) Release 

func (p *Page) Release(obj *proto.RuntimeRemoteObject) error

Release the remote object. Usually, you don't need to call it. When a page is closed or reloaded, all remote objects will be released automatically. It's useful if the page never closes or reloads.

func (*Page) Reload 

func (p *Page) Reload() error

Reload page.

func (*Page) ResetNavigationHistory 

func (p *Page) ResetNavigationHistory() error

ResetNavigationHistory reset history.

func (*Page) Screenshot 

func (p *Page) Screenshot(fullPage bool, req *proto.PageCaptureScreenshot) ([]byte, error)

Screenshot captures the screenshot of current page.

func (*Page) ScrollScreenshot 

func (p *Page) ScrollScreenshot(opt *ScrollScreenshotOptions) ([]byte, error)

ScrollScreenshot Scroll screenshot does not adjust the size of the viewport, but achieves it by scrolling and capturing screenshots in a loop, and then stitching them together. Note that this method also has a flaw: when there are elements with fixed positioning on the page (usually header navigation components), these elements will appear repeatedly, you can set the FixedTop parameter to optimize it.

Only support png and jpeg format yet, webP is not supported because no suitable processing library was found in golang.

func (*Page) Search 

func (p *Page) Search(query string) (*SearchResult, error)

Search for the given query in the DOM tree until the result count is not zero, before that it will keep retrying. The query can be plain text or css selector or xpath. It will search nested iframes and shadow doms too.

func (*Page) SetBlockedURLs 

func (p *Page) SetBlockedURLs(urls []string) error

SetBlockedURLs For some requests that do not want to be triggered, such as some dangerous operations, delete, quit logout, etc. Wildcards ('*') are allowed, such as ["*/api/logout/*","delete"]. NOTE: if you set empty pattern "", it will block all requests.

func (*Page) SetCookies 

func (p *Page) SetCookies(cookies []*proto.NetworkCookieParam) error

SetCookies is similar to Browser.SetCookies .

func (*Page) SetDocumentContent 

func (p *Page) SetDocumentContent(html string) error

SetDocumentContent sets the page document html content.

func (*Page) SetExtraHeaders 

func (p *Page) SetExtraHeaders(dict []string) (func(), error)

SetExtraHeaders whether to always send extra HTTP headers with the requests from this page.

func (*Page) SetUserAgent 

func (p *Page) SetUserAgent(req *proto.NetworkSetUserAgentOverride) error

SetUserAgent (browser brand, accept-language, etc) of the page. If req is nil, a default user agent will be used, a typical mac chrome.

func (*Page) SetViewport 

func (p *Page) SetViewport(params *proto.EmulationSetDeviceMetricsOverride) error

SetViewport overrides the values of device screen dimensions.

func (*Page) SetWindow 

func (p *Page) SetWindow(bounds *proto.BrowserBounds) error

SetWindow location and size.

func (*Page) Sleeper 

func (p *Page) Sleeper(sleeper func() utils.Sleeper) *Page

Sleeper returns a clone with the specified sleeper for chained sub-operations.

func (*Page) StopLoading 

func (p *Page) StopLoading() error

StopLoading forces the page stop navigation and pending resource fetches.

func (*Page) String 

func (p *Page) String() string

String interface.

func (*Page) Timeout 

func (p *Page) Timeout(d time.Duration) *Page

Timeout returns a clone with the specified total timeout of all chained sub-operations.

func (*Page) TriggerFavicon 

func (p *Page) TriggerFavicon() error

TriggerFavicon supports when browser in headless mode to trigger favicon's request. Pay attention to this function only supported when browser in headless mode, if you call it in no-headless mode, it will raise an error with the message "browser is no-headless".

func (*Page) Wait 

func (p *Page) Wait(opts *EvalOptions) error

Wait until the js returns true.

func (*Page) WaitDOMStable 

func (p *Page) WaitDOMStable(d time.Duration, diff float64) error

WaitDOMStable waits until the change of the DOM tree is less or equal than diff percent for d duration. Be careful, d is not the max wait timeout, it's the least stable time. If you want to set a timeout you can use the Page.Timeout function.

func (*Page) WaitElementsMoreThan 

func (p *Page) WaitElementsMoreThan(selector string, num int) error

WaitElementsMoreThan waits until there are more than num elements that match the selector.

func (*Page) WaitEvent 

func (p *Page) WaitEvent(e proto.Event) (wait func())

WaitEvent waits for the next event for one time. It will also load the data into the event object.

func (*Page) WaitIdle 

func (p *Page) WaitIdle(timeout time.Duration) (err error)

WaitIdle waits until the next window.requestIdleCallback is called.

func (*Page) WaitLoad 

func (p *Page) WaitLoad() error

WaitLoad waits for the `window.onload` event, it returns immediately if the event is already fired.

func (*Page) WaitNavigation 

func (p *Page) WaitNavigation(name proto.PageLifecycleEventName) func()

WaitNavigation wait for a page lifecycle event when navigating. Usually you will wait for proto.PageLifecycleEventNameNetworkAlmostIdle.

func (*Page) WaitOpen 

func (p *Page) WaitOpen() func() (*Page, error)

WaitOpen waits for the next new page opened by the current one.

func (*Page) WaitRepaint 

func (p *Page) WaitRepaint() error

WaitRepaint waits until the next repaint. A hidden or frozen page paints no frame, so the wait ends only with the page's context: use Page.Timeout or Page.Context to bound it. Doc: https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame

func (*Page) WaitRequestIdle 

func (p *Page) WaitRequestIdle(
	d time.Duration,
	includes, excludes []string,
	excludeTypes []proto.NetworkResourceType,
) func()

WaitRequestIdle returns a wait function that waits until no request for d duration. Be careful, d is not the max wait timeout, it's the least idle time. If you want to set a timeout you can use the Page.Timeout function. Use the includes and excludes regexp list to filter the requests by their url.

func (*Page) WaitStable 

func (p *Page) WaitStable(d time.Duration) error

WaitStable waits until the page is stable for d duration.

func (*Page) WithCancel 

func (p *Page) WithCancel() (*Page, func())

WithCancel returns a clone with a context cancel function.

func (*Page) WithPanic 

func (p *Page) WithPanic(fail func(interface{})) *Page

WithPanic returns a page clone with the specified panic function. The fail must stop the current goroutine's execution immediately, such as use runtime.Goexit or panic inside it.

type PageCloseCanceledError 

type PageCloseCanceledError struct{}

PageCloseCanceledError error.

func (*PageCloseCanceledError) Error 

func (e *PageCloseCanceledError) Error() string

type PageNotFoundError 

type PageNotFoundError struct{}

PageNotFoundError error.

func (*PageNotFoundError) Error 

func (e *PageNotFoundError) Error() string

type Pages 

type Pages []*Page

Pages provides some helpers to deal with page list.

func (Pages) Empty 

func (ps Pages) Empty() bool

Empty returns true if the list is empty.

func (Pages) Find 

func (ps Pages) Find(selector string) (*Page, error)

Find the page that has the specified element with the css selector.

func (Pages) FindByURL 

func (ps Pages) FindByURL(jsRegex string) (*Page, error)

FindByURL returns the page that has the url that matches the jsRegex.

func (Pages) First 

func (ps Pages) First() *Page

First returns the first page, if the list is empty returns nil.

func (Pages) Last 

func (ps Pages) Last() *Page

Last returns the last page, if the list is empty returns nil.

func (Pages) MustFind 

func (ps Pages) MustFind(selector string) *Page

MustFind is similar to [Browser.Find].

func (Pages) MustFindByURL 

func (ps Pages) MustFindByURL(regex string) *Page

MustFindByURL is similar to [Page.FindByURL].

type Pool 

type Pool[T any] struct {
	// contains filtered or unexported fields
}

Pool is used to thread-safely limit the number of elements at the same time: Get takes one of its slots, creating the element when the slot is empty, and Put gives the slot back with the element in it for the next Get. Use NewPool, the zero value is not a pool.

Cleanup ends the pool: from then on Get returns ErrPoolCleanedUp at once, and an element Put back later goes to Cleanup's function, so a caller that held one across Cleanup leaks nothing and hits no closed channel.

func NewBrowserPool 

func NewBrowserPool(limit int) Pool[Browser]

NewBrowserPool instance.

func NewPagePool 

func NewPagePool(limit int) Pool[Page]

NewPagePool instance.

func NewPool 

func NewPool[T any](limit int) Pool[T]

NewPool instance.

func (Pool[T]) Cleanup 

func (p Pool[T]) Cleanup(iteratee func(*T))

Cleanup runs iteratee on every element the pool holds and ends the pool: an element out of the pool at the time goes to iteratee when it is Put back, and Get returns ErrPoolCleanedUp. The calls of iteratee never overlap, whichever goroutine Puts; iteratee must not use the pool itself. A second Cleanup does nothing.

func (Pool[T]) Get 

func (p Pool[T]) Get(create func() (*T, error)) (elem *T, err error)

Get a elem from the pool, allow error. Use the [Pool[T].Put] to make it reusable later. A Get after Cleanup returns ErrPoolCleanedUp; one that took its slot before Cleanup ran completes, and its elem goes to Cleanup's function when it is Put back.

func (Pool[T]) MustGet 

func (p Pool[T]) MustGet(create func() *T) *T

MustGet an elem from the pool. Use the [Pool[T].Put] to make it reusable later.

func (Pool[T]) Put 

func (p Pool[T]) Put(elem *T)

Put an elem back to the pool. After Cleanup the elem goes to Cleanup's function instead. A Put with every slot in the pool already, a Put without a Get, panics.

type RaceContext 

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

RaceContext stores the branches to race.

func (*RaceContext) Do 

func (rc *RaceContext) Do() (*Element, error)

Do the race.

func (*RaceContext) Element 

func (rc *RaceContext) Element(selector string) *RaceContext

Element is similar to Page.Element.

func (*RaceContext) ElementByJS 

func (rc *RaceContext) ElementByJS(opts *EvalOptions) *RaceContext

ElementByJS is similar to Page.ElementByJS.

func (*RaceContext) ElementFunc 

func (rc *RaceContext) ElementFunc(fn func(*Page) (*Element, error)) *RaceContext

ElementFunc takes a custom function to determine race success.

func (*RaceContext) ElementR 

func (rc *RaceContext) ElementR(selector, regex string) *RaceContext

ElementR is similar to Page.ElementR.

func (*RaceContext) ElementX 

func (rc *RaceContext) ElementX(selector string) *RaceContext

ElementX is similar to Page.ElementX.

func (*RaceContext) Handle 

func (rc *RaceContext) Handle(callback func(*Element) error) *RaceContext

Handle adds a callback function to the most recent chained selector. The callback function is run, if the corresponding selector is present first, in the Race condition.

func (*RaceContext) MustDo 

func (rc *RaceContext) MustDo() *Element

MustDo is similar to RaceContext.Do.

func (*RaceContext) MustElementByJS 

func (rc *RaceContext) MustElementByJS(js string, params []interface{}) *RaceContext

MustElementByJS is similar to RaceContext.ElementByJS.

func (*RaceContext) MustHandle 

func (rc *RaceContext) MustHandle(callback func(*Element)) *RaceContext

MustHandle is similar to RaceContext.Handle.

func (*RaceContext) Search 

func (rc *RaceContext) Search(query string) *RaceContext

Search is similar to Page.Search.

type ScrollScreenshotOptions 

type ScrollScreenshotOptions struct {
	// Format (optional) Image compression format (defaults to png).
	Format proto.PageCaptureScreenshotFormat `json:"format,omitempty"`

	// Quality (optional) Compression quality from range [0..100] (jpeg only).
	Quality *int `json:"quality,omitempty"`

	// FixedTop (optional) The number of pixels to skip from the top.
	// It is suitable for optimizing the screenshot effect when there is a fixed
	// positioning element at the top of the page.
	FixedTop float64

	// FixedBottom (optional) The number of pixels to skip from the bottom.
	FixedBottom float64

	// WaitPerScroll until no animation (default is 300ms)
	WaitPerScroll time.Duration
}

ScrollScreenshotOptions is the options for the ScrollScreenshot.

type SearchResult 

type SearchResult struct {
	*proto.DOMPerformSearchResult

	// First element in the search result
	First *Element
	// contains filtered or unexported fields
}

SearchResult handler.

func (*SearchResult) All 

func (s *SearchResult) All() (Elements, error)

All returns all elements.

func (*SearchResult) Get 

func (s *SearchResult) Get(i, l int) (Elements, error)

Get l elements at the index of i from the remote search result.

func (*SearchResult) Release 

func (s *SearchResult) Release()

Release the remote search result.

type SelectorType 

type SelectorType string

SelectorType enum. 

const (
	// SelectorTypeRegex type.
	SelectorTypeRegex SelectorType = "regex"
	// SelectorTypeCSSSector type.
	SelectorTypeCSSSector SelectorType = "css-selector"
	// SelectorTypeText type.
	SelectorTypeText SelectorType = "text"
)

type StreamReader 

type StreamReader struct {
	Offset *int
	// contains filtered or unexported fields
}

StreamReader for browser data stream.

func NewStreamReader 

func NewStreamReader(c proto.Client, h proto.IOStreamHandle) *StreamReader

NewStreamReader instance.

func (*StreamReader) Close 

func (sr *StreamReader) Close() error

Close the stream, discard any temporary backing storage.

func (*StreamReader) Read 

func (sr *StreamReader) Read(p []byte) (n int, err error)

type Touch 

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

Touch presents a touch device, such as a hand with fingers, each finger is a proto.InputTouchPoint. Touch events is stateless, we use the struct here only as a namespace to make the API style unified.

func (*Touch) Cancel 

func (t *Touch) Cancel() error

Cancel touch action.

func (*Touch) End 

func (t *Touch) End() error

End touch action.

func (*Touch) Move 

func (t *Touch) Move(points ...*proto.InputTouchPoint) error

Move touch points. Use the proto.InputTouchPoint.ID (Touch.identifier) to track points. Doc: https://developer.mozilla.org/en-US/docs/Web/API/Touch_events

func (*Touch) MustCancel 

func (t *Touch) MustCancel() *Touch

MustCancel is similar to Touch.Cancel.

func (*Touch) MustEnd 

func (t *Touch) MustEnd() *Touch

MustEnd is similar to Touch.End.

func (*Touch) MustMove 

func (t *Touch) MustMove(points ...*proto.InputTouchPoint) *Touch

MustMove is similar to Touch.Move.

func (*Touch) MustStart 

func (t *Touch) MustStart(points ...*proto.InputTouchPoint) *Touch

MustStart is similar to Touch.Start.

func (*Touch) MustTap 

func (t *Touch) MustTap(x, y float64) *Touch

MustTap is similar to Touch.Tap.

func (*Touch) Start 

func (t *Touch) Start(points ...*proto.InputTouchPoint) error

Start a touch action.

func (*Touch) Tap 

func (t *Touch) Tap(x, y float64) error

Tap dispatches a touchstart and touchend event.

type TraceType 

type TraceType string

TraceType for logger. 

const (
	// TraceTypeWaitRequestsIdle type.
	TraceTypeWaitRequestsIdle TraceType = "wait requests idle"

	// TraceTypeWaitRequests type.
	TraceTypeWaitRequests TraceType = "wait requests"

	// TraceTypeQuery type.
	TraceTypeQuery TraceType = "query"

	// TraceTypeWait type.
	TraceTypeWait TraceType = "wait"

	// TraceTypeInput type.
	TraceTypeInput TraceType = "input"
)

func (TraceType) String 

func (t TraceType) String() string

String interface.

type TryError 

type TryError struct {
	Value interface{}
	Stack string
}

TryError error.

func (*TryError) Error 

func (e *TryError) Error() string

func (*TryError) Is 

func (e *TryError) Is(err error) bool

Is interface.

func (*TryError) Unwrap 

func (e *TryError) Unwrap() error

Unwrap stdlib interface.

Source Files

View all Source files

Directories

Path Synopsis
cmd
wand-fetch-browser command
Command wand-fetch-browser downloads the Managed browser into wand's browser cache ahead of time, for container image builds and offline bundles, and prints the path of the browser binary, alone on stdout so that a script can take it, with the download's progress on stderr.
 Command wand-fetch-browser downloads the Managed browser into wand's browser cache ahead of time, for container image builds and offline bundles, and prints the path of the browser binary, alone on stdout so that a script can take it, with the download's progress on stderr.
wand-manager command
Command wand-manager is a server to help launch browsers remotely.
 Command wand-manager is a server to help launch browsers remotely.
fixtures
gen-fonts command
Package main ...
 Package main ...
internal
assets
Package assets is generated by "internal/assets/generate"
 Package assets is generated by "internal/assets/generate"
assets/generate command
Package main ...
 Package main ...
devutil
Package devutil holds helpers for wand's generators and developer tools.
 Package devutil holds helpers for wand's generators and developer tools.
tools/ci-test command
Package main A helper to run go test on CI with the right environment variables.
 Package main A helper to run go test on CI with the right environment variables.
tools/docker command
Package main is wand's image build script: it builds the two container images from the checkout it is run in, proves what the image Gate proves, and either keeps them on this machine or pushes them by digest for the release workflow to publish (spec #33, section 14; tickets #55 and #60).
 Package main is wand's image build script: it builds the two container images from the checkout it is run in, proves what the image Gate proves, and either keeps them on this machine or pushes them by digest for the release workflow to publish (spec #33, section 14; tickets #55 and #60).
tools/govulncheck command
Package main is the vulnerability scan of the Gate's linux/amd64 Go stable job, and the same command to run before pushing:
 Package main is the vulnerability scan of the Gate's linux/amd64 Go stable job, and the same command to run before pushing:
tools/lint command
Package main is the lint step of go generate and of the generate Gate: the Node linters that internal/tools/package.json pins, then golangci-lint at the version internal/devutil pins (its formatters rewrite, its linters report), then upstream's Must-prefix rule and a clean git tree, so that a generator whose output drifted from the committed files fails here (spec #33, section 13).
 Package main is the lint step of go generate and of the generate Gate: the Node linters that internal/tools/package.json pins, then golangci-lint at the version internal/devutil pins (its formatters rewrite, its linters report), then upstream's Must-prefix rule and a clean git tree, so that a generator whose output drifted from the committed files fails here (spec #33, section 13).
tools/nightly-report command
Package main is the Nightly's issue opener: it reads the jobs of one workflow run and, for every job that went red, opens an issue keyed by that job's name or comments on the open one (spec #33, section 13; ticket #61):
 Package main is the Nightly's issue opener: it reads the jobs of one workflow run and, for every job that went red, opens an issue keyed by that job's name or comments on the open one (spec #33, section 13; ticket #61):
tools/print-pins command
Package main prints the three pins of lib/launcher/pins for the release workflow, which heads every release with them and appends them to versions.json, so no workflow parses Go source (ADR-0008, ADR-0009):
 Package main prints the three pins of lib/launcher/pins for the release workflow, which heads every release with them and appends them to versions.json, so no workflow parses Go source (ADR-0008, ADR-0009):
tools/release command
Package main is the version arithmetic and the release body of the release workflow: it validates the version it is given against the tags already published, appends that release's row to versions.json, and writes the head of the GitHub Release body — the three pins on the first line, and the Release preamble of docs/releases/<tag>.md under it when the release has one (spec #33, section 15; ADR-0008; ticket #60):
 Package main is the version arithmetic and the release body of the release workflow: it validates the version it is given against the tags already published, appends that release's row to versions.json, and writes the head of the GitHub Release body — the three pins on the first line, and the Release preamble of docs/releases/<tag>.md under it when the release has one (spec #33, section 15; ADR-0008; ticket #60):
tools/repo-settings command
Package main applies the headlesslab repository settings bundle to one or more GitHub repositories through `gh api` and reports what it changed, so a new repository needs one command and drift is one re-run away:
 Package main applies the headlesslab repository settings bundle to one or more GitHub repositories through `gh api` and reports what it changed, so a new repository needs one command and drift is one re-run away:
tools/setup command
Package main is the setup step of go generate and of the generate Gate: the Go modules, the Node tools of internal/tools/package.json from their lockfile (Node must be on PATH; golangci-lint needs no install, go run builds it at the pinned version), and the .dockerignore mirrored from .gitignore.
 Package main is the setup step of go generate and of the generate Gate: the Go modules, the Node tools of internal/tools/package.json from their lockfile (Node must be on PATH; golangci-lint needs no install, go run builds it at the pinned version), and the .dockerignore mirrored from .gitignore.
tools/shell command
Package main It helps to launcher a transparent shell under the current shell with some extra environment variables that are required by wand testing.
 Package main It helps to launcher a transparent shell under the current shell with some extra environment variables that are required by wand testing.
tools/simple-check command
Package main ...
 Package main ...
tools/support-window command
Package main prints the Chrome the oldest milestone in the Support window resolves to, which is the browser the Support-window Nightly runs the suite on (spec #33, section 13; ADR-0008; ticket #61):
 Package main prints the Chrome the oldest milestone in the Support window resolves to, which is the browser the Support-window Nightly runs the suite on (spec #33, section 13; ADR-0008; ticket #61):
tools/updated-graph command
Package main moves every module in the graph as far forward as the Go floor allows, and says which ones could not come the whole way, which is what the Nightly's updated-graph job runs before it runs the suite (spec #33, section 13; ADR-0006; ticket #61):
 Package main moves every module in the graph as far forward as the Go floor allows, and says which ones could not come the whole way, which is what the Nightly's updated-graph job runs before it runs the suite (spec #33, section 13; ADR-0006; ticket #61):
tools/zero-leftover command
Package main is the Zero leftover step every Tier 1 job ends with: it waits up to 30 s for the browsers a run launched to be gone, then fails on any chrome or chromium process still running and on anything still under launcher.DefaultUserDataDirPrefix, the directory the launcher makes its temporary user data directories in (spec #33, section 12; ticket #54).
 Package main is the Zero leftover step every Tier 1 job ends with: it waits up to 30 s for the browsers a run launched to be gone, then fails on any chrome or chromium process still running and on anything still under launcher.DefaultUserDataDirPrefix, the directory the launcher makes its temporary user data directories in (spec #33, section 12; ticket #54).
lib
cdp
Package cdp for application layer communication with browser.
 Package cdp for application layer communication with browser.
defaults
Package defaults of commonly used options parsed from environment.
 Package defaults of commonly used options parsed from environment.
devices
Package devices ...
 Package devices ...
devices/generate command
Package main ...
 Package main ...
examples/compare-chromedp/click command
Package main ...
 Package main ...
examples/compare-chromedp/cookie command
Package main ...
 Package main ...
examples/compare-chromedp/download_file command
Package main ...
 Package main ...
examples/compare-chromedp/download_image command
Package main ...
 Package main ...
examples/compare-chromedp/emulate command
Package main ...
 Package main ...
examples/compare-chromedp/eval command
Package main ...
 Package main ...
examples/compare-chromedp/headers command
Package main ...
 Package main ...
examples/compare-chromedp/keys command
Package main ...
 Package main ...
examples/compare-chromedp/logic command
Package main ...
 Package main ...
examples/compare-chromedp/pdf command
Package main ...
 Package main ...
examples/compare-chromedp/proxy command
Package main ...
 Package main ...
examples/compare-chromedp/remote command
Package main ...
 Package main ...
examples/compare-chromedp/screenshot command
Package main ...
 Package main ...
examples/compare-chromedp/submit command
Package main ...
 Package main ...
examples/compare-chromedp/subtree command
Package main ...
 Package main ...
examples/compare-chromedp/text command
Package main ...
 Package main ...
examples/compare-chromedp/upload command
Package main ...
 Package main ...
examples/compare-chromedp/visible command
Package main ...
 Package main ...
examples/connect-browser command
Package main ...
 Package main ...
examples/custom-launch command
Package main ...
 Package main ...
examples/disable-window-alert command
Package main ...
 Package main ...
examples/launch-managed command
Package main ...
 Package main ...
examples/stripe command
Package main ...
 Package main ...
examples/translator command
Package main ...
 Package main ...
examples/use-wand-like-chrome-extension command
Package main ...
 Package main ...
input
Package input ...
 Package input ...
js
Package js generated by "lib/js/generate"
 Package js generated by "lib/js/generate"
js/generate command
Package main ...
 Package main ...
launcher
Package launcher for launching browser utils.
 Package launcher for launching browser utils.
launcher/fixtures/chrome-empty command
Package main ...
 Package main ...
launcher/fixtures/chrome-exit-err command
Package main ...
 Package main ...
launcher/fixtures/chrome-headless command
Package main is a fake browser that answers --dump-dom the way a headless browser does, for the launcher's validation test.
 Package main is a fake browser that answers --dump-dom the way a headless browser does, for the launcher's validation test.
launcher/fixtures/chrome-lib-missing command
Package main ...
 Package main ...
launcher/flags
Package flags ...
 Package flags ...
launcher/pins
Package pins holds the Target Chrome and everything that rolls with it: the Chrome for Testing Stable version wand is aligned to and its Chromium main branch position, the Protocol roll the protocol layer is generated from, the Companion Chromium trunk build, and the SHA-256 of every Managed browser archive the launcher may download.
 Package pins holds the Target Chrome and everything that rolls with it: the Chrome for Testing Stable version wand is aligned to and its Chromium main branch position, the Protocol roll the protocol layer is generated from, the Companion Chromium trunk build, and the SHA-256 of every Managed browser archive the launcher may download.
launcher/pins/generate command
Package main is the Roll tool: it computes everything lib/launcher/pins holds and rewrites every place the pins appear, so the launcher, the protocol generator, the Roll, the release workflow and the READMEs all carry the same numbers.
 Package main is the Roll tool: it computes everything lib/launcher/pins holds and rewrites every place the pins appear, so the launcher, the protocol generator, the Roll, the release workflow and the READMEs all carry the same numbers.
proto
Package proto is a lib to encode/decode the data of the cdp protocol.
 Package proto is a lib to encode/decode the data of the cdp protocol.
proto/generate command
Package main generates lib/proto from ChromeDevTools/devtools-protocol at the Protocol roll of lib/launcher/pins, with no browser involved (ADR-0004):
 Package main generates lib/proto from ChromeDevTools/devtools-protocol at the Protocol roll of lib/launcher/pins, with no browser involved (ADR-0004):
utils
Package utils ...
 Package utils ...

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.