devbrowser

README

devbrowser

A lightweight Go library for launching and controlling web browsers programmatically, designed for automation and development tools.

Usage

The main entry point is the New function, which creates a new browser controller:

import "github.com/cdvelop/devbrowser"

type myServerConfig struct{}
func (myServerConfig) GetServerPort() string { return "8080" }

type myUI struct{}
func (myUI) ReturnFocus() {}

func main() {
	exitChan := make(chan bool)
	browser := devbrowser.New(myServerConfig{}, myUI{}, exitChan)
	err := browser.OpenBrowser()
	if err != nil {
		// handle error
	}
	// ... use browser ...
	browser.CloseBrowser()
}

Public API

• New(sc serverConfig, ui userInterface, exitChan chan bool) *DevBrowser: Create a new DevBrowser instance.

• (*DevBrowser) OpenBrowser() error: Launch a new browser window.

• (*DevBrowser) CloseBrowser() error: Close the browser and clean up resources.

• (*DevBrowser) Reload() error: Reload the current page in the browser.

• (*DevBrowser) RestartBrowser() error: Restart the browser (close and reopen).

• (*DevBrowser) BrowserStartUrlChanged(fieldName, oldValue, newValue string) error: Handle changes to the start URL and restart the browser if open.

• (*DevBrowser) BrowserPositionAndSizeChanged(fieldName, oldValue, newValue string) error: Change the browser window's position and size, and restart the browser.

• (*DevBrowser) Name() string and (*DevBrowser) Label() string: For UI integration, returns the component name and label.

• (*DevBrowser) Execute(progress func(msgs ...any)): For UI integration, toggles browser open/close and reports progress.

• (*DevBrowser) SetHeadless(headless bool): Configure whether the browser runs in headless mode (without a visible UI).

  • Signature: func (b *DevBrowser) SetHeadless(headless bool)
  • Default: false (shows the browser window). This is convenient for local development and debugging.
  • Tests: the test helper DefaultTestBrowser() configures the returned DevBrowser with headless = true so unit tests run without requiring a graphical display.
  • Notes: Call this before OpenBrowser() (or before the browser context is created) to ensure the headless flag is applied when launching Chrome/Chromium.
  • Example:

db := devbrowser.New(myServerConfig{}, myUI{}, exitChan)
// run with no UI (useful in CI/tests)
db.SetHeadless(true)
err := db.OpenBrowser()
if err != nil {
		// handle error
}

• (*DevBrowser) GetConsoleLogs() ([]string, error): Capture console messages from the loaded page.
  • Signature: func (b *DevBrowser) GetConsoleLogs() ([]string, error)
  • Behavior: injects a small script into the page that maintains window.__consoleLogs and returns its contents as a slice of strings. Captures console.log, console.error, console.warn, and console.info messages.
  • Requirements: the browser context must be initialized (OpenBrowser() called and context created). Returns an error if the context is not ready or the evaluation fails.
  • Example:

logs, err := db.GetConsoleLogs()
if err != nil {
		// handle error
}
for _, l := range logs {
		fmt.Println(l)
}

• (*DevBrowser) ClearConsoleLogs() error: Clear the in-page captured console log buffer.
  • Signature: func (b *DevBrowser) ClearConsoleLogs() error
  • Behavior: executes a small script that resets window.__consoleLogs = [] if present.
  • Requirements: the browser context must be initialized. Returns an error if the evaluation fails.
  • Example:

err := db.ClearConsoleLogs()
if err != nil {
		// handle error
}

Documentation

Index

• type BinaryData
• type DevBrowser
  • func New(sc serverConfig, ui userInterface, st store, exitChan chan bool, ...) *DevBrowser
  • func (h *DevBrowser) BrowserPositionAndSizeChanged(fieldName string, oldValue, newValue string) error
  • func (h *DevBrowser) BrowserStartUrlChanged(fieldName string, oldValue, newValue string) error
  • func (b *DevBrowser) ClearConsoleLogs() error
  • func (h *DevBrowser) CloseBrowser() error
  • func (h *DevBrowser) CreateBrowserContext() error
  • func (h *DevBrowser) Execute(progress chan<- string)
  • func (b *DevBrowser) GetConsoleLogs() ([]string, error)
  • func (h *DevBrowser) GetLastOperationID() string
  • func (b *DevBrowser) GetMCPToolsMetadata() []ToolMetadata
  • func (h *DevBrowser) Label() string
  • func (h *DevBrowser) Name() string
  • func (h *DevBrowser) OpenBrowser()
  • func (b *DevBrowser) Reload() error
  • func (h *DevBrowser) RestartBrowser() error
  • func (b *DevBrowser) SetHeadless(headless bool)
  • func (h *DevBrowser) SetLastOperationID(id string)
• type JSError
• type NetworkLogEntry
• type ParameterMetadata
• type ToolExecutor
• type ToolMetadata

Types

type BinaryData

type BinaryData struct {
	MimeType string // e.g., "image/png", "application/pdf"
	Data     []byte // Raw binary data
}

BinaryData represents binary response data with metadata

type DevBrowser

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

func New

func New(sc serverConfig, ui userInterface, st store, exitChan chan bool, logger func(message ...any)) *DevBrowser

devbrowser.New creates a new DevBrowser instance.

type serverConfig interface {
	GetServerPort() string
}

type userInterface interface {
	RefreshUI()
	ReturnFocus() error
}

example :  New(serverConfig, userInterface, exitChan)

func (*DevBrowser) BrowserPositionAndSizeChanged

func (h *DevBrowser) BrowserPositionAndSizeChanged(fieldName string, oldValue, newValue string) error

func (*DevBrowser) BrowserStartUrlChanged

func (h *DevBrowser) BrowserStartUrlChanged(fieldName string, oldValue, newValue string) error

func (*DevBrowser) ClearConsoleLogs

func (b *DevBrowser) ClearConsoleLogs() error

ClearConsoleLogs clears the captured console logs.

func (*DevBrowser) CloseBrowser

func (h *DevBrowser) CloseBrowser() error

func (*DevBrowser) CreateBrowserContext

func (h *DevBrowser) CreateBrowserContext() error

func (*DevBrowser) Execute

func (h *DevBrowser) Execute(progress chan<- string)

run the open/close browser operation

func (*DevBrowser) GetConsoleLogs

func (b *DevBrowser) GetConsoleLogs() ([]string, error)

GetConsoleLogs returns captured console logs from the browser. Returns an error if the browser context is not initialized.

func (*DevBrowser) GetLastOperationID

func (h *DevBrowser) GetLastOperationID() string

MessageTracker implementation for operation tracking

func (*DevBrowser) GetMCPToolsMetadata

func (b *DevBrowser) GetMCPToolsMetadata() []ToolMetadata

GetMCPToolsMetadata returns metadata for all DevBrowser MCP tools

func (*DevBrowser) Label

func (h *DevBrowser) Label() string

func (*DevBrowser) Name

func (h *DevBrowser) Name() string

func (*DevBrowser) OpenBrowser

func (h *DevBrowser) OpenBrowser()

func (*DevBrowser) Reload

func (b *DevBrowser) Reload() error

func (*DevBrowser) RestartBrowser

func (h *DevBrowser) RestartBrowser() error

func (*DevBrowser) SetHeadless

func (b *DevBrowser) SetHeadless(headless bool)

SetHeadless configura si el navegador debe ejecutarse en modo headless (sin UI). Por defecto es false (muestra la ventana del navegador). Debe llamarse antes de OpenBrowser().

func (*DevBrowser) SetLastOperationID

func (h *DevBrowser) SetLastOperationID(id string)

type JSError

type JSError struct {
	Message      string
	Source       string // File/URL where error occurred
	LineNumber   int
	ColumnNumber int
	StackTrace   string
	Timestamp    time.Time
}

type NetworkLogEntry

type NetworkLogEntry struct {
	URL       string
	Method    string
	Status    int
	Type      string // xhr, fetch, document, script, image, etc.
	Duration  int64  // milliseconds
	Failed    bool
	ErrorText string
}

type ParameterMetadata

type ParameterMetadata struct {
	Name        string
	Description string
	Required    bool
	Type        string
	EnumValues  []string
	Default     any
}

ParameterMetadata describes a tool parameter

type ToolExecutor

type ToolExecutor func(args map[string]any, progress chan<- any)

ToolExecutor defines how a tool should be executed Channel can receive: - string: text messages - []byte: binary data (images, files, etc.) with mime type prefix - BinaryData: structured binary response

type ToolMetadata

type ToolMetadata struct {
	Name        string
	Description string
	Parameters  []ParameterMetadata
	Execute     ToolExecutor // Execution function
}

ToolMetadata provides MCP tool configuration metadata