vibium

package module
v0.2.1 Latest Latest
Warning

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

 Go to latest Published: Feb 28, 2026 License: MIT Imports: 18 Imported by: 7

README

Vibium Go

Build Status Go Report Card Docs License

Go client and tooling for the Vibium browser automation platform.

Vibium uses WebDriver BiDi for real-time bidirectional communication with browsers, making it ideal for AI-assisted automation.

Overview

This project provides:

Component Description Origin
Go Client SDK Programmatic browser control Feature parity with JS/Python
MCP Server 75+ tools for AI assistants Go-specific
CLI Command-line browser automation Go-specific
Script Runner Deterministic test execution Go-specific
Session Recording Capture actions as replayable scripts Go-specific

Architecture

┌────────────────────────────────────────────────────────────────┐
│                         vibium-go                              │
├─────────────┬─────────────┬─────────────┬──────────────────────┤
│  Go Client  │ MCP Server  │    CLI      │   Script Runner      │
│    SDK      │  (75 tools) │  (vibium)   │   (vibium run)       │
├─────────────┴─────────────┴─────────────┴──────────────────────┤
│                    WebDriver BiDi Protocol                     │
├────────────────────────────────────────────────────────────────┤
│                   Vibium Clicker (upstream)                    │
├────────────────────────────────────────────────────────────────┤
│                    Chrome / Chromium                           │
└────────────────────────────────────────────────────────────────┘

Installation

go get github.com/plexusone/vibium-go
Prerequisites

Install the Vibium clicker binary:

npm install -g vibium

Or set VIBIUM_CLICKER_PATH to point to the binary.

Quick Start

Go Client SDK
package main

import (
    "context"
    "log"

    vibium "github.com/plexusone/vibium-go"
)

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

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

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

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

Start the MCP server for AI assistant integration:

vibium mcp --headless

Configure in Claude Desktop (claude_desktop_config.json):

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

Execute deterministic test scripts:

vibium 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 (Parity with JS/Python)
Feature JS Python Go
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 ✅ ✅ ✅
Go-Specific Features
Feature Description
MCP Server 75+ tools for AI-assisted automation
CLI vibium 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 75+ 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
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
Input keyboard_*, mouse_*, touch_*
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 vibium run

API Reference

See pkg.go.dev for full API documentation.

Key Types
// Launch browser
vibe, err := vibium.Launch(ctx)
vibe, err := vibium.LaunchHeadless(ctx)

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

// Finding elements
elem, err := vibe.Find(ctx, selector, &vibium.FindOptions{})
elems, err := vibe.FindAll(ctx, selector)

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

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

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

Testing

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

# Integration tests (requires clicker)
go test -tags=integration -v ./integration/...

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

Debug Logging

VIBIUM_DEBUG=1 vibium mcp

License

MIT

Documentation

Overview

Package vibium provides a Go client for the Vibium browser automation platform.

Vibium 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()
vibe, err := vibium.Launch(ctx)
if err != nil {
    log.Fatal(err)
}
defer vibe.Quit(ctx)

if err := vibe.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 := vibe.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 := vibe.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 := vibe.Screenshot(ctx)
if err != nil {
    log.Fatal(err)
}
os.WriteFile("screenshot.png", data, 0644)

Headless Mode

Launch in headless mode for CI/server environments: 

vibe, err := vibium.LaunchHeadless(ctx)

Or with explicit options: 

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

Requirements

This client requires the Vibium clicker binary to be available. Install it via: 

npm install -g vibium

Or set the VIBIUM_CLICKER_PATH environment variable to point to the binary.

Package vibium provides a Go client for browser automation via the Vibium platform. It communicates with the Vibium clicker binary over WebSocket using the WebDriver BiDi protocol.

Example 
ctx := context.Background()

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

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

// Find and click a link
link, err := vibe.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 := vibe.Title(ctx)
if err != nil {
	log.Fatal(err)
}
fmt.Println("Page title:", title)
Example (FormInteraction) 
ctx := context.Background()

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

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

// Fill in username
username, err := vibe.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 := vibe.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 := vibe.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) 
ctx := context.Background()

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

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

// Take screenshot
data, err := vibe.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 clicker server")

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

	// ErrClickerNotFound is returned when the clicker binary cannot be found.
	ErrClickerNotFound = errors.New("clicker binary not found")

	// 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 VIBIUM_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 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 the clicker 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 the clicker server.

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 BiDiResponse 

type BiDiResponse struct {
	ID      int64           `json:"id"`
	Type    string          `json:"type"`
	Result  json.RawMessage `json:"result,omitempty"`
	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) 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) (*Vibe, 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 ClickerProcess 

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

ClickerProcess manages the clicker binary subprocess.

func StartClicker 

func StartClicker(ctx context.Context, opts LaunchOptions) (*ClickerProcess, error)

StartClicker starts the clicker binary and returns a ClickerProcess.

func (*ClickerProcess) Port 

func (p *ClickerProcess) Port() int

Port returns the port the clicker is listening on.

func (*ClickerProcess) Stop 

func (p *ClickerProcess) Stop() error

Stop gracefully stops the clicker process.

func (*ClickerProcess) Wait 

func (p *ClickerProcess) Wait() error

Wait waits for the clicker process to exit.

func (*ClickerProcess) WebSocketURL 

func (p *ClickerProcess) WebSocketURL() string

WebSocketURL returns the WebSocket URL for connecting to the clicker.

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

EmulateMediaOptions configures media emulation.

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 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 WebSocket port. If 0, an available port is auto-selected.
	Port int

	// ExecutablePath specifies a custom path to the clicker binary.
	ExecutablePath string
}

LaunchOptions configures browser launch behavior.

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

type StorageStateOrigin 

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

StorageStateOrigin represents localStorage 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 Vibe 

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

Vibe is the main browser control interface.

func Launch 

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

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

func LaunchHeadless 

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

LaunchHeadless is a convenience function that launches a headless browser.

func (*Vibe) A11yTree 

func (v *Vibe) A11yTree(ctx context.Context) (interface{}, error)

A11yTree returns the accessibility tree for the page.

func (*Vibe) AddScript 

func (v *Vibe) AddScript(ctx context.Context, source string) error

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

func (*Vibe) AddStyle 

func (v *Vibe) AddStyle(ctx context.Context, source string) error

AddStyle adds a stylesheet to the page.

func (*Vibe) Back 

func (v *Vibe) Back(ctx context.Context) error

Back navigates back in history.

func (*Vibe) BringToFront 

func (v *Vibe) BringToFront(ctx context.Context) error

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

func (*Vibe) BrowserVersion 

func (v *Vibe) BrowserVersion(ctx context.Context) (string, error)

BrowserVersion returns the browser version string.

func (*Vibe) Clock 

func (v *Vibe) Clock(ctx context.Context) (*Clock, error)

Clock returns the clock controller for this page.

func (*Vibe) Close 

func (v *Vibe) Close(ctx context.Context) error

Close closes the current page but not the browser.

func (*Vibe) Content 

func (v *Vibe) Content(ctx context.Context) (string, error)

Content returns the full HTML content of the page.

func (*Vibe) Context 

func (v *Vibe) Context() *BrowserContext

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

func (*Vibe) EmulateMedia 

func (v *Vibe) EmulateMedia(ctx context.Context, opts EmulateMediaOptions) error

EmulateMedia sets the media emulation options.

func (*Vibe) Evaluate 

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

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

func (*Vibe) Expose 

func (v *Vibe) 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 (*Vibe) Find 

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

Find finds an element by CSS selector.

func (*Vibe) FindAll 

func (v *Vibe) FindAll(ctx context.Context, selector string) ([]*Element, error)

FindAll finds all elements matching the CSS selector.

func (*Vibe) Forward 

func (v *Vibe) Forward(ctx context.Context) error

Forward navigates forward in history.

func (*Vibe) Frame 

func (v *Vibe) Frame(ctx context.Context, nameOrURL string) (*Vibe, error)

Frame finds a frame by name or URL pattern.

func (*Vibe) Frames 

func (v *Vibe) Frames(ctx context.Context) ([]FrameInfo, error)

Frames returns all frames on the page.

func (*Vibe) GetViewport 

func (v *Vibe) GetViewport(ctx context.Context) (Viewport, error)

GetViewport returns the current viewport dimensions.

func (*Vibe) GetWindow 

func (v *Vibe) GetWindow(ctx context.Context) (WindowState, error)

GetWindow returns the browser window state.

func (*Vibe) Go 

func (v *Vibe) Go(ctx context.Context, url string) error

Go navigates to the specified URL.

func (*Vibe) IsClosed 

func (v *Vibe) IsClosed() bool

IsClosed returns whether the browser has been closed.

func (*Vibe) Keyboard 

func (v *Vibe) Keyboard(ctx context.Context) (*Keyboard, error)

Keyboard returns the keyboard controller for this page.

func (*Vibe) Mouse 

func (v *Vibe) Mouse(ctx context.Context) (*Mouse, error)

Mouse returns the mouse controller for this page.

func (*Vibe) MustFind 

func (v *Vibe) MustFind(ctx context.Context, selector string) *Element

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

func (*Vibe) NewContext 

func (v *Vibe) NewContext(ctx context.Context) (*BrowserContext, error)

NewContext creates a new isolated browser context.

func (*Vibe) NewPage 

func (v *Vibe) NewPage(ctx context.Context) (*Vibe, error)

NewPage creates a new page in the default browser context.

func (*Vibe) OnConsole 

func (v *Vibe) OnConsole(ctx context.Context, handler ConsoleHandler) error

OnConsole registers a handler for console messages.

func (*Vibe) OnDialog 

func (v *Vibe) OnDialog(ctx context.Context, handler DialogHandler) error

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

func (*Vibe) OnDownload 

func (v *Vibe) OnDownload(ctx context.Context, handler DownloadHandler) error

OnDownload registers a handler for downloads.

func (*Vibe) OnRequest 

func (v *Vibe) 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 (*Vibe) OnResponse 

func (v *Vibe) OnResponse(ctx context.Context, handler ResponseHandler) error

OnResponse registers a handler for network responses.

func (*Vibe) PDF 

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

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

func (*Vibe) Pages 

func (v *Vibe) Pages(ctx context.Context) ([]*Vibe, error)

Pages returns all open pages.

func (*Vibe) Quit 

func (v *Vibe) Quit(ctx context.Context) error

Quit closes the browser and cleans up resources.

func (*Vibe) Reload 

func (v *Vibe) Reload(ctx context.Context) error

Reload reloads the current page.

func (*Vibe) Route 

func (v *Vibe) 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 (*Vibe) Screenshot 

func (v *Vibe) Screenshot(ctx context.Context) ([]byte, error)

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

func (*Vibe) SetContent 

func (v *Vibe) SetContent(ctx context.Context, html string) error

SetContent sets the HTML content of the page.

func (*Vibe) SetExtraHTTPHeaders 

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

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

func (*Vibe) SetGeolocation 

func (v *Vibe) SetGeolocation(ctx context.Context, coords Geolocation) error

SetGeolocation overrides the browser's geolocation.

func (*Vibe) SetViewport 

func (v *Vibe) SetViewport(ctx context.Context, viewport Viewport) error

SetViewport sets the viewport dimensions.

func (*Vibe) SetWindow 

func (v *Vibe) SetWindow(ctx context.Context, opts SetWindowOptions) error

SetWindow sets the browser window state.

func (*Vibe) Title 

func (v *Vibe) Title(ctx context.Context) (string, error)

Title returns the page title.

func (*Vibe) Touch 

func (v *Vibe) Touch(ctx context.Context) (*Touch, error)

Touch returns the touch controller for this page.

func (*Vibe) URL 

func (v *Vibe) URL(ctx context.Context) (string, error)

URL returns the current page URL.

func (*Vibe) Unroute 

func (v *Vibe) Unroute(ctx context.Context, pattern string) error

Unroute removes a previously registered route handler.

func (*Vibe) WaitForFunction 

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

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

func (*Vibe) WaitForLoad 

func (v *Vibe) 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 (*Vibe) WaitForNavigation 

func (v *Vibe) WaitForNavigation(ctx context.Context, timeout time.Duration) error

WaitForNavigation waits for a navigation to complete.

func (*Vibe) WaitForURL 

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

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

type Viewport 

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

Viewport represents the browser viewport dimensions.

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.
vibium command
Command vibium provides a CLI for browser automation.
 Command vibium provides a CLI for browser automation.
vibium-mcp command
Command vibium-mcp provides an MCP server for browser automation.
 Command vibium-mcp provides an MCP server for browser automation.
vibium-rpa command
vibium-rpa/cmd
vibium/cmd
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.