webpilot

package module
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: Mar 23, 2026 License: MIT Imports: 13 Imported by: 0

README

WebPilot

Go CI Go Lint Go SAST Go Report Card Docs Visualization License

Go browser automation library using WebDriver BiDi for real-time bidirectional communication with browsers, ideal for AI-assisted automation.

Overview

This project provides:

Component Description
Go Client SDK Programmatic browser control
MCP Server 85+ tools for AI assistants
CLI Command-line browser automation
Script Runner Deterministic test execution
Session Recording Capture actions as replayable scripts

Architecture

┌────────────────────────────────────────────────────────────────┐
│                         webpilot                               │
├─────────────┬─────────────┬─────────────┬──────────────────────┤
│  Go Client  │ MCP Server  │    CLI      │   Script Runner      │
│    SDK      │  (85 tools) │  (webpilot) │   (webpilot run)     │
├─────────────┴─────────────┴─────────────┴──────────────────────┤
│                    WebDriver BiDi Protocol                     │
├────────────────────────────────────────────────────────────────┤
│                    Chrome / Chromium                           │
└────────────────────────────────────────────────────────────────┘

Installation

go get github.com/plexusone/webpilot

Quick Start

Go Client SDK
package main

import (
    "context"
    "log"

    "github.com/plexusone/webpilot"
)

func main() {
    ctx := context.Background()

    // Launch browser
    pilot, err := webpilot.Launch(ctx)
    if err != nil {
        log.Fatal(err)
    }
    defer pilot.Quit(ctx)

    // Navigate and interact
    pilot.Go(ctx, "https://example.com")

    link, _ := pilot.Find(ctx, "a", nil)
    link.Click(ctx, nil)
}
MCP Server

Start the MCP server for AI assistant integration:

webpilot mcp --headless

Configure in Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "webpilot": {
      "command": "webpilot",
      "args": ["mcp", "--headless"]
    }
  }
}
CLI Commands
# Launch browser and run commands
webpilot launch --headless
webpilot go https://example.com
webpilot fill "#email" "user@example.com"
webpilot click "#submit"
webpilot screenshot result.png
webpilot quit
Script Runner

Execute deterministic test scripts:

webpilot run test.json

Script format (JSON or YAML):

{
  "name": "Login Test",
  "steps": [
    {"action": "navigate", "url": "https://example.com/login"},
    {"action": "fill", "selector": "#email", "value": "user@example.com"},
    {"action": "fill", "selector": "#password", "value": "secret"},
    {"action": "click", "selector": "#submit"},
    {"action": "assertUrl", "expected": "https://example.com/dashboard"}
  ]
}

Feature Comparison

Client SDK
Feature Status
Browser launch/quit ✅
Navigation (go, back, forward, reload) ✅
Element finding (CSS selectors) ✅
Click, type, fill ✅
Screenshots ✅
JavaScript evaluation ✅
Keyboard/mouse controllers ✅
Browser context management ✅
Network interception ✅
Tracing ✅
Clock control ✅
Additional Features
Feature Description
MCP Server 75+ tools for AI-assisted automation
CLI webpilot command with subcommands
Script Runner Execute JSON/YAML test scripts
Session Recording Capture MCP actions as replayable scripts
JSON Schema Validated script format
Test Reporting Structured test results with diagnostics

MCP Server Tools

The MCP server provides 85+ tools organized by category:

Category Tools
Browser browser_launch, browser_quit
Navigation navigate, back, forward, reload
Interactions click, dblclick, type, fill, clear, press
Forms check, uncheck, select_option, set_files, fill_form
Element State get_text, get_value, is_visible, is_enabled
Page State get_title, get_url, get_content, screenshot
Waiting wait_until, wait_for_url, wait_for_load
Storage get_storage_state, set_storage_state, clear_storage
LocalStorage localstorage_get, localstorage_set, localstorage_list, localstorage_delete, localstorage_clear
SessionStorage sessionstorage_get, sessionstorage_set, sessionstorage_list, sessionstorage_delete, sessionstorage_clear
Network get_network_requests, clear_network_requests, route, unroute, route_list
Tabs list_tabs, select_tab, close_tab
Dialogs handle_dialog, get_dialog
HITL pause_for_human
Input keyboard_*, mouse_*, touch_*
Tracing start_trace, stop_trace, start_trace_chunk, stop_trace_chunk
Init Scripts add_init_script
Recording start_recording, stop_recording, export_script
Assertions assert_text, assert_element, assert_url

Session Recording Workflow

Convert natural language test plans into deterministic scripts:

┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│  Markdown Test   │     │   LLM + MCP      │     │   JSON Script    │
│  Plan (English)  │ ──▶ │   (exploration)  │ ──▶ │ (deterministic)  │
└──────────────────┘     └──────────────────┘     └──────────────────┘
  1. Write test plan in Markdown
  2. LLM executes via MCP with start_recording
  3. LLM explores, finds selectors, handles edge cases
  4. Export with export_script to get JSON
  5. Run deterministically with webpilot run

API Reference

See pkg.go.dev for full API documentation.

Key Types
// Launch browser
pilot, err := webpilot.Launch(ctx)
pilot, err := webpilot.LaunchHeadless(ctx)

// Navigation
pilot.Go(ctx, url)
pilot.Back(ctx)
pilot.Forward(ctx)
pilot.Reload(ctx)

// Finding elements by CSS selector
elem, err := pilot.Find(ctx, selector, nil)
elems, err := pilot.FindAll(ctx, selector, nil)

// Element interactions
elem.Click(ctx, nil)
elem.Fill(ctx, value, nil)
elem.Type(ctx, text, nil)

// Input controllers
pilot.Keyboard().Press(ctx, "Enter")
pilot.Mouse().Click(ctx, x, y)

// Capture
data, err := pilot.Screenshot(ctx)

Semantic Selectors

Find elements by accessibility attributes instead of brittle CSS selectors. This is especially useful for AI-assisted automation where element structure may change but semantics remain stable.

SDK Usage
// Find by ARIA role and text content
elem, err := pilot.Find(ctx, "", &webpilot.FindOptions{
    Role: "button",
    Text: "Submit",
})

// Find by label (for form inputs)
elem, err := pilot.Find(ctx, "", &webpilot.FindOptions{
    Label: "Email address",
})

// Find by placeholder
elem, err := pilot.Find(ctx, "", &webpilot.FindOptions{
    Placeholder: "Enter your email",
})

// Find by data-testid (recommended for testing)
elem, err := pilot.Find(ctx, "", &webpilot.FindOptions{
    TestID: "login-button",
})

// Combine CSS selector with semantic filtering
elem, err := pilot.Find(ctx, "form", &webpilot.FindOptions{
    Role: "textbox",
    Label: "Password",
})

// Find all buttons
buttons, err := pilot.FindAll(ctx, "", &webpilot.FindOptions{Role: "button"})

// Find element near another element
elem, err := pilot.Find(ctx, "", &webpilot.FindOptions{
    Role: "button",
    Near: "#username-input",
})
MCP Tool Usage

Semantic selectors work with click, type, fill, and press tools:

// Click a button by role and text
{"name": "click", "arguments": {"role": "button", "text": "Sign In"}}

// Fill input by label
{"name": "fill", "arguments": {"label": "Email", "value": "user@example.com"}}

// Type in input by placeholder
{"name": "type", "arguments": {"placeholder": "Search...", "text": "query"}}

// Click by data-testid
{"name": "click", "arguments": {"testid": "submit-btn"}}
Available Selectors
Selector Description Example
role ARIA role button, textbox, link, checkbox
text Visible text content "Submit", "Learn more"
label Associated label text "Email address", "Password"
placeholder Input placeholder "Enter email"
testid data-testid attribute "login-btn"
alt Image alt text "Company logo"
title Element title attribute "Close dialog"
xpath XPath expression "//button[@type='submit']"
near CSS selector of nearby element "#username"

Init Scripts

Inject JavaScript that runs before any page scripts on every navigation. Useful for mocking APIs, injecting test helpers, or setting up authentication.

SDK Usage
// Add init script to inject before page scripts
err := pilot.AddInitScript(ctx, `window.testMode = true;`)

// Mock an API
err := pilot.AddInitScript(ctx, `
    window.fetch = async (url, opts) => {
        if (url.includes('/api/user')) {
            return { json: () => ({ id: 1, name: 'Test User' }) };
        }
        return originalFetch(url, opts);
    };
`)
CLI Usage
# Inject scripts when launching
webpilot mcp --init-script=./mock-api.js --init-script=./test-helpers.js

# Or with the standalone binary
webpilot-mcp -init-script=./mock-api.js
MCP Tool Usage
{"name": "add_init_script", "arguments": {"script": "window.testMode = true;"}}

Storage State

Save and restore complete browser state including cookies, localStorage, and sessionStorage. Essential for maintaining login sessions across browser restarts.

SDK Usage
// Get complete storage state
state, err := pilot.StorageState(ctx)

// Save to file
jsonBytes, _ := json.Marshal(state)
os.WriteFile("auth-state.json", jsonBytes, 0600)

// Restore from file
var savedState webpilot.StorageState
json.Unmarshal(jsonBytes, &savedState)
err := pilot.SetStorageState(ctx, &savedState)

// Clear all storage
err := pilot.ClearStorage(ctx)
MCP Tool Usage
// Save session
{"name": "get_storage_state"}

// Restore session
{"name": "set_storage_state", "arguments": {"state": "<json from get_storage_state>"}}

// Clear all storage
{"name": "clear_storage"}

Tracing

Record browser actions with screenshots and DOM snapshots for debugging and test creation.

SDK Usage
// Start tracing
tracing := pilot.Tracing()
err := tracing.Start(ctx, &webpilot.TracingStartOptions{
    Screenshots: true,
    Snapshots:   true,
    Title:       "Login Flow Test",
})

// Perform actions...
pilot.Go(ctx, "https://example.com")
elem, _ := pilot.Find(ctx, "button", nil)
elem.Click(ctx, nil)

// Stop and save trace
data, err := tracing.Stop(ctx, nil)
os.WriteFile("trace.zip", data, 0600)
MCP Tool Usage
// Start trace
{"name": "start_trace", "arguments": {"screenshots": true, "title": "My Test"}}

// Stop and get trace data
{"name": "stop_trace", "arguments": {"path": "/tmp/trace.zip"}}

Testing

# Unit tests
go test -v ./...

# Integration tests
go test -tags=integration -v ./integration/...

# Headless mode
WEBPILOT_HEADLESS=1 go test -tags=integration -v ./integration/...

Debug Logging

WEBPILOT_DEBUG=1 webpilot mcp

License

MIT

Documentation

Overview

Package webpilot provides a Go client for the WebPilot browser automation platform.

WebPilot is a browser automation platform built for AI agents that uses the WebDriver BiDi protocol for bidirectional communication with the browser.

Quick Start

Launch a browser and navigate to a page: 

ctx := context.Background()
pilot, err := webpilot.Launch(ctx)
if err != nil {
    log.Fatal(err)
}
defer pilot.Quit(ctx)

if err := pilot.Go(ctx, "https://example.com"); err != nil {
    log.Fatal(err)
}

Finding and Interacting with Elements

Find elements using CSS selectors and interact with them: 

link, err := pilot.Find(ctx, "a.my-link", nil)
if err != nil {
    log.Fatal(err)
}

if err := link.Click(ctx, nil); err != nil {
    log.Fatal(err)
}

Type text into input fields: 

input, err := pilot.Find(ctx, "input[name='search']", nil)
if err != nil {
    log.Fatal(err)
}

if err := input.Type(ctx, "search query", nil); err != nil {
    log.Fatal(err)
}

Screenshots

Capture screenshots as PNG data: 

data, err := pilot.Screenshot(ctx)
if err != nil {
    log.Fatal(err)
}
os.WriteFile("screenshot.png", data, 0644)

Headless Mode

Launch in headless mode for CI/server environments: 

pilot, err := webpilot.LaunchHeadless(ctx)

Or with explicit options: 

pilot, err := webpilot.Browser.Launch(ctx, &webpilot.LaunchOptions{
    Headless: true,
    Port:     9515,
})

Requirements

This client requires Chrome or Chromium. If Chrome is not found on your system, it will automatically download Chrome for Testing from Google's official API.

You can also specify a custom Chrome path via the CHROME_PATH environment variable or the ExecutablePath option in LaunchOptions.

Package webpilot provides a Go client for browser automation using the WebDriver BiDi protocol. It launches Chrome with BiDi support and communicates over WebSocket.

Example 
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/plexusone/webpilot"
)

func main() {
	ctx := context.Background()

	// Launch browser
	pilot, err := webpilot.Launch(ctx)
	if err != nil {
		log.Fatal(err)
	}
	defer func() { _ = pilot.Quit(ctx) }()

	// Navigate to a page
	if err := pilot.Go(ctx, "https://example.com"); err != nil {
		log.Fatal(err)
	}

	// Find and click a link
	link, err := pilot.Find(ctx, "a", nil)
	if err != nil {
		log.Fatal(err)
	}

	if err := link.Click(ctx, nil); err != nil {
		log.Fatal(err)
	}

	// Get page title
	title, err := pilot.Title(ctx)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Page title:", title)
}
Example (FormInteraction) 
package main

import (
	"context"
	"log"

	"github.com/plexusone/webpilot"
)

func main() {
	ctx := context.Background()

	pilot, err := webpilot.Browser.Launch(ctx, &webpilot.LaunchOptions{
		Headless: true,
	})
	if err != nil {
		log.Fatal(err)
	}
	defer func() { _ = pilot.Quit(ctx) }()

	// Navigate to a form page
	if err := pilot.Go(ctx, "https://example.com/login"); err != nil {
		log.Fatal(err)
	}

	// Fill in username
	username, err := pilot.Find(ctx, "input[name='username']", nil)
	if err != nil {
		log.Fatal(err)
	}
	if err := username.Type(ctx, "myuser", nil); err != nil {
		log.Fatal(err)
	}

	// Fill in password
	password, err := pilot.Find(ctx, "input[name='password']", nil)
	if err != nil {
		log.Fatal(err)
	}
	if err := password.Type(ctx, "mypassword", nil); err != nil {
		log.Fatal(err)
	}

	// Click submit
	submit, err := pilot.Find(ctx, "button[type='submit']", nil)
	if err != nil {
		log.Fatal(err)
	}
	if err := submit.Click(ctx, nil); err != nil {
		log.Fatal(err)
	}
}
Example (Headless) 
package main

import (
	"context"
	"log"
	"os"

	"github.com/plexusone/webpilot"
)

func main() {
	ctx := context.Background()

	// Launch headless browser
	pilot, err := webpilot.LaunchHeadless(ctx)
	if err != nil {
		log.Fatal(err)
	}
	defer func() { _ = pilot.Quit(ctx) }()

	// Navigate
	if err := pilot.Go(ctx, "https://example.com"); err != nil {
		log.Fatal(err)
	}

	// Take screenshot
	data, err := pilot.Screenshot(ctx)
	if err != nil {
		log.Fatal(err)
	}

	// Save to file
	if err := os.WriteFile("screenshot.png", data, 0600); err != nil {
		log.Fatal(err)
	}
}

Index

Examples

Constants

View Source 
const DefaultTimeout = 30 * time.Second

DefaultTimeout is the default timeout for finding elements and waiting for actionability.

Variables

View Source 
var (
	// ErrConnectionFailed is returned when WebSocket connection fails.
	ErrConnectionFailed = errors.New("failed to connect to browser")

	// ErrElementNotFound is returned when an element cannot be found.
	ErrElementNotFound = errors.New("element not found")

	// ErrBrowserCrashed is returned when the browser process exits unexpectedly.
	ErrBrowserCrashed = errors.New("browser crashed")

	// ErrBrowserNotFound is returned when Chrome cannot be found.
	ErrBrowserNotFound = errors.New("Chrome not found")

	// ErrClickerNotFound is deprecated: use ErrBrowserNotFound instead.
	// Deprecated: This error is no longer used. Use ErrBrowserNotFound.
	ErrClickerNotFound = ErrBrowserNotFound

	// ErrTimeout is returned when an operation times out.
	ErrTimeout = errors.New("operation timed out")

	// ErrConnectionClosed is returned when the WebSocket connection is closed.
	ErrConnectionClosed = errors.New("connection closed")
)
View Source 
var Browser = &browserLauncher{}

Browser provides browser launching capabilities.

Functions

func ContextWithLogger 

func ContextWithLogger(ctx context.Context, logger *slog.Logger) context.Context

ContextWithLogger returns a new context with the logger attached.

func Debug 

func Debug() bool

Debug returns true if debug logging is enabled via WEBPILOT_DEBUG environment variable.

func LoggerFromContext 

func LoggerFromContext(ctx context.Context) *slog.Logger

LoggerFromContext returns the logger from the context, or nil if not present.

func NewDebugLogger 

func NewDebugLogger() *slog.Logger

NewDebugLogger creates a new debug logger that writes to stderr. Returns nil if debug logging is disabled.

Types

type A11yTreeOptions 

type A11yTreeOptions struct {
	// InterestingOnly filters the tree to only include interesting nodes.
	// Interesting nodes are those with semantic meaning (roles, names, states).
	// Default is true.
	InterestingOnly *bool

	// Root specifies a CSS selector for the root element.
	// If specified, only the subtree under this element is returned.
	Root string
}

A11yTreeOptions configures accessibility tree retrieval.

type ActionOptions 

type ActionOptions struct {
	// Timeout specifies how long to wait for actionability.
	// Default is 30 seconds.
	Timeout time.Duration
}

ActionOptions configures action behavior (click, type).

type BiDiClient 

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

BiDiClient manages WebSocket communication with Chrome's BiDi server.

func NewBiDiClient 

func NewBiDiClient() *BiDiClient

NewBiDiClient creates a new BiDi client.

func (*BiDiClient) Close 

func (c *BiDiClient) Close() error

Close closes the WebSocket connection.

func (*BiDiClient) Connect 

func (c *BiDiClient) Connect(ctx context.Context, url string) error

Connect establishes a WebSocket connection to Chrome's BiDi server.

func (*BiDiClient) OnEvent 

func (c *BiDiClient) OnEvent(method string, handler EventHandler)

OnEvent registers a handler for events matching the given method pattern. The method can be an exact match (e.g., "log.entryAdded") or a prefix (e.g., "log." to match all log events).

func (*BiDiClient) RemoveEventHandlers 

func (c *BiDiClient) RemoveEventHandlers(method string)

RemoveEventHandlers removes all handlers for the given method.

func (*BiDiClient) Send 

func (c *BiDiClient) Send(ctx context.Context, method string, params interface{}) (json.RawMessage, error)

Send sends a command and waits for the response.

type BiDiCommand 

type BiDiCommand struct {
	ID     int64       `json:"id"`
	Method string      `json:"method"`
	Params interface{} `json:"params"`
}

BiDiCommand represents a WebDriver BiDi command.

type BiDiError 

type BiDiError struct {
	ErrorType string
	Message   string
}

BiDiError represents an error from the BiDi protocol.

func (*BiDiError) Error 

func (e *BiDiError) Error() string

type BiDiEvent 

type BiDiEvent struct {
	Method string          `json:"method"`
	Params json.RawMessage `json:"params"`
}

BiDiEvent represents a WebDriver BiDi event.

type BiDiResponse 

type BiDiResponse struct {
	ID      int64           `json:"id"`
	Type    string          `json:"type"`
	Method  string          `json:"method,omitempty"` // For events
	Result  json.RawMessage `json:"result,omitempty"`
	Params  json.RawMessage `json:"params,omitempty"` // For events
	Error   string          `json:"error,omitempty"`
	Message string          `json:"message,omitempty"`
}

BiDiResponse represents a WebDriver BiDi response.

type BoundingBox 

type BoundingBox struct {
	X      float64 `json:"x"`
	Y      float64 `json:"y"`
	Width  float64 `json:"width"`
	Height float64 `json:"height"`
}

BoundingBox represents the position and size of an element.

type BrowserContext 

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

BrowserContext represents an isolated browser context (like an incognito window). Each context has its own cookies, localStorage, and session storage.

func (*BrowserContext) AddInitScript 

func (c *BrowserContext) AddInitScript(ctx context.Context, script string) error

AddInitScript adds a script that will be evaluated in every page created in this context.

func (*BrowserContext) ClearCookies 

func (c *BrowserContext) ClearCookies(ctx context.Context) error

ClearCookies clears all cookies.

func (*BrowserContext) ClearPermissions 

func (c *BrowserContext) ClearPermissions(ctx context.Context) error

ClearPermissions clears all granted permissions.

func (*BrowserContext) Close 

func (c *BrowserContext) Close(ctx context.Context) error

Close closes the browser context and all pages within it.

func (*BrowserContext) Cookies 

func (c *BrowserContext) Cookies(ctx context.Context, urls ...string) ([]Cookie, error)

Cookies returns cookies matching the specified URLs. If no URLs are specified, returns all cookies for the context.

func (*BrowserContext) DeleteCookie 

func (c *BrowserContext) DeleteCookie(ctx context.Context, name string, domain string, path string) error

DeleteCookie deletes a specific cookie by name. Optional domain and path can be specified to target a specific cookie.

func (*BrowserContext) GrantPermissions 

func (c *BrowserContext) GrantPermissions(ctx context.Context, permissions []string, origin string) error

GrantPermissions grants the specified permissions.

func (*BrowserContext) NewPage 

func (c *BrowserContext) NewPage(ctx context.Context) (*Pilot, error)

NewPage creates a new page in this browser context.

func (*BrowserContext) SetCookies 

func (c *BrowserContext) SetCookies(ctx context.Context, cookies []SetCookieParam) error

SetCookies sets cookies.

func (*BrowserContext) StorageState 

func (c *BrowserContext) StorageState(ctx context.Context) (*StorageState, error)

StorageState returns the storage state including cookies and localStorage.

func (*BrowserContext) Tracing 

func (c *BrowserContext) Tracing() *Tracing

Tracing returns the tracing controller for this context.

type BrowserCrashedError 

type BrowserCrashedError struct {
	ExitCode int
	Output   string
}

BrowserCrashedError represents an unexpected browser exit.

func (*BrowserCrashedError) Error 

func (e *BrowserCrashedError) Error() string

type ClickOptions 

type ClickOptions struct {
	Button     MouseButton
	ClickCount int
	Delay      int // milliseconds between mousedown and mouseup
}

ClickOptions configures mouse click behavior.

type Clock 

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

Clock provides control over time in the browser.

func NewClock 

func NewClock(client *BiDiClient, browsingContext string) *Clock

NewClock creates a new Clock controller.

func (*Clock) FastForward 

func (c *Clock) FastForward(ctx context.Context, ticks int64) error

FastForward advances time by the specified number of milliseconds. Timers are not fired.

func (*Clock) Install 

func (c *Clock) Install(ctx context.Context, opts *ClockInstallOptions) error

Install installs fake timers in the browser. This replaces native time-related functions like Date, setTimeout, etc.

func (*Clock) PauseAt 

func (c *Clock) PauseAt(ctx context.Context, t interface{}) error

PauseAt pauses time at the specified timestamp.

func (*Clock) Resume 

func (c *Clock) Resume(ctx context.Context) error

Resume resumes time from a paused state.

func (*Clock) RunFor 

func (c *Clock) RunFor(ctx context.Context, ticks int64) error

RunFor advances time by the specified number of milliseconds, firing all pending timers.

func (*Clock) SetFixedTime 

func (c *Clock) SetFixedTime(ctx context.Context, t interface{}) error

SetFixedTime sets a fixed time that will be returned by Date.now() and new Date().

func (*Clock) SetSystemTime 

func (c *Clock) SetSystemTime(ctx context.Context, t interface{}) error

SetSystemTime sets the system time.

func (*Clock) SetTimezone 

func (c *Clock) SetTimezone(ctx context.Context, tz string) error

SetTimezone sets the timezone.

type ClockInstallOptions 

type ClockInstallOptions struct {
	// Time to set as the current time (Unix timestamp in milliseconds or time.Time)
	Time interface{}
}

ClockInstallOptions configures clock installation.

type ConnectionError 

type ConnectionError struct {
	URL   string
	Cause error
}

ConnectionError represents a WebSocket connection failure.

func (*ConnectionError) Error 

func (e *ConnectionError) Error() string

func (*ConnectionError) Unwrap 

func (e *ConnectionError) Unwrap() error

type ConsoleHandler 

type ConsoleHandler func(*ConsoleMessage)

ConsoleHandler is called for each console message.

type ConsoleMessage 

type ConsoleMessage struct {
	Type string   `json:"type"`
	Text string   `json:"text"`
	Args []string `json:"args,omitempty"`
	URL  string   `json:"url,omitempty"`
	Line int      `json:"line,omitempty"`
}

ConsoleMessage represents a console message from the browser.

type ContinueOptions 

type ContinueOptions struct {
	URL      string
	Method   string
	Headers  map[string]string
	PostData string
}

ContinueOptions configures how to continue a route. 

type Cookie struct {
	Name         string  `json:"name"`
	Value        string  `json:"value"`
	Domain       string  `json:"domain"`
	Path         string  `json:"path"`
	Expires      float64 `json:"expires"`
	HTTPOnly     bool    `json:"httpOnly"`
	Secure       bool    `json:"secure"`
	SameSite     string  `json:"sameSite"`
	PartitionKey string  `json:"partitionKey,omitempty"`
}

Cookie represents a browser cookie.

type Dialog 

type Dialog struct {
	Type    string `json:"type"` // "alert", "confirm", "prompt", "beforeunload"
	Message string `json:"message"`
	Default string `json:"defaultValue,omitempty"` // For prompt dialogs
	// contains filtered or unexported fields
}

Dialog represents a browser dialog (alert, confirm, prompt, beforeunload).

func (*Dialog) Accept 

func (d *Dialog) Accept(ctx context.Context, promptText string) error

Accept accepts the dialog. For prompt dialogs, optionally provide a text value.

func (*Dialog) Dismiss 

func (d *Dialog) Dismiss(ctx context.Context) error

Dismiss dismisses the dialog (clicks cancel/no).

type DialogHandler 

type DialogHandler func(*Dialog)

DialogHandler is called when a dialog appears.

type DialogInfo 

type DialogInfo struct {
	HasDialog    bool   `json:"has_dialog"`
	Type         string `json:"type,omitempty"`
	Message      string `json:"message,omitempty"`
	DefaultValue string `json:"default_value,omitempty"`
}

DialogInfo contains information about the current dialog.

type Download 

type Download struct {
	URL  string `json:"url"`
	Name string `json:"suggestedFilename"`
	// contains filtered or unexported fields
}

Download represents a file download.

func (*Download) Cancel 

func (d *Download) Cancel(ctx context.Context) error

Cancel cancels the download.

func (*Download) Failure 

func (d *Download) Failure(ctx context.Context) (string, error)

Failure returns the download failure reason, if any.

func (*Download) Path 

func (d *Download) Path(ctx context.Context) (string, error)

Path returns the path to the downloaded file after it completes.

func (*Download) SaveAs 

func (d *Download) SaveAs(ctx context.Context, path string) error

SaveAs saves the download to the specified path.

type DownloadHandler 

type DownloadHandler func(*Download)

DownloadHandler is called when a download starts.

type Element 

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

Element represents a DOM element that can be interacted with.

func NewElement 

func NewElement(client *BiDiClient, browsingContext, selector string, info ElementInfo) *Element

NewElement creates a new Element instance.

func (*Element) BoundingBox 

func (e *Element) BoundingBox(ctx context.Context) (BoundingBox, error)

BoundingBox returns the element's bounding box.

func (*Element) Center 

func (e *Element) Center() (x, y float64)

Center returns the center point of the element.

func (*Element) Check 

func (e *Element) Check(ctx context.Context, opts *ActionOptions) error

Check checks a checkbox element. It waits for the element to be visible, stable, and enabled.

func (*Element) Clear 

func (e *Element) Clear(ctx context.Context, opts *ActionOptions) error

Clear clears the text content of an input field.

func (*Element) Click 

func (e *Element) Click(ctx context.Context, opts *ActionOptions) error

Click clicks on the element. It waits for the element to be visible, stable, able to receive events, and enabled before clicking.

func (*Element) DblClick 

func (e *Element) DblClick(ctx context.Context, opts *ActionOptions) error

DblClick double-clicks on the element.

func (*Element) DispatchEvent 

func (e *Element) DispatchEvent(ctx context.Context, eventType string, eventInit map[string]interface{}) error

DispatchEvent dispatches a DOM event on the element.

func (*Element) DragTo 

func (e *Element) DragTo(ctx context.Context, target *Element, opts *ActionOptions) error

DragTo drags this element to the target element.

func (*Element) Eval 

func (e *Element) Eval(ctx context.Context, fn string, args ...interface{}) (interface{}, error)

Eval evaluates a JavaScript function with this element as the argument. The function should accept the element as its first parameter.

func (*Element) Fill 

func (e *Element) Fill(ctx context.Context, value string, opts *ActionOptions) error

Fill clears the input and fills it with the specified value. It waits for the element to be visible, stable, enabled, and editable before filling.

func (*Element) Find 

func (e *Element) Find(ctx context.Context, selector string, opts *FindOptions) (*Element, error)

Find finds a child element within this element by CSS selector or semantic options.

func (*Element) FindAll 

func (e *Element) FindAll(ctx context.Context, selector string, opts *FindOptions) ([]*Element, error)

FindAll finds all child elements within this element by CSS selector or semantic options.

func (*Element) Focus 

func (e *Element) Focus(ctx context.Context, opts *ActionOptions) error

Focus focuses the element.

func (*Element) GetAttribute 

func (e *Element) GetAttribute(ctx context.Context, name string) (string, error)

GetAttribute returns the value of the specified attribute.

func (*Element) HTML 

func (e *Element) HTML(ctx context.Context) (string, error)

HTML returns the outerHTML of the element (including the element itself).

func (*Element) Highlight 

func (e *Element) Highlight(ctx context.Context, opts *HighlightOptions) error

Highlight draws a visual overlay on the element for debugging. The highlight is displayed for the specified duration (default 2 seconds). This is useful for visual debugging to see which element is being targeted.

func (*Element) Hover 

func (e *Element) Hover(ctx context.Context, opts *ActionOptions) error

Hover moves the mouse over the element.

func (*Element) Info 

func (e *Element) Info() ElementInfo

Info returns the element's metadata.

func (*Element) InnerHTML 

func (e *Element) InnerHTML(ctx context.Context) (string, error)

InnerHTML returns the inner HTML of the element.

func (*Element) InnerText 

func (e *Element) InnerText(ctx context.Context) (string, error)

InnerText returns the rendered text content of the element.

func (*Element) IsChecked 

func (e *Element) IsChecked(ctx context.Context) (bool, error)

IsChecked returns whether a checkbox or radio element is checked.

func (*Element) IsEditable 

func (e *Element) IsEditable(ctx context.Context) (bool, error)

IsEditable returns whether the element is editable.

func (*Element) IsEnabled 

func (e *Element) IsEnabled(ctx context.Context) (bool, error)

IsEnabled returns whether the element is enabled.

func (*Element) IsHidden 

func (e *Element) IsHidden(ctx context.Context) (bool, error)

IsHidden returns whether the element is hidden.

func (*Element) IsVisible 

func (e *Element) IsVisible(ctx context.Context) (bool, error)

IsVisible returns whether the element is visible.

func (*Element) Label 

func (e *Element) Label(ctx context.Context) (string, error)

Label returns the accessible label of the element.

func (*Element) Press 

func (e *Element) Press(ctx context.Context, key string, opts *ActionOptions) error

Press presses a key on the element. It waits for the element to be visible, stable, and able to receive events.

func (*Element) Role 

func (e *Element) Role(ctx context.Context) (string, error)

Role returns the ARIA role of the element.

func (*Element) Screenshot 

func (e *Element) Screenshot(ctx context.Context) ([]byte, error)

Screenshot captures a screenshot of just this element.

func (*Element) ScrollIntoView 

func (e *Element) ScrollIntoView(ctx context.Context, opts *ActionOptions) error

ScrollIntoView scrolls the element into the visible area of the viewport.

func (*Element) SelectOption 

func (e *Element) SelectOption(ctx context.Context, values SelectOptionValues, opts *ActionOptions) error

SelectOption selects an option in a <select> element by value, label, or index.

func (*Element) Selector 

func (e *Element) Selector() string

Selector returns the CSS selector used to find this element.

func (*Element) SetFiles 

func (e *Element) SetFiles(ctx context.Context, paths []string, opts *ActionOptions) error

SetFiles sets the files for a file input element.

func (*Element) Tap 

func (e *Element) Tap(ctx context.Context, opts *ActionOptions) error

Tap performs a touch tap on the element.

func (*Element) Text 

func (e *Element) Text(ctx context.Context) (string, error)

Text returns the text content of the element.

func (*Element) Type 

func (e *Element) Type(ctx context.Context, text string, opts *ActionOptions) error

Type types text into the element. It waits for the element to be visible, stable, able to receive events, enabled, and editable before typing.

func (*Element) Uncheck 

func (e *Element) Uncheck(ctx context.Context, opts *ActionOptions) error

Uncheck unchecks a checkbox element. It waits for the element to be visible, stable, and enabled.

func (*Element) Value 

func (e *Element) Value(ctx context.Context) (string, error)

Value returns the value of an input element.

func (*Element) WaitFor 

func (e *Element) WaitFor(ctx context.Context, timeout time.Duration) error

WaitFor waits for the element to appear in the DOM.

func (*Element) WaitUntil 

func (e *Element) WaitUntil(ctx context.Context, state string, timeout time.Duration) error

WaitUntil waits for the element to reach the specified state. State can be: "attached", "detached", "visible", "hidden".

type ElementInfo 

type ElementInfo struct {
	Tag  string      `json:"tag"`
	Text string      `json:"text"`
	Box  BoundingBox `json:"box"`
}

ElementInfo contains metadata about a DOM element.

type ElementNotFoundError 

type ElementNotFoundError struct {
	Selector string
}

ElementNotFoundError represents an element that could not be found.

func (*ElementNotFoundError) Error 

func (e *ElementNotFoundError) Error() string

type EmulateMediaOptions 

type EmulateMediaOptions struct {
	Media         string // "screen", "print", or ""
	ColorScheme   string // "light", "dark", "no-preference", or ""
	ReducedMotion string // "reduce", "no-preference", or ""
	ForcedColors  string // "active", "none", or ""
	Contrast      string // "more", "less", "no-preference", or ""
}

EmulateMediaOptions configures media emulation for accessibility testing.

type EventHandler 

type EventHandler func(event *BiDiEvent)

EventHandler is a callback for handling BiDi events.

type FindOptions 

type FindOptions struct {
	// Timeout specifies how long to wait for the element to appear.
	// Default is 30 seconds.
	Timeout time.Duration

	// Role matches elements by ARIA role (e.g., "button", "textbox").
	Role string

	// Text matches elements containing the specified text.
	Text string

	// Label matches elements by their associated label text.
	Label string

	// Placeholder matches input elements by placeholder attribute.
	Placeholder string

	// TestID matches elements by data-testid attribute.
	TestID string

	// Alt matches image elements by alt attribute.
	Alt string

	// Title matches elements by title attribute.
	Title string

	// XPath matches elements using an XPath expression.
	XPath string

	// Near finds elements near another element specified by selector.
	Near string
}

FindOptions configures element finding behavior.

type FrameInfo 

type FrameInfo struct {
	URL  string `json:"url"`
	Name string `json:"name"`
}

FrameInfo contains metadata about a frame.

type FulfillOptions 

type FulfillOptions struct {
	Status      int
	Headers     map[string]string
	ContentType string
	Body        []byte
	Path        string // Path to file to serve
}

FulfillOptions configures how to fulfill a route.

type Geolocation 

type Geolocation struct {
	Latitude  float64
	Longitude float64
	Accuracy  float64
}

Geolocation represents geographic coordinates.

type HighlightOptions 

type HighlightOptions struct {
	// Color is the highlight border color (CSS color value).
	// Default is "red".
	Color string

	// Duration is how long to show the highlight in milliseconds.
	// Default is 2000 (2 seconds). Use 0 for persistent highlight.
	Duration int
}

HighlightOptions configures element highlighting.

type Keyboard 

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

Keyboard provides keyboard input control.

func NewKeyboard 

func NewKeyboard(client *BiDiClient, browsingContext string) *Keyboard

NewKeyboard creates a new Keyboard controller.

func (*Keyboard) Down 

func (k *Keyboard) Down(ctx context.Context, key string) error

Down holds down a key.

func (*Keyboard) InsertText 

func (k *Keyboard) InsertText(ctx context.Context, text string) error

InsertText inserts text directly without keypress events. This is faster than Type but doesn't trigger keyboard events.

func (*Keyboard) Press 

func (k *Keyboard) Press(ctx context.Context, key string) error

Press presses a key on the keyboard. Key names follow the Playwright key naming convention (e.g., "Enter", "Tab", "ArrowUp").

func (*Keyboard) Type 

func (k *Keyboard) Type(ctx context.Context, text string) error

Type types text character by character. This sends individual keypress events for each character.

func (*Keyboard) Up 

func (k *Keyboard) Up(ctx context.Context, key string) error

Up releases a held key.

type LaunchOptions 

type LaunchOptions struct {
	// Headless runs the browser without a visible window.
	Headless bool

	// Port specifies the debugging port. If 0, an available port is auto-selected.
	Port int

	// ExecutablePath specifies a custom Chrome executable path.
	ExecutablePath string

	// UserDataDir specifies a custom user data directory.
	// If empty, a temporary directory is used.
	UserDataDir string

	// Args specifies additional command-line arguments for Chrome.
	Args []string

	// AutoInstall automatically downloads Chrome for Testing if not found.
	// Defaults to true (nil means true).
	AutoInstall *bool
}

LaunchOptions configures browser launch behavior.

type MockRouteOptions 

type MockRouteOptions struct {
	Status      int               // HTTP status code (default: 200)
	Body        string            // Response body
	ContentType string            // Content-Type header (default: application/json)
	Headers     map[string]string // Additional response headers
}

MockRouteOptions configures a static mock response for a route.

type Mouse 

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

Mouse provides mouse input control.

func NewMouse 

func NewMouse(client *BiDiClient, browsingContext string) *Mouse

NewMouse creates a new Mouse controller.

func (*Mouse) Click 

func (m *Mouse) Click(ctx context.Context, x, y float64, opts *ClickOptions) error

Click clicks at the specified coordinates.

func (*Mouse) DblClick 

func (m *Mouse) DblClick(ctx context.Context, x, y float64, opts *ClickOptions) error

DblClick double-clicks at the specified coordinates.

func (*Mouse) Down 

func (m *Mouse) Down(ctx context.Context, button MouseButton) error

Down presses the mouse button.

func (*Mouse) Move 

func (m *Mouse) Move(ctx context.Context, x, y float64) error

Move moves the mouse to the specified coordinates.

func (*Mouse) Up 

func (m *Mouse) Up(ctx context.Context, button MouseButton) error

Up releases the mouse button.

func (*Mouse) Wheel 

func (m *Mouse) Wheel(ctx context.Context, deltaX, deltaY float64) error

Wheel scrolls the mouse wheel.

type MouseButton 

type MouseButton string

MouseButton represents a mouse button. 

const (
	MouseButtonLeft   MouseButton = "left"
	MouseButtonRight  MouseButton = "right"
	MouseButtonMiddle MouseButton = "middle"
)

type NetworkRequest 

type NetworkRequest struct {
	URL          string            `json:"url"`
	Method       string            `json:"method"`
	Headers      map[string]string `json:"headers,omitempty"`
	PostData     string            `json:"postData,omitempty"`
	ResourceType string            `json:"resourceType"`
	Status       int               `json:"status,omitempty"`
	StatusText   string            `json:"statusText,omitempty"`
	ResponseSize int64             `json:"responseSize,omitempty"`
	Timestamp    int64             `json:"timestamp,omitempty"`
}

NetworkRequest represents a captured network request with its response.

type NetworkRequestsOptions 

type NetworkRequestsOptions struct {
	URLPattern   string // Glob or regex pattern to filter URLs
	Method       string // Filter by HTTP method (GET, POST, etc.)
	ResourceType string // Filter by resource type (document, script, xhr, etc.)
}

NetworkRequestsOptions configures network request filtering.

type PDFMargin 

type PDFMargin struct {
	Top    string
	Right  string
	Bottom string
	Left   string
}

PDFMargin configures PDF page margins.

type PDFOptions 

type PDFOptions struct {
	Path            string
	Scale           float64
	DisplayHeader   bool
	DisplayFooter   bool
	PrintBackground bool
	Landscape       bool
	PageRanges      string
	Format          string // "Letter", "Legal", "Tabloid", "A0"-"A6"
	Width           string
	Height          string
	Margin          *PDFMargin
}

PDFOptions configures PDF generation.

type PageError 

type PageError struct {
	Message string `json:"message"`
	Stack   string `json:"stack,omitempty"`
	URL     string `json:"url,omitempty"`
	Line    int    `json:"line,omitempty"`
	Column  int    `json:"column,omitempty"`
}

PageError represents a JavaScript error that occurred on the page.

type PageErrorHandler 

type PageErrorHandler func(*PageError)

PageErrorHandler is called when a JavaScript error occurs on the page.

type PageHandler 

type PageHandler func(*Pilot)

PageHandler is called when a new page is created.

type Pilot 

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

Pilot is the main browser control interface.

func Launch 

func Launch(ctx context.Context) (*Pilot, error)

Launch is a convenience function that launches a browser with default options.

func LaunchHeadless 

func LaunchHeadless(ctx context.Context) (*Pilot, error)

LaunchHeadless is a convenience function that launches a headless browser.

func (*Pilot) A11yTree 

func (p *Pilot) A11yTree(ctx context.Context, opts *A11yTreeOptions) (interface{}, error)

A11yTree returns the accessibility tree for the page. Options can filter the tree to only interesting nodes or specify a root element.

func (*Pilot) AddInitScript 

func (p *Pilot) AddInitScript(ctx context.Context, script string) error

AddInitScript adds a script that will be evaluated in every page before any page scripts. This is useful for mocking APIs, injecting test helpers, or setting up authentication.

func (*Pilot) AddScript 

func (p *Pilot) AddScript(ctx context.Context, source string) error

AddScript adds a script that will be evaluated in the page context.

func (*Pilot) AddStyle 

func (p *Pilot) AddStyle(ctx context.Context, source string) error

AddStyle adds a stylesheet to the page.

func (*Pilot) Back 

func (p *Pilot) Back(ctx context.Context) error

Back navigates back in history.

func (*Pilot) BringToFront 

func (p *Pilot) BringToFront(ctx context.Context) error

BringToFront activates the page (brings the browser tab to front).

func (*Pilot) BrowserVersion 

func (p *Pilot) BrowserVersion(ctx context.Context) (string, error)

BrowserVersion returns the browser version string.

func (*Pilot) BrowsingContext 

func (p *Pilot) BrowsingContext() string

BrowsingContext returns the browsing context ID for this page.

func (*Pilot) ClearConsoleMessages 

func (p *Pilot) ClearConsoleMessages(ctx context.Context) error

ClearConsoleMessages clears the buffered console messages.

func (*Pilot) ClearErrors 

func (p *Pilot) ClearErrors(ctx context.Context) error

ClearErrors clears the buffered page errors.

func (*Pilot) ClearNetworkRequests 

func (p *Pilot) ClearNetworkRequests(ctx context.Context) error

ClearNetworkRequests clears the buffered network requests.

func (*Pilot) ClearStorage 

func (p *Pilot) ClearStorage(ctx context.Context) error

ClearStorage clears all cookies, localStorage, and sessionStorage.

func (*Pilot) Clock 

func (p *Pilot) Clock(ctx context.Context) (*Clock, error)

Clock returns the clock controller for this page.

func (*Pilot) Close 

func (p *Pilot) Close(ctx context.Context) error

Close closes the current page but not the browser.

func (*Pilot) CollectConsole 

func (p *Pilot) CollectConsole(ctx context.Context) error

CollectConsole enables buffered console message collection. Messages can be retrieved with ConsoleMessages() and cleared with ClearConsoleMessages().

func (*Pilot) CollectErrors 

func (p *Pilot) CollectErrors(ctx context.Context) error

CollectErrors enables buffered page error collection. Errors can be retrieved with Errors() and cleared with ClearErrors().

func (*Pilot) ConsoleMessages 

func (p *Pilot) ConsoleMessages(ctx context.Context, level string) ([]ConsoleMessage, error)

ConsoleMessages returns buffered console messages from the page. The level parameter filters messages by type (log, info, warn, error, debug). If level is empty, all messages are returned.

func (*Pilot) Content 

func (p *Pilot) Content(ctx context.Context) (string, error)

Content returns the full HTML content of the page.

func (*Pilot) Context 

func (p *Pilot) Context() *BrowserContext

Context returns the browser context for this page. Returns nil if this is the default context.

func (*Pilot) EmulateMedia 

func (p *Pilot) EmulateMedia(ctx context.Context, opts EmulateMediaOptions) error

EmulateMedia sets the media emulation options.

func (*Pilot) Errors 

func (p *Pilot) Errors(ctx context.Context) ([]PageError, error)

Errors retrieves buffered page errors. Call CollectErrors() first to enable error collection.

func (*Pilot) Evaluate 

func (p *Pilot) Evaluate(ctx context.Context, script string) (interface{}, error)

Evaluate executes JavaScript in the page context and returns the result.

func (*Pilot) Expose 

func (p *Pilot) Expose(ctx context.Context, name string) error

Expose exposes a function that can be called from JavaScript in the page. Note: The handler function must be registered separately.

func (*Pilot) Find 

func (p *Pilot) Find(ctx context.Context, selector string, opts *FindOptions) (*Element, error)

Find finds an element by CSS selector.

func (*Pilot) FindAll 

func (p *Pilot) FindAll(ctx context.Context, selector string, opts *FindOptions) ([]*Element, error)

FindAll finds all elements matching the selector and optional semantic options. If selector is empty but semantic options are provided, elements are found by those options.

func (*Pilot) Forward 

func (p *Pilot) Forward(ctx context.Context) error

Forward navigates forward in history.

func (*Pilot) Frame 

func (p *Pilot) Frame(ctx context.Context, nameOrURL string) (*Pilot, error)

Frame finds a frame by name or URL pattern.

func (*Pilot) Frames 

func (p *Pilot) Frames(ctx context.Context) ([]FrameInfo, error)

Frames returns all frames on the page.

func (*Pilot) GetDialog 

func (p *Pilot) GetDialog(ctx context.Context) (DialogInfo, error)

GetDialog returns information about the current dialog, if any.

func (*Pilot) GetViewport 

func (p *Pilot) GetViewport(ctx context.Context) (Viewport, error)

GetViewport returns the current viewport dimensions.

func (*Pilot) GetWindow 

func (p *Pilot) GetWindow(ctx context.Context) (WindowState, error)

GetWindow returns the browser window state.

func (*Pilot) Go 

func (p *Pilot) Go(ctx context.Context, url string) error

Go navigates to the specified URL.

func (*Pilot) HandleDialog 

func (p *Pilot) HandleDialog(ctx context.Context, accept bool, promptText string) error

HandleDialog handles the current dialog by accepting or dismissing it. If accept is true, the dialog is accepted. If promptText is provided (for prompt dialogs), it will be entered before accepting.

func (*Pilot) IsClosed 

func (p *Pilot) IsClosed() bool

IsClosed returns whether the browser has been closed.

func (*Pilot) Keyboard 

func (p *Pilot) Keyboard(ctx context.Context) (*Keyboard, error)

Keyboard returns the keyboard controller for this page.

func (*Pilot) ListRoutes 

func (p *Pilot) ListRoutes(ctx context.Context) ([]RouteInfo, error)

ListRoutes returns all active route handlers.

func (*Pilot) MainFrame 

func (p *Pilot) MainFrame() *Pilot

MainFrame returns the main frame of the page. Since Pilot represents both page and frame in this SDK, it returns itself. This method exists for API compatibility with other WebPilot clients.

func (*Pilot) MockRoute 

func (p *Pilot) MockRoute(ctx context.Context, pattern string, opts MockRouteOptions) error

MockRoute registers a route that returns a static mock response. This is useful for MCP tools and testing without callbacks.

func (*Pilot) Mouse 

func (p *Pilot) Mouse(ctx context.Context) (*Mouse, error)

Mouse returns the mouse controller for this page.

func (*Pilot) MustFind 

func (p *Pilot) MustFind(ctx context.Context, selector string) *Element

MustFind finds an element by CSS selector and panics if not found.

func (*Pilot) NetworkRequests 

func (p *Pilot) NetworkRequests(ctx context.Context, opts *NetworkRequestsOptions) ([]NetworkRequest, error)

NetworkRequests returns buffered network requests from the page. Options can filter by URL pattern, method, or resource type.

func (*Pilot) NewContext 

func (p *Pilot) NewContext(ctx context.Context) (*BrowserContext, error)

NewContext creates a new isolated browser context.

func (*Pilot) NewPage 

func (p *Pilot) NewPage(ctx context.Context) (*Pilot, error)

NewPage creates a new page in the default browser context.

func (*Pilot) OnConsole 

func (p *Pilot) OnConsole(ctx context.Context, handler ConsoleHandler) error

OnConsole registers a handler for console messages.

func (*Pilot) OnDialog 

func (p *Pilot) OnDialog(ctx context.Context, handler DialogHandler) error

OnDialog registers a handler for dialogs (alert, confirm, prompt).

func (*Pilot) OnDownload 

func (p *Pilot) OnDownload(ctx context.Context, handler DownloadHandler) error

OnDownload registers a handler for downloads.

func (*Pilot) OnError 

func (p *Pilot) OnError(ctx context.Context, handler PageErrorHandler) error

OnError registers a handler for JavaScript errors on the page.

func (*Pilot) OnPage 

func (p *Pilot) OnPage(ctx context.Context, handler PageHandler) error

OnPage registers a handler that is called when a new page is created in the browser. This includes pages created via NewPage(), window.open(), or clicking links with target="_blank".

func (*Pilot) OnPopup 

func (p *Pilot) OnPopup(ctx context.Context, handler PopupHandler) error

OnPopup registers a handler that is called when a popup window is opened. Popups are typically created via window.open() with specific features.

func (*Pilot) OnRequest 

func (p *Pilot) OnRequest(ctx context.Context, handler RequestHandler) error

OnRequest registers a handler for network requests. Note: This is a convenience method; for full control use Route().

func (*Pilot) OnResponse 

func (p *Pilot) OnResponse(ctx context.Context, handler ResponseHandler) error

OnResponse registers a handler for network responses.

func (*Pilot) OnWebSocket 

func (p *Pilot) OnWebSocket(ctx context.Context, handler WebSocketHandler) error

OnWebSocket registers a handler that is called when the page opens a WebSocket connection.

func (*Pilot) PDF 

func (p *Pilot) PDF(ctx context.Context, opts *PDFOptions) ([]byte, error)

PDF generates a PDF of the page and returns the bytes.

func (*Pilot) Pages 

func (p *Pilot) Pages(ctx context.Context) ([]*Pilot, error)

Pages returns all open pages.

func (*Pilot) Quit 

func (p *Pilot) Quit(ctx context.Context) error

Quit closes the browser and cleans up resources.

func (*Pilot) Reload 

func (p *Pilot) Reload(ctx context.Context) error

Reload reloads the current page.

func (*Pilot) RemoveAllListeners 

func (p *Pilot) RemoveAllListeners()

RemoveAllListeners removes all registered event listeners. This is useful for cleanup when you no longer need to receive events.

func (*Pilot) Route 

func (p *Pilot) Route(ctx context.Context, pattern string, handler RouteHandler) error

Route registers a handler for requests matching the URL pattern. The pattern can be a glob pattern (e.g., "**/*.png") or regex (e.g., "/api/.*").

func (*Pilot) Screenshot 

func (p *Pilot) Screenshot(ctx context.Context) ([]byte, error)

Screenshot captures a screenshot of the current page and returns PNG data.

func (*Pilot) Scroll 

func (p *Pilot) Scroll(ctx context.Context, direction string, amount int, opts *ScrollOptions) error

Scroll scrolls the page or a specific element. direction can be "up", "down", "left", or "right". amount is the number of pixels to scroll (use 0 for full page).

func (*Pilot) SetContent 

func (p *Pilot) SetContent(ctx context.Context, html string) error

SetContent sets the HTML content of the page.

func (*Pilot) SetExtraHTTPHeaders 

func (p *Pilot) SetExtraHTTPHeaders(ctx context.Context, headers map[string]string) error

SetExtraHTTPHeaders sets extra HTTP headers that will be sent with every request.

func (*Pilot) SetGeolocation 

func (p *Pilot) SetGeolocation(ctx context.Context, coords Geolocation) error

SetGeolocation overrides the browser's geolocation.

func (*Pilot) SetOffline 

func (p *Pilot) SetOffline(ctx context.Context, offline bool) error

SetOffline sets the browser's offline mode.

func (*Pilot) SetStorageState 

func (p *Pilot) SetStorageState(ctx context.Context, state *StorageState) error

SetStorageState restores browser storage state from a previously saved StorageState. This includes cookies, localStorage, and sessionStorage. The browser should be on a page (or will be navigated to the first origin) for storage to be set correctly.

func (*Pilot) SetViewport 

func (p *Pilot) SetViewport(ctx context.Context, viewport Viewport) error

SetViewport sets the viewport dimensions.

func (*Pilot) SetWindow 

func (p *Pilot) SetWindow(ctx context.Context, opts SetWindowOptions) error

SetWindow sets the browser window state.

func (*Pilot) StartVideo 

func (p *Pilot) StartVideo(ctx context.Context, opts *VideoOptions) (*Video, error)

StartVideo starts recording video of the page. The video is saved when StopVideo is called or the browser closes.

func (*Pilot) StopVideo 

func (p *Pilot) StopVideo(ctx context.Context) (string, error)

StopVideo stops video recording and returns the video path.

func (*Pilot) StorageState 

func (p *Pilot) StorageState(ctx context.Context) (*StorageState, error)

StorageState returns the complete browser storage state including cookies, localStorage, and sessionStorage for the current page's origin. This can be saved and later restored using SetStorageState to resume a session.

func (*Pilot) Title 

func (p *Pilot) Title(ctx context.Context) (string, error)

Title returns the page title.

func (*Pilot) Touch 

func (p *Pilot) Touch(ctx context.Context) (*Touch, error)

Touch returns the touch controller for this page.

func (*Pilot) Tracing 

func (p *Pilot) Tracing() *Tracing

Tracing returns a tracing controller for the default browser context. Use this to record traces for debugging and analysis.

func (*Pilot) URL 

func (p *Pilot) URL(ctx context.Context) (string, error)

URL returns the current page URL.

func (*Pilot) Unroute 

func (p *Pilot) Unroute(ctx context.Context, pattern string) error

Unroute removes a previously registered route handler.

func (*Pilot) WaitForFunction 

func (p *Pilot) WaitForFunction(ctx context.Context, fn string, timeout time.Duration) error

WaitForFunction waits for a JavaScript function to return a truthy value.

func (*Pilot) WaitForLoad 

func (p *Pilot) WaitForLoad(ctx context.Context, state string, timeout time.Duration) error

WaitForLoad waits for the page to reach the specified load state. State can be: "load", "domcontentloaded", "networkidle".

func (*Pilot) WaitForNavigation 

func (p *Pilot) WaitForNavigation(ctx context.Context, timeout time.Duration) error

WaitForNavigation waits for a navigation to complete.

func (*Pilot) WaitForURL 

func (p *Pilot) WaitForURL(ctx context.Context, pattern string, timeout time.Duration) error

WaitForURL waits for the page URL to match the specified pattern.

type PopupHandler 

type PopupHandler func(*Pilot)

PopupHandler is called when a popup window opens.

type Request 

type Request struct {
	URL                 string            `json:"url"`
	Method              string            `json:"method"`
	Headers             map[string]string `json:"headers"`
	PostData            string            `json:"postData,omitempty"`
	ResourceType        string            `json:"resourceType"`
	IsNavigationRequest bool              `json:"isNavigationRequest"`
}

Request represents a network request.

type RequestHandler 

type RequestHandler func(*Request)

RequestHandler is called for each network request.

type Response 

type Response struct {
	URL        string            `json:"url"`
	Status     int               `json:"status"`
	StatusText string            `json:"statusText"`
	Headers    map[string]string `json:"headers"`
	Body       []byte            `json:"-"`
}

Response represents a network response.

type ResponseHandler 

type ResponseHandler func(*Response)

ResponseHandler is called for each network response.

type Route 

type Route struct {
	Request *Request
	// contains filtered or unexported fields
}

Route represents an intercepted network request.

func (*Route) Abort 

func (r *Route) Abort(ctx context.Context) error

Abort aborts the route.

func (*Route) Continue 

func (r *Route) Continue(ctx context.Context, opts *ContinueOptions) error

Continue continues the route with optional modifications.

func (*Route) Fulfill 

func (r *Route) Fulfill(ctx context.Context, opts FulfillOptions) error

Fulfill fulfills the route with the given response.

type RouteHandler 

type RouteHandler func(ctx context.Context, route *Route) error

RouteHandler is called when a request matches a route pattern.

type RouteInfo 

type RouteInfo struct {
	Pattern     string `json:"pattern"`
	Status      int    `json:"status,omitempty"`
	ContentType string `json:"contentType,omitempty"`
}

RouteInfo represents information about an active route.

type ScrollOptions 

type ScrollOptions struct {
	Selector string // Optional CSS selector to scroll within
}

ScrollOptions configures scroll behavior.

type SelectOptionValues 

type SelectOptionValues struct {
	// Values selects options by their value attribute.
	Values []string

	// Labels selects options by their visible text.
	Labels []string

	// Indexes selects options by their zero-based index.
	Indexes []int
}

SelectOptionValues specifies which options to select in a <select> element.

type SetCookieParam 

type SetCookieParam struct {
	Name         string  `json:"name"`
	Value        string  `json:"value"`
	URL          string  `json:"url,omitempty"`
	Domain       string  `json:"domain,omitempty"`
	Path         string  `json:"path,omitempty"`
	Expires      float64 `json:"expires,omitempty"`
	HTTPOnly     bool    `json:"httpOnly,omitempty"`
	Secure       bool    `json:"secure,omitempty"`
	SameSite     string  `json:"sameSite,omitempty"`
	PartitionKey string  `json:"partitionKey,omitempty"`
}

SetCookieParam represents parameters for setting a cookie.

type SetWindowOptions 

type SetWindowOptions struct {
	X      *int
	Y      *int
	Width  *int
	Height *int
	State  string // "normal", "minimized", "maximized", "fullscreen"
}

SetWindowOptions configures window state.

type StorageState 

type StorageState struct {
	Cookies []Cookie             `json:"cookies"`
	Origins []StorageStateOrigin `json:"origins"`
}

StorageState represents browser storage state including cookies, localStorage, and sessionStorage.

type StorageStateOrigin 

type StorageStateOrigin struct {
	Origin         string            `json:"origin"`
	LocalStorage   map[string]string `json:"localStorage"`
	SessionStorage map[string]string `json:"sessionStorage,omitempty"`
}

StorageStateOrigin represents storage for an origin.

type TimeoutError 

type TimeoutError struct {
	Selector string
	Timeout  int64 // milliseconds
	Reason   string
}

TimeoutError represents a timeout waiting for an element or action.

func (*TimeoutError) Error 

func (e *TimeoutError) Error() string

type Touch 

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

Touch provides touch input control.

func NewTouch 

func NewTouch(client *BiDiClient, browsingContext string) *Touch

NewTouch creates a new Touch controller.

func (*Touch) Pinch 

func (t *Touch) Pinch(ctx context.Context, x, y float64, scale float64) error

Pinch performs a pinch gesture. Scale < 1 zooms out, scale > 1 zooms in.

func (*Touch) Swipe 

func (t *Touch) Swipe(ctx context.Context, startX, startY, endX, endY float64) error

Swipe performs a swipe gesture from one point to another.

func (*Touch) Tap 

func (t *Touch) Tap(ctx context.Context, x, y float64) error

Tap performs a tap at the specified coordinates.

type Tracing 

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

Tracing provides control over trace recording.

func (*Tracing) Start 

func (t *Tracing) Start(ctx context.Context, opts *TracingStartOptions) error

Start starts trace recording.

func (*Tracing) StartChunk 

func (t *Tracing) StartChunk(ctx context.Context, opts *TracingChunkOptions) error

StartChunk starts a new trace chunk.

func (*Tracing) StartGroup 

func (t *Tracing) StartGroup(ctx context.Context, name string, opts *TracingGroupOptions) error

StartGroup starts a new trace group.

func (*Tracing) Stop 

func (t *Tracing) Stop(ctx context.Context, opts *TracingStopOptions) ([]byte, error)

Stop stops trace recording and returns the trace data.

func (*Tracing) StopChunk 

func (t *Tracing) StopChunk(ctx context.Context, opts *TracingChunkOptions) ([]byte, error)

StopChunk stops the current trace chunk and returns the data.

func (*Tracing) StopGroup 

func (t *Tracing) StopGroup(ctx context.Context) error

StopGroup stops the current trace group.

type TracingChunkOptions 

type TracingChunkOptions struct {
	// Name for the chunk.
	Name string

	// Title for the chunk.
	Title string
}

TracingChunkOptions configures trace chunk recording.

type TracingGroupOptions 

type TracingGroupOptions struct {
	// Location to associate with the group.
	Location string
}

TracingGroupOptions configures trace groups.

type TracingStartOptions 

type TracingStartOptions struct {
	// Name is the trace file name (optional).
	Name string

	// Screenshots includes screenshots in the trace.
	Screenshots bool

	// Snapshots includes DOM snapshots in the trace.
	Snapshots bool

	// Sources includes source files in the trace.
	Sources bool

	// Title is the trace title (shown in trace viewer).
	Title string

	// Categories specifies which trace categories to include.
	Categories []string
}

TracingStartOptions configures trace recording.

type TracingStopOptions 

type TracingStopOptions struct {
	// Path to save the trace file.
	Path string
}

TracingStopOptions configures how to stop trace recording.

type Video 

type Video struct {

	// FilePath is the file path where the video will be saved.
	FilePath string `json:"path,omitempty"`
	// contains filtered or unexported fields
}

Video represents an ongoing or completed video recording.

func (*Video) Delete 

func (vid *Video) Delete(ctx context.Context) error

Delete deletes the video file.

func (*Video) Path 

func (vid *Video) Path() string

Path returns the path where the video will be saved. The file may not exist until StopVideo is called.

type VideoOptions 

type VideoOptions struct {
	// Dir is the directory to save videos to. Defaults to a temp directory.
	Dir string `json:"dir,omitempty"`
	// Size specifies the video dimensions. Defaults to viewport size.
	Size *VideoSize `json:"size,omitempty"`
}

VideoOptions configures video recording.

type VideoSize 

type VideoSize struct {
	Width  int `json:"width"`
	Height int `json:"height"`
}

VideoSize specifies video dimensions.

type Viewport 

type Viewport struct {
	Width  int `json:"width"`
	Height int `json:"height"`
}

Viewport represents the browser viewport dimensions.

type WebSocketCloseHandler 

type WebSocketCloseHandler func(code int, reason string)

WebSocketCloseHandler is called when a WebSocket connection is closed.

type WebSocketHandler 

type WebSocketHandler func(*WebSocketInfo)

WebSocketHandler is called when a new WebSocket connection is opened.

type WebSocketInfo 

type WebSocketInfo struct {
	URL      string `json:"url"`
	IsClosed bool   `json:"isClosed"`
	// contains filtered or unexported fields
}

WebSocketInfo represents a WebSocket connection made by the page.

func (*WebSocketInfo) OnClose 

func (ws *WebSocketInfo) OnClose(handler WebSocketCloseHandler)

OnClose registers a handler for when the WebSocket closes.

func (*WebSocketInfo) OnMessage 

func (ws *WebSocketInfo) OnMessage(handler WebSocketMessageHandler)

OnMessage registers a handler for WebSocket messages.

type WebSocketMessage 

type WebSocketMessage struct {
	SocketID  string `json:"socketId"`
	Data      string `json:"data"`
	IsBinary  bool   `json:"isBinary"`
	Direction string `json:"direction"` // "sent" or "received"
}

WebSocketMessage represents a message sent or received on a WebSocket.

type WebSocketMessageHandler 

type WebSocketMessageHandler func(*WebSocketMessage)

WebSocketMessageHandler is called when a WebSocket message is sent or received.

type WindowState 

type WindowState struct {
	X         int    `json:"x"`
	Y         int    `json:"y"`
	Width     int    `json:"width"`
	Height    int    `json:"height"`
	State     string `json:"state"` // "normal", "minimized", "maximized", "fullscreen"
	IsVisible bool   `json:"isVisible"`
}

WindowState represents the browser window state.

Source Files

View all Source files

Directories

Path Synopsis
cmd
genscriptschema command
Command genscriptschema generates JSON Schema from Go types.
 Command genscriptschema generates JSON Schema from Go types.
webpilot command
Command webpilot provides a CLI for browser automation.
 Command webpilot provides a CLI for browser automation.
webpilot-mcp command
Command webpilot-mcp provides an MCP server for browser automation.
 Command webpilot-mcp provides an MCP server for browser automation.
webpilot-rpa command
webpilot-rpa/cmd
webpilot/cmd
Package launcher provides Chrome browser launching and installation.
 Package launcher provides Chrome browser launching and installation.
mcp
Package mcp provides an MCP (Model Context Protocol) server for browser automation.
 Package mcp provides an MCP (Model Context Protocol) server for browser automation.
report
Package report provides test result tracking and report generation.
 Package report provides test result tracking and report generation.
rpa
Package rpa provides a Robotic Process Automation platform for browser automation.
 Package rpa provides a Robotic Process Automation platform for browser automation.
activity
Package activity provides the activity system for RPA workflow execution.
 Package activity provides the activity system for RPA workflow execution.
Package script defines the test script format for Vibium automation.
 Package script defines the test script format for Vibium automation.

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.