go-webview

Chrome DevTools Protocol (CDP) client for browser automation in Go.


Module	`forge.lthn.ai/core/go-webview`
Dependency	`github.com/gorilla/websocket`
Licence	EUPL-1.2

Overview

go-webview provides a high-level Go API for controlling Chrome and Chromium browsers via the Chrome DevTools Protocol. It is designed for automated testing, web scraping, and GUI automation. The library communicates over WebSocket using the gorilla/websocket package and supports the full spectrum of browser interactions: navigation, DOM queries, mouse and keyboard input, screenshots, JavaScript evaluation, console monitoring, and Angular-specific helpers.

Features

Navigation -- Navigate to URLs, reload, go back/forward, wait for page load
DOM Queries -- QuerySelector and QuerySelectorAll with full element info (tag, attributes, bounding box)
Mouse Input -- Click, double-click, right-click, hover, drag-and-drop
Keyboard Input -- Type text into elements, press special keys (Enter, Tab, Escape, arrows)
Form Interaction -- Set values, select options, check/uncheck checkboxes, clear inputs, upload files
Screenshots -- Capture full-page PNG screenshots
JavaScript Evaluation -- Execute arbitrary scripts in the browser context
Viewport & User Agent -- Override device metrics and user agent strings
Console Monitoring -- Capture and filter console.log, console.error, etc.
Exception Watching -- Detect and inspect uncaught JavaScript exceptions
Action Sequences -- Chain actions into fluent, reusable sequences
Angular Helpers -- Wait for Zone.js stability, router navigation, component inspection
Multi-Tab -- Create new tabs, list targets, close tabs

Quick Start

package main

import (
    "log"
    "os"

    "forge.lthn.ai/core/go-webview"
)

func main() {
    wv, err := webview.New(webview.WithDebugURL("http://localhost:9222"))
    if err != nil {
        log.Fatal(err)
    }
    defer wv.Close()

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

    title, _ := wv.GetTitle()
    log.Println("Page title:", title)

    data, _ := wv.Screenshot()
    os.WriteFile("screenshot.png", data, 0644)
}

Start Chrome with remote debugging enabled before running:

google-chrome --remote-debugging-port=9222 --headless

Wiki Pages

Page	Description
Getting-Started	Connection setup, options, launching Chrome
DOM-Queries	QuerySelector, QuerySelectorAll, element information
Actions	Click, type, navigate, screenshot, key press, action sequences
Console-Monitoring	Console message capture, filtering, exception watching
Angular-Testing	Angular-specific helpers for Zone.js, router, components

Architecture

The package is organised into five source files:

File	Responsibility
`webview.go`	Core `Webview` struct, options, navigation, DOM queries, screenshots, JS evaluation
`cdp.go`	Low-level `CDPClient` -- WebSocket connection, message dispatch, event handlers
`actions.go`	`Action` interface, concrete action types, `ActionSequence` builder, file upload, drag-and-drop
`console.go`	`ConsoleWatcher`, `ExceptionWatcher`, filtering, formatted output
`angular.go`	`AngularHelper` -- Zone.js stability, router navigation, component property access

Key Types

Webview           -- Main entry point; holds CDPClient, context, console buffer
CDPClient         -- WebSocket connection to a Chrome DevTools target
ConsoleMessage    -- Captured console log entry (type, text, timestamp, source location)
ElementInfo       -- DOM element details (nodeId, tagName, attributes, boundingBox)
BoundingBox       -- Element geometry (x, y, width, height)
Action            -- Interface for executable browser actions
ActionSequence    -- Fluent builder for chaining multiple actions
ConsoleWatcher    -- Advanced console message capture with filters and handlers
ExceptionWatcher  -- JavaScript exception capture with handlers
AngularHelper     -- Angular-specific testing utilities
AngularRouterState -- Current Angular router URL, params, query params, fragment