browser

Documentation

Overview

Package browser provides Chrome detection, launch, and target management.

Index

• Constants
• Variables
• func FindChrome() (string, error)
• type Browser
  • func Start(opts LaunchOptions) (*Browser, error)
  • func StartWithBinary(binPath string, opts LaunchOptions) (*Browser, error)
  • func (b *Browser) Close() error
  • func (b *Browser) PID() int
  • func (b *Browser) PageTarget(ctx context.Context) (*Target, error)
  • func (b *Browser) Port() int
  • func (b *Browser) Targets(ctx context.Context) ([]Target, error)
  • func (b *Browser) Version(ctx context.Context) (*VersionInfo, error)
  • func (b *Browser) WebSocketURL(ctx context.Context) (string, error)
• type LaunchOptions
• type Target
  • func FetchTargets(ctx context.Context, host string, port int) ([]Target, error)
  • func FindPageTarget(targets []Target) *Target
• type VersionInfo
  • func FetchVersion(ctx context.Context, host string, port int) (*VersionInfo, error)

Constants

const DefaultPort = 9222

DefaultPort is the default CDP debugging port.

const UserDataDirDefault = "default"

UserDataDirDefault is the special value that means "use the user's Chrome profile".

Variables

var ErrBrowserClosed = errors.New("browser is closed")

ErrBrowserClosed is returned when operating on a closed browser.

var ErrChromeNotFound = errors.New("chrome not found")

ErrChromeNotFound is returned when no Chrome binary can be located.

var ErrNoPageTarget = errors.New("no page target found")

ErrNoPageTarget is returned when no page target is available.

var ErrPortInUse = errors.New("port is already in use")

ErrPortInUse is returned when the requested port is already in use.

var ErrStartTimeout = errors.New("browser start timeout")

ErrStartTimeout is returned when the browser fails to start in time.

Functions

func FindChrome

func FindChrome() (string, error)

FindChrome searches for a Chrome or Chromium binary on the system. It first checks the WEBCTL_CHROME environment variable, then searches common installation paths for the current platform. Returns the path to the executable or ErrChromeNotFound.

Types

type Browser

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

Browser represents a running Chrome instance with CDP enabled.

func Start

func Start(opts LaunchOptions) (*Browser, error)

Start launches a new Chrome browser with CDP enabled. It waits for the CDP endpoint to become available before returning.

func StartWithBinary

func StartWithBinary(binPath string, opts LaunchOptions) (*Browser, error)

StartWithBinary launches Chrome using the specified binary path.

func (*Browser) Close

func (b *Browser) Close() error

Close terminates the browser process and cleans up resources.

func (*Browser) PID

func (b *Browser) PID() int

PID returns the browser process ID.

func (*Browser) PageTarget

func (b *Browser) PageTarget(ctx context.Context) (*Target, error)

PageTarget returns the first page-type target.

func (*Browser) Port

func (b *Browser) Port() int

Port returns the CDP debugging port.

func (*Browser) Targets

func (b *Browser) Targets(ctx context.Context) ([]Target, error)

Targets fetches the list of available CDP targets.

func (*Browser) Version

func (b *Browser) Version(ctx context.Context) (*VersionInfo, error)

Version fetches the browser version information.

func (*Browser) WebSocketURL

func (b *Browser) WebSocketURL(ctx context.Context) (string, error)

WebSocketURL returns the WebSocket URL for connecting to the first page target.

type LaunchOptions

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

	// Port for CDP remote debugging. If 0, uses default 9222.
	Port int

	// UserDataDir specifies the browser profile directory.
	// Special values:
	//   - Empty string: create a temporary directory (default)
	//   - "default": use the user's default Chrome profile
	//   - Any path: use that directory
	UserDataDir string
}

LaunchOptions configures browser launch behavior.

type Target

type Target struct {
	ID           string `json:"id"`
	Type         string `json:"type"`
	Title        string `json:"title"`
	URL          string `json:"url"`
	Description  string `json:"description,omitempty"`
	WebSocketURL string `json:"webSocketDebuggerUrl"`
}

Target represents a CDP target (page, worker, etc).

func FetchTargets

func FetchTargets(ctx context.Context, host string, port int) ([]Target, error)

FetchTargets retrieves the list of available targets from the CDP endpoint. Uses http.DefaultClient which has no timeout; callers must provide a context with timeout. This is acceptable for local CDP calls where network issues are rare.

func FindPageTarget

func FindPageTarget(targets []Target) *Target

FindPageTarget returns the first page-type target from the list.

type VersionInfo

type VersionInfo struct {
	Browser       string `json:"Browser"`
	ProtocolVer   string `json:"Protocol-Version"`
	UserAgent     string `json:"User-Agent"`
	V8Version     string `json:"V8-Version"`
	WebKitVersion string `json:"WebKit-Version"`
	WebSocketURL  string `json:"webSocketDebuggerUrl"`
}

VersionInfo contains browser version information from /json/version.

func FetchVersion

func FetchVersion(ctx context.Context, host string, port int) (*VersionInfo, error)

FetchVersion retrieves browser version info from the CDP endpoint. Uses http.DefaultClient which has no timeout; callers must provide a context with timeout. This is acceptable for local CDP calls where network issues are rare.