browser

Documentation

Overview

Package browser provides browser utilities for context management, tab management, remote browser connections, and browser preferences configuration.

Key features:

• Context management: Create isolated browser contexts for parallel testing
• Tab management: Create, close, list, and activate browser tabs (pages)
• Remote connection: Connect to remote Chrome/Chromium instances
• Preferences: Configure browser settings for anti-bot evasion

Example usage:

browser, err := browser.ConnectToRemoteBrowser("http://localhost:9222")
if err != nil {
    log.Fatal(err)
}
defer browser.MustClose()

// Create a new tab
page, err := browser.NewTab("https://example.com")

Index

• func ActivateTab(p *rod.Page) error
• func CloseTab(p *rod.Page) error
• func ConnectToRemoteBrowser(addr string) (*rod.Browser, error)
• func ConnectToRemoteBrowserWithURL(addr, url string) (*rod.Browser, *rod.Page, error)
• func CreateContext(b *rod.Browser, opts ...ContextOption) (*rod.Browser, error)
• func CreateIncognitoContext(b *rod.Browser) (*rod.Browser, error)
• func DisposeContext(b *rod.Browser) error
• func GetContexts(b *rod.Browser) ([]string, error)
• func ListTabs(b *rod.Browser) ([]*rod.Page, error)
• func NewTab(b *rod.Browser, url string) (*rod.Page, error)
• type BrowserOptions
  • func NewBrowserOptions() *BrowserOptions
  • func (o *BrowserOptions) ApplyToLauncher(l *launcher.Launcher) *launcher.Launcher
  • func (o *BrowserOptions) GetBrowserPreferences() map[string]interface{}
  • func (o *BrowserOptions) SetBrowserPreferences(prefs map[string]interface{}) *BrowserOptions
  • func (o *BrowserOptions) StealthPreset() map[string]interface{}
• type ContextOption

Examples

• ActivateTab
• BrowserOptions.StealthPreset
• CloseTab
• ListTabs
• NewTab

Functions

func ActivateTab

func ActivateTab(p *rod.Page) error

ActivateTab brings a tab (page) to the foreground/focus

In go-rod, "tabs" are called "pages". This function activates the specified page, bringing it to the foreground and giving it focus.

Activating a tab will: - Bring the page to the front in the browser UI - Focus the page for keyboard/mouse events - Make it the target for subsequent automation commands

This is useful when working with multiple pages and you need to switch between them during automation.

This is a thin wrapper around go-rod's Activate() method which sends the CDP Target.activateTarget command to bring the page to the foreground.

Example

ExampleActivateTab demonstrates bringing a tab to the foreground

package main

import (
	"testing"

	"github.com/agenthands/godoll/browser"
	"github.com/go-rod/rod"
)

func main() {
	if testing.Short() {
		return
	}

	b := rod.New().MustConnect()
	defer b.MustClose()

	// Create multiple tabs
	tab1, _ := browser.NewTab(b, "about:blank")
	defer browser.CloseTab(tab1)

	tab2, _ := browser.NewTab(b, "about:blank")
	defer browser.CloseTab(tab2)

	// Activate tab1 to bring it to foreground
	_ = browser.ActivateTab(tab1)
}

func CloseTab

func CloseTab(p *rod.Page) error

CloseTab closes a tab (page)

In go-rod, "tabs" are called "pages". This function closes the specified page and releases all associated resources.

Closing a tab will: - Close the page in the browser - Release memory and resources - Terminate any ongoing operations on the page

After closing, the page instance should not be used. Any subsequent operations on the closed page will return errors.

This is a thin wrapper around go-rod's Close() method which sends the CDP Target.closeTarget command to close the page.

Example

ExampleCloseTab demonstrates closing a tab

package main

import (
	"testing"

	"github.com/agenthands/godoll/browser"
	"github.com/go-rod/rod"
)

func main() {
	if testing.Short() {
		return
	}

	b := rod.New().MustConnect()
	defer b.MustClose()

	// Create a tab
	tab, err := browser.NewTab(b, "about:blank")
	if err != nil {
		panic(err)
	}

	// Close the tab
	err = browser.CloseTab(tab)
	if err != nil {
		panic(err)
	}
}

func ConnectToRemoteBrowser

func ConnectToRemoteBrowser(addr string) (*rod.Browser, error)

ConnectToRemoteBrowser connects to a remote Chrome/Chromium instance. The remote browser must be started with the --remote-debugging-port flag.

To start a remote Chrome instance:

chrome --remote-debugging-port=9222

Or on Windows:

"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222

The addr parameter should be the full URL to the remote debugging port, typically "http://localhost:9222" or "ws://localhost:9222".

Example:

browser, err := browser.ConnectToRemoteBrowser("http://localhost:9222")
if err != nil {
    log.Fatal(err)
}
defer browser.MustClose()

page := browser.MustPage("https://example.com")

func ConnectToRemoteBrowserWithURL

func ConnectToRemoteBrowserWithURL(addr, url string) (*rod.Browser, *rod.Page, error)

ConnectToRemoteBrowserWithURL connects to a remote browser and creates a page with the given URL in one call. This is a convenience function that combines connection and initial navigation.

The remote browser must be started with --remote-debugging-port. See ConnectToRemoteBrowser for details on starting a remote browser.

If page creation fails, the browser connection is closed automatically.

Example:

browser, page, err := browser.ConnectToRemoteBrowserWithURL(
    "http://localhost:9222",
    "https://example.com",
)
if err != nil {
    log.Fatal(err)
}
defer page.MustClose()
defer browser.MustClose()

// page is already on the specified URL
title := page.MustInfo().Title

func CreateContext

func CreateContext(b *rod.Browser, opts ...ContextOption) (*rod.Browser, error)

CreateContext creates a new browser context with custom options

Returns an isolated incognito browser context that shares no cookies/cache/storage with the original browser. This provides actual context isolation.

The options parameter is reserved for future features like: - Custom storage paths - Viewport configuration - Locale/timezone settings

Note: In go-rod, context isolation is achieved through Incognito(). This function always creates an isolated context for actual separation.

func CreateIncognitoContext

func CreateIncognitoContext(b *rod.Browser) (*rod.Browser, error)

CreateIncognitoContext creates an incognito browser context for isolated browsing Returns a new browser instance that shares no cookies/cache/storage with the original

go-rod's Incognito() method creates a new browser context with full isolation: - Separate cookie jar - Separate cache storage - Separate localStorage/sessionStorage - Separate browser state

This is useful for: - Testing authentication flows in isolation - Running multiple scraping sessions without interference - Privacy-sensitive operations

func DisposeContext

func DisposeContext(b *rod.Browser) error

DisposeContext closes a browser context and releases all associated resources

This will: - Close all pages in the context - Release memory and resources - Clean up browser state

Important: Always dispose contexts when done to prevent resource leaks

func GetContexts

func GetContexts(b *rod.Browser) ([]string, error)

GetContexts returns information about browser contexts

Note: This function is not yet implemented. go-rod doesn't expose context IDs directly through the public API. Contexts are managed internally through browser instances.

In practice, contexts are tracked through the browser instances returned by CreateIncognitoContext() and CreateContext().

Returns an error until actual context inspection is implemented via CDP targets API.

func ListTabs

func ListTabs(b *rod.Browser) ([]*rod.Page, error)

ListTabs returns a list of all open tabs (pages) in the browser

In go-rod, "tabs" are called "pages". This function retrieves all currently open pages in the browser.

The returned list includes: - Pages created via NewTab() - Pages created via browser.Page() - The initial blank page (if present) - Any other pages opened in the browser

This is useful for: - Monitoring browser state - Managing multiple pages - Cleaning up resources

This is a thin wrapper around go-rod's Pages() method which retrieves all pages via the Chrome DevTools Protocol (CDP) Target.getTargets command.

Example

ExampleListTabs demonstrates listing all open tabs

package main

import (
	"testing"

	"github.com/agenthands/godoll/browser"
	"github.com/go-rod/rod"
)

func main() {
	if testing.Short() {
		return
	}

	b := rod.New().MustConnect()
	defer b.MustClose()

	// Create multiple tabs
	for i := 0; i < 3; i++ {
		_, err := browser.NewTab(b, "about:blank")
		if err != nil {
			panic(err)
		}
	}

	// List all tabs
	tabs, err := browser.ListTabs(b)
	if err != nil {
		panic(err)
	}

	// tabs contains all open pages
	_ = tabs
}

func NewTab

func NewTab(b *rod.Browser, url string) (*rod.Page, error)

NewTab creates a new tab (page) in the browser

In go-rod, "tabs" are called "pages". This function creates a new page instance. If url is empty, creates a blank page. Otherwise navigates to the specified URL.

The returned page is a new browser page that can be used for navigation, interaction, and automation. The page will remain open until explicitly closed.

This is a thin wrapper around go-rod's Page() method which creates a new page using the Chrome DevTools Protocol (CDP) Target.createTarget command.

Example

ExampleNewTab demonstrates creating a new tab in the browser

package main

import (
	"testing"

	"github.com/agenthands/godoll/browser"
	"github.com/go-rod/rod"
)

func main() {
	if testing.Short() {
		return
	}

	b := rod.New().MustConnect()
	defer b.MustClose()

	// Create a blank tab
	tab1, err := browser.NewTab(b, "")
	if err != nil {
		panic(err)
	}
	defer browser.CloseTab(tab1)

	// Create a tab with URL
	tab2, err := browser.NewTab(b, "about:blank")
	if err != nil {
		panic(err)
	}
	defer browser.CloseTab(tab2)
}

Types

type BrowserOptions

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

BrowserOptions holds browser configuration

func NewBrowserOptions

func NewBrowserOptions() *BrowserOptions

NewBrowserOptions creates a new browser options

func (*BrowserOptions) ApplyToLauncher

func (o *BrowserOptions) ApplyToLauncher(l *launcher.Launcher) *launcher.Launcher

ApplyToLauncher applies preferences to a launcher

func (*BrowserOptions) GetBrowserPreferences

func (o *BrowserOptions) GetBrowserPreferences() map[string]interface{}

GetBrowserPreferences returns the browser preferences

func (*BrowserOptions) SetBrowserPreferences

func (o *BrowserOptions) SetBrowserPreferences(prefs map[string]interface{}) *BrowserOptions

SetBrowserPreferences sets browser preferences

func (*BrowserOptions) StealthPreset

func (o *BrowserOptions) StealthPreset() map[string]interface{}

StealthPreset returns common anti-bot fingerprinting preferences

Example

package main

import (
	"testing"

	"github.com/agenthands/godoll/browser"
	"github.com/go-rod/rod/lib/launcher"
)

func main() {
	// This example shows how to create a stealth browser
	// with anti-bot fingerprinting settings
	if testing.Short() {
		return
	}

	opts := browser.NewBrowserOptions()

	// Apply stealth preset
	prefs := opts.StealthPreset()
	opts.SetBrowserPreferences(prefs)

	// Use with launcher
	l := opts.ApplyToLauncher(launcher.New())
	l.MustLaunch()
}

type ContextOption

type ContextOption func(*contextConfig)

ContextOption configures context creation

Context options use the functional options pattern for extensibility. This interface is reserved for future features like: - Custom storage paths - Viewport configuration - Locale/timezone settings