gorod

GoRod

GoRod is a Go package providing helper utilities for the Rod web automation library. It simplifies common browser automation tasks like interactive sessions, cookie extraction, element waiting, and screenshot capture.

Installation

go get github.com/grokify/gorod

CLI Tool

go install github.com/grokify/gorod/cmd/gorod@latest

Features

• 🖥️ Interactive Browser Sessions - Launch browsers that pause for manual interaction (e.g., login, CAPTCHA)
• 🍪 Cookie Extraction - Extract browser cookies and convert to standard http.Cookie format
• ⏳ Wait Helpers - Wait for elements to be visible or clickable with timeout
• 📸 Screenshot Capture - Full-page screenshots with HTTP status handling
• 🛠️ CLI Tool - Command-line tool for headless page fetching

Quick Start

Interactive Browser Session

Launch a browser, navigate to a URL, and pause for user interaction:

package main

import (
    "fmt"
    "log"

    "github.com/grokify/gorod"
)

func main() {
    // Open browser, navigate to URL, pause for login
    fb, err := gorod.NewForegroundBrowserPaused("https://example.com/login", 2, true)
    if err != nil {
        log.Fatal(err)
    }
    defer fb.Close()

    // Extract cookies after user logs in
    cookies, err := fb.Cookies()
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Session cookies: %s\n", cookies.String())
}

Cookie Extraction

Convert Rod cookies to standard HTTP cookies:

cookies, _ := fb.Cookies()

// Get as []*http.Cookie
httpCookies := cookies.HTTPCookies()

// Get as cookie header string
headerValue := cookies.String()

Wait for Elements

Wait for elements to be visible or clickable:

import (
    "time"
    "github.com/go-rod/rod"
    "github.com/grokify/gorod"
)

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

// Wait for element to be visible
el, err := gorod.WaitVisible(page, "#login-button", 10*time.Second)
if err != nil {
    log.Fatal("Login button not found")
}

// Wait for element to be clickable (visible and enabled)
el, err = gorod.WaitClickable(page, "#submit", 10*time.Second)
if err != nil {
    log.Fatal("Submit button not clickable")
}
el.MustClick()

Full-Page Screenshot

Capture a full-page screenshot with HTTP status handling:

import "github.com/grokify/gorod"

page, err := gorod.RetrieveWriteScreenshotFullPage(
    nil,                    // browser (nil creates new)
    "https://example.com",  // URL
    "screenshot.png",       // output file
    nil,                    // screenshot options
)
if err != nil {
    log.Fatal(err)
}
defer page.Close()

CLI Usage

The gorod CLI provides headless browser operations from the command line.

Fetch Command

Render a page and extract content:

# Get page text
gorod fetch -u https://example.com

# Get page HTML
gorod fetch -u https://example.com -o html

# Extract specific element
gorod fetch -u https://example.com -s ".main-content" -o html

# Wait for page stability (JS-heavy pages)
gorod fetch -u https://example.com -w

# With timeout
gorod fetch -u https://example.com -t 60

Flags

API Reference

Types

ForegroundBrowser

Interactive browser session with pause capability.

type ForegroundBrowser struct {
    Launcher *launcher.Launcher
    Browser  *rod.Browser
}

// Create new browser, navigate to URL, optionally pause
func NewForegroundBrowserPaused(navURL string, delaySeconds int, paused bool) (ForegroundBrowser, error)

// Close browser and cleanup
func (fb *ForegroundBrowser) Close()

// Extract cookies from browser
func (fb *ForegroundBrowser) Cookies() (Cookies, error)

// Fetch and write HTML to file
func (fb *ForegroundBrowser) GetWriteFileHTML(url, filename string, perm os.FileMode, force bool, writeDelay time.Duration) error

Cookies

Browser cookie collection with conversion utilities.

type Cookies []*proto.NetworkCookie

// Convert to standard HTTP cookies
func (c Cookies) HTTPCookies() []*http.Cookie

// Serialize to cookie header string
func (c Cookies) String() string

Functions

Wait Helpers

// Wait for element to become visible
func WaitVisible(page *rod.Page, selector string, timeout time.Duration) (*rod.Element, error)

// Wait for element to be visible and enabled
func WaitClickable(page *rod.Page, selector string, timeout time.Duration) (*rod.Element, error)

Screenshot

// Capture full-page screenshot with HTTP status handling
func RetrieveWriteScreenshotFullPage(browser *rod.Browser, srcURL, filename string, opts *proto.PageCaptureScreenshot) (*rod.Page, error)

Examples

See the examples/ directory:

• examples/cookies/ - Cookie extraction demo
• examples/screenshot/ - Screenshot capture demo

Use Cases

• Session capture: Extract authenticated session cookies for API testing
• Web scraping: Render JavaScript-heavy pages and extract content
• E2E testing helpers: Wait utilities for reliable element interaction
• Screenshot automation: Capture full-page screenshots for visual testing
• Manual authentication flows: Pause for CAPTCHA, 2FA, or complex logins

Dependencies

• go-rod/rod - Main browser automation library
• grokify/mogo - Go utility library

License

MIT License - see LICENSE for details.