engine

package
v1.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 28, 2026 License: BSD-3-Clause Imports: 79 Imported by: 0

Documentation

Overview

Package engine provides a Go-idiomatic API for headless browser automation, web scraping, and search built on go-rod. It wraps rod's types (Browser, Page, Element) with a simplified interface and adds higher-level scraping capabilities.

Core features: navigation, element interaction, screenshots, PDF generation, JavaScript evaluation, network interception, cookies, stealth mode, window state control (minimize, maximize, fullscreen), and HAR network recording via NetworkRecorder.

Scraping toolkit: struct-tag extraction (Page.Extract), HTML table and metadata parsing, form detection and filling, rate limiting with retry, generic pagination (click-next, URL-pattern, infinite-scroll, load-more), search engine integration (Google, Bing, DuckDuckGo), and BFS web crawling with sitemap support.

Basic usage: 

b, err := scout.New(scout.WithHeadless(true))
if err != nil {
	log.Fatal(err)
}
defer b.Close()

page, err := b.NewPage("https://example.com")
if err != nil {
	log.Fatal(err)
}

title, err := page.Title()
if err != nil {
	log.Fatal(err)
}
fmt.Println(title)

Struct-tag extraction: 

type Product struct {
	Name  string `scout:"h2.title"`
	Price string `scout:"span.price"`
	Image string `scout:"img.hero@src"`
}
var p Product
err := page.Extract(&p)

HAR recording: 

rec := scout.NewNetworkRecorder(page, scout.WithCaptureBody(true))
defer rec.Stop()
page.Navigate("https://example.com")
data, count, _ := rec.ExportHAR()

A gRPC service layer is available in the grpc/ subtree for remote browser control with event streaming and forensic capture. See cmd/server and cmd/client for the server and interactive client binaries.

See the examples/ directory for 18 runnable programs covering all features.

Example (ConvertHTMLToMarkdown) 
package main

import (
	"fmt"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	// convertHTMLToMarkdown is a pure function (unexported).
	// Use Page.Markdown() or Page.MarkdownContent() for the public API.
	// This example shows the options pattern:
	b, err := scout.New(scout.WithHeadless(true))
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = b.Close() }()

	page, err := b.NewPage("https://example.com")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	_ = page.WaitLoad()

	md, err := page.Markdown(
		scout.WithIncludeImages(false),
		scout.WithIncludeLinks(false),
	)
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	fmt.Println(md)
}

Index

Examples

Constants

View Source 
const (
	BridgeEventDOMMutation = "dom.mutation"
	BridgeEventUserClick   = "user.click"
	BridgeEventUserInput   = "user.input"
	BridgeEventNavigation  = "navigation"
	BridgeEventConsoleLog  = "console.log"
)

Standard bridge event types.

View Source 
const (
	RenderCSR     = detect.RenderCSR
	RenderSSR     = detect.RenderSSR
	RenderSSG     = detect.RenderSSG
	RenderISR     = detect.RenderISR
	RenderUnknown = detect.RenderUnknown
)

Re-export constants.

View Source 
const (
	FingerprintRotatePerSession = fingerprint.FingerprintRotatePerSession
	FingerprintRotatePerPage    = fingerprint.FingerprintRotatePerPage
	FingerprintRotatePerDomain  = fingerprint.FingerprintRotatePerDomain
	FingerprintRotateInterval   = fingerprint.FingerprintRotateInterval
)

Fingerprint rotation strategy constants.

View Source 
const (
	HijackEventRequest  = hijack.EventRequest
	HijackEventResponse = hijack.EventResponse
	HijackWSSent        = hijack.WSSent
	HijackWSReceived    = hijack.WSReceived
	HijackWSOpened      = hijack.WSOpened
	HijackWSClosed      = hijack.WSClosed
)

Re-export constants.

View Source 
const (
	JobStatusPending    = llm.JobStatusPending
	JobStatusExtracting = llm.JobStatusExtracting
	JobStatusReviewing  = llm.JobStatusReviewing
	JobStatusCompleted  = llm.JobStatusCompleted
	JobStatusFailed     = llm.JobStatusFailed

	AnthropicBaseURL    = llm.AnthropicBaseURL
	AnthropicAPIVersion = llm.AnthropicAPIVersion
	OpenAIBaseURL       = llm.OpenAIBaseURL
	OpenRouterBaseURL   = llm.OpenRouterBaseURL
	DeepSeekBaseURL     = llm.DeepSeekBaseURL
	GeminiBaseURL       = llm.GeminiBaseURL
)

Re-export constants.

View Source 
const (
	// BrowserChrome selects Google Chrome for Testing.
	BrowserChrome = browser.Chrome
	// BrowserChromium selects open-source Chromium (rod default).
	BrowserChromium = browser.Chromium
	// BrowserBrave selects Brave Browser.
	BrowserBrave = browser.Brave
	// BrowserEdge selects Microsoft Edge.
	BrowserEdge = browser.Edge
	// BrowserElectron selects Electron runtime for app automation.
	BrowserElectron = browser.Electron
)
View Source 
const DefaultOrphanCheckInterval = session.DefaultOrphanCheckInterval

DefaultOrphanCheckInterval is the default interval for periodic orphan checks.

View Source 
const HelperClickAll = `` /* 303-byte string literal not displayed */

HelperClickAll is a self-executing JS script that clicks all elements matching a CSS selector. window.__scout.clickAll(selector) returns the count of clicked elements.

View Source 
const HelperInfiniteScroll = `` /* 800-byte string literal not displayed */

HelperInfiniteScroll is a self-executing JS script that scrolls to the bottom of the page repeatedly until no new content loads. Configurable via window.__scout.infiniteScroll(maxScrolls, delayMs).

View Source 
const HelperShadowQuery = `` /* 1000-byte string literal not displayed */

HelperShadowQuery is a self-executing JS script that provides recursive shadow DOM querying via window.__scout.shadowQuery(selector) and window.__scout.shadowQueryAll(selector).

View Source 
const HelperTableExtract = `` /* 1098-byte string literal not displayed */

HelperTableExtract is a self-executing JS script that extracts all HTML tables as JSON arrays of {headers, rows} objects. Results are stored in window.__scout.tables.

View Source 
const HelperWaitForSelector = `` /* 680-byte string literal not displayed */

HelperWaitForSelector is a self-executing JS script that polls for a CSS selector to appear in the DOM. window.__scout.waitForSelector(selector, timeoutMs) returns a Promise that resolves to the element or rejects on timeout.

Variables

View Source 
var (
	GenerateFingerprint = fingerprint.GenerateFingerprint
	NewFingerprintStore = fingerprint.NewFingerprintStore

	WithFingerprintOS     = fingerprint.WithFingerprintOS
	WithFingerprintMobile = fingerprint.WithFingerprintMobile
	WithFingerprintLocale = fingerprint.WithFingerprintLocale
)
View Source 
var (
	WithHijackURLFilter   = hijack.WithURLFilter
	WithHijackBodyCapture = hijack.WithBodyCapture
	WithHijackChannelSize = hijack.WithChannelSize
	NewHijackRecorder     = hijack.NewRecorder
)

Re-export constructors and option functions.

View Source 
var (
	NewAnthropicProvider    = llm.NewAnthropicProvider
	WithAnthropicBaseURL    = llm.WithAnthropicBaseURL
	WithAnthropicKey        = llm.WithAnthropicKey
	WithAnthropicModel      = llm.WithAnthropicModel
	WithAnthropicHTTPClient = llm.WithAnthropicHTTPClient

	NewOllamaProvider    = llm.NewOllamaProvider
	WithOllamaHost       = llm.WithOllamaHost
	WithOllamaModel      = llm.WithOllamaModel
	WithOllamaAutoPull   = llm.WithOllamaAutoPull
	WithOllamaHTTPClient = llm.WithOllamaHTTPClient

	NewOpenAIProvider      = llm.NewOpenAIProvider
	NewOpenRouterProvider  = llm.NewOpenRouterProvider
	NewDeepSeekProvider    = llm.NewDeepSeekProvider
	NewGeminiProvider      = llm.NewGeminiProvider
	WithOpenAIBaseURL      = llm.WithOpenAIBaseURL
	WithOpenAIKey          = llm.WithOpenAIKey
	WithOpenAIModel        = llm.WithOpenAIModel
	WithOpenAIHTTPClient   = llm.WithOpenAIHTTPClient
	WithOpenAIAuthHeader   = llm.WithOpenAIAuthHeader
	WithOpenAIExtraHeaders = llm.WithOpenAIExtraHeaders

	NewLLMWorkspace = llm.NewWorkspace
)

Re-export constructors and option functions.

View Source 
var (
	// BlockAds blocks common advertising domains.
	BlockAds = []string{
		"*doubleclick.net*", "*googlesyndication.com*", "*googleadservices.com*",
		"*adnxs.com*", "*adsrvr.org*", "*amazon-adsystem.com*",
		"*moatads.com*", "*serving-sys.com*", "*adform.net*",
	}

	// BlockTrackers blocks common analytics and tracking domains.
	BlockTrackers = []string{
		"*google-analytics.com*", "*googletagmanager.com*",
		"*facebook.net/tr*", "*facebook.com/tr*",
		"*hotjar.com*", "*fullstory.com*", "*segment.io*",
		"*mixpanel.com*", "*amplitude.com*",
	}

	// BlockFonts blocks web font requests.
	BlockFonts = []string{
		"*.woff", "*.woff2", "*.ttf", "*.otf", "*.eot",
		"*fonts.googleapis.com*", "*fonts.gstatic.com*",
	}

	// BlockImages blocks image requests.
	BlockImages = []string{
		"*.png", "*.jpg", "*.jpeg", "*.gif", "*.webp", "*.svg", "*.ico", "*.bmp",
	}
)

Common URL-blocking presets for use with WithBlockPatterns.

View Source 
var (
	WithCaptureBody = hijack.WithCaptureBody
	WithCreatorName = hijack.WithCreatorName
)
View Source 
var (
	NewDirectProxy         = vpn.NewDirectProxy
	WithDirectProxyScheme  = vpn.WithDirectProxyScheme
	WithDirectProxyAuth    = vpn.WithDirectProxyAuth
	NewSurfsharkProvider   = vpn.NewSurfsharkProvider
	FilterServersByCountry = vpn.FilterServersByCountry
	ParseSurfsharkClusters = vpn.ParseSurfsharkClusters
)

Re-exported functions.

View Source 
var BuiltinTemplates = map[string]ScriptTemplate{
	"extract-list": {
		Name:        "extract-list",
		Description: "Extract items from a list by container and field selectors",
		Template: `(function() {
  var container = document.querySelector('{{.container}}');
  if (!container) return [];
  var items = container.querySelectorAll('{{.item}}');
  var result = [];
  for (var i = 0; i < items.length; i++) {
    var obj = {};
    {{range $key, $sel := .fields}}
    var el = items[i].querySelector('{{$sel}}');
    obj['{{$key}}'] = el ? el.innerText.trim() : '';
    {{end}}
    result.push(obj);
  }
  return JSON.stringify(result);
})()`,
	},
	"fill-form": {
		Name:        "fill-form",
		Description: "Fill a form by field name/value pairs",
		Template: `(function() {
  var filled = 0;
  {{range $name, $value := .fields}}
  (function() {
    var el = document.querySelector('[name="{{$name}}"]') || document.getElementById('{{$name}}');
    if (el) {
      var nativeSetter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value').set;
      nativeSetter.call(el, '{{$value}}');
      el.dispatchEvent(new Event('input', {bubbles: true}));
      el.dispatchEvent(new Event('change', {bubbles: true}));
      filled++;
    }
  })();
  {{end}}
  return filled;
})()`,
	},
	"scroll-and-collect": {
		Name:        "scroll-and-collect",
		Description: "Scroll page and collect items matching a selector as they load",
		Template: `(function() {
  var selector = '{{.selector}}';
  var maxScrolls = {{if .maxScrolls}}{{.maxScrolls}}{{else}}20{{end}};
  var delayMs = {{if .delayMs}}{{.delayMs}}{{else}}500{{end}};
  return new Promise(function(resolve) {
    var seen = new Set();
    var results = [];
    var count = 0;
    function collect() {
      document.querySelectorAll(selector).forEach(function(el) {
        var text = el.innerText.trim();
        if (!seen.has(text) && text) { seen.add(text); results.push(text); }
      });
    }
    function step() {
      collect();
      if (count >= maxScrolls) { resolve(JSON.stringify(results)); return; }
      window.scrollTo(0, document.body.scrollHeight);
      count++;
      setTimeout(function() {
        var prev = results.length;
        collect();
        if (results.length === prev && count > 1) { resolve(JSON.stringify(results)); return; }
        step();
      }, delayMs);
    }
    step();
  });
})()`,
	},
}

BuiltinTemplates maps template names to their ScriptTemplate definitions.

View Source 
var DefaultLogger = log.New(os.Stdout, "[rod] ", log.LstdFlags)

DefaultLogger for rod.

View Source 
var DefaultSleeper = func() utils2.Sleeper {
	return utils2.BackoffSleeper(100*time.Millisecond, time.Second, nil)
}

DefaultSleeper generates the default sleeper for retry, it uses backoff to grow the interval. The growth looks like: 

A(0) = 100ms, A(n) = A(n-1) * random[1.9, 2.1), A(n) < 1s

Why the default is not RequestAnimationFrame or DOM change events is because of if a retry never ends it can easily flood the program. But you can always easily config it into what you want.

View Source 
var ReportsDir = defaultReportsDir

ReportsDir is the function that returns the base directory for reports. It is a variable so tests can override it.

Functions

func AddSessionJobStep added in v0.57.0 

func AddSessionJobStep(sessionID string, step SessionJobStep) error

AddSessionJobStep appends a step to the job and auto-updates progress.

func CleanOrphans 

func CleanOrphans() (int, error)

CleanOrphans scans for orphaned browser processes and kills them.

func CleanStaleSessions added in v0.57.0 

func CleanStaleSessions() (int, error)

CleanStaleSessions removes leftover session directories on startup.

func CompleteSessionJob added in v0.57.0 

func CompleteSessionJob(sessionID string, output string) error

CompleteSessionJob marks a job as completed with output and timestamp.

func ConvertHTMLToMarkdown 

func ConvertHTMLToMarkdown(rawHTML string, opts ...MarkdownOption) (string, error)

ConvertHTMLToMarkdown is the pure-function core: parses HTML and produces Markdown. It requires no browser instance and can be used for offline HTML-to-Markdown conversion.

func DeleteReport added in v0.72.0 

func DeleteReport(id string) error

DeleteReport removes a report file by ID.

func DomainHash 

func DomainHash(rawURL string) string

DomainHash returns a short SHA-256 hash of the root domain.

func DownloadElectron 

func DownloadElectron(ctx context.Context, version string) (string, error)

DownloadElectron downloads a specific Electron version from GitHub releases and extracts it to ~/.scout/electron/<version>/. Returns the path to the executable. The version should include the "v" prefix (e.g. "v33.2.0").

func DownloadLatestElectron 

func DownloadLatestElectron(ctx context.Context) (string, error)

DownloadLatestElectron downloads the latest Electron release.

func ElectronCacheDir 

func ElectronCacheDir() (string, error)

ElectronCacheDir returns the path to ~/.scout/electron/, creating it if needed.

func EnrichSessionInfo 

func EnrichSessionInfo(info *SessionInfo)

EnrichSessionInfo populates Exec and BuildVersion from gops if available.

func ExtensionDir 

func ExtensionDir() (string, error)

ExtensionDir returns the path to ~/.scout/extensions/, creating it if needed.

func FailSessionJob added in v0.57.0 

func FailSessionJob(sessionID string, errMsg string) error

FailSessionJob marks a job as failed with an error message and timestamp.

func InjectAllHelpers 

func InjectAllHelpers(page *Page) error

InjectAllHelpers injects all built-in helpers onto the page, exposing them under the window.__scout namespace. Safe to call multiple times (idempotent).

func InjectHelper 

func InjectHelper(page *Page, helper string) error

InjectHelper evaluates a single JS helper string on the given page. 

func NavigateWithBypass(page *Page, url string, solver *ChallengeSolver) error

NavigateWithBypass navigates to the URL and automatically solves any detected bot protection challenges. If solver is nil, falls back to normal navigation.

func NotFoundSleeper 

func NotFoundSleeper() utils2.Sleeper

NotFoundSleeper returns ErrElementNotFound on the first call.

func PaginateByClick 

func PaginateByClick[T any](p *Page, nextSelector string, opts ...PaginateOption) ([]T, error)

PaginateByClick scrapes items from the current page, clicks the "next" button, and repeats until maxPages or no next button is found. T must be a struct with `scout:` tags.

Example 
package main

import (
	"fmt"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	type Item struct {
		Title string `scout:"h3.item-title"`
	}

	b, err := scout.New(scout.WithHeadless(true))
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = b.Close() }()

	page, err := b.NewPage("https://example.com/items")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	_ = page.WaitLoad()

	// Paginate by clicking a "Next" button, extracting items from each page.
	items, err := scout.PaginateByClick[Item](page, "a.next-page",
		scout.WithPaginateMaxPages(5),
	)
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	fmt.Printf("Collected %d items\n", len(items))
}

func PaginateByLoadMore 

func PaginateByLoadMore[T any](p *Page, loadMoreSelector string, opts ...PaginateOption) ([]T, error)

PaginateByLoadMore scrapes items by clicking a "load more" button repeatedly. T must be a struct with `scout:` tags.

func PaginateByScroll 

func PaginateByScroll[T any](p *Page, itemSelector string, opts ...PaginateOption) ([]T, error)

PaginateByScroll scrapes items by scrolling to the bottom and waiting for new content. T must be a struct with `scout:` tags. itemSelector identifies the repeating items.

func PaginateByURL 

func PaginateByURL[T any](b *Browser, urlFunc func(page int) string, opts ...PaginateOption) ([]T, error)

PaginateByURL scrapes items by navigating to URLs generated by urlFunc. urlFunc receives a 1-based page number and returns the URL to navigate to. T must be a struct with `scout:` tags.

func ParseAttrSpec 

func ParseAttrSpec(spec string) (selector, attr string, ok bool)

ParseAttrSpec parses "selector@attr" into selector and attribute name.

func ProxyChainDescription 

func ProxyChainDescription(chain *ProxyChain) string

ProxyChainDescription returns a human-readable description of the chain for logging and debugging. Auth credentials are masked.

func ReadReportRaw added in v0.72.0 

func ReadReportRaw(id string) (string, error)

ReadReportRaw returns the full text content of a report file.

func RemoveADBForward added in v1.0.0 

func RemoveADBForward(ctx context.Context, cfg MobileConfig) error

RemoveADBForward removes a previously created port forward.

func RemoveExtension 

func RemoveExtension(id string) error

RemoveExtension deletes a locally stored extension by ID.

func RemoveSessionInfo 

func RemoveSessionInfo(id string)

RemoveSessionInfo removes the scout.pid file from a session directory.

func RemoveSessionJob added in v0.57.0 

func RemoveSessionJob(sessionID string) error

RemoveSessionJob removes the job.json file from a session directory.

func RenderTemplate 

func RenderTemplate(tmpl ScriptTemplate, data map[string]any) (string, error)

RenderTemplate renders a ScriptTemplate with the given data map using Go's text/template engine.

func ResetAllSessions 

func ResetAllSessions() (int, error)

ResetAllSessions removes all session directories.

func ResetSession 

func ResetSession(id string) error

ResetSession removes an entire session directory.

func ResolveExtensions 

func ResolveExtensions(p *UserProfile) []string

ResolveExtensions resolves extension entries in a profile to valid filesystem paths. Each entry is checked as-is first (absolute path). If the path does not exist, it is treated as an extension ID and looked up in ~/.scout/extensions/<id>/. Missing extensions produce a warning log but do not cause errors.

func ResolveExtensionsWithBase 

func ResolveExtensionsWithBase(p *UserProfile, baseDir string) []string

ResolveExtensionsWithBase resolves extensions using a custom base directory instead of the default ~/.scout/extensions/. If baseDir is empty, the default is used. This variant exists for testing.

func RootDomain 

func RootDomain(rawURL string) string

RootDomain extracts the root domain from a URL.

func SaveCredentials 

func SaveCredentials(creds *CapturedCredentials, path string) error

SaveCredentials writes captured credentials to a JSON file.

func SaveProfile 

func SaveProfile(p *UserProfile, path string) error

SaveProfile writes a UserProfile to a JSON file with 0600 permissions.

func SaveProfileEncrypted 

func SaveProfileEncrypted(p *UserProfile, path, passphrase string) error

SaveProfileEncrypted writes an encrypted profile using AES-256-GCM + Argon2id.

func SaveReport added in v0.72.0 

func SaveReport(r *Report) (string, error)

SaveReport persists a report to ~/.scout/reports/{uuidv7}.txt as a structured, AI-consumable document with context, findings, and instructions. Returns the report ID.

func SaveSessionToFile 

func SaveSessionToFile(state *SessionState, path string) error

SaveSessionToFile marshals the session state to JSON and writes it to the given path.

func SaveUploadConfig 

func SaveUploadConfig(cfg *UploadConfig) error

SaveUploadConfig persists upload config to ~/.scout/upload.json.

func SessionDataDir added in v0.57.0 

func SessionDataDir(id string) string

SessionDataDir returns the browser user-data directory for a given session ID.

func SessionDir 

func SessionDir(id string) string

SessionDir returns the directory for a given session ID.

func SessionHash 

func SessionHash(rawURL, label string) string

SessionHash returns a deterministic hash for a session directory name.

func SessionsDir 

func SessionsDir() string

SessionsDir returns the base directory for session data.

func SetupADBForward added in v1.0.0 

func SetupADBForward(ctx context.Context, cfg MobileConfig) (string, error)

SetupADBForward creates a TCP port forward from localhost to the device's Chrome CDP socket.

func SnapshotWithLLM 

func SnapshotWithLLM(page *Page, provider LLMProvider, prompt string, opts ...SnapshotOption) (string, error)

SnapshotWithLLM takes an accessibility snapshot and sends it to the given LLM provider along with the user's prompt. Returns the LLM's response.

func StartOrphanWatchdog 

func StartOrphanWatchdog(interval time.Duration, done <-chan struct{})

StartOrphanWatchdog starts a background goroutine for periodic orphan cleanup.

func StartSessionJob added in v0.57.0 

func StartSessionJob(sessionID string) error

StartSessionJob transitions a job from pending to running.

func TabGroupCollect 

func TabGroupCollect[T any](tg *TabGroup, fn func(*Page) (T, error)) ([]T, []error)

TabGroupCollect extracts T from each tab in parallel using fn.

func Try 

func Try(fn func()) (err error)

Try try fn with recover, return the panic as rod.ErrTry.

func UpdateSessionJobProgress added in v0.57.0 

func UpdateSessionJobProgress(sessionID string, current, total int, message string) error

UpdateSessionJobProgress updates the progress fields on a job.

func UploadOAuthConfig 

func UploadOAuthConfig(sink UploadSink, clientID, clientSecret, redirectURL string) *oauth2.Config

UploadOAuthConfig returns OAuth2 configs for supported sinks.

func ValidateProxyChain 

func ValidateProxyChain(chain *ProxyChain) error

ValidateProxyChain checks that all hops in the chain have valid URLs with supported schemes.

func WriteSessionInfo 

func WriteSessionInfo(id string, info *SessionInfo) error

WriteSessionInfo writes the session info as JSON to <SessionsDir>/<id>/scout.pid.

func WriteSessionJob added in v0.57.0 

func WriteSessionJob(sessionID string, job *SessionJob) error

WriteSessionJob writes the job as JSON to <SessionsDir>/<sessionID>/job.json.

Types

type ADBDevice added in v1.0.0 

type ADBDevice struct {
	Serial string `json:"serial"`
	Model  string `json:"model"`
	State  string `json:"state"` // "device", "offline", "unauthorized"
}

ADBDevice represents a connected Android device.

func ListADBDevices added in v1.0.0 

func ListADBDevices(ctx context.Context, adbPath string) ([]ADBDevice, error)

ListADBDevices returns connected Android devices.

type AnthropicOption 

type AnthropicOption = llm.AnthropicOption

type AnthropicProvider 

type AnthropicProvider = llm.AnthropicProvider

AnthropicProvider re-exports llm.AnthropicProvider from sub-package.

type AsyncJob 

type AsyncJob struct {
	ID        string           `json:"id"`
	Type      string           `json:"type"`
	Status    AsyncJobStatus   `json:"status"`
	CreatedAt time.Time        `json:"created_at"`
	StartedAt *time.Time       `json:"started_at,omitempty"`
	EndedAt   *time.Time       `json:"ended_at,omitempty"`
	Progress  AsyncJobProgress `json:"progress"`
	Error     string           `json:"error,omitempty"`
	Result    any              `json:"result,omitempty"`
	Config    any              `json:"config,omitempty"`
}

AsyncJob represents a long-running operation such as batch scraping or crawling.

type AsyncJobManager 

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

AsyncJobManager manages async jobs with persistent state on disk.

func NewAsyncJobManager 

func NewAsyncJobManager(dir string) (*AsyncJobManager, error)

NewAsyncJobManager creates a job manager that persists jobs to dir. It creates the directory if it does not exist and loads any existing jobs.

func (*AsyncJobManager) Cancel 

func (m *AsyncJobManager) Cancel(id string) error

Cancel cancels a running job. If a cancel function was registered, it is called.

func (*AsyncJobManager) Complete 

func (m *AsyncJobManager) Complete(id string, result any) error

Complete marks a job as completed with a result.

func (*AsyncJobManager) Create 

func (m *AsyncJobManager) Create(jobType string, config any) (string, error)

Create creates a new pending job and returns its ID.

func (*AsyncJobManager) Fail 

func (m *AsyncJobManager) Fail(id string, errMsg string) error

Fail marks a job as failed with an error message.

func (*AsyncJobManager) Get 

func (m *AsyncJobManager) Get(id string) (*AsyncJob, error)

Get returns a job by ID.

func (*AsyncJobManager) List 

func (m *AsyncJobManager) List(status ...AsyncJobStatus) []*AsyncJob

List returns all jobs, optionally filtered by status. Jobs are sorted by creation time descending.

func (*AsyncJobManager) RegisterCancel 

func (m *AsyncJobManager) RegisterCancel(id string, fn context.CancelFunc)

RegisterCancel registers a context cancel function for a running job.

func (*AsyncJobManager) Start 

func (m *AsyncJobManager) Start(id string) error

Start marks a job as running.

func (*AsyncJobManager) UpdateProgress 

func (m *AsyncJobManager) UpdateProgress(id string, completed, failed int) error

UpdateProgress updates the progress counters of a running job.

type AsyncJobProgress 

type AsyncJobProgress struct {
	Total     int `json:"total"`
	Completed int `json:"completed"`
	Failed    int `json:"failed"`
}

AsyncJobProgress tracks completion of a job's units of work.

type AsyncJobStatus 

type AsyncJobStatus string

AsyncJobStatus represents the state of an async job. 

const (
	AsyncJobPending   AsyncJobStatus = "pending"
	AsyncJobRunning   AsyncJobStatus = "running"
	AsyncJobCompleted AsyncJobStatus = "completed"
	AsyncJobFailed    AsyncJobStatus = "failed"
	AsyncJobCancelled AsyncJobStatus = "cancelled"
)

type AutoFreeConfig 

type AutoFreeConfig struct {
	Interval  time.Duration
	OnRecycle func() // optional callback before recycle
}

AutoFreeConfig holds recycling configuration.

type BatchHandler 

type BatchHandler func(page *Page, url string) (any, error)

BatchHandler processes a single URL. Return data and error.

type BatchOption 

type BatchOption func(*batchOptions)

BatchOption configures batch scraping.

func WithBatchConcurrency 

func WithBatchConcurrency(n int) BatchOption

WithBatchConcurrency sets parallel page count. Default: 3.

func WithBatchJobManager 

func WithBatchJobManager(m *AsyncJobManager) BatchOption

WithBatchJobManager attaches an async job manager to track batch progress.

func WithBatchProgress 

func WithBatchProgress(fn func(done, total int)) BatchOption

WithBatchProgress sets a progress callback.

func WithBatchRateLimit 

func WithBatchRateLimit(rl *RateLimiter) BatchOption

WithBatchRateLimit applies a rate limiter to batch requests.

type BatchOutput 

type BatchOutput struct {
	JobID   string // non-empty when WithBatchJobManager is used
	Results []BatchResult
}

BatchOutput holds the overall results of a batch scrape, including a job ID when an AsyncJobManager is attached.

type BatchResult 

type BatchResult struct {
	URL   string
	Error error
	Data  any // user-defined result from handler
}

BatchResult holds the result of processing a single URL.

type Bridge 

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

Bridge provides bidirectional communication between Go and the browser runtime via CDP bindings. It is initialized lazily via Page.Bridge().

func (*Bridge) Available 

func (b *Bridge) Available() bool

Available returns true if the bridge extension's content script has loaded and signaled readiness.

func (*Bridge) DOM 

func (b *Bridge) DOM(opts ...DOMOption) (*DOMNode, error)

DOM returns the page DOM as a JSON tree via the bridge extension.

func (*Bridge) DOMMarkdown 

func (b *Bridge) DOMMarkdown(opts ...DOMOption) (string, error)

DOMMarkdown returns the page content as markdown, converted in-browser by the bridge extension.

func (*Bridge) MonitorDOMChanges 

func (b *Bridge) MonitorDOMChanges(opts ...map[string]any) (<-chan DOMChangeSummary, func(), error)

MonitorDOMChanges starts the DOM changes monitor and returns a channel of change summaries and a stop function.

func (*Bridge) ObserveMutations 

func (b *Bridge) ObserveMutations(selector string) error

ObserveMutations starts the DOM MutationObserver in the browser for the given selector. If selector is empty, observes document.body.

func (*Bridge) Off 

func (b *Bridge) Off(eventType string)

Off removes all handlers for the given event type.

func (*Bridge) On 

func (b *Bridge) On(eventType string, handler BridgeHandler)

On registers a handler for events of the given type from the browser.

func (*Bridge) OnMutation 

func (b *Bridge) OnMutation(handler func([]MutationEvent))

OnMutation registers a handler for DOM mutation events.

func (*Bridge) Query 

func (b *Bridge) Query(method string, params any) (json.RawMessage, error)

Query sends a request to the browser and waits for a response with a timeout.

func (*Bridge) ResetReady added in v0.72.0 

func (b *Bridge) ResetReady()

ResetReady clears the ready/available flags so that waitBridgeReady will block until the next __bridge_ready event fires. Call this before navigating to a new URL when reusing the same page and bridge.

func (*Bridge) Send 

func (b *Bridge) Send(eventType string, data any) error

Send dispatches a command from Go to the browser content script.

func (*Bridge) TakeDOMSnapshot 

func (b *Bridge) TakeDOMSnapshot(selector string) (*DOMSnapshotResult, error)

TakeDOMSnapshot captures the current DOM state for later comparison.

type BridgeEvent 

type BridgeEvent struct {
	Type      string         `json:"type"`
	PageID    string         `json:"pageID"`
	Timestamp int64          `json:"timestamp"`
	Data      map[string]any `json:"data,omitempty"`
}

BridgeEvent represents an event streamed from a browser page via the bridge WebSocket.

type BridgeFallback 

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

BridgeFallback provides CDP-based equivalents for bridge operations when the bridge extension WebSocket is not connected. It wraps a Page and falls back to direct CDP evaluation.

func NewBridgeFallback 

func NewBridgeFallback(page *Page) *BridgeFallback

NewBridgeFallback creates a new BridgeFallback that wraps the given page. If a bridge server and pageID are provided, it will attempt bridge operations first and fall back to CDP if the bridge is not connected.

func (*BridgeFallback) AutoFillForm 

func (f *BridgeFallback) AutoFillForm(selector string, data map[string]string) error

AutoFillForm fills a form using the window.__scout API as a fallback path. It evaluates JavaScript directly via CDP to fill form fields by name/id.

func (*BridgeFallback) Click 

func (f *BridgeFallback) Click(selector string) error

Click clicks an element by selector, falling back to CDP if bridge is unavailable.

func (*BridgeFallback) Eval 

func (f *BridgeFallback) Eval(js string) (*EvalResult, error)

Eval evaluates JavaScript on the page, falling back to CDP. This method always uses CDP since bridge eval is not meaningfully different.

func (*BridgeFallback) FetchFile 

func (f *BridgeFallback) FetchFile(url string) ([]byte, error)

FetchFile downloads a file using the window.__scout API as a fallback path. It evaluates JavaScript directly via CDP using XMLHttpRequest to fetch the URL.

func (*BridgeFallback) Query 

func (f *BridgeFallback) Query(selector string) ([]map[string]any, error)

Query queries DOM elements, falling back to CDP page.Eval if bridge is unavailable.

func (*BridgeFallback) SetPageID 

func (f *BridgeFallback) SetPageID(id string)

SetPageID sets the bridge page ID for bridge-first operations.

func (*BridgeFallback) Type 

func (f *BridgeFallback) Type(selector, text string) error

Type types text into an element by selector, falling back to CDP if bridge is unavailable.

type BridgeHandler 

type BridgeHandler func(data json.RawMessage)

BridgeHandler processes an event received from the browser.

type BridgeMessage 

type BridgeMessage struct {
	ID     string          `json:"id"`
	Type   string          `json:"type"` // "request", "response", "event"
	Method string          `json:"method"`
	Params json.RawMessage `json:"params,omitempty"`
	Result json.RawMessage `json:"result,omitempty"`
	Error  string          `json:"error,omitempty"`
}

BridgeMessage represents a message exchanged over the bridge WebSocket.

type BridgeOption 

type BridgeOption func(*bridgeOptions)

BridgeOption configures bridge behavior.

func WithQueryTimeout 

func WithQueryTimeout(d time.Duration) BridgeOption

WithQueryTimeout sets the timeout for Bridge.Query() calls.

type BridgeRecorder 

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

BridgeRecorder records bridge events and converts them to runbook steps.

func NewBridgeRecorder 

func NewBridgeRecorder(server *BridgeServer) *BridgeRecorder

NewBridgeRecorder creates a new recorder attached to a bridge server. Returns nil if server is nil.

func (*BridgeRecorder) Start 

func (r *BridgeRecorder) Start()

Start begins recording bridge events and converting them to runbook steps. It subscribes to user.click, user.input, and navigation events.

func (*BridgeRecorder) Steps 

func (r *BridgeRecorder) Steps() []RecordedStep

Steps returns the current steps without stopping the recorder.

func (*BridgeRecorder) Stop 

func (r *BridgeRecorder) Stop() []RecordedStep

Stop stops recording and returns the accumulated steps.

func (*BridgeRecorder) ToRecipe deprecated 

func (r *BridgeRecorder) ToRecipe(name, url string) *RecordedRunbook

Deprecated: ToRecipe is an alias for ToRunbook. Use ToRunbook instead.

func (*BridgeRecorder) ToRunbook 

func (r *BridgeRecorder) ToRunbook(name, url string) *RecordedRunbook

ToRunbook converts the recorded steps into a full automate runbook.

type BridgeServer 

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

BridgeServer provides a WebSocket server for bridge communication between Go and browser extensions.

func NewBridgeServer 

func NewBridgeServer(addr string) *BridgeServer

NewBridgeServer creates a new WebSocket bridge server bound to the given address. The address should be in "host:port" form, e.g. "127.0.0.1:0" for auto-assigned port.

func (*BridgeServer) Addr 

func (s *BridgeServer) Addr() string

Addr returns the listener address, useful when started on port 0.

func (*BridgeServer) AutoFillForm 

func (s *BridgeServer) AutoFillForm(pageID, selector string, data map[string]string) error

AutoFillForm finds a form by selector and fills each field by name/id matching the map keys with the map values. Input and change events are dispatched for framework compatibility.

func (*BridgeServer) Broadcast 

func (s *BridgeServer) Broadcast(method string, params any) error

Broadcast sends a message to all connected clients. It does not wait for responses.

func (*BridgeServer) CallExposed 

func (s *BridgeServer) CallExposed(pageID, funcName string, args ...any) (json.RawMessage, error)

CallExposed calls a JavaScript function registered via window.__scout.expose() in the page identified by pageID. The function is invoked with the given arguments and the result is returned as raw JSON.

func (*BridgeServer) ClickElement 

func (s *BridgeServer) ClickElement(pageID, selector string) error

ClickElement clicks an element matching selector via the bridge.

func (*BridgeServer) Clients 

func (s *BridgeServer) Clients() []string

Clients returns the page IDs of all currently connected clients.

func (*BridgeServer) CloseTab 

func (s *BridgeServer) CloseTab(tabID int) error

CloseTab closes a browser tab by its tab ID.

func (*BridgeServer) ConsoleMessages 

func (s *BridgeServer) ConsoleMessages(pageID string) ([]map[string]any, error)

ConsoleMessages retrieves captured console messages from the page. The content script must have console capture enabled via console.capture first.

func (*BridgeServer) DownloadFile 

func (s *BridgeServer) DownloadFile(pageID, url string) ([]byte, error)

DownloadFile fetches a URL via the page's fetch API (inheriting cookies/auth) and returns the response body as bytes. The data is base64-encoded over the bridge.

func (*BridgeServer) EmitEvent 

func (s *BridgeServer) EmitEvent(pageID, eventName string, data any) error

EmitEvent emits an event to the page's window.__scout.on() listeners.

func (*BridgeServer) Events 

func (s *BridgeServer) Events() <-chan BridgeEvent

Events returns a read-only channel that receives all bridge events from connected browser clients.

func (*BridgeServer) GetClipboard 

func (s *BridgeServer) GetClipboard(pageID string) (string, error)

GetClipboard reads clipboard text from the page via the bridge.

func (*BridgeServer) InsertHTML 

func (s *BridgeServer) InsertHTML(pageID, selector, position, html string) error

InsertHTML inserts HTML adjacent to an element. Position must be one of: "beforebegin", "afterbegin", "beforeend", "afterend".

func (*BridgeServer) ListFrames 

func (s *BridgeServer) ListFrames(pageID string) ([]map[string]any, error)

ListFrames returns information about all frames in the page.

func (*BridgeServer) ListTabs 

func (s *BridgeServer) ListTabs() ([]map[string]any, error)

ListTabs lists all open browser tabs via the bridge extension background script. It sends to the first connected client (background script).

func (*BridgeServer) ModifyAttribute 

func (s *BridgeServer) ModifyAttribute(pageID, selector, attr, value string) error

ModifyAttribute sets an attribute on an element matching selector.

func (*BridgeServer) ObserveDOM 

func (s *BridgeServer) ObserveDOM(pageID, selector string) error

ObserveDOM starts a MutationObserver on elements matching selector. Mutations are emitted as bridge events of type "dom.mutation".

func (*BridgeServer) OnMessage 

func (s *BridgeServer) OnMessage(method string, handler BridgeWSHandler)

OnMessage registers a handler for a specific method name. When a request with the given method arrives from a browser client, the handler is invoked and its result is sent back as a response.

func (*BridgeServer) QueryDOM 

func (s *BridgeServer) QueryDOM(pageID, selector string, all bool) ([]map[string]any, error)

QueryDOM queries DOM elements via the bridge WebSocket. If all is true, returns all matching elements; otherwise returns the first match.

func (*BridgeServer) QueryShadowDOM 

func (s *BridgeServer) QueryShadowDOM(pageID, selector string) ([]map[string]any, error)

QueryShadowDOM queries the page's DOM with shadow DOM piercing. It walks into open shadow roots recursively to find elements matching the CSS selector.

func (*BridgeServer) RemoveElement 

func (s *BridgeServer) RemoveElement(pageID, selector string) error

RemoveElement removes an element matching selector from the DOM.

func (*BridgeServer) Send 

func (s *BridgeServer) Send(pageID, method string, params any) (*BridgeMessage, error)

Send sends a request to a specific page and waits for the response. It returns an error if no client with the given pageID is connected or if the response is not received within 10 seconds.

func (*BridgeServer) SendToFrame 

func (s *BridgeServer) SendToFrame(pageID string, frameIndex int, method string, params any) (*BridgeMessage, error)

SendToFrame sends a command to a specific frame in the page. The frameIndex identifies which frame to target (0-based, matching the order from ListFrames).

func (*BridgeServer) SetClipboard 

func (s *BridgeServer) SetClipboard(pageID, text string) error

SetClipboard writes text to the clipboard via the bridge.

func (*BridgeServer) Start 

func (s *BridgeServer) Start() error

Start begins listening for WebSocket connections. It returns once the listener is active; connections are handled in background goroutines.

func (*BridgeServer) StartConsoleCapture 

func (s *BridgeServer) StartConsoleCapture(pageID string) error

StartConsoleCapture enables console message interception on the page.

func (*BridgeServer) Stop 

func (s *BridgeServer) Stop() error

Stop gracefully shuts down the WebSocket server and closes all client connections.

func (*BridgeServer) Subscribe 

func (s *BridgeServer) Subscribe(eventType string, fn func(BridgeEvent))

Subscribe registers a callback for events of the given type. If eventType is empty, the callback receives all events. Subscriptions are not removable; they live for the lifetime of the server.

func (*BridgeServer) TypeText 

func (s *BridgeServer) TypeText(pageID, selector, text string) error

TypeText types text into an element matching selector via the bridge.

type BridgeWSHandler 

type BridgeWSHandler func(msg BridgeMessage) (any, error)

BridgeWSHandler processes an incoming bridge WebSocket request and returns a result.

type Browser 

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

Browser wraps a rod browser instance with a simplified API. For standalone browser detection, download, and cache management without the full scout dependency, see the pkg/browser/ package.

func New 

func New(opts ...Option) (*Browser, error)

New creates and connects a new headless browser with the given options.

Example 
package main

import (
	"fmt"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	b, err := scout.New(scout.WithHeadless(true))
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = b.Close() }()

	page, err := b.NewPage("https://example.com")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	title, err := page.Title()
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	fmt.Println(title)
}

func (*Browser) BatchScrape 

func (b *Browser) BatchScrape(urls []string, handler BatchHandler, opts ...BatchOption) []BatchResult

BatchScrape processes multiple URLs concurrently with error isolation. Results are returned in the same order as input URLs.

func (*Browser) BatchScrapeWithJob 

func (b *Browser) BatchScrapeWithJob(urls []string, handler BatchHandler, opts ...BatchOption) BatchOutput

BatchScrapeWithJob is like BatchScrape but returns a BatchOutput that includes the async job ID when WithBatchJobManager is used.

func (*Browser) BridgeServer 

func (b *Browser) BridgeServer() *BridgeServer

BridgeServer returns the WebSocket bridge server, or nil if bridge port was not configured (see WithBridgePort).

func (*Browser) CDPURL added in v0.72.0 

func (b *Browser) CDPURL() string

CDPURL returns the CDP WebSocket URL used to connect to this browser.

func (*Browser) Close 

func (b *Browser) Close() error

Close shuts down the browser and kills any orphan child processes. It is nil-safe, idempotent, and safe for concurrent use.

Example 
package main

import (
	"fmt"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	b, err := scout.New(scout.WithHeadless(true))
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	// Close is nil-safe and idempotent — safe to call multiple times.
	_ = b.Close()
	_ = b.Close() // no-op, no error

	// Also safe on a nil *Browser.
	var nilBrowser *scout.Browser

	_ = nilBrowser.Close()
}

func (*Browser) ConnectVPN 

func (b *Browser) ConnectVPN(_ context.Context, conn *VPNConnection, username, password string) error

ConnectVPN sets up VPN proxy at the browser level. It configures proxy authentication via rod's HandleAuth and stores the connection state on the Browser for status queries.

For a full workflow, use SurfsharkProvider.Connect() first to get the connection details and proxy credentials, then call this method.

func (*Browser) Crawl 

func (b *Browser) Crawl(startURL string, handler CrawlHandler, opts ...CrawlOption) ([]CrawlResult, error)

Crawl performs a BFS crawl starting from startURL, calling handler for each page.

Example 
package main

import (
	"fmt"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	b, err := scout.New(scout.WithHeadless(true))
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = b.Close() }()

	results, err := b.Crawl("https://example.com", func(page *scout.Page, result *scout.CrawlResult) error {
		fmt.Printf("Crawled: %s (depth=%d)\n", result.URL, result.Depth)
		return nil
	}, scout.WithCrawlMaxDepth(2), scout.WithCrawlMaxPages(10))
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	fmt.Printf("Total pages: %d\n", len(results))
}

func (*Browser) CrawlWithJob 

func (b *Browser) CrawlWithJob(startURL string, handler CrawlHandler, opts ...CrawlOption) (CrawlOutput, error)

CrawlWithJob is like Crawl but returns a CrawlOutput that includes the async job ID when WithCrawlJobManager is used.

func (*Browser) DisconnectVPN 

func (b *Browser) DisconnectVPN() error

DisconnectVPN clears VPN connection state and proxy auth handlers.

func (*Browser) Done 

func (b *Browser) Done() <-chan struct{}

Done returns a channel that is closed when the browser process exits. This allows callers to detect when the user closes the browser window. Returns nil if the browser was connected via remote CDP (no launcher).

func (*Browser) ExtractSwagger 

func (b *Browser) ExtractSwagger(url string, opts ...SwaggerOption) (*SwaggerSpec, error)

ExtractSwagger navigates to the given URL and extracts the Swagger/OpenAPI spec.

func (*Browser) Gather 

func (b *Browser) Gather(targetURL string, opts ...GatherOption) (*GatherResult, error)

Gather navigates to targetURL and collects all requested page intelligence in a single pass. By default, all data types are collected. Use specific WithGather* options to collect only what you need.

func (*Browser) GitHubExtractIssues 

func (b *Browser) GitHubExtractIssues(owner, repo string, opts ...GitHubExtractOption) ([]GitHubExtractIssue, error)

GitHubExtractIssues extracts the issue list from the issues tab.

func (*Browser) GitHubExtractPRs 

func (b *Browser) GitHubExtractPRs(owner, repo string, opts ...GitHubExtractOption) ([]GitHubExtractIssue, error)

GitHubExtractPRs extracts the pull request list from the pulls tab.

func (*Browser) GitHubExtractReleases 

func (b *Browser) GitHubExtractReleases(owner, repo string, opts ...GitHubExtractOption) ([]GitHubExtractRelease, error)

GitHubExtractReleases extracts the releases list from the releases page.

func (*Browser) GitHubExtractRepoInfo 

func (b *Browser) GitHubExtractRepoInfo(owner, repo string, opts ...GitHubExtractOption) (*GitHubExtractRepo, error)

GitHubExtractRepoInfo navigates to github.com/{owner}/{repo} and extracts metadata.

func (*Browser) GitHubIssues 

func (b *Browser) GitHubIssues(owner, name string, opts ...GitHubOption) ([]GitHubIssue, error)

GitHubIssues navigates to the issues page of a GitHub repo and extracts issue metadata.

func (*Browser) GitHubPRs 

func (b *Browser) GitHubPRs(owner, name string, opts ...GitHubOption) ([]GitHubPR, error)

GitHubPRs navigates to the pull requests page of a GitHub repo and extracts PR metadata.

func (*Browser) GitHubReleases 

func (b *Browser) GitHubReleases(owner, name string, opts ...GitHubOption) ([]GitHubRelease, error)

GitHubReleases navigates to the releases page of a GitHub repo and extracts release metadata.

func (*Browser) GitHubRepo 

func (b *Browser) GitHubRepo(owner, name string, opts ...GitHubOption) (*GitHubRepo, error)

GitHubRepo navigates to a GitHub repository page and extracts metadata.

func (*Browser) GitHubSearchCode 

func (b *Browser) GitHubSearchCode(query string, opts ...GitHubOption) ([]GitHubCodeResult, error)

GitHubSearchCode searches GitHub code search and extracts results.

func (*Browser) GitHubTree 

func (b *Browser) GitHubTree(owner, name, branch string) ([]string, error)

GitHubTree navigates to a GitHub repo and extracts the file tree.

func (*Browser) GitHubUser 

func (b *Browser) GitHubUser(username string) (*GitHubUser, error)

GitHubUser navigates to a GitHub user profile and extracts metadata.

func (*Browser) HandleAuth 

func (b *Browser) HandleAuth(username, password string) func() error

HandleAuth sets up HTTP basic authentication for the browser. Returns a function that waits for and handles the next auth challenge.

func (*Browser) HealthCheck 

func (b *Browser) HealthCheck(targetURL string, opts ...HealthCheckOption) (*HealthReport, error)

HealthCheck crawls targetURL and reports broken links, console errors, JS exceptions, and network failures. It reuses the Crawl BFS engine with per-page CDP event listeners.

func (*Browser) Knowledge 

func (b *Browser) Knowledge(targetURL string, opts ...KnowledgeOption) (*KnowledgeResult, error)

Knowledge crawls a site and collects all possible intelligence per page.

func (*Browser) Map 

func (b *Browser) Map(startURL string, opts ...MapOption) ([]string, error)

Map discovers all URLs on a site by combining sitemap.xml parsing with on-page link harvesting. It returns a deduplicated list of URLs.

Example 
package main

import (
	"fmt"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	b, err := scout.New(scout.WithHeadless(true))
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = b.Close() }()

	urls, err := b.Map("https://example.com",
		scout.WithMapLimit(50),
		scout.WithMapMaxDepth(2),
	)
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	fmt.Printf("Discovered %d URLs\n", len(urls))
}

func (*Browser) NewManagedPagePool added in v0.72.0 

func (b *Browser) NewManagedPagePool(size int) (*ManagedPagePool, error)

NewManagedPagePool is a convenience method that creates a ManagedPagePool from this browser.

func (*Browser) NewPage 

func (b *Browser) NewPage(url string) (*Page, error)

NewPage creates a new browser tab and navigates to the given URL. If stealth mode is enabled, the page is created with anti-detection measures.

Example 
package main

import (
	"fmt"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	b, err := scout.New(scout.WithHeadless(true), scout.WithStealth())
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = b.Close() }()

	// NewPage creates a tab and navigates to the URL.
	page, err := b.NewPage("https://example.com")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = page.Close() }()

	url, _ := page.URL()
	fmt.Println(url)
}

func (*Browser) NewTabGroup 

func (b *Browser) NewTabGroup(n int, opts ...TabGroupOption) (*TabGroup, error)

NewTabGroup creates a group of n blank tabs. It returns an error if n < 1 or the browser is nil. On partial failure, already-created tabs are closed.

func (*Browser) Pages 

func (b *Browser) Pages() ([]*Page, error)

Pages returns all open pages (tabs) in the browser.

func (*Browser) ParseSitemap 

func (b *Browser) ParseSitemap(sitemapURL string) ([]SitemapURL, error)

ParseSitemap fetches and parses a sitemap.xml, returning all URLs found. Supports both sitemap index files and regular sitemaps.

func (*Browser) Search 

func (b *Browser) Search(query string, opts ...SearchOption) (*SearchResults, error)

Search performs a search query and returns the results from the first page.

Example 
package main

import (
	"fmt"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	b, err := scout.New(scout.WithHeadless(true))
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = b.Close() }()

	results, err := b.Search("golang tutorial",
		scout.WithSearchEngine(scout.Google),
		scout.WithSearchMaxPages(1),
	)
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	for _, r := range results.Results {
		fmt.Printf("%d. %s\n   %s\n", r.Position, r.Title, r.URL)
	}
}

func (*Browser) SearchAll 

func (b *Browser) SearchAll(query string, opts ...SearchOption) ([]SearchResult, error)

SearchAll performs a search and collects results across multiple pages.

func (*Browser) SessionID 

func (b *Browser) SessionID() string

SessionID returns the UUID v7 session identifier for this browser instance.

func (*Browser) SitemapExtract 

func (b *Browser) SitemapExtract(startURL string, opts ...SitemapOption) (*SitemapResult, error)

SitemapExtract crawls a site starting from startURL and extracts DOM JSON and Markdown for every page using the bridge extension.

func (*Browser) VPNStatus 

func (b *Browser) VPNStatus() *VPNStatus

VPNStatus returns the current VPN connection status for the browser.

func (*Browser) Version 

func (b *Browser) Version() (string, error)

Version returns the browser version string (cached from startup).

func (*Browser) WebFetch 

func (b *Browser) WebFetch(url string, opts ...WebFetchOption) (*WebFetchResult, error)

WebFetch navigates to a URL and extracts structured content in a single call. Combines navigation, readability, metadata, and markdown conversion.

func (*Browser) WebFetchBatch 

func (b *Browser) WebFetchBatch(urls []string, opts ...WebFetchOption) []*WebFetchResult

WebFetchBatch fetches multiple URLs concurrently and returns results.

func (*Browser) WebMCPRegistry 

func (b *Browser) WebMCPRegistry() *WebMCPRegistry

WebMCPRegistry returns the browser's WebMCP tool registry, or nil if auto-discover is not enabled (see WithWebMCPAutoDiscover).

func (*Browser) WebSearch 

func (b *Browser) WebSearch(query string, opts ...WebSearchOption) (*WebSearchResult, error)

WebSearch performs a search query and optionally fetches result pages.

type BrowserInfo 

type BrowserInfo struct {
	Product  string `json:"product"`
	Platform string `json:"platform"`
	OS       string `json:"os"`
	Arch     string `json:"arch"`
}

BrowserInfo describes the browser used during capture.

type BrowserType 

type BrowserType = browser.BrowserType

BrowserType is an alias for browser.BrowserType.

type CDPClient 

type CDPClient interface {
	Event() <-chan *cdp.Event
	Call(ctx context.Context, sessionID, method string, params any) ([]byte, error)
}

CDPClient is usually used to make rod side-effect free. Such as proxy all IO of rod.

type CapSolverService 

type CapSolverService struct {
	APIKey     string
	BaseURL    string
	HTTPClient *http.Client
}

CapSolverService implements CaptchaSolverService using the capsolver.com API.

func NewCapSolverService 

func NewCapSolverService(apiKey string) *CapSolverService

NewCapSolverService creates a new capsolver.com solver.

func (*CapSolverService) Name 

func (s *CapSolverService) Name() string

Name returns the service name.

func (*CapSolverService) Solve 

func (s *CapSolverService) Solve(ctx context.Context, req SolveRequest) (string, error)

Solve submits a task to CapSolver and polls for the result.

type CaptchaSolverService 

type CaptchaSolverService interface {
	// Solve submits a CAPTCHA task and returns the solution token.
	Solve(ctx context.Context, req SolveRequest) (string, error)
	// Name returns the service name.
	Name() string
}

CaptchaSolverService is the interface for third-party CAPTCHA solving services.

type CaptureOption added in v0.72.0 

type CaptureOption func(*captureConfig)

CaptureOption configures the CaptureOnClose workflow.

func WithCapturePersist added in v0.72.0 

func WithCapturePersist() CaptureOption

WithCapturePersist keeps the browser session directory after capture. By default the session is deleted after credentials are saved.

func WithCaptureSavePath added in v0.72.0 

func WithCaptureSavePath(path string) CaptureOption

WithCaptureSavePath sets the file path where captured credentials are saved. If empty, credentials are returned but not written to disk.

type CapturedCredentials 

type CapturedCredentials struct {
	URL            string            `json:"url"`
	FinalURL       string            `json:"final_url"`
	CapturedAt     time.Time         `json:"captured_at"`
	Browser        BrowserInfo       `json:"browser"`
	Cookies        []Cookie          `json:"cookies"`
	LocalStorage   map[string]string `json:"local_storage,omitempty"`
	SessionStorage map[string]string `json:"session_storage,omitempty"`
	UserAgent      string            `json:"user_agent"`
}

CapturedCredentials holds all browser state needed to replicate an authenticated session.

func CaptureCredentials 

func CaptureCredentials(ctx context.Context, url string, opts ...Option) (*CapturedCredentials, error)

CaptureCredentials opens a headed (visible) browser, navigates to the given URL, and blocks until the user presses Ctrl+C or the context is cancelled. Before returning, it captures all authentication state (cookies, localStorage, sessionStorage, user agent, browser version).

Usage: navigate to a login page, log in manually, then press Ctrl+C. The returned CapturedCredentials can be saved with SaveCredentials.

func CaptureOnClose added in v0.72.0 

func CaptureOnClose(ctx context.Context, url string, browserOpts []Option, opts ...CaptureOption) (*CapturedCredentials, error)

CaptureOnClose opens a headed browser to the given URL, continuously snapshots authentication state while the user interacts, then returns the last good snapshot when the browser window is closed. If a save path is configured via WithCaptureSavePath, credentials are written to disk. Unless WithCapturePersist is set, the session directory is deleted after capture.

func LoadCredentials 

func LoadCredentials(path string) (*CapturedCredentials, error)

LoadCredentials reads captured credentials from a JSON file.

func (*CapturedCredentials) ToSessionState 

func (c *CapturedCredentials) ToSessionState() *SessionState

ToSessionState converts captured credentials to a SessionState for use with LoadSession.

type CapturedRequest 

type CapturedRequest = hijack.CapturedRequest

type CapturedResponse 

type CapturedResponse = hijack.CapturedResponse

type ChallengeInfo 

type ChallengeInfo struct {
	Type       ChallengeType `json:"type"`
	Detected   bool          `json:"detected"`
	Confidence float64       `json:"confidence"`
	Details    string        `json:"details"`
	Selector   string        `json:"selector,omitempty"`
}

ChallengeInfo describes a detected bot protection challenge.

type ChallengeSolver 

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

ChallengeSolver detects and attempts to bypass bot protection challenges.

func NewChallengeSolver 

func NewChallengeSolver(browser *Browser, opts ...SolverOption) *ChallengeSolver

NewChallengeSolver creates a new solver with built-in handlers for common challenge types.

func (*ChallengeSolver) Register 

func (cs *ChallengeSolver) Register(ct ChallengeType, fn SolveFunc)

Register adds or replaces a solver for the given challenge type.

func (*ChallengeSolver) Solve 

func (cs *ChallengeSolver) Solve(page *Page) error

Solve detects the highest-confidence challenge on the page and applies the appropriate solver. Returns nil if no challenge is detected.

func (*ChallengeSolver) SolveAll 

func (cs *ChallengeSolver) SolveAll(page *Page) error

SolveAll detects and solves all challenges iteratively, up to 3 retries.

type ChallengeType 

type ChallengeType string

ChallengeType identifies a bot protection mechanism. 

const (
	ChallengeNone        ChallengeType = "none"
	ChallengeCloudflare  ChallengeType = "cloudflare"
	ChallengeTurnstile   ChallengeType = "turnstile"
	ChallengeRecaptchaV2 ChallengeType = "recaptcha_v2"
	ChallengeRecaptchaV3 ChallengeType = "recaptcha_v3"
	ChallengeHCaptcha    ChallengeType = "hcaptcha"
	ChallengeDataDome    ChallengeType = "datadome"
	ChallengePerimeterX  ChallengeType = "perimeterx"
	ChallengeAkamai      ChallengeType = "akamai"
	ChallengeAWSWAF      ChallengeType = "aws_waf"
)
type Cookie struct {
	Name     string    `json:"name"`
	Value    string    `json:"value"`
	URL      string    `json:"url,omitempty"`
	Domain   string    `json:"domain,omitempty"`
	Path     string    `json:"path,omitempty"`
	Expires  time.Time `json:"expires,omitzero"`
	Secure   bool      `json:"secure,omitempty"`
	HTTPOnly bool      `json:"http_only,omitempty"`
	SameSite string    `json:"same_site,omitempty"`
}

Cookie represents an HTTP cookie.

type CoveredError 

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

CoveredError error.

func (CoveredError) Attribute 

func (el CoveredError) Attribute(name string) (*string, error)

Attribute of the DOM object. Attribute vs Property: https://stackoverflow.com/questions/6003819/what-is-the-difference-between-properties-and-attributes-in-html

func (CoveredError) BackgroundImage 

func (el CoveredError) BackgroundImage() ([]byte, error)

BackgroundImage returns the css background-image of the element.

func (CoveredError) Blur 

func (el CoveredError) Blur() error

Blur removes focus from the element.

func (CoveredError) Call 

func (el CoveredError) Call(ctx context.Context, sessionID, methodName string, params any) (res []byte, err error)

Call implements the proto.Client.

func (CoveredError) CancelTimeout 

func (el CoveredError) CancelTimeout() *rodElement

CancelTimeout cancels the current timeout context and returns a clone with the parent context.

func (CoveredError) CanvasToImage 

func (el CoveredError) CanvasToImage(format string, quality float64) ([]byte, error)

CanvasToImage get image data of a canvas. The default format is image/png. The default quality is 0.92. doc: https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toDataURL

func (CoveredError) Click 

func (el CoveredError) Click(button proto2.InputMouseButton, clickCount int) error

Click will press then release the button just like a human. Before the action, it will try to scroll to the element, hover the mouse over it, wait until the it's interactable and enabled.

func (CoveredError) ContainsElement 

func (el CoveredError) ContainsElement(target *rodElement) (bool, error)

ContainsElement check if the target is equal or inside the element.

func (CoveredError) Context 

func (el CoveredError) Context(ctx context.Context) *rodElement

Context returns a clone with the specified ctx for chained sub-operations.

func (CoveredError) Describe 

func (el CoveredError) Describe(depth int, pierce bool) (*proto2.DOMNode, error)

Describe the current element. The depth is the maximum depth at which children should be retrieved, defaults to 1, use -1 for the entire subtree or provide an integer larger than 0. The pierce decides whether or not iframes and shadow roots should be traversed when returning the subtree. The returned proto.DOMNode.NodeID will always be empty, because NodeID is not stable (when proto.DOMDocumentUpdated is fired all NodeID on the page will be reassigned to another value) we don't recommend using the NodeID, instead, use the proto.DOMBackendNodeID to identify the element.

func (CoveredError) Disabled 

func (el CoveredError) Disabled() (bool, error)

Disabled checks if the element is disabled.

func (CoveredError) Element 

func (el CoveredError) Element(selector string) (*rodElement, error)

Element returns the first child that matches the css selector.

func (CoveredError) ElementByJS 

func (el CoveredError) ElementByJS(opts *EvalOptions) (*rodElement, error)

ElementByJS returns the element from the return value of the js.

func (CoveredError) ElementR 

func (el CoveredError) ElementR(selector, jsRegex string) (*rodElement, error)

ElementR returns the first child element that matches the css selector and its text matches the jsRegex.

func (CoveredError) ElementX 

func (el CoveredError) ElementX(xPath string) (*rodElement, error)

ElementX returns the first child that matches the XPath selector.

func (CoveredError) Elements 

func (el CoveredError) Elements(selector string) (Elements, error)

Elements returns all elements that match the css selector.

func (CoveredError) ElementsByJS 

func (el CoveredError) ElementsByJS(opts *EvalOptions) (Elements, error)

ElementsByJS returns the elements from the return value of the js.

func (CoveredError) ElementsX 

func (el CoveredError) ElementsX(xpath string) (Elements, error)

ElementsX returns all elements that match the XPath selector.

func (CoveredError) Equal 

func (el CoveredError) Equal(elm *rodElement) (bool, error)

Equal checks if the two elements are equal.

func (*CoveredError) Error 

func (e *CoveredError) Error() string

Error ...

func (CoveredError) Eval 

func (el CoveredError) Eval(js string, params ...any) (*proto2.RuntimeRemoteObject, error)

Eval is a shortcut for [Element.Evaluate] with AwaitPromise, ByValue and AutoExp set to true.

func (CoveredError) Evaluate 

func (el CoveredError) Evaluate(opts *EvalOptions) (*proto2.RuntimeRemoteObject, error)

Evaluate is just a shortcut of [Page.Evaluate] with This set to current element.

func (CoveredError) Focus 

func (el CoveredError) Focus() error

Focus sets focus on the specified element. Before the action, it will try to scroll to the element.

func (CoveredError) Frame 

func (el CoveredError) Frame() (*rodPage, error)

Frame creates a page instance that represents the iframe.

func (CoveredError) GetContext 

func (el CoveredError) GetContext() context.Context

GetContext of current instance.

func (CoveredError) GetSessionID 

func (el CoveredError) GetSessionID() proto2.TargetSessionID

GetSessionID interface.

func (CoveredError) GetXPath 

func (el CoveredError) GetXPath(optimized bool) (string, error)

GetXPath returns the xpath of the element.

func (CoveredError) HTML 

func (el CoveredError) HTML() (string, error)

HTML of the element.

func (CoveredError) Has 

func (el CoveredError) Has(selector string) (bool, *rodElement, error)

Has an element that matches the css selector.

func (CoveredError) HasR 

func (el CoveredError) HasR(selector, jsRegex string) (bool, *rodElement, error)

HasR returns true if a child element that matches the css selector and its text matches the jsRegex.

func (CoveredError) HasX 

func (el CoveredError) HasX(selector string) (bool, *rodElement, error)

HasX an element that matches the XPath selector.

func (CoveredError) Hover 

func (el CoveredError) Hover() error

Hover the mouse over the center of the element. Before the action, it will try to scroll to the element and wait until it's interactable.

func (CoveredError) Input 

func (el CoveredError) Input(text string) error

Input focuses on the element and input text to it. Before the action, it will scroll to the element, wait until it's visible, enabled and writable. To empty the input you can use something like 

el.SelectAllText().MustInput("")

func (CoveredError) InputColor 

func (el CoveredError) InputColor(color string) error

InputColor focuses on the element and inputs a color string to it. Before the action, it will scroll to the element, wait until it's visible, enabled and writable.

func (CoveredError) InputTime 

func (el CoveredError) InputTime(t time.Time) error

InputTime focuses on the element and input time to it. Before the action, it will scroll to the element, wait until it's visible, enabled and writable. It will wait until the element is visible, enabled and writable.

func (CoveredError) Interactable 

func (el CoveredError) Interactable() (pt *proto2.Point, err error)

Interactable checks if the element is interactable with cursor. The cursor can be mouse, finger, stylus, etc. If not interactable err will be ErrNotInteractable, such as when covered by a modal,.

func (*CoveredError) Is 

func (e *CoveredError) Is(err error) bool

Is interface.

func (CoveredError) KeyActions 

func (el CoveredError) KeyActions() (*KeyActions, error)

KeyActions is similar with Page.KeyActions. Before the action, it will try to scroll to the element and focus on it.

func (CoveredError) Matches 

func (el CoveredError) Matches(selector string) (bool, error)

Matches checks if the element can be selected by the css selector.

func (CoveredError) MoveMouseOut 

func (el CoveredError) MoveMouseOut() error

MoveMouseOut of the current element.

func (CoveredError) MustAttribute 

func (el CoveredError) MustAttribute(name string) *string

MustAttribute is similar to Element.Attribute.

func (CoveredError) MustBackgroundImage 

func (el CoveredError) MustBackgroundImage() []byte

MustBackgroundImage is similar to Element.BackgroundImage.

func (CoveredError) MustBlur 

func (el CoveredError) MustBlur() *rodElement

MustBlur is similar to Element.Blur.

func (CoveredError) MustCanvasToImage 

func (el CoveredError) MustCanvasToImage() []byte

MustCanvasToImage is similar to Element.CanvasToImage.

func (CoveredError) MustClick 

func (el CoveredError) MustClick() *rodElement

MustClick is similar to Element.Click.

func (CoveredError) MustContainsElement 

func (el CoveredError) MustContainsElement(target *rodElement) bool

MustContainsElement is similar to Element.ContainsElement.

func (CoveredError) MustDescribe 

func (el CoveredError) MustDescribe() *proto2.DOMNode

MustDescribe is similar to [Element.Describe].

func (CoveredError) MustDisabled 

func (el CoveredError) MustDisabled() bool

MustDisabled is similar to Element.Disabled.

func (CoveredError) MustDoubleClick 

func (el CoveredError) MustDoubleClick() *rodElement

MustDoubleClick is similar to Element.Click.

func (CoveredError) MustElement 

func (el CoveredError) MustElement(selector string) *rodElement

MustElement is similar to Element.Element.

func (CoveredError) MustElementByJS 

func (el CoveredError) MustElementByJS(js string, params ...any) *rodElement

MustElementByJS is similar to [Element.ElementByJS].

func (CoveredError) MustElementR 

func (el CoveredError) MustElementR(selector, regex string) *rodElement

MustElementR is similar to [Element.ElementR].

func (CoveredError) MustElementX 

func (el CoveredError) MustElementX(xpath string) *rodElement

MustElementX is similar to [Element.ElementX].

func (CoveredError) MustElements 

func (el CoveredError) MustElements(selector string) Elements

MustElements is similar to Element.Elements.

func (CoveredError) MustElementsByJS 

func (el CoveredError) MustElementsByJS(js string, params ...any) Elements

MustElementsByJS is similar to [Element.ElementsByJS].

func (CoveredError) MustElementsX 

func (el CoveredError) MustElementsX(xpath string) Elements

MustElementsX is similar to [Element.ElementsX].

func (CoveredError) MustEqual 

func (el CoveredError) MustEqual(elm *rodElement) bool

MustEqual is similar to Element.Equal.

func (CoveredError) MustEval 

func (el CoveredError) MustEval(js string, params ...any) gson.JSON

MustEval is similar to Element.Eval.

func (CoveredError) MustFocus 

func (el CoveredError) MustFocus() *rodElement

MustFocus is similar to Element.Focus.

func (CoveredError) MustFrame 

func (el CoveredError) MustFrame() *rodPage

MustFrame is similar to Element.Frame.

func (CoveredError) MustGetXPath 

func (el CoveredError) MustGetXPath(optimized bool) string

MustGetXPath is similar to Element.GetXPath.

func (CoveredError) MustHTML 

func (el CoveredError) MustHTML() string

MustHTML is similar to Element.HTML.

func (CoveredError) MustHas 

func (el CoveredError) MustHas(selector string) bool

MustHas is similar to [Element.Has].

func (CoveredError) MustHasR 

func (el CoveredError) MustHasR(selector, regex string) bool

MustHasR is similar to [Element.HasR].

func (CoveredError) MustHasX 

func (el CoveredError) MustHasX(selector string) bool

MustHasX is similar to [Element.HasX].

func (CoveredError) MustHover 

func (el CoveredError) MustHover() *rodElement

MustHover is similar to Element.Hover.

func (CoveredError) MustInput 

func (el CoveredError) MustInput(text string) *rodElement

MustInput is similar to Element.Input.

func (CoveredError) MustInputColor 

func (el CoveredError) MustInputColor(color string) *rodElement

MustInputColor is similar to Element.InputColor.

func (CoveredError) MustInputTime 

func (el CoveredError) MustInputTime(t time.Time) *rodElement

MustInputTime is similar to Element.Input.

func (CoveredError) MustInteractable 

func (el CoveredError) MustInteractable() bool

MustInteractable is similar to Element.Interactable.

func (CoveredError) MustKeyActions 

func (el CoveredError) MustKeyActions() *KeyActions

MustKeyActions is similar to [Element.KeyActions].

func (CoveredError) MustMatches 

func (el CoveredError) MustMatches(selector string) bool

MustMatches is similar to Element.Matches.

func (CoveredError) MustMoveMouseOut 

func (el CoveredError) MustMoveMouseOut() *rodElement

MustMoveMouseOut is similar to Element.MoveMouseOut.

func (CoveredError) MustNext 

func (el CoveredError) MustNext() *rodElement

MustNext is similar to Element.Next.

func (CoveredError) MustParent 

func (el CoveredError) MustParent() *rodElement

MustParent is similar to Element.Parent.

func (CoveredError) MustParents 

func (el CoveredError) MustParents(selector string) Elements

MustParents is similar to Element.Parents.

func (CoveredError) MustPrevious 

func (el CoveredError) MustPrevious() *rodElement

MustPrevious is similar to Element.Previous.

func (CoveredError) MustProperty 

func (el CoveredError) MustProperty(name string) gson.JSON

MustProperty is similar to Element.Property.

func (CoveredError) MustRelease 

func (el CoveredError) MustRelease()

MustRelease is similar to [Element.Release].

func (CoveredError) MustRemove 

func (el CoveredError) MustRemove()

MustRemove is similar to Element.Remove.

func (CoveredError) MustResource 

func (el CoveredError) MustResource() []byte

MustResource is similar to Element.Resource.

func (CoveredError) MustScreenshot 

func (el CoveredError) MustScreenshot(toFile ...string) []byte

MustScreenshot is similar to Element.Screenshot.

func (CoveredError) MustScrollIntoView 

func (el CoveredError) MustScrollIntoView() *rodElement

MustScrollIntoView is similar to Element.ScrollIntoView.

func (CoveredError) MustSelect 

func (el CoveredError) MustSelect(selectors ...string) *rodElement

MustSelect is similar to [Element.Select].

func (CoveredError) MustSelectAllText 

func (el CoveredError) MustSelectAllText() *rodElement

MustSelectAllText is similar to Element.SelectAllText.

func (CoveredError) MustSelectText 

func (el CoveredError) MustSelectText(regex string) *rodElement

MustSelectText is similar to Element.SelectText.

func (CoveredError) MustSetFiles 

func (el CoveredError) MustSetFiles(paths ...string) *rodElement

MustSetFiles is similar to Element.SetFiles.

func (CoveredError) MustShadowRoot 

func (el CoveredError) MustShadowRoot() *rodElement

MustShadowRoot is similar to Element.ShadowRoot.

func (CoveredError) MustShape 

func (el CoveredError) MustShape() *proto2.DOMGetContentQuadsResult

MustShape is similar to [Element.Shape].

func (CoveredError) MustTap 

func (el CoveredError) MustTap() *rodElement

MustTap is similar to Element.Tap.

func (CoveredError) MustText 

func (el CoveredError) MustText() string

MustText is similar to Element.Text.

func (CoveredError) MustType 

func (el CoveredError) MustType(keys ...input.Key) *rodElement

MustType is similar to Element.Type.

func (CoveredError) MustVisible 

func (el CoveredError) MustVisible() bool

MustVisible is similar to Element.Visible.

func (CoveredError) MustWait 

func (el CoveredError) MustWait(js string, params ...any) *rodElement

MustWait is similar to [Element.Wait].

func (CoveredError) MustWaitEnabled 

func (el CoveredError) MustWaitEnabled() *rodElement

MustWaitEnabled is similar to Element.WaitEnabled.

func (CoveredError) MustWaitInteractable 

func (el CoveredError) MustWaitInteractable() *rodElement

MustWaitInteractable is similar to Element.WaitInteractable.

func (CoveredError) MustWaitInvisible 

func (el CoveredError) MustWaitInvisible() *rodElement

MustWaitInvisible is similar to Element.WaitInvisible..

func (CoveredError) MustWaitLoad 

func (el CoveredError) MustWaitLoad() *rodElement

MustWaitLoad is similar to Element.WaitLoad.

func (CoveredError) MustWaitStable 

func (el CoveredError) MustWaitStable() *rodElement

MustWaitStable is similar to Element.WaitStable.

func (CoveredError) MustWaitVisible 

func (el CoveredError) MustWaitVisible() *rodElement

MustWaitVisible is similar to Element.WaitVisible.

func (CoveredError) MustWaitWritable 

func (el CoveredError) MustWaitWritable() *rodElement

MustWaitWritable is similar to Element.WaitWritable.

func (CoveredError) Next 

func (el CoveredError) Next() (*rodElement, error)

Next returns the next sibling element in the DOM tree.

func (CoveredError) Overlay 

func (el CoveredError) Overlay(msg string) (removeOverlay func())

Overlay msg on the element.

func (CoveredError) Page 

func (el CoveredError) Page() *rodPage

Page of the element.

func (CoveredError) Parent 

func (el CoveredError) Parent() (*rodElement, error)

Parent returns the parent element in the DOM tree.

func (CoveredError) Parents 

func (el CoveredError) Parents(selector string) (Elements, error)

Parents that match the selector.

func (CoveredError) Previous 

func (el CoveredError) Previous() (*rodElement, error)

Previous returns the previous sibling element in the DOM tree.

func (CoveredError) Property 

func (el CoveredError) Property(name string) (gson.JSON, error)

Property of the DOM object. Property vs Attribute: https://stackoverflow.com/questions/6003819/what-is-the-difference-between-properties-and-attributes-in-html

func (CoveredError) Release 

func (el CoveredError) Release() error

Release is a shortcut for [Page.Release] current element.

func (CoveredError) Remove 

func (el CoveredError) Remove() error

Remove the element from the page.

func (CoveredError) Resource 

func (el CoveredError) Resource() ([]byte, error)

Resource returns the "src" content of current element. Such as the jpg of <img src="a.jpg">.

func (CoveredError) Screenshot 

func (el CoveredError) Screenshot(format proto2.PageCaptureScreenshotFormat, quality int) ([]byte, error)

Screenshot of the area of the element.

func (CoveredError) ScrollIntoView 

func (el CoveredError) ScrollIntoView() error

ScrollIntoView scrolls the current element into the visible area of the browser window if it's not already within the visible area.

func (CoveredError) Select 

func (el CoveredError) Select(selectors []string, selected bool, t SelectorType) error

Select the children option elements that match the selectors. Before the action, it will scroll to the element, wait until it's visible. If no option matches the selectors, it will return [ErrElementNotFound].

func (CoveredError) SelectAllText 

func (el CoveredError) SelectAllText() error

SelectAllText selects all text Before the action, it will try to scroll to the element and focus on it.

func (CoveredError) SelectText 

func (el CoveredError) SelectText(regex string) error

SelectText selects the text that matches the regular expression. Before the action, it will try to scroll to the element and focus on it.

func (CoveredError) SetFiles 

func (el CoveredError) SetFiles(paths []string) error

SetFiles of the current file input element.

func (CoveredError) ShadowRoot 

func (el CoveredError) ShadowRoot() (*rodElement, error)

ShadowRoot returns the shadow root of this element.

func (CoveredError) Shape 

func (el CoveredError) Shape() (*proto2.DOMGetContentQuadsResult, error)

Shape of the DOM element content. The shape is a group of 4-sides polygons. A 4-sides polygon is not necessary a rectangle. 4-sides polygons can be apart from each other. For example, we use 2 4-sides polygons to describe the shape below: 

  ____________          ____________
 /        ___/    =    /___________/    +     _________
/________/                                   /________/

func (CoveredError) Sleeper 

func (el CoveredError) Sleeper(sleeper func() utils.Sleeper) *rodElement

Sleeper returns a clone with the specified sleeper for chained sub-operations.

func (CoveredError) String 

func (el CoveredError) String() string

String interface.

func (CoveredError) Tap 

func (el CoveredError) Tap() error

Tap will scroll to the button and tap it just like a human. Before the action, it will try to scroll to the element and wait until it's interactable and enabled.

func (CoveredError) Text 

func (el CoveredError) Text() (string, error)

Text that the element displays.

func (CoveredError) Timeout 

func (el CoveredError) Timeout(d time.Duration) *rodElement

Timeout returns a clone with the specified total timeout of all chained sub-operations.

func (CoveredError) Type 

func (el CoveredError) Type(keys ...input.Key) error

Type is similar with Keyboard.Type. Before the action, it will try to scroll to the element and focus on it.

func (*CoveredError) Unwrap 

func (e *CoveredError) Unwrap() error

Unwrap ...

func (CoveredError) Visible 

func (el CoveredError) Visible() (bool, error)

Visible returns true if the element is visible on the page.

func (CoveredError) Wait 

func (el CoveredError) Wait(opts *EvalOptions) error

Wait until the js returns true.

func (CoveredError) WaitEnabled 

func (el CoveredError) WaitEnabled() error

WaitEnabled until the element is not disabled. Doc for readonly: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/readonly

func (CoveredError) WaitInteractable 

func (el CoveredError) WaitInteractable() (pt *proto2.Point, err error)

WaitInteractable waits for the element to be interactable. It will try to scroll to the element on each try.

func (CoveredError) WaitInvisible 

func (el CoveredError) WaitInvisible() error

WaitInvisible until the element invisible.

func (CoveredError) WaitLoad 

func (el CoveredError) WaitLoad() error

WaitLoad for element like <img>.

func (CoveredError) WaitStable 

func (el CoveredError) WaitStable(d time.Duration) error

WaitStable waits until no shape or position change for d duration. Be careful, d is not the max wait timeout, it's the least stable time. If you want to set a timeout you can use the [Element.Timeout] function.

func (CoveredError) WaitStableRAF 

func (el CoveredError) WaitStableRAF() error

WaitStableRAF waits until no shape or position change for 2 consecutive animation frames. If you want to wait animation that is triggered by JS not CSS, you'd better use Element.WaitStable. About animation frame: https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame

func (CoveredError) WaitVisible 

func (el CoveredError) WaitVisible() error

WaitVisible until the element is visible.

func (CoveredError) WaitWritable 

func (el CoveredError) WaitWritable() error

WaitWritable until the element is not readonly. Doc for disabled: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/disabled

func (CoveredError) WithCancel 

func (el CoveredError) WithCancel() (*rodElement, func())

WithCancel returns a clone with a context cancel function.

func (CoveredError) WithPanic 

func (el CoveredError) WithPanic(fail func(any)) *rodElement

WithPanic returns an element clone with the specified panic function. The fail must stop the current goroutine's execution immediately, such as use runtime.Goexit or panic inside it.

type CrawlHandler 

type CrawlHandler func(page *Page, result *CrawlResult) error

CrawlHandler is called for each page visited during crawling. Return a non-nil error to stop the crawl.

type CrawlOption 

type CrawlOption func(*crawlOptions)

CrawlOption configures crawl behavior.

func WithCrawlAllowedDomains 

func WithCrawlAllowedDomains(domains ...string) CrawlOption

WithCrawlAllowedDomains restricts crawling to the specified domains.

func WithCrawlConcurrent 

func WithCrawlConcurrent(n int) CrawlOption

WithCrawlConcurrent sets the number of concurrent pages for crawling. Default: 1.

func WithCrawlDelay 

func WithCrawlDelay(d time.Duration) CrawlOption

WithCrawlDelay sets the delay between page visits. Default: 500ms.

func WithCrawlJobManager 

func WithCrawlJobManager(m *AsyncJobManager) CrawlOption

WithCrawlJobManager attaches an async job manager to track crawl progress.

func WithCrawlMaxDepth 

func WithCrawlMaxDepth(n int) CrawlOption

WithCrawlMaxDepth sets the maximum crawl depth from the start URL. Default: 3.

func WithCrawlMaxPages 

func WithCrawlMaxPages(n int) CrawlOption

WithCrawlMaxPages sets the maximum number of pages to crawl. Default: 100.

type CrawlOutput 

type CrawlOutput struct {
	JobID   string // non-empty when WithCrawlJobManager is used
	Results []CrawlResult
}

CrawlOutput holds the overall results of a crawl, including a job ID when an AsyncJobManager is attached.

type CrawlReport added in v0.72.0 

type CrawlReport struct {
	URL      string   `json:"url"`
	Pages    int      `json:"pages"`
	Duration string   `json:"duration"`
	Links    []string `json:"links"`
	Errors   []string `json:"errors"`
}

CrawlReport holds the results of a site crawl for report rendering.

type CrawlResult 

type CrawlResult struct {
	URL   string
	Title string
	Depth int
	Links []string
	Error error
}

CrawlResult holds information about a crawled page.

type DOMChange 

type DOMChange struct {
	Type          string `json:"type"`
	Target        string `json:"target"`
	AddedNodes    int    `json:"addedNodes"`
	RemovedNodes  int    `json:"removedNodes"`
	AttributeName string `json:"attributeName,omitempty"`
	OldValue      string `json:"oldValue,omitempty"`
	Timestamp     int64  `json:"ts"`
}

DOMChange represents a DOM change event from the monitor.

type DOMChangeSummary 

type DOMChangeSummary struct {
	Added    int         `json:"added"`
	Removed  int         `json:"removed"`
	Modified int         `json:"modified"`
	Details  []DOMChange `json:"details"`
}

DOMChangeSummary is the periodic summary sent by the DOM monitor.

type DOMNode 

type DOMNode struct {
	Tag        string            `json:"tag"`
	Attributes map[string]string `json:"attributes,omitempty"`
	Children   []DOMNode         `json:"children,omitempty"`
	Text       string            `json:"text,omitempty"`
}

DOMNode represents a DOM node as a JSON tree.

type DOMOption 

type DOMOption func(*domOptions)

DOMOption configures DOM extraction via the bridge.

func WithDOMDepth 

func WithDOMDepth(n int) DOMOption

WithDOMDepth sets the maximum tree depth for JSON extraction.

func WithDOMMainOnly 

func WithDOMMainOnly() DOMOption

WithDOMMainOnly uses a heuristic to find the main content area (markdown only).

func WithDOMSelector 

func WithDOMSelector(s string) DOMOption

WithDOMSelector scopes extraction to elements matching the CSS selector.

type DOMSnapshot 

type DOMSnapshot struct {
	Tag      string        `json:"t"`
	ID       string        `json:"id,omitempty"`
	Class    string        `json:"cls,omitempty"`
	Value    string        `json:"v,omitempty"`
	Children []DOMSnapshot `json:"c,omitempty"`
}

DOMSnapshot represents a serialized DOM state for comparison.

type DOMSnapshotResult 

type DOMSnapshotResult struct {
	Snapshot *DOMSnapshot `json:"snapshot"`
	TS       int64        `json:"ts"`
}

DOMSnapshotResult wraps a snapshot with its capture timestamp.

type DirectProxy 

type DirectProxy = vpn.DirectProxy

type DirectProxyOption 

type DirectProxyOption = vpn.DirectProxyOption

type Element 

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

Element wraps a rod element with a simplified API.

func (*Element) Attribute 

func (e *Element) Attribute(name string) (string, bool, error)

Attribute returns the value of the named attribute. The bool return indicates whether the attribute exists.

func (*Element) BackgroundImage 

func (e *Element) BackgroundImage() ([]byte, error)

BackgroundImage returns the CSS background image data.

func (*Element) Blur 

func (e *Element) Blur() error

Blur removes focus from the element.

func (*Element) CanvasToImage 

func (e *Element) CanvasToImage(format string, quality float64) ([]byte, error)

CanvasToImage returns the image data of a canvas element.

func (*Element) Clear 

func (e *Element) Clear() error

Clear removes all text from the element by selecting all and replacing with empty string.

func (*Element) Click 

func (e *Element) Click() error

Click performs a left mouse click on the element.

Example 
package main

import (
	"fmt"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	b, err := scout.New(scout.WithHeadless(true))
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = b.Close() }()

	page, err := b.NewPage("https://example.com")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	_ = page.WaitLoad()

	el, err := page.Element("a")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	// Click the element.
	if err := el.Click(); err != nil {
		fmt.Println("error:", err)
		return
	}

	_ = page.WaitLoad()
	title, _ := page.Title()
	fmt.Println(title)
}

func (*Element) ContainsElement 

func (e *Element) ContainsElement(target *Element) (bool, error)

ContainsElement checks if the target element is equal to or inside this element.

func (*Element) Disabled 

func (e *Element) Disabled() (bool, error)

Disabled returns true if the element is disabled.

func (*Element) DoubleClick 

func (e *Element) DoubleClick() error

DoubleClick performs a double-click on the element.

func (*Element) Element 

func (e *Element) Element(selector string) (*Element, error)

Element finds the first child element matching the CSS selector.

func (*Element) ElementByText 

func (e *Element) ElementByText(selector, regex string) (*Element, error)

ElementByText finds the first child element matching the CSS selector whose text matches the regex.

func (*Element) ElementByXPath 

func (e *Element) ElementByXPath(xpath string) (*Element, error)

ElementByXPath finds the first child matching the XPath expression relative to this element.

func (*Element) Elements 

func (e *Element) Elements(selector string) ([]*Element, error)

Elements finds all child elements matching the CSS selector.

func (*Element) ElementsByXPath 

func (e *Element) ElementsByXPath(xpath string) ([]*Element, error)

ElementsByXPath finds all children matching the XPath expression relative to this element.

func (*Element) Equal 

func (e *Element) Equal(other *Element) (bool, error)

Equal checks if two elements refer to the same DOM node.

func (*Element) Eval 

func (e *Element) Eval(js string, args ...any) (*EvalResult, error)

Eval evaluates JavaScript with this element as `this`.

func (*Element) Extract 

func (e *Element) Extract(target any, _ ...ExtractOption) error

Extract populates a struct from the element's subtree using `scout:"selector"` tags.

func (*Element) Focus 

func (e *Element) Focus() error

Focus sets focus on the element.

func (*Element) Frame 

func (e *Element) Frame() (*Page, error)

Frame creates a Page that represents the iframe content.

func (*Element) GetXPath 

func (e *Element) GetXPath() (string, error)

GetXPath returns the XPath of the element.

func (*Element) HTML 

func (e *Element) HTML() (string, error)

HTML returns the outer HTML of the element.

func (*Element) Hover 

func (e *Element) Hover() error

Hover moves the mouse over the element.

func (*Element) Input 

func (e *Element) Input(text string) error

Input focuses the element and inputs the given text.

Example 
package main

import (
	"fmt"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	b, err := scout.New(scout.WithHeadless(true))
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = b.Close() }()

	page, err := b.NewPage("https://example.com")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	el, err := page.Element("input[type=text]")
	if err != nil {
		fmt.Println("not found")
		return
	}

	// Type text into the input field.
	if err := el.Input("hello world"); err != nil {
		fmt.Println("error:", err)
	}
}

func (*Element) InputColor 

func (e *Element) InputColor(color string) error

InputColor inputs a color value (e.g. "#ff0000") into a color input element.

func (*Element) InputTime 

func (e *Element) InputTime(t time.Time) error

InputTime inputs a time value into a date/time input element.

func (*Element) Interactable 

func (e *Element) Interactable() (bool, error)

Interactable returns true if the element can be interacted with.

func (*Element) Matches 

func (e *Element) Matches(selector string) (bool, error)

Matches checks if the element matches the CSS selector.

func (*Element) MoveMouseOut 

func (e *Element) MoveMouseOut() error

MoveMouseOut moves the mouse out of the element.

func (*Element) Next 

func (e *Element) Next() (*Element, error)

Next returns the next sibling element.

func (*Element) Parent 

func (e *Element) Parent() (*Element, error)

Parent returns the parent element.

func (*Element) Parents 

func (e *Element) Parents(selector string) ([]*Element, error)

Parents returns all ancestor elements matching the optional CSS selector. Pass empty string to match all ancestors.

func (*Element) Press 

func (e *Element) Press(key input.Key) error

Press simulates pressing a single key on the element.

func (*Element) Previous 

func (e *Element) Previous() (*Element, error)

Previous returns the previous sibling element.

func (*Element) Property 

func (e *Element) Property(name string) (string, error)

Property returns the value of a DOM property as a string.

func (*Element) Remove 

func (e *Element) Remove() error

Remove removes the element from the DOM.

func (*Element) Resource 

func (e *Element) Resource() ([]byte, error)

Resource returns the "src" content of the element (e.g. image data).

func (*Element) RightClick 

func (e *Element) RightClick() error

RightClick performs a right mouse click on the element.

func (*Element) RodElement 

func (e *Element) RodElement() *rodElement

RodElement returns the underlying rod.Element for advanced use cases.

func (*Element) Screenshot 

func (e *Element) Screenshot() ([]byte, error)

Screenshot captures a PNG screenshot of the element.

func (*Element) ScreenshotJPEG 

func (e *Element) ScreenshotJPEG(quality int) ([]byte, error)

ScreenshotJPEG captures a JPEG screenshot of the element with the given quality.

func (*Element) ScrollIntoView 

func (e *Element) ScrollIntoView() error

ScrollIntoView scrolls the element into the visible area.

func (*Element) SelectAllText 

func (e *Element) SelectAllText() error

SelectAllText selects all text in the element.

func (*Element) SelectOption 

func (e *Element) SelectOption(selectors ...string) error

SelectOption selects option elements in a <select> element by their text.

func (*Element) SelectOptionByCSS 

func (e *Element) SelectOptionByCSS(selectors ...string) error

SelectOptionByCSS selects option elements in a <select> element by CSS selector.

func (*Element) SelectText 

func (e *Element) SelectText(regex string) error

SelectText selects text matching the regex in the element.

func (*Element) SetFiles 

func (e *Element) SetFiles(paths []string) error

SetFiles sets the file paths for a file input element.

func (*Element) ShadowRoot 

func (e *Element) ShadowRoot() (*Element, error)

ShadowRoot returns the shadow root of this element.

func (*Element) Tap 

func (e *Element) Tap() error

Tap simulates a touch tap on the element.

func (*Element) Text 

func (e *Element) Text() (string, error)

Text returns the visible text content of the element.

func (*Element) Type 

func (e *Element) Type(keys ...input.Key) error

Type simulates keyboard key presses on the element.

func (*Element) Visible 

func (e *Element) Visible() (bool, error)

Visible returns true if the element is visible on the page.

func (*Element) WaitEnabled 

func (e *Element) WaitEnabled() error

WaitEnabled waits until the element is not disabled.

func (*Element) WaitInteractable 

func (e *Element) WaitInteractable() error

WaitInteractable waits for the element to become interactable.

func (*Element) WaitInvisible 

func (e *Element) WaitInvisible() error

WaitInvisible waits until the element becomes invisible.

func (*Element) WaitLoad 

func (e *Element) WaitLoad() error

WaitLoad waits for the element to finish loading (e.g. <img>).

func (*Element) WaitStable 

func (e *Element) WaitStable(d time.Duration) error

WaitStable waits until the element's shape stops changing for the given duration.

func (*Element) WaitStableRAF 

func (e *Element) WaitStableRAF() error

WaitStableRAF waits until the element's shape is stable for 2 animation frames.

func (*Element) WaitVisible 

func (e *Element) WaitVisible() error

WaitVisible waits until the element becomes visible.

func (*Element) WaitWritable 

func (e *Element) WaitWritable() error

WaitWritable waits until the element is not readonly.

type ElementNotFoundError 

type ElementNotFoundError struct{}

ElementNotFoundError error.

func (*ElementNotFoundError) Error 

func (e *ElementNotFoundError) Error() string

type Elements 

type Elements []*rodElement

Elements provides some helpers to deal with element list.

func (Elements) Empty 

func (els Elements) Empty() bool

Empty returns true if the list is empty.

func (Elements) First 

func (els Elements) First() *rodElement

First returns the first element, if the list is empty returns nil.

func (Elements) Last 

func (els Elements) Last() *rodElement

Last returns the last element, if the list is empty returns nil.

type EvalError 

type EvalError struct {
	*proto.RuntimeExceptionDetails
}

EvalError error.

func (*EvalError) Error 

func (e *EvalError) Error() string

func (*EvalError) Is 

func (e *EvalError) Is(err error) bool

Is interface.

type EvalOptions 

type EvalOptions struct {
	// If enabled the eval result will be a plain JSON value.
	// If disabled the eval result will be a reference of a remote js object.
	ByValue bool

	AwaitPromise bool

	// ThisObj represents the "this" object in the JS
	ThisObj *proto2.RuntimeRemoteObject

	// JS function definition to execute.
	JS string

	// JSArgs represents the arguments that will be passed to JS.
	// If an argument is [*proto.RuntimeRemoteObject] type, the corresponding remote object will be used.
	// Or it will be passed as a plain JSON value.
	// When an arg in the args is a *js.Function, the arg will be cached on the page's js context.
	// When the arg.Name exists in the page's cache, it reuse the cache without sending
	// the definition to the browser again.
	// Useful when you need to eval a huge js expression many times.
	JSArgs []any

	// Whether execution should be treated as initiated by user in the UI.
	UserGesture bool
}

EvalOptions for Page.Evaluate.

func Eval 

func Eval(js string, args ...any) *EvalOptions

Eval creates a EvalOptions with ByValue set to true.

func (*EvalOptions) ByObject 

func (e *EvalOptions) ByObject() *EvalOptions

ByObject disables ByValue.

func (*EvalOptions) ByPromise 

func (e *EvalOptions) ByPromise() *EvalOptions

ByPromise enables AwaitPromise.

func (*EvalOptions) ByUser 

func (e *EvalOptions) ByUser() *EvalOptions

ByUser enables UserGesture.

func (*EvalOptions) String 

func (e *EvalOptions) String() string

String interface.

func (*EvalOptions) This 

func (e *EvalOptions) This(obj *proto2.RuntimeRemoteObject) *EvalOptions

This set the obj as ThisObj.

type EvalResult 

type EvalResult struct {
	Type    string
	Subtype string
	Value   any
	// contains filtered or unexported fields
}

EvalResult wraps the result of a JavaScript evaluation.

func InjectTemplate 

func InjectTemplate(page *Page, tmplName string, data map[string]any) (*EvalResult, error)

InjectTemplate renders the named built-in template with data and evaluates it on the page, returning the result.

func (*EvalResult) Bool 

func (r *EvalResult) Bool() bool

Bool returns the result as a bool.

func (*EvalResult) Decode 

func (r *EvalResult) Decode(target any) error

Decode unmarshals the result into the provided target.

func (*EvalResult) Float 

func (r *EvalResult) Float() float64

Float returns the result as a float64.

func (*EvalResult) Int 

func (r *EvalResult) Int() int

Int returns the result as an int.

func (*EvalResult) IsNull 

func (r *EvalResult) IsNull() bool

IsNull returns true if the result is null or undefined.

func (*EvalResult) JSON 

func (r *EvalResult) JSON() []byte

JSON returns the raw JSON representation of the value.

func (*EvalResult) String 

func (r *EvalResult) String() string

String returns the result as a string.

type ExpectElementError 

type ExpectElementError struct {
	*proto.RuntimeRemoteObject
}

ExpectElementError error.

func (*ExpectElementError) Error 

func (e *ExpectElementError) Error() string

func (*ExpectElementError) Is 

func (e *ExpectElementError) Is(err error) bool

Is interface.

type ExpectElementsError 

type ExpectElementsError struct {
	*proto.RuntimeRemoteObject
}

ExpectElementsError error.

func (*ExpectElementsError) Error 

func (e *ExpectElementsError) Error() string

func (*ExpectElementsError) Is 

func (e *ExpectElementsError) Is(err error) bool

Is interface.

type ExtensionInfo 

type ExtensionInfo struct {
	ID      string `json:"id"`
	Name    string `json:"name"`
	Version string `json:"version"`
	Path    string `json:"path"`
}

ExtensionInfo holds metadata about a locally stored Chrome extension.

func DownloadExtension 

func DownloadExtension(id string) (*ExtensionInfo, error)

DownloadExtension downloads a Chrome extension by ID from the Chrome Web Store, unpacks the CRX3 file, and stores it in ~/.scout/extensions/<id>/.

func ListLocalExtensions 

func ListLocalExtensions() ([]ExtensionInfo, error)

ListLocalExtensions returns metadata for all extensions stored in ~/.scout/extensions/.

type ExtractOption 

type ExtractOption func(*extractOptions)

ExtractOption configures extraction behavior.

type ExtractionRequest 

type ExtractionRequest struct {
	Selectors     []string // CSS selectors for text extraction
	Attrs         []string // "selector@attr" specs
	TableSelector string   // CSS selector for table
	Links         bool     // Extract all links
	Meta          bool     // Extract metadata
}

ExtractionRequest configures what to extract from a page.

type ExtractionResult 

type ExtractionResult struct {
	URL       string              `json:"url"`
	Selectors map[string][]string `json:"selectors,omitempty"`
	Attrs     map[string][]string `json:"attrs,omitempty"`
	Table     *TableData          `json:"table,omitempty"`
	Links     []string            `json:"links,omitempty"`
	Meta      *MetaData           `json:"meta,omitempty"`
	Errors    []string            `json:"errors,omitempty"`
}

ExtractionResult holds all extracted data.

type Fingerprint 

type Fingerprint = fingerprint.Fingerprint

Fingerprint re-exports fingerprint.Fingerprint from sub-package.

type FingerprintOption 

type FingerprintOption = fingerprint.FingerprintOption

type FingerprintRotation 

type FingerprintRotation = fingerprint.FingerprintRotation

type FingerprintRotationConfig 

type FingerprintRotationConfig = fingerprint.FingerprintRotationConfig

type FingerprintStore 

type FingerprintStore = fingerprint.FingerprintStore

type Form 

type Form struct {
	Action string
	Method string
	Fields []FormField
	// contains filtered or unexported fields
}

Form represents a detected HTML form on the page.

func (*Form) CSRFToken 

func (f *Form) CSRFToken() (string, error)

CSRFToken attempts to find a CSRF token field in the form. It looks for hidden inputs with common CSRF field names.

func (*Form) Fill 

func (f *Form) Fill(data map[string]string) error

Fill fills form fields using a map of field name (or ID) to value.

Example 
package main

import (
	"fmt"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	b, err := scout.New(scout.WithHeadless(true))
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = b.Close() }()

	page, err := b.NewPage("https://example.com/login")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	_ = page.WaitLoad()

	// Detect a form by CSS selector, then fill fields by name/id.
	form, err := page.DetectForm("form#login")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	if err := form.Fill(map[string]string{
		"username": "alice",
		"password": "s3cret",
	}); err != nil {
		fmt.Println("error:", err)
		return
	}

	if err := form.Submit(); err != nil {
		fmt.Println("error:", err)
	}
}

func (*Form) FillStruct 

func (f *Form) FillStruct(data any) error

FillStruct fills form fields using struct tags: `form:"field_name"`.

func (*Form) Submit 

func (f *Form) Submit() error

Submit submits the form by clicking the submit button or triggering form submit via JS.

type FormField 

type FormField struct {
	Name        string
	Type        string
	ID          string
	Value       string
	Placeholder string
	Required    bool
	Options     []string // populated for <select> elements
}

FormField describes a single field within an HTML form.

type FormWizard 

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

FormWizard manages multi-step form workflows.

func (*FormWizard) Run 

func (w *FormWizard) Run() error

Run executes all steps of the form wizard sequentially.

type FrameworkInfo 

type FrameworkInfo = detect.FrameworkInfo

FrameworkInfo re-exports detect.FrameworkInfo from sub-package.

type GatherOption 

type GatherOption func(*gatherOptions)

GatherOption configures a Gather operation.

func WithGatherConsole 

func WithGatherConsole() GatherOption

WithGatherConsole captures console output during page load.

func WithGatherCookies 

func WithGatherCookies() GatherOption

WithGatherCookies includes page cookies.

func WithGatherFrameworks 

func WithGatherFrameworks() GatherOption

WithGatherFrameworks includes detected frontend frameworks.

func WithGatherHAR 

func WithGatherHAR() GatherOption

WithGatherHAR enables HAR recording during page load.

func WithGatherHTML 

func WithGatherHTML() GatherOption

WithGatherHTML includes raw HTML in the result. 

func WithGatherLinks() GatherOption

WithGatherLinks includes extracted links.

func WithGatherMarkdown 

func WithGatherMarkdown() GatherOption

WithGatherMarkdown includes markdown conversion in the result.

func WithGatherMeta 

func WithGatherMeta() GatherOption

WithGatherMeta includes page metadata (OG, Twitter, JSON-LD).

func WithGatherScreenshot 

func WithGatherScreenshot() GatherOption

WithGatherScreenshot includes a base64-encoded PNG screenshot.

func WithGatherSnapshot 

func WithGatherSnapshot() GatherOption

WithGatherSnapshot includes accessibility tree snapshot.

func WithGatherTimeout 

func WithGatherTimeout(d time.Duration) GatherOption

WithGatherTimeout sets the page load timeout. Default: 30s.

type GatherResult 

type GatherResult struct {
	URL         string          `json:"url"`
	Title       string          `json:"title"`
	Meta        *MetaData       `json:"meta,omitempty"`
	Links       []string        `json:"links,omitempty"`
	Cookies     []Cookie        `json:"cookies,omitempty"`
	HTML        string          `json:"html,omitempty"`
	Markdown    string          `json:"markdown,omitempty"`
	Snapshot    string          `json:"snapshot,omitempty"`
	Screenshot  string          `json:"screenshot,omitempty"` // base64-encoded PNG
	HAR         []byte          `json:"har,omitempty"`
	HAREntries  int             `json:"har_entries,omitempty"`
	Frameworks  []FrameworkInfo `json:"frameworks,omitempty"`
	PageInfo    *PageInfo       `json:"page_info,omitempty"`
	ConsoleLog  []string        `json:"console_log,omitempty"`
	Duration    string          `json:"duration"`
	CollectedAt time.Time       `json:"collected_at"`
}

GatherResult holds all data collected from a single page in one pass.

type GitHubCodeResult 

type GitHubCodeResult struct {
	Repo     string `json:"repo"`
	FilePath string `json:"file_path"`
	Snippet  string `json:"snippet"`
}

GitHubCodeResult holds a single code search result from GitHub.

type GitHubExtractIssue 

type GitHubExtractIssue struct {
	Number    int      `json:"number"`
	Title     string   `json:"title"`
	State     string   `json:"state"` // open, closed, merged
	Author    string   `json:"author"`
	Labels    []string `json:"labels"`
	CreatedAt string   `json:"created_at"`
	Body      string   `json:"body,omitempty"`
	Comments  int      `json:"comments"`
	IsPR      bool     `json:"is_pr"`
}

GitHubExtractIssue holds extracted issue/PR data with unified type.

type GitHubExtractOption 

type GitHubExtractOption func(*githubExtractOpts)

GitHubExtractOption configures extraction.

func WithGitHubExtractBody 

func WithGitHubExtractBody() GitHubExtractOption

WithGitHubExtractBody returns an option to include issue/PR/release body text.

func WithGitHubExtractMaxItems 

func WithGitHubExtractMaxItems(n int) GitHubExtractOption

WithGitHubExtractMaxItems limits items returned. Default: 25.

func WithGitHubExtractState 

func WithGitHubExtractState(state string) GitHubExtractOption

WithGitHubExtractState filters by state for issues/PRs: "open", "closed", "all". Default: "open".

func WithGitHubReadme 

func WithGitHubReadme() GitHubExtractOption

WithGitHubReadme returns an option to include README HTML for repo extraction.

type GitHubExtractRelease 

type GitHubExtractRelease struct {
	Tag         string   `json:"tag"`
	Name        string   `json:"name"`
	PublishedAt string   `json:"published_at"`
	Author      string   `json:"author"`
	Body        string   `json:"body,omitempty"`
	Assets      []string `json:"assets,omitempty"`
}

GitHubExtractRelease holds extracted release data.

type GitHubExtractRepo 

type GitHubExtractRepo struct {
	Owner       string   `json:"owner"`
	Name        string   `json:"name"`
	Description string   `json:"description"`
	Stars       int      `json:"stars"`
	Forks       int      `json:"forks"`
	Language    string   `json:"language"`
	Topics      []string `json:"topics"`
	License     string   `json:"license"`
	LastUpdated string   `json:"last_updated"`
	ReadmeHTML  string   `json:"readme_html,omitempty"`
}

GitHubExtractRepo holds extracted repository metadata (extended).

type GitHubIssue 

type GitHubIssue struct {
	Number    int      `json:"number"`
	Title     string   `json:"title"`
	State     string   `json:"state"`
	Author    string   `json:"author"`
	Labels    []string `json:"labels"`
	Body      string   `json:"body,omitempty"`
	CreatedAt string   `json:"created_at"`
}

GitHubIssue holds metadata about a GitHub issue.

type GitHubOption 

type GitHubOption func(*githubConfig)

GitHubOption configures GitHub extraction behavior.

func WithGitHubBody 

func WithGitHubBody() GitHubOption

WithGitHubBody includes the full body of issues and pull requests.

func WithGitHubMaxItems 

func WithGitHubMaxItems(n int) GitHubOption

WithGitHubMaxItems limits the number of items returned. Default: 30.

func WithGitHubMaxPages 

func WithGitHubMaxPages(n int) GitHubOption

WithGitHubMaxPages sets the maximum number of pages to fetch for paginated results. Default: 1.

func WithGitHubRepo 

func WithGitHubRepo(owner, repo string) GitHubOption

WithGitHubRepo scopes code search to a specific repository by appending repo:owner/name to the query.

func WithGitHubState 

func WithGitHubState(state string) GitHubOption

WithGitHubState filters issues/PRs by state: "open", "closed", or "all". Default: "open".

type GitHubPR 

type GitHubPR struct {
	Number    int      `json:"number"`
	Title     string   `json:"title"`
	State     string   `json:"state"`
	Author    string   `json:"author"`
	Labels    []string `json:"labels"`
	Body      string   `json:"body,omitempty"`
	CreatedAt string   `json:"created_at"`
}

GitHubPR holds metadata about a GitHub pull request.

type GitHubRelease 

type GitHubRelease struct {
	Tag    string `json:"tag"`
	Name   string `json:"name"`
	Body   string `json:"body"`
	Date   string `json:"date"`
	Assets int    `json:"assets"`
}

GitHubRelease holds metadata about a GitHub release.

type GitHubRepo 

type GitHubRepo struct {
	Owner       string   `json:"owner"`
	Name        string   `json:"name"`
	Description string   `json:"description"`
	Stars       int      `json:"stars"`
	Forks       int      `json:"forks"`
	Language    string   `json:"language"`
	Topics      []string `json:"topics"`
	License     string   `json:"license"`
	ReadmeMD    string   `json:"readme_md,omitempty"`
}

GitHubRepo holds metadata about a GitHub repository.

type GitHubUser 

type GitHubUser struct {
	Username    string `json:"username"`
	DisplayName string `json:"display_name"`
	Bio         string `json:"bio"`
	Location    string `json:"location"`
	Repos       int    `json:"repos"`
	Followers   int    `json:"followers"`
	Following   int    `json:"following"`
}

GitHubUser holds metadata about a GitHub user profile.

type HARContent 

type HARContent = hijack.HARContent

type HARCreator 

type HARCreator = hijack.HARCreator

type HAREntry 

type HAREntry = hijack.HAREntry

type HARHeader 

type HARHeader = hijack.HARHeader

type HARLog 

type HARLog = hijack.HARLog

HARLog re-exports hijack.HARLog from sub-package.

type HARPost 

type HARPost = hijack.HARPost

type HARQuery 

type HARQuery = hijack.HARQuery

type HARRequest 

type HARRequest = hijack.HARRequest

type HARResponse 

type HARResponse = hijack.HARResponse

type HARTimings 

type HARTimings = hijack.HARTimings

type HealthCheckOption 

type HealthCheckOption func(*healthCheckOptions)

HealthCheckOption configures a health check run.

func WithHealthClickElements 

func WithHealthClickElements() HealthCheckOption

WithHealthClickElements enables clicking interactive elements to discover JS errors. Default: false.

func WithHealthConcurrency 

func WithHealthConcurrency(n int) HealthCheckOption

WithHealthConcurrency sets concurrent page limit. Default: 3.

func WithHealthDepth 

func WithHealthDepth(n int) HealthCheckOption

WithHealthDepth sets maximum crawl depth for health checking. Default: 2.

func WithHealthTimeout 

func WithHealthTimeout(d time.Duration) HealthCheckOption

WithHealthTimeout sets overall health check timeout. Default: 60s.

type HealthIssue 

type HealthIssue struct {
	URL        string `json:"url"`
	Source     string `json:"source"`   // "link", "console", "network", "js_exception"
	Severity   string `json:"severity"` // "error", "warning", "info"
	Message    string `json:"message"`
	Location   string `json:"location,omitempty"`
	StatusCode int    `json:"status_code,omitempty"`
}

HealthIssue describes a single problem found during a health check.

type HealthReport 

type HealthReport struct {
	URL      string         `json:"url"`
	Pages    int            `json:"pages_checked"`
	Duration string         `json:"duration"`
	Issues   []HealthIssue  `json:"issues"`
	Summary  map[string]int `json:"summary"`
}

HealthReport summarizes the results of a site health check.

type Hijack 

type Hijack struct {
	Request  *rodHijackRequest
	Response *rodHijackResponse
	OnError  func(error)

	// Skip to next handler
	Skip bool

	// CustomState is used to store things for this context
	CustomState any
	// contains filtered or unexported fields
}

Hijack context.

func (*Hijack) ContinueRequest 

func (h *Hijack) ContinueRequest(cq *proto2.FetchContinueRequest)

ContinueRequest without hijacking. The RequestID will be set by the router, you don't have to set it.

func (*Hijack) LoadResponse 

func (h *Hijack) LoadResponse(client *http.Client, loadBody bool) error

LoadResponse will send request to the real destination and load the response as default response to override.

func (*Hijack) MustLoadResponse 

func (h *Hijack) MustLoadResponse()

MustLoadResponse is similar to Hijack.LoadResponse.

type HijackContext 

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

HijackContext provides access to the intercepted request and response.

func (*HijackContext) ContinueRequest 

func (c *HijackContext) ContinueRequest()

ContinueRequest forwards the request to the server without modification.

func (*HijackContext) LoadResponse 

func (c *HijackContext) LoadResponse(loadBody bool) error

LoadResponse sends the request to the server and loads the response.

func (*HijackContext) Request 

func (c *HijackContext) Request() *HijackRequest

Request returns the intercepted request.

func (*HijackContext) Response 

func (c *HijackContext) Response() *HijackResponse

Response returns the response that will be sent to the browser.

func (*HijackContext) Skip 

func (c *HijackContext) Skip()

Skip marks this handler to skip to the next matching handler.

type HijackEvent 

type HijackEvent = hijack.Event

type HijackEventType 

type HijackEventType = hijack.EventType

HijackEventType re-exports hijack.EventType from sub-package.

type HijackFilter 

type HijackFilter = hijack.Filter

type HijackHandler 

type HijackHandler func(*HijackContext)

HijackHandler is a function called for each intercepted request.

type HijackOption 

type HijackOption = hijack.Option

type HijackRecorder 

type HijackRecorder = hijack.Recorder

type HijackRequest 

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

HijackRequest provides read access to the intercepted request.

func (*HijackRequest) Body 

func (r *HijackRequest) Body() string

Body returns the request body as a string.

func (*HijackRequest) Header 

func (r *HijackRequest) Header(key string) string

Header returns the value of the given header.

func (*HijackRequest) Method 

func (r *HijackRequest) Method() string

Method returns the HTTP method of the request.

func (*HijackRequest) URL 

func (r *HijackRequest) URL() *url.URL

URL returns the URL of the request.

type HijackResponse 

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

HijackResponse provides write access to the response.

func (*HijackResponse) Body 

func (r *HijackResponse) Body() string

Body returns the response body as a string. Only available after LoadResponse(true).

func (*HijackResponse) Fail 

func (r *HijackResponse) Fail(reason proto2.NetworkErrorReason)

Fail sends an error response.

func (*HijackResponse) SetBody 

func (r *HijackResponse) SetBody(body any)

SetBody sets the response body. Accepts string, []byte, or any JSON-serializable value.

func (*HijackResponse) SetHeader 

func (r *HijackResponse) SetHeader(pairs ...string)

SetHeader sets a response header.

type HijackRouter 

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

HijackRouter manages request interception. Call Run() in a goroutine, then Stop() when done.

func (*HijackRouter) Run 

func (r *HijackRouter) Run()

Run starts the hijack router. This method blocks, so call it in a goroutine.

func (*HijackRouter) Stop 

func (r *HijackRouter) Stop() error

Stop stops the hijack router and disables request interception.

type InvisibleShapeError 

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

InvisibleShapeError error.

func (InvisibleShapeError) Attribute 

func (el InvisibleShapeError) Attribute(name string) (*string, error)

Attribute of the DOM object. Attribute vs Property: https://stackoverflow.com/questions/6003819/what-is-the-difference-between-properties-and-attributes-in-html

func (InvisibleShapeError) BackgroundImage 

func (el InvisibleShapeError) BackgroundImage() ([]byte, error)

BackgroundImage returns the css background-image of the element.

func (InvisibleShapeError) Blur 

func (el InvisibleShapeError) Blur() error

Blur removes focus from the element.

func (InvisibleShapeError) Call 

func (el InvisibleShapeError) Call(ctx context.Context, sessionID, methodName string, params any) (res []byte, err error)

Call implements the proto.Client.

func (InvisibleShapeError) CancelTimeout 

func (el InvisibleShapeError) CancelTimeout() *rodElement

CancelTimeout cancels the current timeout context and returns a clone with the parent context.

func (InvisibleShapeError) CanvasToImage 

func (el InvisibleShapeError) CanvasToImage(format string, quality float64) ([]byte, error)

CanvasToImage get image data of a canvas. The default format is image/png. The default quality is 0.92. doc: https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toDataURL

func (InvisibleShapeError) Click 

func (el InvisibleShapeError) Click(button proto2.InputMouseButton, clickCount int) error

Click will press then release the button just like a human. Before the action, it will try to scroll to the element, hover the mouse over it, wait until the it's interactable and enabled.

func (InvisibleShapeError) ContainsElement 

func (el InvisibleShapeError) ContainsElement(target *rodElement) (bool, error)

ContainsElement check if the target is equal or inside the element.

func (InvisibleShapeError) Context 

func (el InvisibleShapeError) Context(ctx context.Context) *rodElement

Context returns a clone with the specified ctx for chained sub-operations.

func (InvisibleShapeError) Describe 

func (el InvisibleShapeError) Describe(depth int, pierce bool) (*proto2.DOMNode, error)

Describe the current element. The depth is the maximum depth at which children should be retrieved, defaults to 1, use -1 for the entire subtree or provide an integer larger than 0. The pierce decides whether or not iframes and shadow roots should be traversed when returning the subtree. The returned proto.DOMNode.NodeID will always be empty, because NodeID is not stable (when proto.DOMDocumentUpdated is fired all NodeID on the page will be reassigned to another value) we don't recommend using the NodeID, instead, use the proto.DOMBackendNodeID to identify the element.

func (InvisibleShapeError) Disabled 

func (el InvisibleShapeError) Disabled() (bool, error)

Disabled checks if the element is disabled.

func (InvisibleShapeError) Element 

func (el InvisibleShapeError) Element(selector string) (*rodElement, error)

Element returns the first child that matches the css selector.

func (InvisibleShapeError) ElementByJS 

func (el InvisibleShapeError) ElementByJS(opts *EvalOptions) (*rodElement, error)

ElementByJS returns the element from the return value of the js.

func (InvisibleShapeError) ElementR 

func (el InvisibleShapeError) ElementR(selector, jsRegex string) (*rodElement, error)

ElementR returns the first child element that matches the css selector and its text matches the jsRegex.

func (InvisibleShapeError) ElementX 

func (el InvisibleShapeError) ElementX(xPath string) (*rodElement, error)

ElementX returns the first child that matches the XPath selector.

func (InvisibleShapeError) Elements 

func (el InvisibleShapeError) Elements(selector string) (Elements, error)

Elements returns all elements that match the css selector.

func (InvisibleShapeError) ElementsByJS 

func (el InvisibleShapeError) ElementsByJS(opts *EvalOptions) (Elements, error)

ElementsByJS returns the elements from the return value of the js.

func (InvisibleShapeError) ElementsX 

func (el InvisibleShapeError) ElementsX(xpath string) (Elements, error)

ElementsX returns all elements that match the XPath selector.

func (InvisibleShapeError) Equal 

func (el InvisibleShapeError) Equal(elm *rodElement) (bool, error)

Equal checks if the two elements are equal.

func (*InvisibleShapeError) Error 

func (e *InvisibleShapeError) Error() string

Error ...

func (InvisibleShapeError) Eval 

func (el InvisibleShapeError) Eval(js string, params ...any) (*proto2.RuntimeRemoteObject, error)

Eval is a shortcut for [Element.Evaluate] with AwaitPromise, ByValue and AutoExp set to true.

func (InvisibleShapeError) Evaluate 

func (el InvisibleShapeError) Evaluate(opts *EvalOptions) (*proto2.RuntimeRemoteObject, error)

Evaluate is just a shortcut of [Page.Evaluate] with This set to current element.

func (InvisibleShapeError) Focus 

func (el InvisibleShapeError) Focus() error

Focus sets focus on the specified element. Before the action, it will try to scroll to the element.

func (InvisibleShapeError) Frame 

func (el InvisibleShapeError) Frame() (*rodPage, error)

Frame creates a page instance that represents the iframe.

func (InvisibleShapeError) GetContext 

func (el InvisibleShapeError) GetContext() context.Context

GetContext of current instance.

func (InvisibleShapeError) GetSessionID 

func (el InvisibleShapeError) GetSessionID() proto2.TargetSessionID

GetSessionID interface.

func (InvisibleShapeError) GetXPath 

func (el InvisibleShapeError) GetXPath(optimized bool) (string, error)

GetXPath returns the xpath of the element.

func (InvisibleShapeError) HTML 

func (el InvisibleShapeError) HTML() (string, error)

HTML of the element.

func (InvisibleShapeError) Has 

func (el InvisibleShapeError) Has(selector string) (bool, *rodElement, error)

Has an element that matches the css selector.

func (InvisibleShapeError) HasR 

func (el InvisibleShapeError) HasR(selector, jsRegex string) (bool, *rodElement, error)

HasR returns true if a child element that matches the css selector and its text matches the jsRegex.

func (InvisibleShapeError) HasX 

func (el InvisibleShapeError) HasX(selector string) (bool, *rodElement, error)

HasX an element that matches the XPath selector.

func (InvisibleShapeError) Hover 

func (el InvisibleShapeError) Hover() error

Hover the mouse over the center of the element. Before the action, it will try to scroll to the element and wait until it's interactable.

func (InvisibleShapeError) Input 

func (el InvisibleShapeError) Input(text string) error

Input focuses on the element and input text to it. Before the action, it will scroll to the element, wait until it's visible, enabled and writable. To empty the input you can use something like 

el.SelectAllText().MustInput("")

func (InvisibleShapeError) InputColor 

func (el InvisibleShapeError) InputColor(color string) error

InputColor focuses on the element and inputs a color string to it. Before the action, it will scroll to the element, wait until it's visible, enabled and writable.

func (InvisibleShapeError) InputTime 

func (el InvisibleShapeError) InputTime(t time.Time) error

InputTime focuses on the element and input time to it. Before the action, it will scroll to the element, wait until it's visible, enabled and writable. It will wait until the element is visible, enabled and writable.

func (InvisibleShapeError) Interactable 

func (el InvisibleShapeError) Interactable() (pt *proto2.Point, err error)

Interactable checks if the element is interactable with cursor. The cursor can be mouse, finger, stylus, etc. If not interactable err will be ErrNotInteractable, such as when covered by a modal,.

func (*InvisibleShapeError) Is 

func (e *InvisibleShapeError) Is(err error) bool

Is interface.

func (InvisibleShapeError) KeyActions 

func (el InvisibleShapeError) KeyActions() (*KeyActions, error)

KeyActions is similar with Page.KeyActions. Before the action, it will try to scroll to the element and focus on it.

func (InvisibleShapeError) Matches 

func (el InvisibleShapeError) Matches(selector string) (bool, error)

Matches checks if the element can be selected by the css selector.

func (InvisibleShapeError) MoveMouseOut 

func (el InvisibleShapeError) MoveMouseOut() error

MoveMouseOut of the current element.

func (InvisibleShapeError) MustAttribute 

func (el InvisibleShapeError) MustAttribute(name string) *string

MustAttribute is similar to Element.Attribute.

func (InvisibleShapeError) MustBackgroundImage 

func (el InvisibleShapeError) MustBackgroundImage() []byte

MustBackgroundImage is similar to Element.BackgroundImage.

func (InvisibleShapeError) MustBlur 

func (el InvisibleShapeError) MustBlur() *rodElement

MustBlur is similar to Element.Blur.

func (InvisibleShapeError) MustCanvasToImage 

func (el InvisibleShapeError) MustCanvasToImage() []byte

MustCanvasToImage is similar to Element.CanvasToImage.

func (InvisibleShapeError) MustClick 

func (el InvisibleShapeError) MustClick() *rodElement

MustClick is similar to Element.Click.

func (InvisibleShapeError) MustContainsElement 

func (el InvisibleShapeError) MustContainsElement(target *rodElement) bool

MustContainsElement is similar to Element.ContainsElement.

func (InvisibleShapeError) MustDescribe 

func (el InvisibleShapeError) MustDescribe() *proto2.DOMNode

MustDescribe is similar to [Element.Describe].

func (InvisibleShapeError) MustDisabled 

func (el InvisibleShapeError) MustDisabled() bool

MustDisabled is similar to Element.Disabled.

func (InvisibleShapeError) MustDoubleClick 

func (el InvisibleShapeError) MustDoubleClick() *rodElement

MustDoubleClick is similar to Element.Click.

func (InvisibleShapeError) MustElement 

func (el InvisibleShapeError) MustElement(selector string) *rodElement

MustElement is similar to Element.Element.

func (InvisibleShapeError) MustElementByJS 

func (el InvisibleShapeError) MustElementByJS(js string, params ...any) *rodElement

MustElementByJS is similar to [Element.ElementByJS].

func (InvisibleShapeError) MustElementR 

func (el InvisibleShapeError) MustElementR(selector, regex string) *rodElement

MustElementR is similar to [Element.ElementR].

func (InvisibleShapeError) MustElementX 

func (el InvisibleShapeError) MustElementX(xpath string) *rodElement

MustElementX is similar to [Element.ElementX].

func (InvisibleShapeError) MustElements 

func (el InvisibleShapeError) MustElements(selector string) Elements

MustElements is similar to Element.Elements.

func (InvisibleShapeError) MustElementsByJS 

func (el InvisibleShapeError) MustElementsByJS(js string, params ...any) Elements

MustElementsByJS is similar to [Element.ElementsByJS].

func (InvisibleShapeError) MustElementsX 

func (el InvisibleShapeError) MustElementsX(xpath string) Elements

MustElementsX is similar to [Element.ElementsX].

func (InvisibleShapeError) MustEqual 

func (el InvisibleShapeError) MustEqual(elm *rodElement) bool

MustEqual is similar to Element.Equal.

func (InvisibleShapeError) MustEval 

func (el InvisibleShapeError) MustEval(js string, params ...any) gson.JSON

MustEval is similar to Element.Eval.

func (InvisibleShapeError) MustFocus 

func (el InvisibleShapeError) MustFocus() *rodElement

MustFocus is similar to Element.Focus.

func (InvisibleShapeError) MustFrame 

func (el InvisibleShapeError) MustFrame() *rodPage

MustFrame is similar to Element.Frame.

func (InvisibleShapeError) MustGetXPath 

func (el InvisibleShapeError) MustGetXPath(optimized bool) string

MustGetXPath is similar to Element.GetXPath.

func (InvisibleShapeError) MustHTML 

func (el InvisibleShapeError) MustHTML() string

MustHTML is similar to Element.HTML.

func (InvisibleShapeError) MustHas 

func (el InvisibleShapeError) MustHas(selector string) bool

MustHas is similar to [Element.Has].

func (InvisibleShapeError) MustHasR 

func (el InvisibleShapeError) MustHasR(selector, regex string) bool

MustHasR is similar to [Element.HasR].

func (InvisibleShapeError) MustHasX 

func (el InvisibleShapeError) MustHasX(selector string) bool

MustHasX is similar to [Element.HasX].

func (InvisibleShapeError) MustHover 

func (el InvisibleShapeError) MustHover() *rodElement

MustHover is similar to Element.Hover.

func (InvisibleShapeError) MustInput 

func (el InvisibleShapeError) MustInput(text string) *rodElement

MustInput is similar to Element.Input.

func (InvisibleShapeError) MustInputColor 

func (el InvisibleShapeError) MustInputColor(color string) *rodElement

MustInputColor is similar to Element.InputColor.

func (InvisibleShapeError) MustInputTime 

func (el InvisibleShapeError) MustInputTime(t time.Time) *rodElement

MustInputTime is similar to Element.Input.

func (InvisibleShapeError) MustInteractable 

func (el InvisibleShapeError) MustInteractable() bool

MustInteractable is similar to Element.Interactable.

func (InvisibleShapeError) MustKeyActions 

func (el InvisibleShapeError) MustKeyActions() *KeyActions

MustKeyActions is similar to [Element.KeyActions].

func (InvisibleShapeError) MustMatches 

func (el InvisibleShapeError) MustMatches(selector string) bool

MustMatches is similar to Element.Matches.

func (InvisibleShapeError) MustMoveMouseOut 

func (el InvisibleShapeError) MustMoveMouseOut() *rodElement

MustMoveMouseOut is similar to Element.MoveMouseOut.

func (InvisibleShapeError) MustNext 

func (el InvisibleShapeError) MustNext() *rodElement

MustNext is similar to Element.Next.

func (InvisibleShapeError) MustParent 

func (el InvisibleShapeError) MustParent() *rodElement

MustParent is similar to Element.Parent.

func (InvisibleShapeError) MustParents 

func (el InvisibleShapeError) MustParents(selector string) Elements

MustParents is similar to Element.Parents.

func (InvisibleShapeError) MustPrevious 

func (el InvisibleShapeError) MustPrevious() *rodElement

MustPrevious is similar to Element.Previous.

func (InvisibleShapeError) MustProperty 

func (el InvisibleShapeError) MustProperty(name string) gson.JSON

MustProperty is similar to Element.Property.

func (InvisibleShapeError) MustRelease 

func (el InvisibleShapeError) MustRelease()

MustRelease is similar to [Element.Release].

func (InvisibleShapeError) MustRemove 

func (el InvisibleShapeError) MustRemove()

MustRemove is similar to Element.Remove.

func (InvisibleShapeError) MustResource 

func (el InvisibleShapeError) MustResource() []byte

MustResource is similar to Element.Resource.

func (InvisibleShapeError) MustScreenshot 

func (el InvisibleShapeError) MustScreenshot(toFile ...string) []byte

MustScreenshot is similar to Element.Screenshot.

func (InvisibleShapeError) MustScrollIntoView 

func (el InvisibleShapeError) MustScrollIntoView() *rodElement

MustScrollIntoView is similar to Element.ScrollIntoView.

func (InvisibleShapeError) MustSelect 

func (el InvisibleShapeError) MustSelect(selectors ...string) *rodElement

MustSelect is similar to [Element.Select].

func (InvisibleShapeError) MustSelectAllText 

func (el InvisibleShapeError) MustSelectAllText() *rodElement

MustSelectAllText is similar to Element.SelectAllText.

func (InvisibleShapeError) MustSelectText 

func (el InvisibleShapeError) MustSelectText(regex string) *rodElement

MustSelectText is similar to Element.SelectText.

func (InvisibleShapeError) MustSetFiles 

func (el InvisibleShapeError) MustSetFiles(paths ...string) *rodElement

MustSetFiles is similar to Element.SetFiles.

func (InvisibleShapeError) MustShadowRoot 

func (el InvisibleShapeError) MustShadowRoot() *rodElement

MustShadowRoot is similar to Element.ShadowRoot.

func (InvisibleShapeError) MustShape 

func (el InvisibleShapeError) MustShape() *proto2.DOMGetContentQuadsResult

MustShape is similar to [Element.Shape].

func (InvisibleShapeError) MustTap 

func (el InvisibleShapeError) MustTap() *rodElement

MustTap is similar to Element.Tap.

func (InvisibleShapeError) MustText 

func (el InvisibleShapeError) MustText() string

MustText is similar to Element.Text.

func (InvisibleShapeError) MustType 

func (el InvisibleShapeError) MustType(keys ...input.Key) *rodElement

MustType is similar to Element.Type.

func (InvisibleShapeError) MustVisible 

func (el InvisibleShapeError) MustVisible() bool

MustVisible is similar to Element.Visible.

func (InvisibleShapeError) MustWait 

func (el InvisibleShapeError) MustWait(js string, params ...any) *rodElement

MustWait is similar to [Element.Wait].

func (InvisibleShapeError) MustWaitEnabled 

func (el InvisibleShapeError) MustWaitEnabled() *rodElement

MustWaitEnabled is similar to Element.WaitEnabled.

func (InvisibleShapeError) MustWaitInteractable 

func (el InvisibleShapeError) MustWaitInteractable() *rodElement

MustWaitInteractable is similar to Element.WaitInteractable.

func (InvisibleShapeError) MustWaitInvisible 

func (el InvisibleShapeError) MustWaitInvisible() *rodElement

MustWaitInvisible is similar to Element.WaitInvisible..

func (InvisibleShapeError) MustWaitLoad 

func (el InvisibleShapeError) MustWaitLoad() *rodElement

MustWaitLoad is similar to Element.WaitLoad.

func (InvisibleShapeError) MustWaitStable 

func (el InvisibleShapeError) MustWaitStable() *rodElement

MustWaitStable is similar to Element.WaitStable.

func (InvisibleShapeError) MustWaitVisible 

func (el InvisibleShapeError) MustWaitVisible() *rodElement

MustWaitVisible is similar to Element.WaitVisible.

func (InvisibleShapeError) MustWaitWritable 

func (el InvisibleShapeError) MustWaitWritable() *rodElement

MustWaitWritable is similar to Element.WaitWritable.

func (InvisibleShapeError) Next 

func (el InvisibleShapeError) Next() (*rodElement, error)

Next returns the next sibling element in the DOM tree.

func (InvisibleShapeError) Overlay 

func (el InvisibleShapeError) Overlay(msg string) (removeOverlay func())

Overlay msg on the element.

func (InvisibleShapeError) Page 

func (el InvisibleShapeError) Page() *rodPage

Page of the element.

func (InvisibleShapeError) Parent 

func (el InvisibleShapeError) Parent() (*rodElement, error)

Parent returns the parent element in the DOM tree.

func (InvisibleShapeError) Parents 

func (el InvisibleShapeError) Parents(selector string) (Elements, error)

Parents that match the selector.

func (InvisibleShapeError) Previous 

func (el InvisibleShapeError) Previous() (*rodElement, error)

Previous returns the previous sibling element in the DOM tree.

func (InvisibleShapeError) Property 

func (el InvisibleShapeError) Property(name string) (gson.JSON, error)

Property of the DOM object. Property vs Attribute: https://stackoverflow.com/questions/6003819/what-is-the-difference-between-properties-and-attributes-in-html

func (InvisibleShapeError) Release 

func (el InvisibleShapeError) Release() error

Release is a shortcut for [Page.Release] current element.

func (InvisibleShapeError) Remove 

func (el InvisibleShapeError) Remove() error

Remove the element from the page.

func (InvisibleShapeError) Resource 

func (el InvisibleShapeError) Resource() ([]byte, error)

Resource returns the "src" content of current element. Such as the jpg of <img src="a.jpg">.

func (InvisibleShapeError) Screenshot 

func (el InvisibleShapeError) Screenshot(format proto2.PageCaptureScreenshotFormat, quality int) ([]byte, error)

Screenshot of the area of the element.

func (InvisibleShapeError) ScrollIntoView 

func (el InvisibleShapeError) ScrollIntoView() error

ScrollIntoView scrolls the current element into the visible area of the browser window if it's not already within the visible area.

func (InvisibleShapeError) Select 

func (el InvisibleShapeError) Select(selectors []string, selected bool, t SelectorType) error

Select the children option elements that match the selectors. Before the action, it will scroll to the element, wait until it's visible. If no option matches the selectors, it will return [ErrElementNotFound].

func (InvisibleShapeError) SelectAllText 

func (el InvisibleShapeError) SelectAllText() error

SelectAllText selects all text Before the action, it will try to scroll to the element and focus on it.

func (InvisibleShapeError) SelectText 

func (el InvisibleShapeError) SelectText(regex string) error

SelectText selects the text that matches the regular expression. Before the action, it will try to scroll to the element and focus on it.

func (InvisibleShapeError) SetFiles 

func (el InvisibleShapeError) SetFiles(paths []string) error

SetFiles of the current file input element.

func (InvisibleShapeError) ShadowRoot 

func (el InvisibleShapeError) ShadowRoot() (*rodElement, error)

ShadowRoot returns the shadow root of this element.

func (InvisibleShapeError) Shape 

func (el InvisibleShapeError) Shape() (*proto2.DOMGetContentQuadsResult, error)

Shape of the DOM element content. The shape is a group of 4-sides polygons. A 4-sides polygon is not necessary a rectangle. 4-sides polygons can be apart from each other. For example, we use 2 4-sides polygons to describe the shape below: 

  ____________          ____________
 /        ___/    =    /___________/    +     _________
/________/                                   /________/

func (InvisibleShapeError) Sleeper 

func (el InvisibleShapeError) Sleeper(sleeper func() utils.Sleeper) *rodElement

Sleeper returns a clone with the specified sleeper for chained sub-operations.

func (InvisibleShapeError) String 

func (el InvisibleShapeError) String() string

String interface.

func (InvisibleShapeError) Tap 

func (el InvisibleShapeError) Tap() error

Tap will scroll to the button and tap it just like a human. Before the action, it will try to scroll to the element and wait until it's interactable and enabled.

func (InvisibleShapeError) Text 

func (el InvisibleShapeError) Text() (string, error)

Text that the element displays.

func (InvisibleShapeError) Timeout 

func (el InvisibleShapeError) Timeout(d time.Duration) *rodElement

Timeout returns a clone with the specified total timeout of all chained sub-operations.

func (InvisibleShapeError) Type 

func (el InvisibleShapeError) Type(keys ...input.Key) error

Type is similar with Keyboard.Type. Before the action, it will try to scroll to the element and focus on it.

func (*InvisibleShapeError) Unwrap 

func (e *InvisibleShapeError) Unwrap() error

Unwrap ...

func (InvisibleShapeError) Visible 

func (el InvisibleShapeError) Visible() (bool, error)

Visible returns true if the element is visible on the page.

func (InvisibleShapeError) Wait 

func (el InvisibleShapeError) Wait(opts *EvalOptions) error

Wait until the js returns true.

func (InvisibleShapeError) WaitEnabled 

func (el InvisibleShapeError) WaitEnabled() error

WaitEnabled until the element is not disabled. Doc for readonly: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/readonly

func (InvisibleShapeError) WaitInteractable 

func (el InvisibleShapeError) WaitInteractable() (pt *proto2.Point, err error)

WaitInteractable waits for the element to be interactable. It will try to scroll to the element on each try.

func (InvisibleShapeError) WaitInvisible 

func (el InvisibleShapeError) WaitInvisible() error

WaitInvisible until the element invisible.

func (InvisibleShapeError) WaitLoad 

func (el InvisibleShapeError) WaitLoad() error

WaitLoad for element like <img>.

func (InvisibleShapeError) WaitStable 

func (el InvisibleShapeError) WaitStable(d time.Duration) error

WaitStable waits until no shape or position change for d duration. Be careful, d is not the max wait timeout, it's the least stable time. If you want to set a timeout you can use the [Element.Timeout] function.

func (InvisibleShapeError) WaitStableRAF 

func (el InvisibleShapeError) WaitStableRAF() error

WaitStableRAF waits until no shape or position change for 2 consecutive animation frames. If you want to wait animation that is triggered by JS not CSS, you'd better use Element.WaitStable. About animation frame: https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame

func (InvisibleShapeError) WaitVisible 

func (el InvisibleShapeError) WaitVisible() error

WaitVisible until the element is visible.

func (InvisibleShapeError) WaitWritable 

func (el InvisibleShapeError) WaitWritable() error

WaitWritable until the element is not readonly. Doc for disabled: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/disabled

func (InvisibleShapeError) WithCancel 

func (el InvisibleShapeError) WithCancel() (*rodElement, func())

WithCancel returns a clone with a context cancel function.

func (InvisibleShapeError) WithPanic 

func (el InvisibleShapeError) WithPanic(fail func(any)) *rodElement

WithPanic returns an element clone with the specified panic function. The fail must stop the current goroutine's execution immediately, such as use runtime.Goexit or panic inside it.

type JobIndex 

type JobIndex = llm.JobIndex

type JobRef 

type JobRef = llm.JobRef

type JobStatus 

type JobStatus = llm.JobStatus

type KeyAction 

type KeyAction struct {
	Type KeyActionType
	Key  input2.Key
}

KeyAction to perform.

type KeyActionType 

type KeyActionType int

KeyActionType enum. 

const (
	KeyActionPress KeyActionType = iota
	KeyActionRelease
	KeyActionTypeKey
)

KeyActionTypes.

type KeyActions 

type KeyActions struct {
	Actions []KeyAction
	// contains filtered or unexported fields
}

KeyActions to simulate.

func (*KeyActions) Do 

func (ka *KeyActions) Do() (err error)

Do the actions.

func (*KeyActions) MustDo 

func (ka *KeyActions) MustDo()

MustDo is similar to KeyActions.Do.

func (*KeyActions) Press 

func (ka *KeyActions) Press(keys ...input2.Key) *KeyActions

Press keys is guaranteed to have a release at the end of actions.

func (*KeyActions) Release 

func (ka *KeyActions) Release(keys ...input2.Key) *KeyActions

Release keys.

func (*KeyActions) Type 

func (ka *KeyActions) Type(keys ...input2.Key) *KeyActions

Type will release the key immediately after the pressing.

type Keyboard 

type Keyboard struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Keyboard represents the keyboard on a page, it's always related the main frame.

func (*Keyboard) MustType 

func (k *Keyboard) MustType(key ...input.Key) *Keyboard

MustType is similar to Keyboard.Type.

func (*Keyboard) Press 

func (k *Keyboard) Press(key input2.Key) error

Press the key down. To input characters that are not on the keyboard, such as Chinese or Japanese, you should use method like [Page.InsertText].

func (*Keyboard) Release 

func (k *Keyboard) Release(key input2.Key) error

Release the key.

func (*Keyboard) Type 

func (k *Keyboard) Type(keys ...input2.Key) (err error)

Type releases the key after the press.

type KnowledgeOption 

type KnowledgeOption func(*knowledgeOptions)

KnowledgeOption configures a Knowledge operation.

func WithKnowledgeConcurrency 

func WithKnowledgeConcurrency(n int) KnowledgeOption

WithKnowledgeConcurrency sets concurrent page processing. Default: 1.

func WithKnowledgeDepth 

func WithKnowledgeDepth(n int) KnowledgeOption

WithKnowledgeDepth sets the BFS crawl depth. Default: 3.

func WithKnowledgeMaxPages 

func WithKnowledgeMaxPages(n int) KnowledgeOption

WithKnowledgeMaxPages sets the maximum pages to visit. Default: 100.

func WithKnowledgeOutput 

func WithKnowledgeOutput(dir string) KnowledgeOption

WithKnowledgeOutput sets the output directory for streaming pages to disk.

func WithKnowledgeTimeout 

func WithKnowledgeTimeout(d time.Duration) KnowledgeOption

WithKnowledgeTimeout sets per-page timeout. Default: 30s.

type KnowledgePage 

type KnowledgePage struct {
	URL        string          `json:"url"`
	Title      string          `json:"title"`
	Depth      int             `json:"depth"`
	Markdown   string          `json:"markdown"`
	HTML       string          `json:"html"`
	Links      []string        `json:"links"`
	Meta       *MetaData       `json:"meta,omitempty"`
	Cookies    []Cookie        `json:"cookies"`
	Screenshot string          `json:"screenshot"`
	Snapshot   string          `json:"snapshot"`
	HAR        []byte          `json:"har,omitempty"`
	HAREntries int             `json:"har_entries"`
	Frameworks []FrameworkInfo `json:"frameworks"`
	PageInfo   *PageInfo       `json:"page_info,omitempty"`
	ConsoleLog []string        `json:"console_log"`
	Swagger    *SwaggerSpec    `json:"swagger,omitempty"`
	PDF        []byte          `json:"pdf,omitempty"`
	Error      string          `json:"error,omitempty"`
}

KnowledgePage holds all intelligence collected from a single page.

type KnowledgeResult 

type KnowledgeResult struct {
	URL       string           `json:"url"`
	Domain    string           `json:"domain"`
	CrawledAt time.Time        `json:"crawled_at"`
	Duration  string           `json:"duration"`
	TechStack *TechStack       `json:"tech_stack,omitempty"`
	Sitemap   []SitemapURL     `json:"sitemap,omitempty"`
	Pages     []KnowledgePage  `json:"pages"`
	Summary   KnowledgeSummary `json:"summary"`
}

KnowledgeResult holds the complete knowledge collection for a site.

type KnowledgeSummary 

type KnowledgeSummary struct {
	PagesTotal   int           `json:"pages_total"`
	PagesSuccess int           `json:"pages_success"`
	PagesFailed  int           `json:"pages_failed"`
	UniqueLinks  int           `json:"unique_links"`
	Issues       []HealthIssue `json:"issues,omitempty"`
}

KnowledgeSummary provides aggregate stats for the knowledge collection.

type KnowledgeWriter 

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

KnowledgeWriter streams knowledge pages to a structured directory.

func NewKnowledgeWriter 

func NewKnowledgeWriter(dir string) *KnowledgeWriter

NewKnowledgeWriter creates a writer for the given output directory.

func (*KnowledgeWriter) Init 

func (w *KnowledgeWriter) Init() error

Init creates the directory structure.

func (*KnowledgeWriter) WriteManifest 

func (w *KnowledgeWriter) WriteManifest(result *KnowledgeResult) error

WriteManifest writes the KnowledgeResult (minus page content) as manifest.json.

func (*KnowledgeWriter) WritePage 

func (w *KnowledgeWriter) WritePage(kp *KnowledgePage) error

WritePage writes a single page's data to the directory structure.

type LLMJob 

type LLMJob = llm.Job

type LLMJobResult 

type LLMJobResult = llm.JobResult

type LLMOption 

type LLMOption func(*llmOptions)

LLMOption configures LLM extraction behavior.

func WithLLMMainContent 

func WithLLMMainContent() LLMOption

WithLLMMainContent uses MarkdownContent() (main content only) instead of Markdown().

func WithLLMMaxTokens 

func WithLLMMaxTokens(n int) LLMOption

WithLLMMaxTokens sets the maximum number of tokens in the response.

func WithLLMMetadata 

func WithLLMMetadata(key, value string) LLMOption

WithLLMMetadata adds a key-value metadata pair to the job.

func WithLLMModel 

func WithLLMModel(model string) LLMOption

WithLLMModel overrides the provider's default model.

func WithLLMProvider 

func WithLLMProvider(p LLMProvider) LLMOption

WithLLMProvider sets the LLM provider to use.

func WithLLMReview 

func WithLLMReview(provider LLMProvider) LLMOption

WithLLMReview sets a review provider that validates the extraction output.

func WithLLMReviewModel 

func WithLLMReviewModel(model string) LLMOption

WithLLMReviewModel overrides the review provider's default model.

func WithLLMReviewPrompt 

func WithLLMReviewPrompt(prompt string) LLMOption

WithLLMReviewPrompt overrides the default review system prompt.

func WithLLMSchema 

func WithLLMSchema(schema json.RawMessage) LLMOption

WithLLMSchema sets a JSON schema for response validation.

func WithLLMSessionID 

func WithLLMSessionID(id string) LLMOption

WithLLMSessionID sets the session ID for job tracking.

func WithLLMSystemPrompt 

func WithLLMSystemPrompt(s string) LLMOption

WithLLMSystemPrompt overrides the default system prompt.

func WithLLMTemperature 

func WithLLMTemperature(t float64) LLMOption

WithLLMTemperature sets the sampling temperature (0.0–1.0).

func WithLLMTimeout 

func WithLLMTimeout(d time.Duration) LLMOption

WithLLMTimeout sets the timeout for the LLM request.

func WithLLMWorkspace 

func WithLLMWorkspace(ws *LLMWorkspace) LLMOption

WithLLMWorkspace sets a workspace for persisting jobs to disk.

type LLMProvider 

type LLMProvider = llm.Provider

LLMProvider re-exports llm.Provider from sub-package.

type LLMSession 

type LLMSession = llm.Session

type LLMWorkspace 

type LLMWorkspace = llm.Workspace

type ManagedPagePool added in v0.72.0 

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

ManagedPagePool manages a fixed-size pool of browser pages for concurrent scraping. Unlike the low-level Pool[Page] from utils.go, ManagedPagePool pre-creates real browser pages and handles lifecycle (state reset on release, cleanup on close).

func NewManagedPagePool added in v0.72.0 

func NewManagedPagePool(browser *Browser, size int) (*ManagedPagePool, error)

NewManagedPagePool creates a pool of reusable browser pages. It pre-creates size pages so they are ready for immediate use. Returns an error if any page fails to be created; already-created pages are cleaned up on failure.

func (*ManagedPagePool) Acquire added in v0.72.0 

func (pp *ManagedPagePool) Acquire(ctx context.Context) (*Page, error)

Acquire retrieves a page from the pool. It blocks until a page becomes available or the context is cancelled.

func (*ManagedPagePool) Available added in v0.72.0 

func (pp *ManagedPagePool) Available() int

Available returns the number of pages currently available in the pool.

func (*ManagedPagePool) Close added in v0.72.0 

func (pp *ManagedPagePool) Close()

Close closes all pages currently in the pool and marks the pool as closed. Pages that are currently acquired will be closed when they are released.

func (*ManagedPagePool) Release added in v0.72.0 

func (pp *ManagedPagePool) Release(page *Page)

Release returns a page to the pool after navigating it to about:blank to reset its state.

func (*ManagedPagePool) Size added in v0.72.0 

func (pp *ManagedPagePool) Size() int

Size returns the total number of pages the pool was created with.

type MapOption 

type MapOption func(*mapOptions)

MapOption configures URL map/link discovery behavior.

func WithMapDelay 

func WithMapDelay(d time.Duration) MapOption

WithMapDelay sets the delay between page visits. Default: 200ms.

func WithMapExcludePaths 

func WithMapExcludePaths(paths ...string) MapOption

WithMapExcludePaths removes URLs whose paths start with any of the given prefixes.

func WithMapIncludePaths 

func WithMapIncludePaths(paths ...string) MapOption

WithMapIncludePaths keeps only URLs whose paths start with any of the given prefixes.

func WithMapLimit 

func WithMapLimit(n int) MapOption

WithMapLimit caps the number of discovered URLs. Default: 1000.

func WithMapMaxDepth 

func WithMapMaxDepth(n int) MapOption

WithMapMaxDepth sets link-follow depth for on-page discovery. Default: 2.

func WithMapSearch 

func WithMapSearch(term string) MapOption

WithMapSearch filters URLs to those containing the search term in the path or query.

func WithMapSitemap 

func WithMapSitemap(v bool) MapOption

WithMapSitemap controls whether to fetch and parse sitemap.xml. Default: true.

func WithMapSubdomains 

func WithMapSubdomains() MapOption

WithMapSubdomains includes URLs from subdomains of the start domain.

type MarkdownOption 

type MarkdownOption func(*markdownOptions)

MarkdownOption configures HTML-to-Markdown conversion.

func WithBaseURL 

func WithBaseURL(u string) MarkdownOption

WithBaseURL sets a base URL for resolving relative URLs in links and images.

func WithIncludeImages 

func WithIncludeImages(v bool) MarkdownOption

WithIncludeImages controls whether images are included in the output. 

func WithIncludeLinks(v bool) MarkdownOption

WithIncludeLinks controls whether links are rendered as markdown links or plain text.

func WithMainContentOnly 

func WithMainContentOnly() MarkdownOption

WithMainContentOnly enables readability scoring to extract only the main content.

type Message 

type Message struct {
	SessionID proto2.TargetSessionID
	Method    string
	// contains filtered or unexported fields
}

Message represents a cdp.Event.

func (*Message) Load 

func (msg *Message) Load(e proto2.Event) bool

Load data into e, returns true if e matches the event type.

type MetaData 

type MetaData struct {
	Title       string            `json:"title"`
	Description string            `json:"description"`
	Canonical   string            `json:"canonical,omitempty"`
	OG          map[string]string `json:"og,omitempty"`
	Twitter     map[string]string `json:"twitter,omitempty"`
	JSONLD      []json.RawMessage `json:"jsonld,omitempty"`
}

MetaData holds common page metadata (title, description, OG tags, etc.).

type MobileConfig added in v1.0.0 

type MobileConfig struct {
	DeviceID    string // ADB device serial (from "adb devices")
	ADBPath     string // path to adb binary (default: "adb")
	PackageName string // Android Chrome package (default: "com.android.chrome")
	CDPPort     int    // local port for CDP forwarding (default: 9222)
}

MobileConfig holds configuration for mobile browser automation.

type Mouse 

type Mouse struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Mouse represents the mouse on a page, it's always related the main frame.

func (*Mouse) Click 

func (m *Mouse) Click(button proto2.InputMouseButton, clickCount int) error

Click the button. It's the combination of Mouse.Down and Mouse.Up.

func (*Mouse) Down 

func (m *Mouse) Down(button proto2.InputMouseButton, clickCount int) error

Down holds the button down.

func (*Mouse) MoveAlong 

func (m *Mouse) MoveAlong(guide func() (proto2.Point, bool)) error

MoveAlong the guide function. Every time the guide function is called it should return the next mouse position, return true to stop. Read the source code of Mouse.MoveLinear as an example to use this method.

func (*Mouse) MoveLinear 

func (m *Mouse) MoveLinear(to proto2.Point, steps int) error

MoveLinear to the absolute position with the given steps. Such as move from (0,0) to (6,6) with 3 steps, the mouse will first move to (2,2) then (4,4) then (6,6).

func (*Mouse) MoveTo 

func (m *Mouse) MoveTo(p proto2.Point) error

MoveTo the absolute position.

func (*Mouse) MustClick 

func (m *Mouse) MustClick(button proto2.InputMouseButton) *Mouse

MustClick is similar to Mouse.Click.

func (*Mouse) MustDown 

func (m *Mouse) MustDown(button proto2.InputMouseButton) *Mouse

MustDown is similar to Mouse.Down.

func (*Mouse) MustMoveTo 

func (m *Mouse) MustMoveTo(x, y float64) *Mouse

MustMoveTo is similar to [Mouse.Move].

func (*Mouse) MustScroll 

func (m *Mouse) MustScroll(x, y float64) *Mouse

MustScroll is similar to Mouse.Scroll.

func (*Mouse) MustUp 

func (m *Mouse) MustUp(button proto2.InputMouseButton) *Mouse

MustUp is similar to Mouse.Up.

func (*Mouse) Position 

func (m *Mouse) Position() proto2.Point

Position of current cursor.

func (*Mouse) Scroll 

func (m *Mouse) Scroll(offsetX, offsetY float64, steps int) error

Scroll the relative offset with specified steps.

func (*Mouse) Up 

func (m *Mouse) Up(button proto2.InputMouseButton, clickCount int) error

Up releases the button.

type MutationEvent 

type MutationEvent struct {
	Type          string `json:"type"`
	Target        string `json:"target"`
	AddedNodes    int    `json:"addedNodes"`
	RemovedNodes  int    `json:"removedNodes"`
	AttributeName string `json:"attributeName,omitempty"`
	OldValue      string `json:"oldValue,omitempty"`
}

MutationEvent represents a DOM mutation observed by the bridge. 

type NavigationError struct {
	Reason string
}

NavigationError error. 

func (e *NavigationError) Error() string
func (e *NavigationError) Is(err error) bool

Is interface.

type NetworkRecorder 

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

NetworkRecorder captures HTTP traffic from a Page via CDP events and exports HAR 1.2 logs.

func NewNetworkRecorder 

func NewNetworkRecorder(page *Page, opts ...RecorderOption) *NetworkRecorder

NewNetworkRecorder creates a recorder that immediately begins capturing network traffic from the given page. Call Stop() to end recording.

Example 
package main

import (
	"fmt"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	b, err := scout.New(scout.WithHeadless(true))
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = b.Close() }()

	page, err := b.NewPage("https://example.com")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	rec := scout.NewNetworkRecorder(page,
		scout.WithCaptureBody(true),
		scout.WithCreatorName("my-tool", "1.0"),
	)
	defer rec.Stop()

	_ = page.Navigate("https://example.com")
	_ = page.WaitLoad()

	harJSON, count, err := rec.ExportHAR()
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	fmt.Printf("Captured %d entries (%d bytes)\n", count, len(harJSON))
}

func (*NetworkRecorder) Clear 

func (r *NetworkRecorder) Clear()

Clear removes all recorded entries.

func (*NetworkRecorder) Entries 

func (r *NetworkRecorder) Entries() []HAREntry

Entries returns a copy of the recorded HAR entries.

func (*NetworkRecorder) ExportHAR 

func (r *NetworkRecorder) ExportHAR() ([]byte, int, error)

ExportHAR returns the recorded traffic as a HAR 1.2 JSON document. The second return value is the number of entries.

func (*NetworkRecorder) Stop 

func (r *NetworkRecorder) Stop()

Stop ends the recording. It is safe to call multiple times.

type NoPointerEventsError 

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

NoPointerEventsError error.

func (NoPointerEventsError) Attribute 

func (el NoPointerEventsError) Attribute(name string) (*string, error)

Attribute of the DOM object. Attribute vs Property: https://stackoverflow.com/questions/6003819/what-is-the-difference-between-properties-and-attributes-in-html

func (NoPointerEventsError) BackgroundImage 

func (el NoPointerEventsError) BackgroundImage() ([]byte, error)

BackgroundImage returns the css background-image of the element.

func (NoPointerEventsError) Blur 

func (el NoPointerEventsError) Blur() error

Blur removes focus from the element.

func (NoPointerEventsError) Call 

func (el NoPointerEventsError) Call(ctx context.Context, sessionID, methodName string, params any) (res []byte, err error)

Call implements the proto.Client.

func (NoPointerEventsError) CancelTimeout 

func (el NoPointerEventsError) CancelTimeout() *rodElement

CancelTimeout cancels the current timeout context and returns a clone with the parent context.

func (NoPointerEventsError) CanvasToImage 

func (el NoPointerEventsError) CanvasToImage(format string, quality float64) ([]byte, error)

CanvasToImage get image data of a canvas. The default format is image/png. The default quality is 0.92. doc: https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toDataURL

func (NoPointerEventsError) Click 

func (el NoPointerEventsError) Click(button proto2.InputMouseButton, clickCount int) error

Click will press then release the button just like a human. Before the action, it will try to scroll to the element, hover the mouse over it, wait until the it's interactable and enabled.

func (NoPointerEventsError) ContainsElement 

func (el NoPointerEventsError) ContainsElement(target *rodElement) (bool, error)

ContainsElement check if the target is equal or inside the element.

func (NoPointerEventsError) Context 

func (el NoPointerEventsError) Context(ctx context.Context) *rodElement

Context returns a clone with the specified ctx for chained sub-operations.

func (NoPointerEventsError) Describe 

func (el NoPointerEventsError) Describe(depth int, pierce bool) (*proto2.DOMNode, error)

Describe the current element. The depth is the maximum depth at which children should be retrieved, defaults to 1, use -1 for the entire subtree or provide an integer larger than 0. The pierce decides whether or not iframes and shadow roots should be traversed when returning the subtree. The returned proto.DOMNode.NodeID will always be empty, because NodeID is not stable (when proto.DOMDocumentUpdated is fired all NodeID on the page will be reassigned to another value) we don't recommend using the NodeID, instead, use the proto.DOMBackendNodeID to identify the element.

func (NoPointerEventsError) Disabled 

func (el NoPointerEventsError) Disabled() (bool, error)

Disabled checks if the element is disabled.

func (NoPointerEventsError) Element 

func (el NoPointerEventsError) Element(selector string) (*rodElement, error)

Element returns the first child that matches the css selector.

func (NoPointerEventsError) ElementByJS 

func (el NoPointerEventsError) ElementByJS(opts *EvalOptions) (*rodElement, error)

ElementByJS returns the element from the return value of the js.

func (NoPointerEventsError) ElementR 

func (el NoPointerEventsError) ElementR(selector, jsRegex string) (*rodElement, error)

ElementR returns the first child element that matches the css selector and its text matches the jsRegex.

func (NoPointerEventsError) ElementX 

func (el NoPointerEventsError) ElementX(xPath string) (*rodElement, error)

ElementX returns the first child that matches the XPath selector.

func (NoPointerEventsError) Elements 

func (el NoPointerEventsError) Elements(selector string) (Elements, error)

Elements returns all elements that match the css selector.

func (NoPointerEventsError) ElementsByJS 

func (el NoPointerEventsError) ElementsByJS(opts *EvalOptions) (Elements, error)

ElementsByJS returns the elements from the return value of the js.

func (NoPointerEventsError) ElementsX 

func (el NoPointerEventsError) ElementsX(xpath string) (Elements, error)

ElementsX returns all elements that match the XPath selector.

func (NoPointerEventsError) Equal 

func (el NoPointerEventsError) Equal(elm *rodElement) (bool, error)

Equal checks if the two elements are equal.

func (*NoPointerEventsError) Error 

func (e *NoPointerEventsError) Error() string

Error ...

func (NoPointerEventsError) Eval 

func (el NoPointerEventsError) Eval(js string, params ...any) (*proto2.RuntimeRemoteObject, error)

Eval is a shortcut for [Element.Evaluate] with AwaitPromise, ByValue and AutoExp set to true.

func (NoPointerEventsError) Evaluate 

func (el NoPointerEventsError) Evaluate(opts *EvalOptions) (*proto2.RuntimeRemoteObject, error)

Evaluate is just a shortcut of [Page.Evaluate] with This set to current element.

func (NoPointerEventsError) Focus 

func (el NoPointerEventsError) Focus() error

Focus sets focus on the specified element. Before the action, it will try to scroll to the element.

func (NoPointerEventsError) Frame 

func (el NoPointerEventsError) Frame() (*rodPage, error)

Frame creates a page instance that represents the iframe.

func (NoPointerEventsError) GetContext 

func (el NoPointerEventsError) GetContext() context.Context

GetContext of current instance.

func (NoPointerEventsError) GetSessionID 

func (el NoPointerEventsError) GetSessionID() proto2.TargetSessionID

GetSessionID interface.

func (NoPointerEventsError) GetXPath 

func (el NoPointerEventsError) GetXPath(optimized bool) (string, error)

GetXPath returns the xpath of the element.

func (NoPointerEventsError) HTML 

func (el NoPointerEventsError) HTML() (string, error)

HTML of the element.

func (NoPointerEventsError) Has 

func (el NoPointerEventsError) Has(selector string) (bool, *rodElement, error)

Has an element that matches the css selector.

func (NoPointerEventsError) HasR 

func (el NoPointerEventsError) HasR(selector, jsRegex string) (bool, *rodElement, error)

HasR returns true if a child element that matches the css selector and its text matches the jsRegex.

func (NoPointerEventsError) HasX 

func (el NoPointerEventsError) HasX(selector string) (bool, *rodElement, error)

HasX an element that matches the XPath selector.

func (NoPointerEventsError) Hover 

func (el NoPointerEventsError) Hover() error

Hover the mouse over the center of the element. Before the action, it will try to scroll to the element and wait until it's interactable.

func (NoPointerEventsError) Input 

func (el NoPointerEventsError) Input(text string) error

Input focuses on the element and input text to it. Before the action, it will scroll to the element, wait until it's visible, enabled and writable. To empty the input you can use something like 

el.SelectAllText().MustInput("")

func (NoPointerEventsError) InputColor 

func (el NoPointerEventsError) InputColor(color string) error

InputColor focuses on the element and inputs a color string to it. Before the action, it will scroll to the element, wait until it's visible, enabled and writable.

func (NoPointerEventsError) InputTime 

func (el NoPointerEventsError) InputTime(t time.Time) error

InputTime focuses on the element and input time to it. Before the action, it will scroll to the element, wait until it's visible, enabled and writable. It will wait until the element is visible, enabled and writable.

func (NoPointerEventsError) Interactable 

func (el NoPointerEventsError) Interactable() (pt *proto2.Point, err error)

Interactable checks if the element is interactable with cursor. The cursor can be mouse, finger, stylus, etc. If not interactable err will be ErrNotInteractable, such as when covered by a modal,.

func (*NoPointerEventsError) Is 

func (e *NoPointerEventsError) Is(err error) bool

Is interface.

func (NoPointerEventsError) KeyActions 

func (el NoPointerEventsError) KeyActions() (*KeyActions, error)

KeyActions is similar with Page.KeyActions. Before the action, it will try to scroll to the element and focus on it.

func (NoPointerEventsError) Matches 

func (el NoPointerEventsError) Matches(selector string) (bool, error)

Matches checks if the element can be selected by the css selector.

func (NoPointerEventsError) MoveMouseOut 

func (el NoPointerEventsError) MoveMouseOut() error

MoveMouseOut of the current element.

func (NoPointerEventsError) MustAttribute 

func (el NoPointerEventsError) MustAttribute(name string) *string

MustAttribute is similar to Element.Attribute.

func (NoPointerEventsError) MustBackgroundImage 

func (el NoPointerEventsError) MustBackgroundImage() []byte

MustBackgroundImage is similar to Element.BackgroundImage.

func (NoPointerEventsError) MustBlur 

func (el NoPointerEventsError) MustBlur() *rodElement

MustBlur is similar to Element.Blur.

func (NoPointerEventsError) MustCanvasToImage 

func (el NoPointerEventsError) MustCanvasToImage() []byte

MustCanvasToImage is similar to Element.CanvasToImage.

func (NoPointerEventsError) MustClick 

func (el NoPointerEventsError) MustClick() *rodElement

MustClick is similar to Element.Click.

func (NoPointerEventsError) MustContainsElement 

func (el NoPointerEventsError) MustContainsElement(target *rodElement) bool

MustContainsElement is similar to Element.ContainsElement.

func (NoPointerEventsError) MustDescribe 

func (el NoPointerEventsError) MustDescribe() *proto2.DOMNode

MustDescribe is similar to [Element.Describe].

func (NoPointerEventsError) MustDisabled 

func (el NoPointerEventsError) MustDisabled() bool

MustDisabled is similar to Element.Disabled.

func (NoPointerEventsError) MustDoubleClick 

func (el NoPointerEventsError) MustDoubleClick() *rodElement

MustDoubleClick is similar to Element.Click.

func (NoPointerEventsError) MustElement 

func (el NoPointerEventsError) MustElement(selector string) *rodElement

MustElement is similar to Element.Element.

func (NoPointerEventsError) MustElementByJS 

func (el NoPointerEventsError) MustElementByJS(js string, params ...any) *rodElement

MustElementByJS is similar to [Element.ElementByJS].

func (NoPointerEventsError) MustElementR 

func (el NoPointerEventsError) MustElementR(selector, regex string) *rodElement

MustElementR is similar to [Element.ElementR].

func (NoPointerEventsError) MustElementX 

func (el NoPointerEventsError) MustElementX(xpath string) *rodElement

MustElementX is similar to [Element.ElementX].

func (NoPointerEventsError) MustElements 

func (el NoPointerEventsError) MustElements(selector string) Elements

MustElements is similar to Element.Elements.

func (NoPointerEventsError) MustElementsByJS 

func (el NoPointerEventsError) MustElementsByJS(js string, params ...any) Elements

MustElementsByJS is similar to [Element.ElementsByJS].

func (NoPointerEventsError) MustElementsX 

func (el NoPointerEventsError) MustElementsX(xpath string) Elements

MustElementsX is similar to [Element.ElementsX].

func (NoPointerEventsError) MustEqual 

func (el NoPointerEventsError) MustEqual(elm *rodElement) bool

MustEqual is similar to Element.Equal.

func (NoPointerEventsError) MustEval 

func (el NoPointerEventsError) MustEval(js string, params ...any) gson.JSON

MustEval is similar to Element.Eval.

func (NoPointerEventsError) MustFocus 

func (el NoPointerEventsError) MustFocus() *rodElement

MustFocus is similar to Element.Focus.

func (NoPointerEventsError) MustFrame 

func (el NoPointerEventsError) MustFrame() *rodPage

MustFrame is similar to Element.Frame.

func (NoPointerEventsError) MustGetXPath 

func (el NoPointerEventsError) MustGetXPath(optimized bool) string

MustGetXPath is similar to Element.GetXPath.

func (NoPointerEventsError) MustHTML 

func (el NoPointerEventsError) MustHTML() string

MustHTML is similar to Element.HTML.

func (NoPointerEventsError) MustHas 

func (el NoPointerEventsError) MustHas(selector string) bool

MustHas is similar to [Element.Has].

func (NoPointerEventsError) MustHasR 

func (el NoPointerEventsError) MustHasR(selector, regex string) bool

MustHasR is similar to [Element.HasR].

func (NoPointerEventsError) MustHasX 

func (el NoPointerEventsError) MustHasX(selector string) bool

MustHasX is similar to [Element.HasX].

func (NoPointerEventsError) MustHover 

func (el NoPointerEventsError) MustHover() *rodElement

MustHover is similar to Element.Hover.

func (NoPointerEventsError) MustInput 

func (el NoPointerEventsError) MustInput(text string) *rodElement

MustInput is similar to Element.Input.

func (NoPointerEventsError) MustInputColor 

func (el NoPointerEventsError) MustInputColor(color string) *rodElement

MustInputColor is similar to Element.InputColor.

func (NoPointerEventsError) MustInputTime 

func (el NoPointerEventsError) MustInputTime(t time.Time) *rodElement

MustInputTime is similar to Element.Input.

func (NoPointerEventsError) MustInteractable 

func (el NoPointerEventsError) MustInteractable() bool

MustInteractable is similar to Element.Interactable.

func (NoPointerEventsError) MustKeyActions 

func (el NoPointerEventsError) MustKeyActions() *KeyActions

MustKeyActions is similar to [Element.KeyActions].

func (NoPointerEventsError) MustMatches 

func (el NoPointerEventsError) MustMatches(selector string) bool

MustMatches is similar to Element.Matches.

func (NoPointerEventsError) MustMoveMouseOut 

func (el NoPointerEventsError) MustMoveMouseOut() *rodElement

MustMoveMouseOut is similar to Element.MoveMouseOut.

func (NoPointerEventsError) MustNext 

func (el NoPointerEventsError) MustNext() *rodElement

MustNext is similar to Element.Next.

func (NoPointerEventsError) MustParent 

func (el NoPointerEventsError) MustParent() *rodElement

MustParent is similar to Element.Parent.

func (NoPointerEventsError) MustParents 

func (el NoPointerEventsError) MustParents(selector string) Elements

MustParents is similar to Element.Parents.

func (NoPointerEventsError) MustPrevious 

func (el NoPointerEventsError) MustPrevious() *rodElement

MustPrevious is similar to Element.Previous.

func (NoPointerEventsError) MustProperty 

func (el NoPointerEventsError) MustProperty(name string) gson.JSON

MustProperty is similar to Element.Property.

func (NoPointerEventsError) MustRelease 

func (el NoPointerEventsError) MustRelease()

MustRelease is similar to [Element.Release].

func (NoPointerEventsError) MustRemove 

func (el NoPointerEventsError) MustRemove()

MustRemove is similar to Element.Remove.

func (NoPointerEventsError) MustResource 

func (el NoPointerEventsError) MustResource() []byte

MustResource is similar to Element.Resource.

func (NoPointerEventsError) MustScreenshot 

func (el NoPointerEventsError) MustScreenshot(toFile ...string) []byte

MustScreenshot is similar to Element.Screenshot.

func (NoPointerEventsError) MustScrollIntoView 

func (el NoPointerEventsError) MustScrollIntoView() *rodElement

MustScrollIntoView is similar to Element.ScrollIntoView.

func (NoPointerEventsError) MustSelect 

func (el NoPointerEventsError) MustSelect(selectors ...string) *rodElement

MustSelect is similar to [Element.Select].

func (NoPointerEventsError) MustSelectAllText 

func (el NoPointerEventsError) MustSelectAllText() *rodElement

MustSelectAllText is similar to Element.SelectAllText.

func (NoPointerEventsError) MustSelectText 

func (el NoPointerEventsError) MustSelectText(regex string) *rodElement

MustSelectText is similar to Element.SelectText.

func (NoPointerEventsError) MustSetFiles 

func (el NoPointerEventsError) MustSetFiles(paths ...string) *rodElement

MustSetFiles is similar to Element.SetFiles.

func (NoPointerEventsError) MustShadowRoot 

func (el NoPointerEventsError) MustShadowRoot() *rodElement

MustShadowRoot is similar to Element.ShadowRoot.

func (NoPointerEventsError) MustShape 

func (el NoPointerEventsError) MustShape() *proto2.DOMGetContentQuadsResult

MustShape is similar to [Element.Shape].

func (NoPointerEventsError) MustTap 

func (el NoPointerEventsError) MustTap() *rodElement

MustTap is similar to Element.Tap.

func (NoPointerEventsError) MustText 

func (el NoPointerEventsError) MustText() string

MustText is similar to Element.Text.

func (NoPointerEventsError) MustType 

func (el NoPointerEventsError) MustType(keys ...input.Key) *rodElement

MustType is similar to Element.Type.

func (NoPointerEventsError) MustVisible 

func (el NoPointerEventsError) MustVisible() bool

MustVisible is similar to Element.Visible.

func (NoPointerEventsError) MustWait 

func (el NoPointerEventsError) MustWait(js string, params ...any) *rodElement

MustWait is similar to [Element.Wait].

func (NoPointerEventsError) MustWaitEnabled 

func (el NoPointerEventsError) MustWaitEnabled() *rodElement

MustWaitEnabled is similar to Element.WaitEnabled.

func (NoPointerEventsError) MustWaitInteractable 

func (el NoPointerEventsError) MustWaitInteractable() *rodElement

MustWaitInteractable is similar to Element.WaitInteractable.

func (NoPointerEventsError) MustWaitInvisible 

func (el NoPointerEventsError) MustWaitInvisible() *rodElement

MustWaitInvisible is similar to Element.WaitInvisible..

func (NoPointerEventsError) MustWaitLoad 

func (el NoPointerEventsError) MustWaitLoad() *rodElement

MustWaitLoad is similar to Element.WaitLoad.

func (NoPointerEventsError) MustWaitStable 

func (el NoPointerEventsError) MustWaitStable() *rodElement

MustWaitStable is similar to Element.WaitStable.

func (NoPointerEventsError) MustWaitVisible 

func (el NoPointerEventsError) MustWaitVisible() *rodElement

MustWaitVisible is similar to Element.WaitVisible.

func (NoPointerEventsError) MustWaitWritable 

func (el NoPointerEventsError) MustWaitWritable() *rodElement

MustWaitWritable is similar to Element.WaitWritable.

func (NoPointerEventsError) Next 

func (el NoPointerEventsError) Next() (*rodElement, error)

Next returns the next sibling element in the DOM tree.

func (NoPointerEventsError) Overlay 

func (el NoPointerEventsError) Overlay(msg string) (removeOverlay func())

Overlay msg on the element.

func (NoPointerEventsError) Page 

func (el NoPointerEventsError) Page() *rodPage

Page of the element.

func (NoPointerEventsError) Parent 

func (el NoPointerEventsError) Parent() (*rodElement, error)

Parent returns the parent element in the DOM tree.

func (NoPointerEventsError) Parents 

func (el NoPointerEventsError) Parents(selector string) (Elements, error)

Parents that match the selector.

func (NoPointerEventsError) Previous 

func (el NoPointerEventsError) Previous() (*rodElement, error)

Previous returns the previous sibling element in the DOM tree.

func (NoPointerEventsError) Property 

func (el NoPointerEventsError) Property(name string) (gson.JSON, error)

Property of the DOM object. Property vs Attribute: https://stackoverflow.com/questions/6003819/what-is-the-difference-between-properties-and-attributes-in-html

func (NoPointerEventsError) Release 

func (el NoPointerEventsError) Release() error

Release is a shortcut for [Page.Release] current element.

func (NoPointerEventsError) Remove 

func (el NoPointerEventsError) Remove() error

Remove the element from the page.

func (NoPointerEventsError) Resource 

func (el NoPointerEventsError) Resource() ([]byte, error)

Resource returns the "src" content of current element. Such as the jpg of <img src="a.jpg">.

func (NoPointerEventsError) Screenshot 

func (el NoPointerEventsError) Screenshot(format proto2.PageCaptureScreenshotFormat, quality int) ([]byte, error)

Screenshot of the area of the element.

func (NoPointerEventsError) ScrollIntoView 

func (el NoPointerEventsError) ScrollIntoView() error

ScrollIntoView scrolls the current element into the visible area of the browser window if it's not already within the visible area.

func (NoPointerEventsError) Select 

func (el NoPointerEventsError) Select(selectors []string, selected bool, t SelectorType) error

Select the children option elements that match the selectors. Before the action, it will scroll to the element, wait until it's visible. If no option matches the selectors, it will return [ErrElementNotFound].

func (NoPointerEventsError) SelectAllText 

func (el NoPointerEventsError) SelectAllText() error

SelectAllText selects all text Before the action, it will try to scroll to the element and focus on it.

func (NoPointerEventsError) SelectText 

func (el NoPointerEventsError) SelectText(regex string) error

SelectText selects the text that matches the regular expression. Before the action, it will try to scroll to the element and focus on it.

func (NoPointerEventsError) SetFiles 

func (el NoPointerEventsError) SetFiles(paths []string) error

SetFiles of the current file input element.

func (NoPointerEventsError) ShadowRoot 

func (el NoPointerEventsError) ShadowRoot() (*rodElement, error)

ShadowRoot returns the shadow root of this element.

func (NoPointerEventsError) Shape 

func (el NoPointerEventsError) Shape() (*proto2.DOMGetContentQuadsResult, error)

Shape of the DOM element content. The shape is a group of 4-sides polygons. A 4-sides polygon is not necessary a rectangle. 4-sides polygons can be apart from each other. For example, we use 2 4-sides polygons to describe the shape below: 

  ____________          ____________
 /        ___/    =    /___________/    +     _________
/________/                                   /________/

func (NoPointerEventsError) Sleeper 

func (el NoPointerEventsError) Sleeper(sleeper func() utils.Sleeper) *rodElement

Sleeper returns a clone with the specified sleeper for chained sub-operations.

func (NoPointerEventsError) String 

func (el NoPointerEventsError) String() string

String interface.

func (NoPointerEventsError) Tap 

func (el NoPointerEventsError) Tap() error

Tap will scroll to the button and tap it just like a human. Before the action, it will try to scroll to the element and wait until it's interactable and enabled.

func (NoPointerEventsError) Text 

func (el NoPointerEventsError) Text() (string, error)

Text that the element displays.

func (NoPointerEventsError) Timeout 

func (el NoPointerEventsError) Timeout(d time.Duration) *rodElement

Timeout returns a clone with the specified total timeout of all chained sub-operations.

func (NoPointerEventsError) Type 

func (el NoPointerEventsError) Type(keys ...input.Key) error

Type is similar with Keyboard.Type. Before the action, it will try to scroll to the element and focus on it.

func (*NoPointerEventsError) Unwrap 

func (e *NoPointerEventsError) Unwrap() error

Unwrap ...

func (NoPointerEventsError) Visible 

func (el NoPointerEventsError) Visible() (bool, error)

Visible returns true if the element is visible on the page.

func (NoPointerEventsError) Wait 

func (el NoPointerEventsError) Wait(opts *EvalOptions) error

Wait until the js returns true.

func (NoPointerEventsError) WaitEnabled 

func (el NoPointerEventsError) WaitEnabled() error

WaitEnabled until the element is not disabled. Doc for readonly: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/readonly

func (NoPointerEventsError) WaitInteractable 

func (el NoPointerEventsError) WaitInteractable() (pt *proto2.Point, err error)

WaitInteractable waits for the element to be interactable. It will try to scroll to the element on each try.

func (NoPointerEventsError) WaitInvisible 

func (el NoPointerEventsError) WaitInvisible() error

WaitInvisible until the element invisible.

func (NoPointerEventsError) WaitLoad 

func (el NoPointerEventsError) WaitLoad() error

WaitLoad for element like <img>.

func (NoPointerEventsError) WaitStable 

func (el NoPointerEventsError) WaitStable(d time.Duration) error

WaitStable waits until no shape or position change for d duration. Be careful, d is not the max wait timeout, it's the least stable time. If you want to set a timeout you can use the [Element.Timeout] function.

func (NoPointerEventsError) WaitStableRAF 

func (el NoPointerEventsError) WaitStableRAF() error

WaitStableRAF waits until no shape or position change for 2 consecutive animation frames. If you want to wait animation that is triggered by JS not CSS, you'd better use Element.WaitStable. About animation frame: https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame

func (NoPointerEventsError) WaitVisible 

func (el NoPointerEventsError) WaitVisible() error

WaitVisible until the element is visible.

func (NoPointerEventsError) WaitWritable 

func (el NoPointerEventsError) WaitWritable() error

WaitWritable until the element is not readonly. Doc for disabled: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/disabled

func (NoPointerEventsError) WithCancel 

func (el NoPointerEventsError) WithCancel() (*rodElement, func())

WithCancel returns a clone with a context cancel function.

func (NoPointerEventsError) WithPanic 

func (el NoPointerEventsError) WithPanic(fail func(any)) *rodElement

WithPanic returns an element clone with the specified panic function. The fail must stop the current goroutine's execution immediately, such as use runtime.Goexit or panic inside it.

type NoShadowRootError 

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

NoShadowRootError error.

func (NoShadowRootError) Attribute 

func (el NoShadowRootError) Attribute(name string) (*string, error)

Attribute of the DOM object. Attribute vs Property: https://stackoverflow.com/questions/6003819/what-is-the-difference-between-properties-and-attributes-in-html

func (NoShadowRootError) BackgroundImage 

func (el NoShadowRootError) BackgroundImage() ([]byte, error)

BackgroundImage returns the css background-image of the element.

func (NoShadowRootError) Blur 

func (el NoShadowRootError) Blur() error

Blur removes focus from the element.

func (NoShadowRootError) Call 

func (el NoShadowRootError) Call(ctx context.Context, sessionID, methodName string, params any) (res []byte, err error)

Call implements the proto.Client.

func (NoShadowRootError) CancelTimeout 

func (el NoShadowRootError) CancelTimeout() *rodElement

CancelTimeout cancels the current timeout context and returns a clone with the parent context.

func (NoShadowRootError) CanvasToImage 

func (el NoShadowRootError) CanvasToImage(format string, quality float64) ([]byte, error)

CanvasToImage get image data of a canvas. The default format is image/png. The default quality is 0.92. doc: https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toDataURL

func (NoShadowRootError) Click 

func (el NoShadowRootError) Click(button proto2.InputMouseButton, clickCount int) error

Click will press then release the button just like a human. Before the action, it will try to scroll to the element, hover the mouse over it, wait until the it's interactable and enabled.

func (NoShadowRootError) ContainsElement 

func (el NoShadowRootError) ContainsElement(target *rodElement) (bool, error)

ContainsElement check if the target is equal or inside the element.

func (NoShadowRootError) Context 

func (el NoShadowRootError) Context(ctx context.Context) *rodElement

Context returns a clone with the specified ctx for chained sub-operations.

func (NoShadowRootError) Describe 

func (el NoShadowRootError) Describe(depth int, pierce bool) (*proto2.DOMNode, error)

Describe the current element. The depth is the maximum depth at which children should be retrieved, defaults to 1, use -1 for the entire subtree or provide an integer larger than 0. The pierce decides whether or not iframes and shadow roots should be traversed when returning the subtree. The returned proto.DOMNode.NodeID will always be empty, because NodeID is not stable (when proto.DOMDocumentUpdated is fired all NodeID on the page will be reassigned to another value) we don't recommend using the NodeID, instead, use the proto.DOMBackendNodeID to identify the element.

func (NoShadowRootError) Disabled 

func (el NoShadowRootError) Disabled() (bool, error)

Disabled checks if the element is disabled.

func (NoShadowRootError) Element 

func (el NoShadowRootError) Element(selector string) (*rodElement, error)

Element returns the first child that matches the css selector.

func (NoShadowRootError) ElementByJS 

func (el NoShadowRootError) ElementByJS(opts *EvalOptions) (*rodElement, error)

ElementByJS returns the element from the return value of the js.

func (NoShadowRootError) ElementR 

func (el NoShadowRootError) ElementR(selector, jsRegex string) (*rodElement, error)

ElementR returns the first child element that matches the css selector and its text matches the jsRegex.

func (NoShadowRootError) ElementX 

func (el NoShadowRootError) ElementX(xPath string) (*rodElement, error)

ElementX returns the first child that matches the XPath selector.

func (NoShadowRootError) Elements 

func (el NoShadowRootError) Elements(selector string) (Elements, error)

Elements returns all elements that match the css selector.

func (NoShadowRootError) ElementsByJS 

func (el NoShadowRootError) ElementsByJS(opts *EvalOptions) (Elements, error)

ElementsByJS returns the elements from the return value of the js.

func (NoShadowRootError) ElementsX 

func (el NoShadowRootError) ElementsX(xpath string) (Elements, error)

ElementsX returns all elements that match the XPath selector.

func (NoShadowRootError) Equal 

func (el NoShadowRootError) Equal(elm *rodElement) (bool, error)

Equal checks if the two elements are equal.

func (*NoShadowRootError) Error 

func (e *NoShadowRootError) Error() string

Error ...

func (NoShadowRootError) Eval 

func (el NoShadowRootError) Eval(js string, params ...any) (*proto2.RuntimeRemoteObject, error)

Eval is a shortcut for [Element.Evaluate] with AwaitPromise, ByValue and AutoExp set to true.

func (NoShadowRootError) Evaluate 

func (el NoShadowRootError) Evaluate(opts *EvalOptions) (*proto2.RuntimeRemoteObject, error)

Evaluate is just a shortcut of [Page.Evaluate] with This set to current element.

func (NoShadowRootError) Focus 

func (el NoShadowRootError) Focus() error

Focus sets focus on the specified element. Before the action, it will try to scroll to the element.

func (NoShadowRootError) Frame 

func (el NoShadowRootError) Frame() (*rodPage, error)

Frame creates a page instance that represents the iframe.

func (NoShadowRootError) GetContext 

func (el NoShadowRootError) GetContext() context.Context

GetContext of current instance.

func (NoShadowRootError) GetSessionID 

func (el NoShadowRootError) GetSessionID() proto2.TargetSessionID

GetSessionID interface.

func (NoShadowRootError) GetXPath 

func (el NoShadowRootError) GetXPath(optimized bool) (string, error)

GetXPath returns the xpath of the element.

func (NoShadowRootError) HTML 

func (el NoShadowRootError) HTML() (string, error)

HTML of the element.

func (NoShadowRootError) Has 

func (el NoShadowRootError) Has(selector string) (bool, *rodElement, error)

Has an element that matches the css selector.

func (NoShadowRootError) HasR 

func (el NoShadowRootError) HasR(selector, jsRegex string) (bool, *rodElement, error)

HasR returns true if a child element that matches the css selector and its text matches the jsRegex.

func (NoShadowRootError) HasX 

func (el NoShadowRootError) HasX(selector string) (bool, *rodElement, error)

HasX an element that matches the XPath selector.

func (NoShadowRootError) Hover 

func (el NoShadowRootError) Hover() error

Hover the mouse over the center of the element. Before the action, it will try to scroll to the element and wait until it's interactable.

func (NoShadowRootError) Input 

func (el NoShadowRootError) Input(text string) error

Input focuses on the element and input text to it. Before the action, it will scroll to the element, wait until it's visible, enabled and writable. To empty the input you can use something like 

el.SelectAllText().MustInput("")

func (NoShadowRootError) InputColor 

func (el NoShadowRootError) InputColor(color string) error

InputColor focuses on the element and inputs a color string to it. Before the action, it will scroll to the element, wait until it's visible, enabled and writable.

func (NoShadowRootError) InputTime 

func (el NoShadowRootError) InputTime(t time.Time) error

InputTime focuses on the element and input time to it. Before the action, it will scroll to the element, wait until it's visible, enabled and writable. It will wait until the element is visible, enabled and writable.

func (NoShadowRootError) Interactable 

func (el NoShadowRootError) Interactable() (pt *proto2.Point, err error)

Interactable checks if the element is interactable with cursor. The cursor can be mouse, finger, stylus, etc. If not interactable err will be ErrNotInteractable, such as when covered by a modal,.

func (*NoShadowRootError) Is 

func (e *NoShadowRootError) Is(err error) bool

Is interface.

func (NoShadowRootError) KeyActions 

func (el NoShadowRootError) KeyActions() (*KeyActions, error)

KeyActions is similar with Page.KeyActions. Before the action, it will try to scroll to the element and focus on it.

func (NoShadowRootError) Matches 

func (el NoShadowRootError) Matches(selector string) (bool, error)

Matches checks if the element can be selected by the css selector.

func (NoShadowRootError) MoveMouseOut 

func (el NoShadowRootError) MoveMouseOut() error

MoveMouseOut of the current element.

func (NoShadowRootError) MustAttribute 

func (el NoShadowRootError) MustAttribute(name string) *string

MustAttribute is similar to Element.Attribute.

func (NoShadowRootError) MustBackgroundImage 

func (el NoShadowRootError) MustBackgroundImage() []byte

MustBackgroundImage is similar to Element.BackgroundImage.

func (NoShadowRootError) MustBlur 

func (el NoShadowRootError) MustBlur() *rodElement

MustBlur is similar to Element.Blur.

func (NoShadowRootError) MustCanvasToImage 

func (el NoShadowRootError) MustCanvasToImage() []byte

MustCanvasToImage is similar to Element.CanvasToImage.

func (NoShadowRootError) MustClick 

func (el NoShadowRootError) MustClick() *rodElement

MustClick is similar to Element.Click.

func (NoShadowRootError) MustContainsElement 

func (el NoShadowRootError) MustContainsElement(target *rodElement) bool

MustContainsElement is similar to Element.ContainsElement.

func (NoShadowRootError) MustDescribe 

func (el NoShadowRootError) MustDescribe() *proto2.DOMNode

MustDescribe is similar to [Element.Describe].

func (NoShadowRootError) MustDisabled 

func (el NoShadowRootError) MustDisabled() bool

MustDisabled is similar to Element.Disabled.

func (NoShadowRootError) MustDoubleClick 

func (el NoShadowRootError) MustDoubleClick() *rodElement

MustDoubleClick is similar to Element.Click.

func (NoShadowRootError) MustElement 

func (el NoShadowRootError) MustElement(selector string) *rodElement

MustElement is similar to Element.Element.

func (NoShadowRootError) MustElementByJS 

func (el NoShadowRootError) MustElementByJS(js string, params ...any) *rodElement

MustElementByJS is similar to [Element.ElementByJS].

func (NoShadowRootError) MustElementR 

func (el NoShadowRootError) MustElementR(selector, regex string) *rodElement

MustElementR is similar to [Element.ElementR].

func (NoShadowRootError) MustElementX 

func (el NoShadowRootError) MustElementX(xpath string) *rodElement

MustElementX is similar to [Element.ElementX].

func (NoShadowRootError) MustElements 

func (el NoShadowRootError) MustElements(selector string) Elements

MustElements is similar to Element.Elements.

func (NoShadowRootError) MustElementsByJS 

func (el NoShadowRootError) MustElementsByJS(js string, params ...any) Elements

MustElementsByJS is similar to [Element.ElementsByJS].

func (NoShadowRootError) MustElementsX 

func (el NoShadowRootError) MustElementsX(xpath string) Elements

MustElementsX is similar to [Element.ElementsX].

func (NoShadowRootError) MustEqual 

func (el NoShadowRootError) MustEqual(elm *rodElement) bool

MustEqual is similar to Element.Equal.

func (NoShadowRootError) MustEval 

func (el NoShadowRootError) MustEval(js string, params ...any) gson.JSON

MustEval is similar to Element.Eval.

func (NoShadowRootError) MustFocus 

func (el NoShadowRootError) MustFocus() *rodElement

MustFocus is similar to Element.Focus.

func (NoShadowRootError) MustFrame 

func (el NoShadowRootError) MustFrame() *rodPage

MustFrame is similar to Element.Frame.

func (NoShadowRootError) MustGetXPath 

func (el NoShadowRootError) MustGetXPath(optimized bool) string

MustGetXPath is similar to Element.GetXPath.

func (NoShadowRootError) MustHTML 

func (el NoShadowRootError) MustHTML() string

MustHTML is similar to Element.HTML.

func (NoShadowRootError) MustHas 

func (el NoShadowRootError) MustHas(selector string) bool

MustHas is similar to [Element.Has].

func (NoShadowRootError) MustHasR 

func (el NoShadowRootError) MustHasR(selector, regex string) bool

MustHasR is similar to [Element.HasR].

func (NoShadowRootError) MustHasX 

func (el NoShadowRootError) MustHasX(selector string) bool

MustHasX is similar to [Element.HasX].

func (NoShadowRootError) MustHover 

func (el NoShadowRootError) MustHover() *rodElement

MustHover is similar to Element.Hover.

func (NoShadowRootError) MustInput 

func (el NoShadowRootError) MustInput(text string) *rodElement

MustInput is similar to Element.Input.

func (NoShadowRootError) MustInputColor 

func (el NoShadowRootError) MustInputColor(color string) *rodElement

MustInputColor is similar to Element.InputColor.

func (NoShadowRootError) MustInputTime 

func (el NoShadowRootError) MustInputTime(t time.Time) *rodElement

MustInputTime is similar to Element.Input.

func (NoShadowRootError) MustInteractable 

func (el NoShadowRootError) MustInteractable() bool

MustInteractable is similar to Element.Interactable.

func (NoShadowRootError) MustKeyActions 

func (el NoShadowRootError) MustKeyActions() *KeyActions

MustKeyActions is similar to [Element.KeyActions].

func (NoShadowRootError) MustMatches 

func (el NoShadowRootError) MustMatches(selector string) bool

MustMatches is similar to Element.Matches.

func (NoShadowRootError) MustMoveMouseOut 

func (el NoShadowRootError) MustMoveMouseOut() *rodElement

MustMoveMouseOut is similar to Element.MoveMouseOut.

func (NoShadowRootError) MustNext 

func (el NoShadowRootError) MustNext() *rodElement

MustNext is similar to Element.Next.

func (NoShadowRootError) MustParent 

func (el NoShadowRootError) MustParent() *rodElement

MustParent is similar to Element.Parent.

func (NoShadowRootError) MustParents 

func (el NoShadowRootError) MustParents(selector string) Elements

MustParents is similar to Element.Parents.

func (NoShadowRootError) MustPrevious 

func (el NoShadowRootError) MustPrevious() *rodElement

MustPrevious is similar to Element.Previous.

func (NoShadowRootError) MustProperty 

func (el NoShadowRootError) MustProperty(name string) gson.JSON

MustProperty is similar to Element.Property.

func (NoShadowRootError) MustRelease 

func (el NoShadowRootError) MustRelease()

MustRelease is similar to [Element.Release].

func (NoShadowRootError) MustRemove 

func (el NoShadowRootError) MustRemove()

MustRemove is similar to Element.Remove.

func (NoShadowRootError) MustResource 

func (el NoShadowRootError) MustResource() []byte

MustResource is similar to Element.Resource.

func (NoShadowRootError) MustScreenshot 

func (el NoShadowRootError) MustScreenshot(toFile ...string) []byte

MustScreenshot is similar to Element.Screenshot.

func (NoShadowRootError) MustScrollIntoView 

func (el NoShadowRootError) MustScrollIntoView() *rodElement

MustScrollIntoView is similar to Element.ScrollIntoView.

func (NoShadowRootError) MustSelect 

func (el NoShadowRootError) MustSelect(selectors ...string) *rodElement

MustSelect is similar to [Element.Select].

func (NoShadowRootError) MustSelectAllText 

func (el NoShadowRootError) MustSelectAllText() *rodElement

MustSelectAllText is similar to Element.SelectAllText.

func (NoShadowRootError) MustSelectText 

func (el NoShadowRootError) MustSelectText(regex string) *rodElement

MustSelectText is similar to Element.SelectText.

func (NoShadowRootError) MustSetFiles 

func (el NoShadowRootError) MustSetFiles(paths ...string) *rodElement

MustSetFiles is similar to Element.SetFiles.

func (NoShadowRootError) MustShadowRoot 

func (el NoShadowRootError) MustShadowRoot() *rodElement

MustShadowRoot is similar to Element.ShadowRoot.

func (NoShadowRootError) MustShape 

func (el NoShadowRootError) MustShape() *proto2.DOMGetContentQuadsResult

MustShape is similar to [Element.Shape].

func (NoShadowRootError) MustTap 

func (el NoShadowRootError) MustTap() *rodElement

MustTap is similar to Element.Tap.

func (NoShadowRootError) MustText 

func (el NoShadowRootError) MustText() string

MustText is similar to Element.Text.

func (NoShadowRootError) MustType 

func (el NoShadowRootError) MustType(keys ...input.Key) *rodElement

MustType is similar to Element.Type.

func (NoShadowRootError) MustVisible 

func (el NoShadowRootError) MustVisible() bool

MustVisible is similar to Element.Visible.

func (NoShadowRootError) MustWait 

func (el NoShadowRootError) MustWait(js string, params ...any) *rodElement

MustWait is similar to [Element.Wait].

func (NoShadowRootError) MustWaitEnabled 

func (el NoShadowRootError) MustWaitEnabled() *rodElement

MustWaitEnabled is similar to Element.WaitEnabled.

func (NoShadowRootError) MustWaitInteractable 

func (el NoShadowRootError) MustWaitInteractable() *rodElement

MustWaitInteractable is similar to Element.WaitInteractable.

func (NoShadowRootError) MustWaitInvisible 

func (el NoShadowRootError) MustWaitInvisible() *rodElement

MustWaitInvisible is similar to Element.WaitInvisible..

func (NoShadowRootError) MustWaitLoad 

func (el NoShadowRootError) MustWaitLoad() *rodElement

MustWaitLoad is similar to Element.WaitLoad.

func (NoShadowRootError) MustWaitStable 

func (el NoShadowRootError) MustWaitStable() *rodElement

MustWaitStable is similar to Element.WaitStable.

func (NoShadowRootError) MustWaitVisible 

func (el NoShadowRootError) MustWaitVisible() *rodElement

MustWaitVisible is similar to Element.WaitVisible.

func (NoShadowRootError) MustWaitWritable 

func (el NoShadowRootError) MustWaitWritable() *rodElement

MustWaitWritable is similar to Element.WaitWritable.

func (NoShadowRootError) Next 

func (el NoShadowRootError) Next() (*rodElement, error)

Next returns the next sibling element in the DOM tree.

func (NoShadowRootError) Overlay 

func (el NoShadowRootError) Overlay(msg string) (removeOverlay func())

Overlay msg on the element.

func (NoShadowRootError) Page 

func (el NoShadowRootError) Page() *rodPage

Page of the element.

func (NoShadowRootError) Parent 

func (el NoShadowRootError) Parent() (*rodElement, error)

Parent returns the parent element in the DOM tree.

func (NoShadowRootError) Parents 

func (el NoShadowRootError) Parents(selector string) (Elements, error)

Parents that match the selector.

func (NoShadowRootError) Previous 

func (el NoShadowRootError) Previous() (*rodElement, error)

Previous returns the previous sibling element in the DOM tree.

func (NoShadowRootError) Property 

func (el NoShadowRootError) Property(name string) (gson.JSON, error)

Property of the DOM object. Property vs Attribute: https://stackoverflow.com/questions/6003819/what-is-the-difference-between-properties-and-attributes-in-html

func (NoShadowRootError) Release 

func (el NoShadowRootError) Release() error

Release is a shortcut for [Page.Release] current element.

func (NoShadowRootError) Remove 

func (el NoShadowRootError) Remove() error

Remove the element from the page.

func (NoShadowRootError) Resource 

func (el NoShadowRootError) Resource() ([]byte, error)

Resource returns the "src" content of current element. Such as the jpg of <img src="a.jpg">.

func (NoShadowRootError) Screenshot 

func (el NoShadowRootError) Screenshot(format proto2.PageCaptureScreenshotFormat, quality int) ([]byte, error)

Screenshot of the area of the element.

func (NoShadowRootError) ScrollIntoView 

func (el NoShadowRootError) ScrollIntoView() error

ScrollIntoView scrolls the current element into the visible area of the browser window if it's not already within the visible area.

func (NoShadowRootError) Select 

func (el NoShadowRootError) Select(selectors []string, selected bool, t SelectorType) error

Select the children option elements that match the selectors. Before the action, it will scroll to the element, wait until it's visible. If no option matches the selectors, it will return [ErrElementNotFound].

func (NoShadowRootError) SelectAllText 

func (el NoShadowRootError) SelectAllText() error

SelectAllText selects all text Before the action, it will try to scroll to the element and focus on it.

func (NoShadowRootError) SelectText 

func (el NoShadowRootError) SelectText(regex string) error

SelectText selects the text that matches the regular expression. Before the action, it will try to scroll to the element and focus on it.

func (NoShadowRootError) SetFiles 

func (el NoShadowRootError) SetFiles(paths []string) error

SetFiles of the current file input element.

func (NoShadowRootError) ShadowRoot 

func (el NoShadowRootError) ShadowRoot() (*rodElement, error)

ShadowRoot returns the shadow root of this element.

func (NoShadowRootError) Shape 

func (el NoShadowRootError) Shape() (*proto2.DOMGetContentQuadsResult, error)

Shape of the DOM element content. The shape is a group of 4-sides polygons. A 4-sides polygon is not necessary a rectangle. 4-sides polygons can be apart from each other. For example, we use 2 4-sides polygons to describe the shape below: 

  ____________          ____________
 /        ___/    =    /___________/    +     _________
/________/                                   /________/

func (NoShadowRootError) Sleeper 

func (el NoShadowRootError) Sleeper(sleeper func() utils.Sleeper) *rodElement

Sleeper returns a clone with the specified sleeper for chained sub-operations.

func (NoShadowRootError) String 

func (el NoShadowRootError) String() string

String interface.

func (NoShadowRootError) Tap 

func (el NoShadowRootError) Tap() error

Tap will scroll to the button and tap it just like a human. Before the action, it will try to scroll to the element and wait until it's interactable and enabled.

func (NoShadowRootError) Text 

func (el NoShadowRootError) Text() (string, error)

Text that the element displays.

func (NoShadowRootError) Timeout 

func (el NoShadowRootError) Timeout(d time.Duration) *rodElement

Timeout returns a clone with the specified total timeout of all chained sub-operations.

func (NoShadowRootError) Type 

func (el NoShadowRootError) Type(keys ...input.Key) error

Type is similar with Keyboard.Type. Before the action, it will try to scroll to the element and focus on it.

func (NoShadowRootError) Visible 

func (el NoShadowRootError) Visible() (bool, error)

Visible returns true if the element is visible on the page.

func (NoShadowRootError) Wait 

func (el NoShadowRootError) Wait(opts *EvalOptions) error

Wait until the js returns true.

func (NoShadowRootError) WaitEnabled 

func (el NoShadowRootError) WaitEnabled() error

WaitEnabled until the element is not disabled. Doc for readonly: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/readonly

func (NoShadowRootError) WaitInteractable 

func (el NoShadowRootError) WaitInteractable() (pt *proto2.Point, err error)

WaitInteractable waits for the element to be interactable. It will try to scroll to the element on each try.

func (NoShadowRootError) WaitInvisible 

func (el NoShadowRootError) WaitInvisible() error

WaitInvisible until the element invisible.

func (NoShadowRootError) WaitLoad 

func (el NoShadowRootError) WaitLoad() error

WaitLoad for element like <img>.

func (NoShadowRootError) WaitStable 

func (el NoShadowRootError) WaitStable(d time.Duration) error

WaitStable waits until no shape or position change for d duration. Be careful, d is not the max wait timeout, it's the least stable time. If you want to set a timeout you can use the [Element.Timeout] function.

func (NoShadowRootError) WaitStableRAF 

func (el NoShadowRootError) WaitStableRAF() error

WaitStableRAF waits until no shape or position change for 2 consecutive animation frames. If you want to wait animation that is triggered by JS not CSS, you'd better use Element.WaitStable. About animation frame: https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame

func (NoShadowRootError) WaitVisible 

func (el NoShadowRootError) WaitVisible() error

WaitVisible until the element is visible.

func (NoShadowRootError) WaitWritable 

func (el NoShadowRootError) WaitWritable() error

WaitWritable until the element is not readonly. Doc for disabled: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/disabled

func (NoShadowRootError) WithCancel 

func (el NoShadowRootError) WithCancel() (*rodElement, func())

WithCancel returns a clone with a context cancel function.

func (NoShadowRootError) WithPanic 

func (el NoShadowRootError) WithPanic(fail func(any)) *rodElement

WithPanic returns an element clone with the specified panic function. The fail must stop the current goroutine's execution immediately, such as use runtime.Goexit or panic inside it.

type NotInteractableError 

type NotInteractableError struct{}

NotInteractableError error. Check the doc of Element.Interactable for details.

func (*NotInteractableError) Error 

func (e *NotInteractableError) Error() string

type ObjectNotFoundError 

type ObjectNotFoundError struct {
	*proto.RuntimeRemoteObject
}

ObjectNotFoundError error.

func (*ObjectNotFoundError) Error 

func (e *ObjectNotFoundError) Error() string

func (*ObjectNotFoundError) Is 

func (e *ObjectNotFoundError) Is(err error) bool

Is interface.

type OllamaOption 

type OllamaOption = llm.OllamaOption

type OllamaProvider 

type OllamaProvider = llm.OllamaProvider

type OpenAIOption 

type OpenAIOption = llm.OpenAIOption

type OpenAIProvider 

type OpenAIProvider = llm.OpenAIProvider

type Option 

type Option func(*options)

Option configures a Browser instance.

func WithAutoBypass 

func WithAutoBypass(solver *ChallengeSolver) Option

WithAutoBypass sets a ChallengeSolver that is automatically applied after every NewPage navigation. When set, NewPage will detect and attempt to solve bot protection challenges on the loaded page.

func WithAutoDetect 

func WithAutoDetect() Option

WithAutoDetect picks the best available browser (Chrome > Brave > Edge > Chromium). If no browser is found, falls back to rod's default auto-detection. This is ignored if WithExecPath or WithBrowser is also set.

func WithAutoFree 

func WithAutoFree(interval time.Duration) Option

WithAutoFree enables periodic browser recycling at the given interval. On each tick the browser saves open page URLs and cookies, restarts, and restores them. This helps avoid memory leaks in long-running sessions.

func WithAutoFreeCallback 

func WithAutoFreeCallback(fn func()) Option

WithAutoFreeCallback sets a function called before each browser recycle.

func WithBlockPatterns 

func WithBlockPatterns(patterns ...string) Option

WithBlockPatterns sets URL patterns to block on every new page. Patterns use wildcards (*) — e.g. "*.css", "*analytics*". Use preset slices (BlockAds, BlockTrackers, BlockFonts, BlockImages) or custom patterns.

Example 
package main

import (
	"fmt"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	// Block ads and trackers for faster, cleaner scraping.
	b, err := scout.New(
		scout.WithHeadless(true),
		scout.WithBlockPatterns(scout.BlockAds...),
		scout.WithBlockPatterns(scout.BlockTrackers...),
		scout.WithBlockPatterns(scout.BlockFonts...),
	)
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = b.Close() }()

	page, err := b.NewPage("https://example.com")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	_ = page.WaitLoad()
	title, _ := page.Title()
	fmt.Println(title)
}

func WithBridge 

func WithBridge() Option

WithBridge enables the built-in Scout Bridge extension for bidirectional Go↔browser communication via CDP bindings. The extension is embedded for security and written to a temp directory at startup. Enabled by default; disable with WithoutBridge() or SCOUT_BRIDGE=false.

func WithBridgePort 

func WithBridgePort(port int) Option

WithBridgePort sets the port for the Bridge WebSocket server. When set and bridge is enabled, a WebSocket server starts at ws://127.0.0.1:{port}/bridge allowing browser extensions to communicate bidirectionally with Go. Use port 0 for auto-assigned port.

func WithBrowser 

func WithBrowser(bt BrowserType) Option

WithBrowser selects which Chromium-based browser to use. Default: chrome (rod auto-detect). This is ignored if WithExecPath is also set.

func WithDevTools 

func WithDevTools() Option

WithDevTools opens Chrome DevTools automatically for each new tab.

func WithElectronApp 

func WithElectronApp(path string) Option

WithElectronApp sets the path to an Electron app directory or packaged binary. The Electron runtime will be used instead of Chrome/Chromium.

func WithElectronCDP 

func WithElectronCDP(endpoint string) Option

WithElectronCDP connects to an already-running Electron app via its CDP endpoint.

func WithElectronVersion 

func WithElectronVersion(version string) Option

WithElectronVersion sets the Electron version to download (e.g. "v33.2.0"). If the version is not cached locally, it will be downloaded from GitHub releases.

func WithEnv 

func WithEnv(env ...string) Option

WithEnv sets additional environment variables for the browser process.

func WithExecPath 

func WithExecPath(path string) Option

WithExecPath sets the path to the browser executable.

func WithExtension 

func WithExtension(paths ...string) Option

WithExtension loads one or more unpacked Chrome extensions by directory path. Extensions require --load-extension and --disable-extensions-except launch flags which are set automatically at browser startup.

func WithExtensionByID 

func WithExtensionByID(ids ...string) Option

WithExtensionByID loads one or more Chrome extensions by their Chrome Web Store ID. The extensions must have been previously downloaded with DownloadExtension.

func WithFingerprint 

func WithFingerprint(fp *Fingerprint) Option

WithFingerprint applies a specific fingerprint to the browser session. The fingerprint JS is injected via EvalOnNewDocument on every new page.

func WithFingerprintRotation 

func WithFingerprintRotation(cfg FingerprintRotationConfig) Option

WithFingerprintRotation enables automatic fingerprint rotation. When set, a new fingerprint is generated or selected according to the strategy (per-session, per-page, per-domain, or time interval). This overrides WithFingerprint and WithRandomFingerprint.

func WithHeadless 

func WithHeadless(v bool) Option

WithHeadless sets whether the browser runs in headless mode. Default: true.

func WithHijackFilter 

func WithHijackFilter(f HijackFilter) Option

WithHijackFilter sets the filter for session hijacking.

func WithIgnoreCerts 

func WithIgnoreCerts() Option

WithIgnoreCerts disables TLS certificate verification.

func WithIncognito 

func WithIncognito() Option

WithIncognito opens the browser in incognito mode.

func WithInjectCode 

func WithInjectCode(code ...string) Option

WithInjectCode injects raw JavaScript code strings into every new page via EvalOnNewDocument before any page scripts run.

func WithInjectDir 

func WithInjectDir(dir string) Option

WithInjectDir loads all .js files from a directory for injection into every new page. Files are sorted alphabetically for deterministic injection order.

func WithInjectJS 

func WithInjectJS(paths ...string) Option

WithInjectJS loads JavaScript files that are injected into every new page via EvalOnNewDocument before any page scripts run.

func WithLaunchFlag 

func WithLaunchFlag(name string, values ...string) Option

WithLaunchFlag adds a custom Chrome CLI flag. The name should not include the "--" prefix.

func WithMaximized 

func WithMaximized() Option

WithMaximized is a convenience shortcut for WithWindowState(WindowStateMaximized).

func WithMobile added in v1.0.0 

func WithMobile(cfg MobileConfig) Option

WithMobile configures the browser for mobile device automation via ADB. It connects to an Android device's Chrome browser via CDP port forwarding.

func WithNoSandbox 

func WithNoSandbox() Option

WithNoSandbox disables the browser sandbox. Use only in containers.

func WithProfile 

func WithProfile(path string) Option

WithProfile returns an Option that loads a profile from disk and applies browser-level settings (user agent, proxy, window size) at launch time. Page-level settings (cookies, storage, headers) must be applied after page creation via Page.ApplyProfile.

func WithProfileData 

func WithProfileData(p *UserProfile) Option

WithProfileData applies an in-memory profile to browser options.

func WithProxy 

func WithProxy(proxy string) Option

WithProxy sets the proxy server URL (e.g. "socks5://127.0.0.1:1080").

func WithProxyAuth 

func WithProxyAuth(username, password string) Option

WithProxyAuth sets username and password for proxy authentication. This configures Chrome's Fetch.AuthRequired handler to automatically respond to proxy auth challenges.

func WithProxyChain 

func WithProxyChain(hops ...ProxyHop) Option

WithProxyChain configures a proxy chain. The browser connects through the first hop. If only one hop is provided, it behaves identically to WithProxy.

For multi-hop chains, the last hop is the exit proxy (closest to the target). Intermediate hops must be configured to forward to the next hop externally, since Chrome's --proxy-server only accepts a single upstream proxy.

Common patterns:

  • Single hop: WithProxyChain(ProxyHop{URL: "socks5://localhost:1080"})
  • Two-hop with gost: gost -L :1080 -F socks5://hop1:1080 -F http://hop2:8080 then: WithProxyChain(ProxyHop{URL: "socks5://localhost:1080"})

func WithRandomFingerprint 

func WithRandomFingerprint(opts ...FingerprintOption) Option

WithRandomFingerprint generates a random fingerprint with the given options and applies it to the browser session.

func WithRemoteCDP 

func WithRemoteCDP(endpoint string) Option

WithRemoteCDP connects to an existing Chrome DevTools Protocol endpoint instead of launching a local browser. Use this for managed browser services (BrightData, Browserless, etc.) or remote Chrome instances. Most launch-related options (execPath, proxy, noSandbox, extensions, etc.) are ignored when a remote endpoint is set.

The endpoint should be a WebSocket URL, e.g. "ws://127.0.0.1:9222".

Example 
package main

import (
	"fmt"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires remote browser
	// Connect to an existing Chrome instance or managed service.
	b, err := scout.New(
		scout.WithRemoteCDP("ws://127.0.0.1:9222"),
	)
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = b.Close() }()

	page, err := b.NewPage("https://example.com")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	_ = page.WaitLoad()
	title, _ := page.Title()
	fmt.Println(title)
}

func WithReusableSession 

func WithReusableSession() Option

WithReusableSession enables session reuse via scout.pid. When enabled, the browser data directory is preserved after close and can be reused by subsequent browser instances with matching browser type and headless mode.

func WithSessionHijack 

func WithSessionHijack() Option

WithSessionHijack enables automatic session hijacking on new pages. When enabled, NewPage will auto-create a SessionHijacker.

func WithSessionID 

func WithSessionID(id string) Option

WithSessionID reuses a specific session by its UUID from scout.pid. The session's data directory will be used and the session is automatically marked as reusable. If the session ID is not found, a new session is created. Use Browser.SessionID() to retrieve the active session ID.

func WithSlowMotion 

func WithSlowMotion(d time.Duration) Option

WithSlowMotion adds a delay between actions for debugging.

func WithSmartWait 

func WithSmartWait() Option

WithSmartWait enables framework-aware waiting on NewPage. When enabled, NewPage will call WaitFrameworkReady after page creation, which detects the frontend framework and waits for it to finish hydrating/rendering.

func WithStealth 

func WithStealth() Option

WithStealth enables stealth mode to avoid bot detection.

Example 
package main

import (
	"fmt"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	// WithStealth enables anti-bot-detection evasions:
	// automation flag removal, JS property masking, etc.
	b, err := scout.New(
		scout.WithHeadless(true),
		scout.WithStealth(),
	)
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = b.Close() }()

	page, err := b.NewPage("https://bot.sannysoft.com")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	_ = page.WaitLoad()
	title, _ := page.Title()
	fmt.Println(title)
}

func WithSystemBrowser 

func WithSystemBrowser() Option

WithSystemBrowser opts in to scanning system-installed browsers (Program Files, /usr/bin, etc.). Without this option, only browsers in ~/.scout/browsers/ are used.

func WithTLSProfile 

func WithTLSProfile(profile string) Option

WithTLSProfile sets the TLS/HTTP fingerprint profile for the browser. Supported profiles:

  • "chrome": default Chrome TLS stack (no extra flags)
  • "randomized": disables HTTP/2 to vary the HTTP fingerprint

For fine-grained TLS/JA3 fingerprint control, use a TLS proxy such as utls-based MITM proxies (e.g. cycletls, got-scraping) in combination with WithProxy, since Chrome does not expose cipher-suite ordering via command-line flags.

func WithTargetURL 

func WithTargetURL(url string) Option

WithTargetURL sets the target URL for domain-based session routing. Sessions are automatically matched by root domain hash, so "https://sub.mysite.com" and "https://admin.mysite.com" share the same session.

func WithTimeout 

func WithTimeout(d time.Duration) Option

WithTimeout sets the default timeout for all operations. Default: 30s.

func WithTouchEmulation added in v1.0.0 

func WithTouchEmulation() Option

WithTouchEmulation enables touch event simulation without a physical device. Use with device emulation (WithDevice) for mobile testing on desktop.

func WithUserAgent 

func WithUserAgent(ua string) Option

WithUserAgent sets a custom User-Agent string.

func WithUserAgentMetadata 

func WithUserAgentMetadata(meta *proto.EmulationUserAgentMetadata) Option

WithUserAgentMetadata sets User Agent Client Hints metadata (Sec-CH-UA-*). This controls what navigator.userAgentData returns in JavaScript.

func WithUserDataDir 

func WithUserDataDir(dir string) Option

WithUserDataDir sets the browser user data directory for persistent sessions.

func WithVPN 

func WithVPN(provider VPNProvider) Option

WithVPN sets the VPN provider for proxy-based connectivity. The provider's Connect is called during browser creation to obtain the proxy URL.

func WithVPNRotation 

func WithVPNRotation(cfg VPNRotationConfig) Option

WithVPNRotation enables automatic server rotation through the configured VPN provider.

func WithWebMCPAutoDiscover 

func WithWebMCPAutoDiscover() Option

WithWebMCPAutoDiscover enables automatic scanning for WebMCP tools after each page load. When enabled, the Browser initializes a WebMCPRegistry that accumulates discovered tools across all pages. Use Browser.WebMCPRegistry() to access the collected tools.

func WithWindowSize 

func WithWindowSize(w, h int) Option

WithWindowSize sets the browser window dimensions. Default: 1920x1080.

Example 
package main

import (
	"fmt"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	// Set a custom viewport size (width x height in pixels).
	b, err := scout.New(
		scout.WithHeadless(true),
		scout.WithWindowSize(1440, 900),
	)
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = b.Close() }()

	page, err := b.NewPage("https://example.com")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	_ = page.WaitLoad()
	title, _ := page.Title()
	fmt.Println(title)
}

func WithWindowState 

func WithWindowState(state WindowState) Option

WithWindowState sets the initial window state for new pages.

func WithXvfb 

func WithXvfb(args ...string) Option

WithXvfb enables Xvfb (X Virtual Framebuffer) for headful mode on systems without a display server. Optional args are passed to xvfb-run.

func WithoutBridge 

func WithoutBridge() Option

WithoutBridge disables the built-in Scout Bridge extension.

type PDFFormField added in v0.56.0 

type PDFFormField struct {
	Name     string `json:"name"`
	Type     string `json:"type"` // text, checkbox, radio, select, button
	Value    string `json:"value"`
	Required bool   `json:"required"`
	ReadOnly bool   `json:"read_only"`
	Page     int    `json:"page"`
}

PDFFormField represents a fillable field in a PDF form rendered by Chrome's PDF viewer.

type PDFOptions 

type PDFOptions struct {
	Landscape           bool
	DisplayHeaderFooter bool
	PrintBackground     bool
	Scale               float64
	PaperWidth          float64
	PaperHeight         float64
	MarginTop           float64
	MarginBottom        float64
	MarginLeft          float64
	MarginRight         float64
	PageRanges          string
	HeaderTemplate      string
	FooterTemplate      string
}

PDFOptions configures PDF generation.

type PWAInfo 

type PWAInfo = detect.PWAInfo

type Page 

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

Page wraps a rod page (browser tab) with a simplified API.

func (*Page) Activate 

func (p *Page) Activate() error

Activate brings this page to the foreground.

func (*Page) AddScriptTag 

func (p *Page) AddScriptTag(url, content string) error

AddScriptTag injects a <script> tag. Provide either a URL or inline content.

func (*Page) AddStyleTag 

func (p *Page) AddStyleTag(url, content string) error

AddStyleTag injects a <style> tag. Provide either a URL or inline content.

func (*Page) ApplyProfile 

func (p *Page) ApplyProfile(prof *UserProfile) error

ApplyProfile restores page-level state from a UserProfile: cookies, storage, and headers. Call this after page creation and navigation to the target origin.

func (*Page) Block 

func (p *Page) Block(patterns ...string) error

Block is a convenience alias for SetBlockedURLs. It blocks requests matching the given URL patterns on this page. Use preset slices (BlockAds, BlockTrackers, BlockFonts, BlockImages) or custom wildcard patterns.

Example 
package main

import (
	"fmt"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	b, err := scout.New(scout.WithHeadless(true))
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = b.Close() }()

	page, err := b.NewPage("https://example.com")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	// Block images on this specific page.
	_ = page.Block(scout.BlockImages...)

	_ = page.Navigate("https://example.com")
	_ = page.WaitLoad()
}

func (*Page) Bridge 

func (p *Page) Bridge(opts ...BridgeOption) (*Bridge, error)

Bridge returns the bridge for this page, initializing it on first call. The bridge sets up a CDP binding (__scoutSend) and a command dispatcher so Go and the content script can exchange messages.

func (*Page) CallWebMCPTool 

func (p *Page) CallWebMCPTool(name string, params map[string]any) (*WebMCPToolResult, error)

CallWebMCPTool invokes a discovered WebMCP tool by name with the given parameters. It first discovers tools on the page, finds the named tool, and calls it. If the tool has a server_url, it sends a JSON-RPC 2.0 POST request. Otherwise, it tries calling window.__mcp_tools[name](params) in the page context.

func (*Page) ClearCookies 

func (p *Page) ClearCookies() error

ClearCookies removes all cookies from the page.

func (*Page) Close 

func (p *Page) Close() error

Close closes the page (tab).

func (*Page) CollectInfo 

func (p *Page) CollectInfo() (*PageInfo, error)

CollectInfo gathers browser environment info via the bridge extension's page.info command. Falls back to CDP evaluation if the bridge is unavailable. The result is cached on the page.

func (*Page) CompareScreenshots 

func (p *Page) CompareScreenshots(baseline []byte, opts ...VisualDiffOption) (*VisualDiffResult, error)

CompareScreenshots is a convenience method on Page that takes a baseline screenshot and compares it with a fresh screenshot of the current page state.

func (*Page) DetectChallenge 

func (p *Page) DetectChallenge() (*ChallengeInfo, error)

DetectChallenge returns the highest-confidence challenge, or nil if none detected.

func (*Page) DetectChallenges 

func (p *Page) DetectChallenges() ([]ChallengeInfo, error)

DetectChallenges returns all bot protection challenges detected on the page.

func (*Page) DetectForm 

func (p *Page) DetectForm(selector string) (*Form, error)

DetectForm finds a specific form by CSS selector.

func (*Page) DetectForms 

func (p *Page) DetectForms() ([]*Form, error)

DetectForms finds all <form> elements on the page and returns parsed Form objects.

func (*Page) DetectFramework 

func (p *Page) DetectFramework() (*FrameworkInfo, error)

DetectFramework returns the primary detected framework, or nil if none found. When multiple frameworks are detected (e.g. React + Next.js), the meta-framework (Next.js, Nuxt, SvelteKit, Remix, Gatsby) takes precedence.

func (*Page) DetectFrameworks 

func (p *Page) DetectFrameworks() ([]FrameworkInfo, error)

DetectFrameworks inspects the current page for frontend framework markers. Returns all detected frameworks. The page should be loaded (call WaitLoad first).

func (*Page) DetectPWA 

func (p *Page) DetectPWA() (*PWAInfo, error)

DetectPWA checks whether the current page is a Progressive Web App. Detects service workers, web app manifest, installability, HTTPS, and push capability. The page should be loaded (call WaitLoad first).

func (*Page) DetectRenderMode 

func (p *Page) DetectRenderMode() (*RenderInfo, error)

DetectRenderMode classifies the current page's rendering mode (CSR, SSR, SSG, ISR). The page should be loaded (call WaitLoad first).

func (*Page) DetectSwagger 

func (p *Page) DetectSwagger() (string, error)

DetectSwagger checks if the current page is a Swagger/OpenAPI UI and returns the spec URL if found.

func (*Page) DetectTechStack 

func (p *Page) DetectTechStack() (*TechStack, error)

DetectTechStack inspects the current page for CSS frameworks, build tools, CMS, analytics, and CDN. Also includes framework detection from DetectFrameworks. The page should be loaded (call WaitLoad first).

func (*Page) DiscoverWebMCPTools 

func (p *Page) DiscoverWebMCPTools() ([]WebMCPTool, error)

DiscoverWebMCPTools scans the current page for MCP tool declarations. Checks: <meta name="mcp-server">, <meta name="mcp-tools">, <link rel="mcp">, <script type="application/mcp+json">, and /.well-known/mcp endpoint.

func (*Page) Element 

func (p *Page) Element(selector string) (*Element, error)

Element finds the first element matching the CSS selector.

Example 
package main

import (
	"fmt"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	b, err := scout.New(scout.WithHeadless(true))
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = b.Close() }()

	page, err := b.NewPage("https://example.com")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	_ = page.WaitLoad()

	// Find an element by CSS selector.
	el, err := page.Element("h1")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	text, _ := el.Text()
	fmt.Println(text)
}

func (*Page) ElementByJS 

func (p *Page) ElementByJS(js string, args ...any) (*Element, error)

ElementByJS finds an element using a JavaScript expression.

func (*Page) ElementByRef 

func (p *Page) ElementByRef(ref string) (*Element, error)

ElementByRef finds an element by its snapshot reference marker. The ref should be in the format "s{gen}e{id}" as produced by Snapshot().

func (*Page) ElementByText 

func (p *Page) ElementByText(selector, regex string) (*Element, error)

ElementByText finds the first element matching the CSS selector whose text matches the regex.

func (*Page) ElementByXPath 

func (p *Page) ElementByXPath(xpath string) (*Element, error)

ElementByXPath finds the first element matching the XPath expression.

func (*Page) ElementFromPoint 

func (p *Page) ElementFromPoint(x, y int) (*Element, error)

ElementFromPoint finds the element at the given page coordinates.

func (*Page) Elements 

func (p *Page) Elements(selector string) ([]*Element, error)

Elements finds all elements matching the CSS selector.

func (*Page) ElementsByXPath 

func (p *Page) ElementsByXPath(xpath string) ([]*Element, error)

ElementsByXPath finds all elements matching the XPath expression.

func (*Page) Emulate 

func (p *Page) Emulate(device devices.Device) error

Emulate configures the page to emulate a specific device.

func (*Page) Eval 

func (p *Page) Eval(js string, args ...any) (*EvalResult, error)

Eval evaluates JavaScript on the page and returns the result.

Example 
package main

import (
	"fmt"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	b, err := scout.New(scout.WithHeadless(true))
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = b.Close() }()

	page, err := b.NewPage("https://example.com")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	result, err := page.Eval("() => document.querySelectorAll('a').length")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	count := result.Int()
	fmt.Printf("Links: %d\n", count)
}

func (*Page) EvalOnNewDocument 

func (p *Page) EvalOnNewDocument(js string) (remove func() error, err error)

EvalOnNewDocument registers JavaScript to run on every new document before any page scripts. Returns a function to remove the script.

Example 
package main

import (
	"fmt"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	b, err := scout.New(scout.WithHeadless(true))
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = b.Close() }()

	page, err := b.NewPage("")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	// Inject JS that runs before any page script. Returns a cleanup function.
	remove, err := page.EvalOnNewDocument(`window.__injected = true`)
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	_ = page.Navigate("https://example.com")
	_ = page.WaitLoad()

	// Clean up the injection when no longer needed.
	if err := remove(); err != nil {
		fmt.Println("error:", err)
	}
}

func (*Page) Extract 

func (p *Page) Extract(target any, _ ...ExtractOption) error

Extract populates a struct from the page DOM using `scout:"selector"` tags.

Tag format: 

`scout:"css-selector"`       — extracts text content
`scout:"css-selector@attr"`  — extracts attribute value

Supported field types: string, int, int64, float64, bool, []string, nested struct (selector scopes a container), []struct (one per match).

Example 
package main

import (
	"fmt"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	type Product struct {
		Name  string `scout:"h2.title"`
		Price string `scout:"span.price"`
		Image string `scout:"img.hero@src"`
	}

	b, err := scout.New(scout.WithHeadless(true))
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = b.Close() }()

	page, err := b.NewPage("https://shop.example.com/product/1")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	_ = page.WaitLoad()

	var p Product
	if err := page.Extract(&p); err != nil {
		fmt.Println("error:", err)
		return
	}

	fmt.Printf("Name: %s, Price: %s\n", p.Name, p.Price)
}

func (*Page) ExtractAll 

func (p *Page) ExtractAll(req *ExtractionRequest) *ExtractionResult

ExtractAll runs all requested extractions on the page. Errors are collected in result.Errors rather than returned, so partial results are always available.

func (*Page) ExtractAttribute 

func (p *Page) ExtractAttribute(selector, attr string) (string, error)

ExtractAttribute extracts an attribute value from the first matching element.

func (*Page) ExtractAttributes 

func (p *Page) ExtractAttributes(selector, attr string) ([]string, error)

ExtractAttributes extracts an attribute value from all matching elements. 

func (p *Page) ExtractLinks() ([]string, error)

ExtractLinks extracts all href values from <a> elements on the page.

func (*Page) ExtractMeta 

func (p *Page) ExtractMeta() (*MetaData, error)

ExtractMeta extracts common page metadata.

func (*Page) ExtractSwagger 

func (p *Page) ExtractSwagger(opts ...SwaggerOption) (*SwaggerSpec, error)

ExtractSwagger detects a Swagger/OpenAPI UI on the current page, fetches the spec, and returns a parsed SwaggerSpec.

func (*Page) ExtractTable 

func (p *Page) ExtractTable(selector string) (*TableData, error)

ExtractTable extracts an HTML table into structured data.

func (*Page) ExtractTableMap 

func (p *Page) ExtractTableMap(selector string) ([]map[string]string, error)

ExtractTableMap extracts an HTML table as a slice of maps keyed by header text.

func (*Page) ExtractText 

func (p *Page) ExtractText(selector string) (string, error)

ExtractText extracts the text content of the first element matching the selector.

func (*Page) ExtractTexts 

func (p *Page) ExtractTexts(selector string) ([]string, error)

ExtractTexts extracts the text content of all elements matching the selector.

func (*Page) ExtractWithLLM 

func (p *Page) ExtractWithLLM(prompt string, opts ...LLMOption) (string, error)

ExtractWithLLM sends the page content to an LLM with the given prompt and returns the response.

func (*Page) ExtractWithLLMJSON 

func (p *Page) ExtractWithLLMJSON(prompt string, target any, opts ...LLMOption) error

ExtractWithLLMJSON sends the page content to an LLM and decodes the JSON response into target.

func (*Page) ExtractWithLLMReview 

func (p *Page) ExtractWithLLMReview(prompt string, opts ...LLMOption) (*LLMJobResult, error)

ExtractWithLLMReview extracts page content with an LLM, then optionally reviews the output with a second LLM provider. Results are persisted to the workspace if set.

func (*Page) FillPDFForm added in v0.56.0 

func (p *Page) FillPDFForm(fields map[string]string) error

FillPDFForm fills form fields in a PDF rendered by the browser. The fields map keys are field names, values are the values to fill.

func (*Page) FullScreenshot 

func (p *Page) FullScreenshot() ([]byte, error)

FullScreenshot captures a full-page screenshot as PNG bytes.

func (*Page) Fullscreen 

func (p *Page) Fullscreen() error

Fullscreen puts the browser window into fullscreen mode.

func (*Page) GetCookies 

func (p *Page) GetCookies(urls ...string) ([]Cookie, error)

GetCookies returns cookies for the current page or the given URLs.

func (*Page) GetWindow 

func (p *Page) GetWindow() (*WindowBounds, error)

GetWindow returns the current browser window bounds and state.

func (*Page) HTML 

func (p *Page) HTML() (string, error)

HTML returns the full HTML content of the page.

func (*Page) HandleDialog 

func (p *Page) HandleDialog() (wait func() *proto2.PageJavascriptDialogOpening, handle func(*proto2.PageHandleJavaScriptDialog) error)

HandleDialog returns functions to wait for and handle JavaScript dialogs (alert, confirm, prompt). Call wait() to block until a dialog appears, then call handle() to accept/dismiss it.

func (*Page) Has 

func (p *Page) Has(selector string) (bool, error)

Has returns true if an element matching the CSS selector exists.

func (*Page) HasChallenge 

func (p *Page) HasChallenge() (bool, error)

HasChallenge returns true if any bot protection challenge is detected.

func (*Page) HasXPath 

func (p *Page) HasXPath(xpath string) (bool, error)

HasXPath returns true if an element matching the XPath exists.

func (*Page) Hijack 

func (p *Page) Hijack(pattern string, handler HijackHandler) (*HijackRouter, error)

Hijack creates a request hijack router for the page. The pattern uses glob-style matching (e.g. "*api*", "*.js"). Call Run() on the returned router in a goroutine, and Stop() when done.

Example 
package main

import (
	"fmt"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	b, err := scout.New(scout.WithHeadless(true))
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = b.Close() }()

	page, err := b.NewPage("")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	// Block all image requests.
	router, err := page.Hijack("*.png", func(ctx *scout.HijackContext) {
		ctx.Response().Fail("BlockedByClient")
	})
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	go router.Run()

	defer func() { _ = router.Stop() }()

	_ = page.Navigate("https://example.com")
}

func (*Page) Hijacker 

func (p *Page) Hijacker() *SessionHijacker

Hijacker returns the session hijacker attached to this page, or nil.

func (*Page) Info 

func (p *Page) Info() *PageInfo

Info returns the page environment info collected via the bridge extension. Returns nil if info has not been collected yet.

func (*Page) KeyPress 

func (p *Page) KeyPress(key input.Key) error

KeyPress presses and releases a single keyboard key on the page.

Example 
package main

import (
	"fmt"

	"github.com/inovacc/scout/internal/engine/lib/input"
	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	b, err := scout.New(scout.WithHeadless(true))
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = b.Close() }()

	page, err := b.NewPage("https://example.com")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	// Press Enter at the page level.
	_ = page.KeyPress(input.Enter)

	// Type text at the page level (sends key-by-key).
	_ = page.KeyType('h', 'i')
}

func (*Page) KeyType 

func (p *Page) KeyType(keys ...input.Key) error

KeyType types a sequence of keyboard keys on the page.

func (*Page) LoadCookiesFromFile 

func (p *Page) LoadCookiesFromFile(path string) error

LoadCookiesFromFile reads cookies from a JSON file and sets them on the page.

func (*Page) LoadSession 

func (p *Page) LoadSession(state *SessionState) error

LoadSession navigates to the saved URL and restores cookies, localStorage, and sessionStorage.

func (*Page) LocalStorageClear 

func (p *Page) LocalStorageClear() error

LocalStorageClear removes all keys from localStorage.

func (*Page) LocalStorageGet 

func (p *Page) LocalStorageGet(key string) (string, error)

LocalStorageGet returns the value for the given key from localStorage.

func (*Page) LocalStorageGetAll 

func (p *Page) LocalStorageGetAll() (map[string]string, error)

LocalStorageGetAll returns all key-value pairs from localStorage.

func (*Page) LocalStorageLength 

func (p *Page) LocalStorageLength() (int, error)

LocalStorageLength returns the number of keys in localStorage.

func (*Page) LocalStorageRemove 

func (p *Page) LocalStorageRemove(key string) error

LocalStorageRemove deletes the given key from localStorage.

func (*Page) LocalStorageSet 

func (p *Page) LocalStorageSet(key, value string) error

LocalStorageSet stores a key-value pair in localStorage.

func (*Page) Markdown 

func (p *Page) Markdown(opts ...MarkdownOption) (string, error)

Markdown converts the page HTML to Markdown.

Example 
package main

import (
	"fmt"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	b, err := scout.New(scout.WithHeadless(true))
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = b.Close() }()

	page, err := b.NewPage("https://example.com")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	_ = page.WaitLoad()

	// Full page as markdown.
	md, err := page.Markdown()
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	fmt.Println(md)
}

func (*Page) MarkdownContent 

func (p *Page) MarkdownContent(opts ...MarkdownOption) (string, error)

MarkdownContent converts only the main content of the page to Markdown.

Example 
package main

import (
	"fmt"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	b, err := scout.New(scout.WithHeadless(true))
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = b.Close() }()

	page, err := b.NewPage("https://example.com")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	_ = page.WaitLoad()

	// Main content only — strips nav, footer, sidebar.
	md, err := page.MarkdownContent()
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	fmt.Println(md)
}

func (*Page) Maximize 

func (p *Page) Maximize() error

Maximize maximizes the browser window.

func (*Page) Minimize 

func (p *Page) Minimize() error

Minimize minimizes the browser window.

func (*Page) MonitorWebSockets added in v0.72.0 

func (p *Page) MonitorWebSockets(opts ...WebSocketOption) (<-chan WebSocketMessage, func(), error)

MonitorWebSockets starts monitoring WebSocket traffic on the page via CDP events. Returns a channel that emits WebSocket messages as they occur.

func (*Page) Navigate 

func (p *Page) Navigate(url string) error

Navigate loads the given URL in the page.

func (*Page) NavigateBack 

func (p *Page) NavigateBack() error

NavigateBack navigates to the previous page in history.

func (*Page) NavigateForward 

func (p *Page) NavigateForward() error

NavigateForward navigates to the next page in history.

func (*Page) NavigateWithRetry 

func (p *Page) NavigateWithRetry(url string, rl *RateLimiter) error

NavigateWithRetry navigates to the URL using the rate limiter for pacing and retry.

func (*Page) NewFormWizard 

func (p *Page) NewFormWizard(steps ...WizardStep) *FormWizard

NewFormWizard creates a wizard for multi-step form interaction.

func (*Page) NewSessionHijacker 

func (p *Page) NewSessionHijacker(opts ...HijackOption) (*SessionHijacker, error)

NewSessionHijacker creates a hijacker that immediately begins capturing network traffic.

func (*Page) PDF 

func (p *Page) PDF() ([]byte, error)

PDF generates a PDF of the current page with default settings.

func (*Page) PDFFormFields added in v0.56.0 

func (p *Page) PDFFormFields() ([]PDFFormField, error)

PDFFormFields detects fillable form fields in a PDF rendered by the browser. The page must have already navigated to a PDF URL.

func (*Page) PDFWithOptions 

func (p *Page) PDFWithOptions(opts PDFOptions) ([]byte, error)

PDFWithOptions generates a PDF with custom options.

func (*Page) PinchZoom added in v1.0.0 

func (p *Page) PinchZoom(cx, cy, scale float64) error

PinchZoom performs a pinch zoom gesture centered at (cx, cy). scale > 1.0 zooms in, scale < 1.0 zooms out.

func (*Page) Race 

func (p *Page) Race(selectors ...string) (*Element, int, error)

Race creates an element race - the first selector to match wins. Returns the matched element and its index in the selectors list.

func (*Page) Reload 

func (p *Page) Reload() error

Reload refreshes the current page.

func (*Page) RestoreWindow 

func (p *Page) RestoreWindow() error

RestoreWindow restores the browser window to its normal state.

func (*Page) RodPage 

func (p *Page) RodPage() *rodPage

RodPage returns the underlying rod.Page for advanced use cases.

func (*Page) SaveCookiesToFile 

func (p *Page) SaveCookiesToFile(path string, includeSession bool) error

SaveCookiesToFile exports the page's cookies to a JSON file. Only non-session cookies (with an expiry) are saved by default. Pass includeSession=true to include session cookies as well.

Example 
package main

import (
	"fmt"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	b, err := scout.New(scout.WithHeadless(true))
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = b.Close() }()

	page, err := b.NewPage("https://example.com")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	_ = page.WaitLoad()

	// Persist cookies to a file (excluding session cookies).
	if err := page.SaveCookiesToFile("cookies.json", false); err != nil {
		fmt.Println("error:", err)
		return
	}

	fmt.Println("Cookies saved")
}

func (*Page) SaveSession 

func (p *Page) SaveSession() (*SessionState, error)

SaveSession captures the current URL, cookies, localStorage, and sessionStorage.

func (*Page) Screenshot 

func (p *Page) Screenshot() ([]byte, error)

Screenshot captures a screenshot of the visible viewport as PNG bytes.

Example 
package main

import (
	"fmt"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	b, err := scout.New(scout.WithHeadless(true))
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = b.Close() }()

	page, err := b.NewPage("https://example.com")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	_ = page.WaitLoad()

	// Viewport screenshot.
	data, err := page.Screenshot()
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	fmt.Printf("Screenshot: %d bytes\n", len(data))
}

func (*Page) ScreenshotJPEG 

func (p *Page) ScreenshotJPEG(quality int) ([]byte, error)

ScreenshotJPEG captures a viewport screenshot in JPEG format with the given quality (0-100).

func (*Page) ScreenshotPNG 

func (p *Page) ScreenshotPNG() ([]byte, error)

ScreenshotPNG captures a viewport screenshot in PNG format.

func (*Page) ScrollScreenshot 

func (p *Page) ScrollScreenshot() ([]byte, error)

ScrollScreenshot captures a scrolling screenshot of the entire page.

func (*Page) Search 

func (p *Page) Search(query string) (*Element, error)

Search finds the first element matching the query using Chrome DevTools search. The query can be a CSS selector, XPath expression, or text.

func (*Page) SendWebSocketMessage added in v0.72.0 

func (p *Page) SendWebSocketMessage(url, data string) error

SendWebSocketMessage sends a message to a WebSocket connection on the page via JS eval.

func (*Page) SessionStorageClear 

func (p *Page) SessionStorageClear() error

SessionStorageClear removes all keys from sessionStorage.

func (*Page) SessionStorageGet 

func (p *Page) SessionStorageGet(key string) (string, error)

SessionStorageGet returns the value for the given key from sessionStorage.

func (*Page) SessionStorageGetAll 

func (p *Page) SessionStorageGetAll() (map[string]string, error)

SessionStorageGetAll returns all key-value pairs from sessionStorage.

func (*Page) SessionStorageLength 

func (p *Page) SessionStorageLength() (int, error)

SessionStorageLength returns the number of keys in sessionStorage.

func (*Page) SessionStorageRemove 

func (p *Page) SessionStorageRemove(key string) error

SessionStorageRemove deletes the given key from sessionStorage.

func (*Page) SessionStorageSet 

func (p *Page) SessionStorageSet(key, value string) error

SessionStorageSet stores a key-value pair in sessionStorage.

func (*Page) SetBlockedURLs 

func (p *Page) SetBlockedURLs(urls ...string) error

SetBlockedURLs blocks requests matching the given URL patterns. Wildcards (*) are supported (e.g. "*.css", "*analytics*").

func (*Page) SetCookies 

func (p *Page) SetCookies(cookies ...Cookie) error

SetCookies sets cookies on the page.

func (*Page) SetDocumentContent 

func (p *Page) SetDocumentContent(html string) error

SetDocumentContent replaces the page's document HTML.

func (*Page) SetHeaders 

func (p *Page) SetHeaders(headers map[string]string) (cleanup func(), err error)

SetHeaders sets extra HTTP headers for all requests from this page. Returns a cleanup function that removes the headers.

func (*Page) SetUserAgent 

func (p *Page) SetUserAgent(ua string) error

SetUserAgent overrides the User-Agent for this page.

func (*Page) SetViewport 

func (p *Page) SetViewport(width, height int) error

SetViewport sets the page viewport dimensions.

func (*Page) SetWindow 

func (p *Page) SetWindow(left, top, width, height int) error

SetWindow sets the browser window bounds.

func (*Page) Snapshot 

func (p *Page) Snapshot() (string, error)

Snapshot returns a YAML-like accessibility tree of the current page.

func (*Page) SnapshotWithOptions 

func (p *Page) SnapshotWithOptions(opts ...SnapshotOption) (string, error)

SnapshotWithOptions returns an accessibility tree with the given options.

func (*Page) StopLoading 

func (p *Page) StopLoading() error

StopLoading stops all pending navigation and resource loading.

func (*Page) Swipe added in v1.0.0 

func (p *Page) Swipe(startX, startY, endX, endY float64, duration time.Duration) error

Swipe performs a swipe gesture from (startX, startY) to (endX, endY).

func (*Page) Title 

func (p *Page) Title() (string, error)

Title returns the current page title.

func (*Page) Touch added in v1.0.0 

func (p *Page) Touch(x, y float64) error

Touch performs a tap gesture at the given coordinates.

func (*Page) TouchWithPoints added in v1.0.0 

func (p *Page) TouchWithPoints(points []TouchPoint) error

TouchWithPoints dispatches a complete touch sequence (start -> end).

func (*Page) URL 

func (p *Page) URL() (string, error)

URL returns the current page URL.

func (*Page) WaitClose 

func (p *Page) WaitClose() <-chan struct{}

WaitClose returns a channel that is closed when the page's target is destroyed (e.g., the user closes the browser window or tab). Useful for detecting when the user manually closes a headed browser.

func (*Page) WaitDOMStable 

func (p *Page) WaitDOMStable(d time.Duration, diff float64) error

WaitDOMStable waits for the DOM to stop changing. The diff threshold controls sensitivity.

func (*Page) WaitFrameworkReady 

func (p *Page) WaitFrameworkReady() error

WaitFrameworkReady detects the page's framework and waits for it to be fully ready. Falls back to WaitLoad + a short WaitDOMStable if no framework is detected.

Example 
package main

import (
	"fmt"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	b, err := scout.New(scout.WithHeadless(true))
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = b.Close() }()

	page, err := b.NewPage("https://example.com")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	// WaitFrameworkReady detects the frontend framework (React, Vue, Angular, etc.)
	// and waits for its specific readiness signal. Falls back to WaitLoad + DOM stable.
	if err := page.WaitFrameworkReady(); err != nil {
		fmt.Println("error:", err)
		return
	}

	title, _ := page.Title()
	fmt.Println(title)
}

func (*Page) WaitIdle 

func (p *Page) WaitIdle(timeout time.Duration) error

WaitIdle waits for the page to reach an idle state.

func (*Page) WaitLoad 

func (p *Page) WaitLoad() error

WaitLoad waits for the page load event.

Example 
package main

import (
	"fmt"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	b, err := scout.New(scout.WithHeadless(true))
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	defer func() { _ = b.Close() }()

	page, err := b.NewPage("https://example.com")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	// Wait for the DOM load event before extracting content.
	if err := page.WaitLoad(); err != nil {
		fmt.Println("error:", err)
		return
	}

	title, _ := page.Title()
	fmt.Println(title)
}

func (*Page) WaitNavigation 

func (p *Page) WaitNavigation() func()

WaitNavigation returns a function that waits for the next navigation to complete. Call the returned function after triggering navigation.

func (*Page) WaitRequestIdle 

func (p *Page) WaitRequestIdle(d time.Duration, includes, excludes []string) func()

WaitRequestIdle waits for all network requests to settle. The duration specifies how long requests must be idle. Returns a function that blocks until the condition is met.

func (*Page) WaitSafe 

func (p *Page) WaitSafe(d time.Duration) error

WaitSafe waits for the page to be stable, recovering from panics that can occur when the execution context is destroyed during SPA navigation.

func (*Page) WaitSelector 

func (p *Page) WaitSelector(selector string) (*Element, error)

WaitSelector waits until an element matching the CSS selector appears.

func (*Page) WaitStable 

func (p *Page) WaitStable(d time.Duration) error

WaitStable waits for the page to be stable (loaded, idle, and DOM stable) for the given duration.

func (*Page) WaitXPath 

func (p *Page) WaitXPath(xpath string) (*Element, error)

WaitXPath waits until an element matching the XPath expression appears.

type PageCloseCanceledError 

type PageCloseCanceledError struct{}

PageCloseCanceledError error.

func (*PageCloseCanceledError) Error 

func (e *PageCloseCanceledError) Error() string

type PageConnInfo 

type PageConnInfo struct {
	EffectiveType string  `json:"effectiveType"`
	Downlink      float64 `json:"downlink"`
	RTT           int     `json:"rtt"`
	SaveData      bool    `json:"saveData"`
}

PageConnInfo holds network connection info.

type PageDisconnectedError 

type PageDisconnectedError struct{}

PageDisconnectedError is returned when an operation is attempted on a disconnected page.

func (*PageDisconnectedError) Error 

func (e *PageDisconnectedError) Error() string

func (*PageDisconnectedError) Is 

func (e *PageDisconnectedError) Is(err error) bool

Is interface.

type PageInfo 

type PageInfo struct {
	URL                 string           `json:"url"`
	Title               string           `json:"title"`
	UserAgent           string           `json:"userAgent"`
	Platform            string           `json:"platform"`
	Language            string           `json:"language"`
	Languages           []string         `json:"languages"`
	CookieEnabled       bool             `json:"cookieEnabled"`
	DoNotTrack          *string          `json:"doNotTrack"`
	HardwareConcurrency int              `json:"hardwareConcurrency"`
	DeviceMemory        float64          `json:"deviceMemory"`
	MaxTouchPoints      int              `json:"maxTouchPoints"`
	Vendor              string           `json:"vendor"`
	Screen              PageScreenInfo   `json:"screen"`
	Viewport            PageViewportInfo `json:"viewport"`
	Connection          *PageConnInfo    `json:"connection"`
	Timing              *PageTimingInfo  `json:"timing"`
	BrowserVersion      string           `json:"browserVersion"`
}

PageInfo holds browser environment information collected via the bridge extension.

type PageNotFoundError 

type PageNotFoundError struct{}

PageNotFoundError error.

func (*PageNotFoundError) Error 

func (e *PageNotFoundError) Error() string

type PageScreenInfo 

type PageScreenInfo struct {
	Width       int `json:"width"`
	Height      int `json:"height"`
	AvailWidth  int `json:"availWidth"`
	AvailHeight int `json:"availHeight"`
	ColorDepth  int `json:"colorDepth"`
	PixelDepth  int `json:"pixelDepth"`
}

PageScreenInfo holds screen dimensions.

type PageTimingInfo 

type PageTimingInfo struct {
	DOMContentLoaded int `json:"domContentLoaded"`
	LoadEvent        int `json:"loadEvent"`
	DOMInteractive   int `json:"domInteractive"`
}

PageTimingInfo holds performance timing info.

type PageViewportInfo 

type PageViewportInfo struct {
	Width            int     `json:"width"`
	Height           int     `json:"height"`
	DevicePixelRatio float64 `json:"devicePixelRatio"`
}

PageViewportInfo holds viewport dimensions.

type Pages 

type Pages []*rodPage

Pages provides some helpers to deal with page list.

func (Pages) Empty 

func (ps Pages) Empty() bool

Empty returns true if the list is empty.

func (Pages) Find 

func (ps Pages) Find(selector string) (*rodPage, error)

Find the page that has the specified element with the css selector.

func (Pages) FindByURL 

func (ps Pages) FindByURL(jsRegex string) (*rodPage, error)

FindByURL returns the page that has the url that matches the jsRegex.

func (Pages) First 

func (ps Pages) First() *rodPage

First returns the first page, if the list is empty returns nil.

func (Pages) Last 

func (ps Pages) Last() *rodPage

Last returns the last page, if the list is empty returns nil.

func (Pages) MustFind 

func (ps Pages) MustFind(selector string) *rodPage

MustFind is similar to [Browser.Find].

func (Pages) MustFindByURL 

func (ps Pages) MustFindByURL(regex string) *rodPage

MustFindByURL is similar to [Page.FindByURL].

type PaginateOption 

type PaginateOption func(*paginateOptions)

PaginateOption configures pagination behavior.

func WithPaginateDedup 

func WithPaginateDedup(fieldName string) PaginateOption

WithPaginateDedup sets a struct field name to use for deduplication.

func WithPaginateDelay 

func WithPaginateDelay(d time.Duration) PaginateOption

WithPaginateDelay sets the delay between page loads. Default: 500ms.

func WithPaginateMaxPages 

func WithPaginateMaxPages(n int) PaginateOption

WithPaginateMaxPages sets the maximum number of pages to scrape. Default: 10.

func WithPaginateStopOnEmpty 

func WithPaginateStopOnEmpty() PaginateOption

WithPaginateStopOnEmpty enables stopping when a page yields no new items. Default: true.

type Pool 

type Pool[T any] chan *T

Pool is used to thread-safely limit the number of elements at the same time. It's a common practice to use a channel to limit concurrency, it's not special for rod. This helper is more like an example to use Go Channel. Reference: https://golang.org/doc/effective_go#channels

func NewBrowserPool 

func NewBrowserPool(limit int) Pool[Browser]

NewBrowserPool instance.

func NewPool 

func NewPool[T any](limit int) Pool[T]

NewPool instance.

func (Pool[T]) Cleanup 

func (p Pool[T]) Cleanup(iteratee func(*T))

Cleanup helper.

func (Pool[T]) Get 

func (p Pool[T]) Get(create func() (*T, error)) (elem *T, err error)

Get a elem from the pool, allow error. Use the [Pool[T].Put] to make it reusable later.

func (Pool[T]) MustGet 

func (p Pool[T]) MustGet(create func() *T) *T

MustGet an elem from the pool. Use the [Pool[T].Put] to make it reusable later.

func (Pool[T]) Put 

func (p Pool[T]) Put(elem *T)

Put an elem back to the pool.

type ProfileBrowser 

type ProfileBrowser struct {
	Type     string `json:"type,omitempty"`
	ExecPath string `json:"exec_path,omitempty"`
	WindowW  int    `json:"window_w,omitempty"`
	WindowH  int    `json:"window_h,omitempty"`
	Platform string `json:"platform,omitempty"`
	Arch     string `json:"arch,omitempty"`
}

ProfileBrowser holds browser type and launch configuration.

type ProfileDiff 

type ProfileDiff struct {
	NameChanged           bool `json:"name_changed,omitempty"`
	IdentityChanged       bool `json:"identity_changed,omitempty"`
	BrowserChanged        bool `json:"browser_changed,omitempty"`
	CookiesAdded          int  `json:"cookies_added,omitempty"`
	CookiesRemoved        int  `json:"cookies_removed,omitempty"`
	CookiesModified       int  `json:"cookies_modified,omitempty"`
	StorageOriginsAdded   int  `json:"storage_origins_added,omitempty"`
	StorageOriginsRemoved int  `json:"storage_origins_removed,omitempty"`
	HeadersChanged        int  `json:"headers_changed,omitempty"`
	ExtensionsAdded       int  `json:"extensions_added,omitempty"`
	ExtensionsRemoved     int  `json:"extensions_removed,omitempty"`
}

ProfileDiff summarizes the differences between two profiles.

func DiffProfiles 

func DiffProfiles(a, b *UserProfile) ProfileDiff

DiffProfiles compares two profiles and returns a summary of differences.

type ProfileIdentity 

type ProfileIdentity struct {
	UserAgent string `json:"user_agent,omitempty"`
	Language  string `json:"language,omitempty"`
	Timezone  string `json:"timezone,omitempty"`
	Locale    string `json:"locale,omitempty"`
}

ProfileIdentity holds browser fingerprint identity fields.

type ProfileOption 

type ProfileOption func(*profileConfig)

ProfileOption configures profile capture behavior.

func WithProfileName 

func WithProfileName(name string) ProfileOption

WithProfileName sets the profile name.

type ProfileOriginStorage 

type ProfileOriginStorage struct {
	LocalStorage   map[string]string `json:"local_storage,omitempty"`
	SessionStorage map[string]string `json:"session_storage,omitempty"`
}

ProfileOriginStorage holds per-origin localStorage and sessionStorage data.

type ProxyChain 

type ProxyChain struct {
	Hops []ProxyHop
}

ProxyChain represents an ordered list of proxies to route through. Chrome only supports a single --proxy-server flag, so chaining is achieved by nesting proxies: each hop forwards traffic to the next.

For two-hop chains (SOCKS5 → HTTP or SOCKS5 → SOCKS5), use a local forwarding proxy or set up the chain externally and provide the entry point via WithProxy.

WithProxyChain validates the chain and configures the browser to use the first hop. For true multi-hop chaining, use an external tool like proxychains-ng, redsocks, or gost, and point WithProxy at the local entry.

type ProxyHop 

type ProxyHop struct {
	// URL is the full proxy URL (e.g. "socks5://host:1080", "http://user:pass@host:8080").
	URL string
}

ProxyHop represents a single proxy in a chain.

type RaceContext 

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

RaceContext stores the branches to race.

func (*RaceContext) Do 

func (rc *RaceContext) Do() (*rodElement, error)

Do the race.

func (*RaceContext) Element 

func (rc *RaceContext) Element(selector string) *RaceContext

Element is similar to Page.Element.

func (*RaceContext) ElementByJS 

func (rc *RaceContext) ElementByJS(opts *EvalOptions) *RaceContext

ElementByJS is similar to Page.ElementByJS.

func (*RaceContext) ElementFunc 

func (rc *RaceContext) ElementFunc(fn func(*rodPage) (*rodElement, error)) *RaceContext

ElementFunc takes a custom function to determine race success.

func (*RaceContext) ElementR 

func (rc *RaceContext) ElementR(selector, regex string) *RaceContext

ElementR is similar to [Page.ElementR].

func (*RaceContext) ElementX 

func (rc *RaceContext) ElementX(selector string) *RaceContext

ElementX is similar to [Page.ElementX].

func (*RaceContext) Handle 

func (rc *RaceContext) Handle(callback func(*rodElement) error) *RaceContext

Handle adds a callback function to the most recent chained selector. The callback function is run, if the corresponding selector is present first, in the Race condition.

func (*RaceContext) MustDo 

func (rc *RaceContext) MustDo() *rodElement

MustDo is similar to RaceContext.Do.

func (*RaceContext) MustElementByJS 

func (rc *RaceContext) MustElementByJS(js string, params []any) *RaceContext

MustElementByJS is similar to RaceContext.ElementByJS.

func (*RaceContext) MustHandle 

func (rc *RaceContext) MustHandle(callback func(*rodElement)) *RaceContext

MustHandle is similar to RaceContext.Handle.

func (*RaceContext) Search 

func (rc *RaceContext) Search(query string) *RaceContext

Search is similar to Page.Search.

type RateLimitOption 

type RateLimitOption func(*rateLimitOptions)

RateLimitOption configures a RateLimiter.

func WithBackoff 

func WithBackoff(d time.Duration) RateLimitOption

WithBackoff sets the initial backoff duration. Default: 1s.

func WithBurstSize 

func WithBurstSize(n int) RateLimitOption

WithBurstSize sets the burst size for the token bucket. Default: 5.

func WithMaxBackoff 

func WithMaxBackoff(d time.Duration) RateLimitOption

WithMaxBackoff sets the maximum backoff duration. Default: 30s.

func WithMaxConcurrent 

func WithMaxConcurrent(n int) RateLimitOption

WithMaxConcurrent limits concurrent executions. 0 means unlimited. Default: 0.

func WithMaxRetries 

func WithMaxRetries(n int) RateLimitOption

WithMaxRetries sets the maximum number of retries on failure. Default: 3.

func WithRateLimit 

func WithRateLimit(rps float64) RateLimitOption

WithRateLimit sets the requests per second. Default: 2.

type RateLimiter 

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

RateLimiter provides rate limiting with retry and backoff for browser operations.

func NewRateLimiter 

func NewRateLimiter(opts ...RateLimitOption) *RateLimiter

NewRateLimiter creates a new rate limiter with the given options.

Example 
package main

import (
	"fmt"
	"time"

	"github.com/inovacc/scout/pkg/scout"
)

func main() { //nolint:testableexamples // requires browser
	rl := scout.NewRateLimiter(
		scout.WithRateLimit(2),  // 2 requests/sec
		scout.WithMaxRetries(3), // retry up to 3 times
		scout.WithBackoff(500*time.Millisecond),
	)

	err := rl.Do(func() error {
		// Your scraping operation here.
		return nil
	})
	if err != nil {
		fmt.Println("error:", err)
		return
	}
}

func (*RateLimiter) Do 

func (rl *RateLimiter) Do(fn func() error) error

Do executes fn with rate limiting and retry with exponential backoff.

func (*RateLimiter) Wait 

func (rl *RateLimiter) Wait()

Wait blocks until a rate limit token is available.

type RecordedRecipe deprecated 

type RecordedRecipe = RecordedRunbook

Deprecated: RecordedRecipe is an alias for RecordedRunbook. Use RecordedRunbook instead.

type RecordedRunbook 

type RecordedRunbook struct {
	Version string         `json:"version"`
	Name    string         `json:"name"`
	Type    string         `json:"type"`
	URL     string         `json:"url,omitempty"`
	Steps   []RecordedStep `json:"steps,omitempty"`
}

RecordedRunbook represents a runbook generated from recorded interactions.

func (*RecordedRunbook) RecordedRunbookJSON 

func (r *RecordedRunbook) RecordedRunbookJSON() ([]byte, error)

RecordedRunbookJSON returns the runbook as indented JSON bytes.

type RecordedStep 

type RecordedStep struct {
	Action   string `json:"action"`
	URL      string `json:"url,omitempty"`
	Selector string `json:"selector,omitempty"`
	Text     string `json:"text,omitempty"`
}

RecordedStep represents a single recorded user interaction.

type RecorderOption 

type RecorderOption = hijack.RecorderOption

RecorderOption re-exports hijack.RecorderOption from sub-package.

type RenderInfo 

type RenderInfo = detect.RenderInfo

type RenderMode 

type RenderMode = detect.RenderMode

type Report added in v0.72.0 

type Report struct {
	ID        string        `json:"id"`
	Type      ReportType    `json:"type"`
	URL       string        `json:"url"`
	CreatedAt time.Time     `json:"created_at"`
	Health    *HealthReport `json:"health,omitempty"`
	Gather    *GatherResult `json:"gather,omitempty"`
	Crawl     *CrawlReport  `json:"crawl,omitempty"`
}

Report wraps a health check, gather, or crawl result with metadata.

func ListReports added in v0.72.0 

func ListReports() ([]Report, error)

ListReports returns all reports sorted by creation time (newest first).

func ReadReport added in v0.72.0 

func ReadReport(id string) (*Report, error)

ReadReport reads a report by ID from ~/.scout/reports/. Supports both the new structured text format (extracts JSON from code block) and legacy raw JSON format.

type ReportType added in v0.72.0 

type ReportType string

ReportType identifies the kind of report. 

const (
	ReportHealthCheck ReportType = "health_check"
	ReportGather      ReportType = "gather"
	ReportCrawl       ReportType = "crawl"
	ReportSwarm       ReportType = "swarm"
)

type ResearchAgent 

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

ResearchAgent orchestrates multi-source research using WebSearch + WebFetch + LLM.

func NewResearchAgent 

func NewResearchAgent(browser *Browser, provider LLMProvider, opts ...ResearchOption) *ResearchAgent

NewResearchAgent creates a new research agent with the given browser, LLM provider, and options.

func (*ResearchAgent) BuildPrompt 

func (ra *ResearchAgent) BuildPrompt(query string, sources []ResearchSource) string

BuildPrompt is exported for testing. It constructs the user prompt for the LLM.

func (*ResearchAgent) DeepResearch 

func (ra *ResearchAgent) DeepResearch(ctx context.Context, query string) (*ResearchResult, error)

DeepResearch performs multi-depth research: initial research + follow-up iterations.

func (*ResearchAgent) Research 

func (ra *ResearchAgent) Research(ctx context.Context, query string) (*ResearchResult, error)

Research performs a single-depth research query: search, fetch, and summarize.

type ResearchCache 

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

ResearchCache caches research results with TTL.

func NewResearchCache 

func NewResearchCache(ttl time.Duration) *ResearchCache

NewResearchCache creates a cache with the given TTL.

func (*ResearchCache) Clear 

func (c *ResearchCache) Clear()

Clear removes all cached entries.

func (*ResearchCache) Evict 

func (c *ResearchCache) Evict() int

Evict removes expired entries.

func (*ResearchCache) Get 

func (c *ResearchCache) Get(query string) (*ResearchResult, bool)

Get returns a cached result if it exists and hasn't expired.

func (*ResearchCache) Put 

func (c *ResearchCache) Put(query string, result *ResearchResult)

Put stores a result in the cache.

func (*ResearchCache) Size 

func (c *ResearchCache) Size() int

Size returns the number of cached entries.

type ResearchDepth 

type ResearchDepth int

ResearchDepth provides named presets for research thoroughness. 

const (
	// ResearchShallow performs a single search+fetch pass (depth 1, 3 sources).
	ResearchShallow ResearchDepth = iota
	// ResearchMedium performs one follow-up pass (depth 2, 5 sources).
	ResearchMedium
	// ResearchDeep performs multiple follow-up passes (depth 3, 8 sources).
	ResearchDeep
)

type ResearchOption 

type ResearchOption func(*researchOpts)

ResearchOption configures ResearchAgent behavior.

func WithResearchCache 

func WithResearchCache(cache *ResearchCache) ResearchOption

WithResearchCache attaches a cache to the research agent. Cached results are returned without performing new searches.

func WithResearchConcurrency 

func WithResearchConcurrency(n int) ResearchOption

WithResearchConcurrency sets fetch parallelism. Default: 3.

func WithResearchDepth 

func WithResearchDepth(d int) ResearchOption

WithResearchDepth sets the maximum depth for deep research iterations. Default: 1.

func WithResearchEngine 

func WithResearchEngine(e SearchEngine) ResearchOption

WithResearchEngine sets the search engine. Default: Google.

func WithResearchFetchMode 

func WithResearchFetchMode(mode string) ResearchOption

WithResearchFetchMode sets the fetch mode for source pages. Default: "markdown".

func WithResearchMainContent 

func WithResearchMainContent(b bool) ResearchOption

WithResearchMainContent enables main content extraction. Default: true.

func WithResearchMaxSources 

func WithResearchMaxSources(n int) ResearchOption

WithResearchMaxSources sets the maximum number of sources to fetch. Default: 5.

func WithResearchPreset 

func WithResearchPreset(depth ResearchDepth) ResearchOption

WithResearchPreset applies a named depth preset.

func WithResearchPrior 

func WithResearchPrior(prior *ResearchResult) ResearchOption

WithResearchPrior provides a previous result to build upon incrementally. The agent will use prior sources to avoid re-fetching and focus on new information.

func WithResearchTimeout 

func WithResearchTimeout(d time.Duration) ResearchOption

WithResearchTimeout sets the overall research timeout. Default: 2m.

type ResearchResult 

type ResearchResult struct {
	Query             string           `json:"query"`
	Summary           string           `json:"summary"`
	Sources           []ResearchSource `json:"sources"`
	FollowUpQuestions []string         `json:"follow_up_questions,omitempty"`
	Duration          time.Duration    `json:"duration"`
	Depth             int              `json:"depth"`
}

ResearchResult holds the output of a research query.

type ResearchSource 

type ResearchSource struct {
	URL       string  `json:"url"`
	Title     string  `json:"title"`
	Content   string  `json:"content"`
	Relevance float64 `json:"relevance"`
}

ResearchSource represents a single source used in a research result.

type ScreenRecordOption 

type ScreenRecordOption func(*screenRecordOpts)

ScreenRecordOption configures a ScreenRecorder.

func WithRecordQuality 

func WithRecordQuality(q int) ScreenRecordOption

WithRecordQuality sets the JPEG compression quality (1-100). Default: 80.

func WithRecordSize 

func WithRecordSize(w, h int) ScreenRecordOption

WithRecordSize sets the maximum frame dimensions. Zero means no limit.

type ScreenRecorder 

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

ScreenRecorder captures browser screen frames via CDP Page.startScreencast.

func NewScreenRecorder 

func NewScreenRecorder(page *Page, opts ...ScreenRecordOption) *ScreenRecorder

NewScreenRecorder creates a new screen recorder for the given page. Call Start() to begin capturing frames.

func (*ScreenRecorder) Duration 

func (r *ScreenRecorder) Duration() time.Duration

Duration returns the time span from the first to the last captured frame.

func (*ScreenRecorder) ExportFrames 

func (r *ScreenRecorder) ExportFrames(dir string) error

ExportFrames saves each captured frame as an individual JPEG file in the given directory.

func (*ScreenRecorder) ExportGIF 

func (r *ScreenRecorder) ExportGIF(w io.Writer) error

ExportGIF encodes all captured frames as an animated GIF.

func (*ScreenRecorder) FrameCount 

func (r *ScreenRecorder) FrameCount() int

FrameCount returns the number of captured frames.

func (*ScreenRecorder) Frames 

func (r *ScreenRecorder) Frames() []screenFrame

Frames returns a copy of the captured frames.

func (*ScreenRecorder) Start 

func (r *ScreenRecorder) Start() error

Start begins capturing screencast frames from the page.

func (*ScreenRecorder) Stop 

func (r *ScreenRecorder) Stop() error

Stop ends the screen recording. It is safe to call multiple times.

type ScriptTemplate 

type ScriptTemplate struct {
	Name        string
	Template    string
	Description string
}

ScriptTemplate is a parameterized JavaScript template that can be rendered with dynamic data before injection.

type ScrollScreenshotOptions 

type ScrollScreenshotOptions struct {
	// Format (optional) Image compression format (defaults to png).
	Format proto2.PageCaptureScreenshotFormat `json:"format,omitempty"`

	// Quality (optional) Compression quality from range [0..100] (jpeg only).
	Quality *int `json:"quality,omitempty"`

	// FixedTop (optional) The number of pixels to skip from the top.
	// It is suitable for optimizing the screenshot effect when there is a fixed
	// positioning element at the top of the page.
	FixedTop float64

	// FixedBottom (optional) The number of pixels to skip from the bottom.
	FixedBottom float64

	// WaitPerScroll until no animation (default is 300ms)
	WaitPerScroll time.Duration
}

ScrollScreenshotOptions is the options for the ScrollScreenshot.

type SearchEngine 

type SearchEngine int

SearchEngine identifies a search engine. 

const (
	// Google is Google Search.
	Google SearchEngine = iota
	// Bing is Microsoft Bing.
	Bing
	// DuckDuckGo is DuckDuckGo Search.
	DuckDuckGo
)
const Wikipedia SearchEngine = 3

Wikipedia is the Wikipedia search engine.

type SearchOption 

type SearchOption func(*searchOptions)

SearchOption configures search behavior.

func WithDDGSearchType 

func WithDDGSearchType(t string) SearchOption

WithDDGSearchType sets the DuckDuckGo search type (web, news, images).

func WithSearchEngine 

func WithSearchEngine(e SearchEngine) SearchOption

WithSearchEngine sets the search engine to use. Default: Google.

func WithSearchLanguage 

func WithSearchLanguage(lang string) SearchOption

WithSearchLanguage sets the language for search results (e.g. "en", "pt-BR").

func WithSearchMaxPages 

func WithSearchMaxPages(n int) SearchOption

WithSearchMaxPages sets the maximum number of result pages. Default: 1.

func WithSearchRecentDuration 

func WithSearchRecentDuration(d time.Duration) SearchOption

WithSearchRecentDuration sets a time filter on search results. For Google this appends tbs=qdr: parameters; for Bing it appends &filters=ex1:"ez5_N" style filters; for DuckDuckGo it appends &df= parameters.

func WithSearchRegion 

func WithSearchRegion(region string) SearchOption

WithSearchRegion sets the region for search results (e.g. "us", "br").

type SearchResult 

type SearchResult struct {
	Title    string
	URL      string
	Snippet  string
	Position int
}

SearchResult represents a single organic search result.

type SearchResults 

type SearchResults struct {
	Query           string
	Engine          SearchEngine
	TotalResults    string
	FeaturedSnippet string
	NextPageURL     string
	Results         []SearchResult
}

SearchResults holds the full response from a search query.

type SelectorType 

type SelectorType string

SelectorType enum. 

const (
	// SelectorTypeRegex type.
	SelectorTypeRegex SelectorType = "regex"
	// SelectorTypeCSSSector type.
	SelectorTypeCSSSector SelectorType = "css-selector"
	// SelectorTypeText type.
	SelectorTypeText SelectorType = "text"
)

type SessionHijacker 

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

SessionHijacker captures real-time network traffic (HTTP + WebSocket) from a Page via CDP events.

func (*SessionHijacker) Events 

func (h *SessionHijacker) Events() <-chan HijackEvent

Events returns a read-only channel of hijacked network events.

func (*SessionHijacker) Stop 

func (h *SessionHijacker) Stop()

Stop ends the hijacking session. It is safe to call multiple times.

type SessionIndex 

type SessionIndex = llm.SessionIndex

type SessionInfo 

type SessionInfo = session.SessionInfo

SessionInfo re-exports session.SessionInfo from sub-package.

func ReadSessionInfo 

func ReadSessionInfo(id string) (*SessionInfo, error)

ReadSessionInfo reads the session info from <SessionsDir>/<id>/scout.pid.

type SessionJob added in v0.57.0 

type SessionJob = session.Job

func NewSessionJob added in v0.57.0 

func NewSessionJob(jobType string, targetURLs []string, command string) *SessionJob

NewSessionJob creates a new Job with a KSUID, pending status, and timestamps.

func ReadSessionJob added in v0.57.0 

func ReadSessionJob(sessionID string) (*SessionJob, error)

ReadSessionJob reads the job from <SessionsDir>/<sessionID>/job.json.

type SessionJobProgress added in v0.57.0 

type SessionJobProgress = session.Progress

type SessionJobStatus added in v0.57.0 

type SessionJobStatus = session.JobStatus

type SessionJobStep added in v0.57.0 

type SessionJobStep = session.JobStep

type SessionListing 

type SessionListing = session.SessionListing

func FindReusableSession 

func FindReusableSession(browser string, headless bool) *SessionListing

FindReusableSession scans session dirs for a matching reusable session.

func FindSessionByDomain 

func FindSessionByDomain(rawURL string) *SessionListing

FindSessionByDomain looks up a session by domain hash directory name.

func ListSessions 

func ListSessions() ([]SessionListing, error)

ListSessions reads all <dir>/scout.pid files under SessionsDir.

type SessionState 

type SessionState struct {
	URL            string            `json:"url"`
	Cookies        []Cookie          `json:"cookies"`
	LocalStorage   map[string]string `json:"local_storage,omitempty"`
	SessionStorage map[string]string `json:"session_storage,omitempty"`
}

SessionState holds all restorable browser state for a page.

func LoadSessionFromFile 

func LoadSessionFromFile(path string) (*SessionState, error)

LoadSessionFromFile reads JSON from the given path and unmarshals it into a SessionState.

type SitemapOption 

type SitemapOption func(*sitemapOptions)

SitemapOption configures SitemapExtract behavior.

func WithSitemapAllowedDomains 

func WithSitemapAllowedDomains(domains ...string) SitemapOption

WithSitemapAllowedDomains restricts crawling to the specified domains.

func WithSitemapDOMDepth 

func WithSitemapDOMDepth(n int) SitemapOption

WithSitemapDOMDepth sets the maximum DOM tree depth for JSON extraction. Default: 50.

func WithSitemapDelay 

func WithSitemapDelay(d time.Duration) SitemapOption

WithSitemapDelay sets the delay between page visits. Default: 500ms.

func WithSitemapMainOnly 

func WithSitemapMainOnly() SitemapOption

WithSitemapMainOnly uses a heuristic to find main content (markdown only).

func WithSitemapMaxDepth 

func WithSitemapMaxDepth(n int) SitemapOption

WithSitemapMaxDepth sets the maximum crawl depth. Default: 3.

func WithSitemapMaxPages 

func WithSitemapMaxPages(n int) SitemapOption

WithSitemapMaxPages sets the maximum number of pages to extract. Default: 100.

func WithSitemapOutputDir 

func WithSitemapOutputDir(dir string) SitemapOption

WithSitemapOutputDir enables writing per-page files and an index to the given directory.

func WithSitemapSelector 

func WithSitemapSelector(s string) SitemapOption

WithSitemapSelector scopes DOM extraction to a CSS selector.

func WithSitemapSkipJSON 

func WithSitemapSkipJSON() SitemapOption

WithSitemapSkipJSON disables DOM JSON extraction.

func WithSitemapSkipMarkdown 

func WithSitemapSkipMarkdown() SitemapOption

WithSitemapSkipMarkdown disables markdown extraction.

type SitemapPage 

type SitemapPage struct {
	URL      string   `json:"url"`
	Title    string   `json:"title"`
	Depth    int      `json:"depth"`
	Links    []string `json:"links,omitempty"`
	DOM      *DOMNode `json:"dom,omitempty"`
	Markdown string   `json:"markdown,omitempty"`
	Error    string   `json:"error,omitempty"`
}

SitemapPage holds DOM extraction results for a single crawled page.

type SitemapResult 

type SitemapResult struct {
	StartURL string        `json:"start_url"`
	Pages    []SitemapPage `json:"pages"`
	Total    int           `json:"total"`
}

SitemapResult holds the complete sitemap extraction output.

type SitemapURL 

type SitemapURL struct {
	Loc        string `xml:"loc" json:"loc"`
	LastMod    string `xml:"lastmod" json:"last_mod,omitempty"`
	ChangeFreq string `xml:"changefreq" json:"change_freq,omitempty"`
	Priority   string `xml:"priority" json:"priority,omitempty"`
}

SitemapURL represents a URL entry in a sitemap.

type SnapshotOption 

type SnapshotOption func(*snapshotConfig)

SnapshotOption configures accessibility snapshot behavior.

func WithSnapshotFilter 

func WithSnapshotFilter(roles ...string) SnapshotOption

WithSnapshotFilter only includes elements with the given ARIA roles.

func WithSnapshotIframes 

func WithSnapshotIframes() SnapshotOption

WithSnapshotIframes includes iframe content in the snapshot.

func WithSnapshotInteractableOnly 

func WithSnapshotInteractableOnly() SnapshotOption

WithSnapshotInteractableOnly only includes interactable elements.

func WithSnapshotMaxDepth 

func WithSnapshotMaxDepth(n int) SnapshotOption

WithSnapshotMaxDepth limits the DOM traversal depth.

type SolveFunc 

type SolveFunc func(page *Page, challenge ChallengeInfo) error

SolveFunc is a function that attempts to solve a specific challenge type on a page.

type SolveRequest 

type SolveRequest struct {
	Type        string `json:"type"`         // e.g. "recaptcha_v2", "hcaptcha", "turnstile"
	SiteKey     string `json:"site_key"`     // CAPTCHA site key from the page
	PageURL     string `json:"page_url"`     // URL where the CAPTCHA is displayed
	ImageBase64 string `json:"image_base64"` // Base64-encoded CAPTCHA image (for image CAPTCHAs)
}

SolveRequest describes a CAPTCHA to solve via an external service.

type SolverOption 

type SolverOption func(*solverOptions)

SolverOption configures a ChallengeSolver.

func WithSolverLLM 

func WithSolverLLM(provider LLMProvider) SolverOption

WithSolverLLM adds an LLM provider for vision-based CAPTCHA solving.

func WithSolverService 

func WithSolverService(svc CaptchaSolverService) SolverOption

WithSolverService adds a third-party CAPTCHA solving service.

func WithSolverTimeout 

func WithSolverTimeout(d time.Duration) SolverOption

WithSolverTimeout sets the maximum time for solving a single challenge.

type StoredFingerprint 

type StoredFingerprint = fingerprint.StoredFingerprint

type StreamReader 

type StreamReader struct {
	Offset *int
	// contains filtered or unexported fields
}

StreamReader for browser data stream.

func NewStreamReader 

func NewStreamReader(c proto2.Client, h proto2.IOStreamHandle) *StreamReader

NewStreamReader instance.

func (*StreamReader) Close 

func (sr *StreamReader) Close() error

Close the stream, discard any temporary backing storage.

func (*StreamReader) Read 

func (sr *StreamReader) Read(p []byte) (n int, err error)

type SurfsharkProvider 

type SurfsharkProvider = vpn.SurfsharkProvider

type SwaggerInfo 

type SwaggerInfo struct {
	Title       string            `json:"title"`
	Description string            `json:"description,omitempty"`
	Version     string            `json:"version"`
	Contact     map[string]string `json:"contact,omitempty"`
	License     map[string]string `json:"license,omitempty"`
}

SwaggerInfo holds API metadata.

type SwaggerOption 

type SwaggerOption func(*swaggerOptions)

SwaggerOption configures swagger extraction behavior.

func WithSwaggerEndpointsOnly 

func WithSwaggerEndpointsOnly(v bool) SwaggerOption

WithSwaggerEndpointsOnly extracts only paths/endpoints, skipping schemas.

func WithSwaggerRaw 

func WithSwaggerRaw(v bool) SwaggerOption

WithSwaggerRaw includes the raw spec JSON in the result.

type SwaggerParam 

type SwaggerParam struct {
	Name     string `json:"name"`
	In       string `json:"in"`
	Required bool   `json:"required,omitempty"`
	Type     string `json:"type,omitempty"`
}

SwaggerParam represents an API parameter.

type SwaggerPath 

type SwaggerPath struct {
	Path        string                `json:"path"`
	Method      string                `json:"method"`
	OperationID string                `json:"operation_id,omitempty"`
	Summary     string                `json:"summary,omitempty"`
	Tags        []string              `json:"tags,omitempty"`
	Parameters  []SwaggerParam        `json:"parameters,omitempty"`
	Responses   map[string]string     `json:"responses,omitempty"`
	Security    []map[string][]string `json:"security,omitempty"`
}

SwaggerPath represents a single API operation.

type SwaggerSecurity 

type SwaggerSecurity struct {
	Name   string `json:"name"`
	Type   string `json:"type"`
	In     string `json:"in,omitempty"`
	Scheme string `json:"scheme,omitempty"`
}

SwaggerSecurity describes a security scheme.

type SwaggerServer 

type SwaggerServer struct {
	URL         string `json:"url"`
	Description string `json:"description,omitempty"`
}

SwaggerServer represents a server/base URL for the API.

type SwaggerSpec 

type SwaggerSpec struct {
	SpecURL  string            `json:"spec_url"`
	Version  string            `json:"version"`
	Format   string            `json:"format"`
	Info     SwaggerInfo       `json:"info"`
	Servers  []SwaggerServer   `json:"servers,omitempty"`
	Paths    []SwaggerPath     `json:"paths,omitempty"`
	Schemas  map[string]any    `json:"schemas,omitempty"`
	Security []SwaggerSecurity `json:"security,omitempty"`
	Raw      json.RawMessage   `json:"raw,omitempty"`
}

SwaggerSpec holds a parsed OpenAPI/Swagger specification.

type TabGroup 

type TabGroup struct {
	Store sync.Map
	// contains filtered or unexported fields
}

TabGroup manages a fixed set of browser tabs for concurrent work.

func (*TabGroup) Broadcast 

func (tg *TabGroup) Broadcast(fn func(*Page) error) []error

Broadcast executes fn concurrently on all tabs. It is a convenience wrapper around DoParallel that adapts a single-page function.

func (*TabGroup) Close 

func (tg *TabGroup) Close() error

Close closes all tabs in the group. It is nil-safe and idempotent.

func (*TabGroup) Do 

func (tg *TabGroup) Do(i int, fn func(*Page) error) error

Do executes fn on the i-th tab. It returns an error if i is out of range.

func (*TabGroup) DoAll 

func (tg *TabGroup) DoAll(fn func(i int, p *Page) error) error

DoAll executes fn sequentially on all tabs, stopping on the first error.

func (*TabGroup) DoParallel 

func (tg *TabGroup) DoParallel(fn func(i int, p *Page) error) []error

DoParallel executes fn concurrently on all tabs. It returns a slice of errors (nil entries for successful tabs).

func (*TabGroup) Len 

func (tg *TabGroup) Len() int

Len returns the number of tabs. It is nil-safe.

func (*TabGroup) Navigate 

func (tg *TabGroup) Navigate(urls ...string) []error

Navigate navigates tab[i] to urls[i] in parallel. If len(urls) != len(tabs), all error slots are filled with a mismatch error.

func (*TabGroup) Tab 

func (tg *TabGroup) Tab(i int) *Page

Tab returns the i-th tab. It panics if i is out of range.

func (*TabGroup) Wait 

func (tg *TabGroup) Wait(i int, cond func(*Page) bool, timeout time.Duration) error

Wait polls every 50ms until cond returns true for tab i, or timeout elapses.

type TabGroupOption 

type TabGroupOption func(*TabGroup)

TabGroupOption configures a TabGroup.

func WithTabGroupRateLimit 

func WithTabGroupRateLimit(rps float64) TabGroupOption

WithTabGroupRateLimit sets a rate limiter for the tab group.

func WithTabGroupTimeout 

func WithTabGroupTimeout(d time.Duration) TabGroupOption

WithTabGroupTimeout sets a per-operation timeout for the tab group.

type TableData 

type TableData struct {
	Headers []string
	Rows    [][]string
}

TableData holds the parsed content of an HTML table.

type TechStack 

type TechStack = detect.TechStack

type Touch 

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

Touch presents a touch device, such as a hand with fingers, each finger is a proto.InputTouchPoint. Touch events is stateless, we use the struct here only as a namespace to make the API style unified.

func (*Touch) Cancel 

func (t *Touch) Cancel() error

Cancel touch action.

func (*Touch) End 

func (t *Touch) End() error

End touch action.

func (*Touch) Move 

func (t *Touch) Move(points ...*proto2.InputTouchPoint) error

Move touch points. Use the proto.InputTouchPoint.ID (Touch.identifier) to track points. Doc: https://developer.mozilla.org/en-US/docs/Web/API/Touch_events

func (*Touch) MustCancel 

func (t *Touch) MustCancel() *Touch

MustCancel is similar to Touch.Cancel.

func (*Touch) MustEnd 

func (t *Touch) MustEnd() *Touch

MustEnd is similar to Touch.End.

func (*Touch) MustMove 

func (t *Touch) MustMove(points ...*proto2.InputTouchPoint) *Touch

MustMove is similar to Touch.Move.

func (*Touch) MustStart 

func (t *Touch) MustStart(points ...*proto2.InputTouchPoint) *Touch

MustStart is similar to Touch.Start.

func (*Touch) MustTap 

func (t *Touch) MustTap(x, y float64) *Touch

MustTap is similar to Touch.Tap.

func (*Touch) Start 

func (t *Touch) Start(points ...*proto2.InputTouchPoint) error

Start a touch action.

func (*Touch) Tap 

func (t *Touch) Tap(x, y float64) error

Tap dispatches a touchstart and touchend event.

type TouchPoint added in v1.0.0 

type TouchPoint struct {
	X, Y  float64
	Force float64 // pressure 0.0-1.0
	ID    int
}

TouchPoint represents a single touch contact point.

type TraceType 

type TraceType string

TraceType for logger. 

const (
	// TraceTypeWaitRequestsIdle type.
	TraceTypeWaitRequestsIdle TraceType = "wait requests idle"

	// TraceTypeWaitRequests type.
	TraceTypeWaitRequests TraceType = "wait requests"

	// TraceTypeQuery type.
	TraceTypeQuery TraceType = "query"

	// TraceTypeWait type.
	TraceTypeWait TraceType = "wait"

	// TraceTypeInput type.
	TraceTypeInput TraceType = "input"
)

func (TraceType) String 

func (t TraceType) String() string

String interface.

type TryError 

type TryError struct {
	Value any
	Stack string
}

TryError error.

func (*TryError) Error 

func (e *TryError) Error() string

func (*TryError) Is 

func (e *TryError) Is(err error) bool

Is interface.

func (*TryError) Unwrap 

func (e *TryError) Unwrap() error

Unwrap stdlib interface.

type TwoCaptchaService 

type TwoCaptchaService struct {
	APIKey     string
	BaseURL    string
	HTTPClient *http.Client
}

TwoCaptchaService implements CaptchaSolverService using the 2captcha.com API.

func NewTwoCaptchaService 

func NewTwoCaptchaService(apiKey string) *TwoCaptchaService

NewTwoCaptchaService creates a new 2captcha.com solver.

func (*TwoCaptchaService) Name 

func (s *TwoCaptchaService) Name() string

Name returns the service name.

func (*TwoCaptchaService) Solve 

func (s *TwoCaptchaService) Solve(ctx context.Context, req SolveRequest) (string, error)

Solve submits a task to 2captcha and polls for the result.

type UploadConfig 

type UploadConfig struct {
	Sink       UploadSink    `json:"sink"`
	Token      *oauth2.Token `json:"token,omitempty"`
	FolderID   string        `json:"folder_id,omitempty"`   // GDrive folder ID or OneDrive folder path
	FolderPath string        `json:"folder_path,omitempty"` // OneDrive folder path
}

UploadConfig holds credentials and destination for cloud upload.

func LoadUploadConfig 

func LoadUploadConfig() (*UploadConfig, error)

LoadUploadConfig reads upload config from ~/.scout/upload.json.

type UploadResult 

type UploadResult struct {
	Sink     UploadSink `json:"sink"`
	FileID   string     `json:"file_id,omitempty"`
	FileName string     `json:"file_name"`
	URL      string     `json:"url,omitempty"`
	Size     int64      `json:"size"`
}

UploadResult describes the outcome of a cloud upload.

type UploadSink 

type UploadSink string

UploadSink identifies a cloud storage destination. 

const (
	SinkGoogleDrive UploadSink = "gdrive"
	SinkOneDrive    UploadSink = "onedrive"
)

type Uploader 

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

Uploader uploads files to cloud storage.

func NewUploader 

func NewUploader(cfg *UploadConfig) *Uploader

NewUploader creates a cloud uploader with the given config. The OAuth2 token must already be obtained (see UploadOAuthConfig for helpers).

func (*Uploader) TokenExpiry 

func (u *Uploader) TokenExpiry() time.Time

TokenExpiry returns the token expiry time, or zero if not set.

func (*Uploader) Upload 

func (u *Uploader) Upload(ctx context.Context, filename string, data []byte) (*UploadResult, error)

Upload sends data to the configured cloud sink.

func (*Uploader) UploadFile 

func (u *Uploader) UploadFile(ctx context.Context, path string) (*UploadResult, error)

UploadFile reads a file from disk and uploads it.

type UserProfile 

type UserProfile struct {
	Version    int                             `json:"version"`
	Name       string                          `json:"name"`
	CreatedAt  time.Time                       `json:"created_at"`
	UpdatedAt  time.Time                       `json:"updated_at"`
	Browser    ProfileBrowser                  `json:"browser"`
	Identity   ProfileIdentity                 `json:"identity"`
	Cookies    []Cookie                        `json:"cookies"`
	Storage    map[string]ProfileOriginStorage `json:"storage,omitempty"`
	Headers    map[string]string               `json:"headers,omitempty"`
	Extensions []string                        `json:"extensions,omitempty"`
	Proxy      string                          `json:"proxy,omitempty"`
	Notes      string                          `json:"notes,omitempty"`
}

UserProfile represents a portable browser identity that can be saved, loaded, and applied to browser sessions. It captures browser configuration, identity fingerprint data, cookies, storage, and custom headers.

func CaptureProfile 

func CaptureProfile(page *Page, opts ...ProfileOption) (*UserProfile, error)

CaptureProfile snapshots the current page's browser state into a UserProfile.

func FingerprintToProfile 

func FingerprintToProfile(fp *Fingerprint) *UserProfile

FingerprintToProfile converts a fingerprint to a UserProfile for persistence.

func LoadProfile 

func LoadProfile(path string) (*UserProfile, error)

LoadProfile reads a UserProfile from a JSON file.

func LoadProfileEncrypted 

func LoadProfileEncrypted(path, passphrase string) (*UserProfile, error)

LoadProfileEncrypted reads and decrypts a profile.

func MergeProfiles 

func MergeProfiles(base, overlay *UserProfile) *UserProfile

MergeProfiles merges two profiles. Overlay values win on conflict. Cookies and storage are merged (overlay additions/updates win, base-only entries kept).

func (*UserProfile) Validate 

func (p *UserProfile) Validate() error

Validate checks a profile for required fields and consistency.

type VPNConnection 

type VPNConnection = vpn.Connection

type VPNProvider 

type VPNProvider = vpn.Provider

VPNProvider re-exports vpn.Provider from sub-package.

type VPNRotationConfig 

type VPNRotationConfig = vpn.RotationConfig

type VPNServer 

type VPNServer = vpn.Server

type VPNStatus 

type VPNStatus = vpn.Status

type VisualDiffOption 

type VisualDiffOption func(*visualDiffConfig)

VisualDiffOption configures a visual diff comparison.

func WithColorThreshold 

func WithColorThreshold(tolerance int) VisualDiffOption

WithColorThreshold sets the per-channel tolerance (0-255) for pixel comparison. A value of 5 means channels differing by 5 or less are considered equal.

func WithDiffImage 

func WithDiffImage() VisualDiffOption

WithDiffImage enables generation of a visual diff overlay PNG. Unchanged pixels are dimmed; differing pixels are highlighted in red.

func WithDiffThreshold 

func WithDiffThreshold(percent float64) VisualDiffOption

WithDiffThreshold sets the maximum allowed percentage of differing pixels (0-100). A threshold of 1.0 means up to 1% of pixels may differ and still match.

type VisualDiffResult 

type VisualDiffResult struct {
	// DiffPixels is the number of pixels that differ beyond the color threshold.
	DiffPixels int
	// TotalPixels is the total number of pixels compared.
	TotalPixels int
	// DiffPercent is the percentage of differing pixels (0-100).
	DiffPercent float64
	// Match is true when the difference is within the given threshold.
	Match bool
	// DiffImage is an optional PNG showing differences highlighted in red.
	// Only populated when generateDiff is true.
	DiffImage []byte
}

VisualDiffResult holds the result of comparing two screenshots.

func VisualDiff 

func VisualDiff(baseline, current []byte, opts ...VisualDiffOption) (*VisualDiffResult, error)

VisualDiff compares two PNG screenshots and returns the difference metrics. Both inputs must be valid PNG-encoded byte slices.

type WebAppManifest 

type WebAppManifest = detect.WebAppManifest

type WebFetchOption 

type WebFetchOption func(*webFetchOptions)

WebFetchOption configures WebFetch behavior.

func WithFetchCache 

func WithFetchCache(ttl time.Duration) WebFetchOption

WithFetchCache enables in-memory caching with the given TTL.

func WithFetchHTML 

func WithFetchHTML() WebFetchOption

WithFetchHTML includes raw HTML in the result.

func WithFetchMainContent 

func WithFetchMainContent() WebFetchOption

WithFetchMainContent enables readability scoring to extract only main content.

func WithFetchMode 

func WithFetchMode(mode string) WebFetchOption

WithFetchMode sets the extraction mode: "markdown", "html", "text", "links", "meta", or "full" (default).

func WithFetchRetries 

func WithFetchRetries(n int) WebFetchOption

WithFetchRetries sets the number of retry attempts when navigation fails. Default is 0 (no retries).

func WithFetchRetryDelay 

func WithFetchRetryDelay(d time.Duration) WebFetchOption

WithFetchRetryDelay sets the delay between retry attempts.

type WebFetchResult 

type WebFetchResult struct {
	URL           string    `json:"url"`
	Title         string    `json:"title"`
	Markdown      string    `json:"markdown"`
	HTML          string    `json:"html,omitempty"`
	Meta          *MetaData `json:"meta,omitempty"`
	Links         []string  `json:"links,omitempty"`
	RedirectChain []string  `json:"redirect_chain,omitempty"`
	StatusCode    int       `json:"status_code,omitempty"`
	FetchedAt     time.Time `json:"fetched_at"`
}

WebFetchResult holds the result of fetching and extracting content from a URL.

type WebMCPRegistry 

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

WebMCPRegistry holds discovered tools across pages, keyed by "origin/toolname".

func NewWebMCPRegistry 

func NewWebMCPRegistry() *WebMCPRegistry

NewWebMCPRegistry creates an empty WebMCPRegistry.

func (*WebMCPRegistry) All 

func (r *WebMCPRegistry) All() []WebMCPTool

All returns a snapshot of all registered tools.

func (*WebMCPRegistry) Clear 

func (r *WebMCPRegistry) Clear()

Clear removes all tools from the registry.

func (*WebMCPRegistry) Get 

func (r *WebMCPRegistry) Get(key string) (*WebMCPTool, bool)

Get returns the tool for the given key ("origin/toolname") and whether it exists.

func (*WebMCPRegistry) Register 

func (r *WebMCPRegistry) Register(origin string, tools []WebMCPTool)

Register adds tools from a given origin to the registry. Existing tools with the same origin/name key are overwritten.

type WebMCPTool 

type WebMCPTool struct {
	Name        string          `json:"name"`
	Description string          `json:"description"`
	ServerURL   string          `json:"server_url,omitempty"`
	InputSchema json.RawMessage `json:"input_schema,omitempty"`
	Source      string          `json:"source"` // "meta", "well-known", "link", "script"
}

WebMCPTool represents an MCP tool discovered on a web page.

type WebMCPToolResult 

type WebMCPToolResult struct {
	Content string `json:"content"`
	IsError bool   `json:"is_error"`
}

WebMCPToolResult holds the result of calling a web-exposed MCP tool.

type WebSearchItem 

type WebSearchItem struct {
	Title    string          `json:"title"`
	URL      string          `json:"url"`
	Snippet  string          `json:"snippet"`
	Position int             `json:"position"`
	RRFScore float64         `json:"rrf_score,omitempty"`
	Content  *WebFetchResult `json:"content,omitempty"`
}

WebSearchItem is a single search result with optional fetched content.

type WebSearchOption 

type WebSearchOption func(*webSearchOptions)

WebSearchOption configures WebSearch behavior.

func WithSearchDomain 

func WithSearchDomain(domain string) WebSearchOption

WithSearchDomain appends "site:domain" to the query to restrict results.

func WithSearchEngines 

func WithSearchEngines(engines ...string) WebSearchOption

WithSearchEngines sets multiple engines for multi-engine aggregation with RRF merging. Accepted values: "google", "bing", "duckduckgo"/"ddg".

func WithSearchExcludeDomain 

func WithSearchExcludeDomain(domains ...string) WebSearchOption

WithSearchExcludeDomain appends "-site:domain" for each domain to exclude.

func WithSearchRecent 

func WithSearchRecent(d time.Duration) WebSearchOption

WithSearchRecent restricts search results to a recent time window. For Google: appends tbs=qdr: parameter (h/d/w/m/y based on duration). For Bing: appends freshness filter (Day/Week/Month). For DuckDuckGo: appends df= parameter (d/w/m/y).

func WithWebSearchCache 

func WithWebSearchCache(ttl time.Duration) WebSearchOption

WithWebSearchCache sets cache TTL for fetched pages.

func WithWebSearchConcurrency 

func WithWebSearchConcurrency(n int) WebSearchOption

WithWebSearchConcurrency sets fetch parallelism. Default: 3.

func WithWebSearchEngine 

func WithWebSearchEngine(e SearchEngine) WebSearchOption

WithWebSearchEngine sets the search engine. Default: Google.

func WithWebSearchFetch 

func WithWebSearchFetch(mode string) WebSearchOption

WithWebSearchFetch enables fetching result pages with the given mode. Mode can be "markdown", "text", "full", etc. Empty string disables fetch.

func WithWebSearchLanguage 

func WithWebSearchLanguage(lang string) WebSearchOption

WithWebSearchLanguage sets the language for search results.

func WithWebSearchMainContent 

func WithWebSearchMainContent() WebSearchOption

WithWebSearchMainContent enables readability filtering on fetched pages.

func WithWebSearchMaxFetch 

func WithWebSearchMaxFetch(n int) WebSearchOption

WithWebSearchMaxFetch limits how many results to fetch. Default: 5.

func WithWebSearchMaxPages 

func WithWebSearchMaxPages(n int) WebSearchOption

WithWebSearchMaxPages sets the max number of search result pages. Default: 1.

func WithWebSearchRegion 

func WithWebSearchRegion(region string) WebSearchOption

WithWebSearchRegion sets the region for search results.

type WebSearchResult 

type WebSearchResult struct {
	Query   string          `json:"query"`
	Engine  SearchEngine    `json:"engine"`
	Results []WebSearchItem `json:"results"`
}

WebSearchResult holds the combined search + fetch results.

type WebSocketConnection added in v0.72.0 

type WebSocketConnection struct {
	RequestID string
	URL       string
	Messages  []WebSocketMessage
	// contains filtered or unexported fields
}

WebSocketConnection represents an active WebSocket connection observed via CDP.

type WebSocketFrame 

type WebSocketFrame = hijack.WebSocketFrame

type WebSocketHandler added in v0.72.0 

type WebSocketHandler func(msg WebSocketMessage)

WebSocketHandler is called for each received WebSocket message.

type WebSocketMessage added in v0.72.0 

type WebSocketMessage struct {
	Direction string    `json:"direction"` // "sent" or "received"
	Data      string    `json:"data"`
	Timestamp time.Time `json:"timestamp"`
	Opcode    int       `json:"opcode"` // 1=text, 2=binary
}

WebSocketMessage is a single WebSocket frame captured via CDP.

type WebSocketOption added in v0.72.0 

type WebSocketOption func(*wsOptions)

WebSocketOption configures WebSocket monitoring.

func WithWSCaptureAll added in v0.72.0 

func WithWSCaptureAll() WebSocketOption

WithWSCaptureAll captures both sent and received messages.

func WithWSURLFilter added in v0.72.0 

func WithWSURLFilter(pattern string) WebSocketOption

WithWSURLFilter filters WebSocket connections by URL pattern.

type WindowBounds 

type WindowBounds struct {
	Left   int
	Top    int
	Width  int
	Height int
	State  WindowState
}

WindowBounds holds the position, size, and state of a browser window.

type WindowState 

type WindowState string

WindowState represents the state of a browser window. 

const (
	WindowStateNormal     WindowState = "normal"
	WindowStateMinimized  WindowState = "minimized"
	WindowStateMaximized  WindowState = "maximized"
	WindowStateFullscreen WindowState = "fullscreen"
)

type WizardStep 

type WizardStep struct {
	FormSelector string
	Data         map[string]string
	NextSelector string // CSS selector for "next" button; empty on last step
	WaitFor      string // CSS selector to wait for before filling
}

WizardStep describes a step in a multi-step form wizard.

Source Files

View all Source files

Directories

Path Synopsis
lib
assets
Package assets is generated by "lib/assets/generate"
 Package assets is generated by "lib/assets/generate"
cdp
Package cdp for application layer communication with browser.
 Package cdp for application layer communication with browser.
defaults
Package defaults of commonly used options parsed from environment.
 Package defaults of commonly used options parsed from environment.
devices
Package devices ...
 Package devices ...
input
Package input ...
 Package input ...
js
Package js generated by "lib/js/generate"
 Package js generated by "lib/js/generate"
launcher
Package launcher for launching browser utils.
 Package launcher for launching browser utils.
launcher/flags
Package flags ...
 Package flags ...
proto
Package proto is a lib to encode/decode the data of the cdp protocol.
 Package proto is a lib to encode/decode the data of the cdp protocol.
utils
Package utils ...
 Package utils ...
Package stealth provides anti-bot-detection capabilities for headless browser automation.
 Package stealth provides anti-bot-detection capabilities for headless browser automation.
generate command
Package main ...
 Package main ...

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.