The highest tagged major version is
Documentation
¶
Overview ¶
Package browser holds the persistent browser session: a long-lived chromedp browser with one or more tabs. The current tab holds the cached accessibility tree so find/filter is free (no new CDP round-trip). A mutex serializes all operations; each public method is atomic.
Index ¶
- Variables
- func ValidateURL(raw string, allowInsecure bool) (string, error)
- type Config
- type Session
- func (s *Session) BuildTree() error
- func (s *Session) ClickAndSee(ref string, settle time.Duration) (*snapshot.Delta, *snapshot.Tree, error)
- func (s *Session) Close()
- func (s *Session) CloseTab(idOrLabel string) error
- func (s *Session) Eval(script string) (string, error)
- func (s *Session) FillAndSee(ref, value string, settle time.Duration) (*snapshot.Delta, *snapshot.Tree, error)
- func (s *Session) FillText() error
- func (s *Session) HoverAndSee(ref string, settle time.Duration) (*snapshot.Delta, *snapshot.Tree, error)
- func (s *Session) Navigate(raw string) error
- func (s *Session) NavigateAndSee(raw string) (*snapshot.Tree, error)
- func (s *Session) NewTab(url string) (*snapshot.Tree, error)
- func (s *Session) PressKeyAndSee(key, modifiers string, settle time.Duration) (*snapshot.Delta, *snapshot.Tree, error)
- func (s *Session) Read(ref string, offset int) (string, error)
- func (s *Session) Screenshot() ([]byte, error)
- func (s *Session) ScrollAndSee(dx, dy int, settle time.Duration) (*snapshot.Delta, *snapshot.Tree, error)
- func (s *Session) SelectAndSee(ref, value string, settle time.Duration) (*snapshot.Delta, *snapshot.Tree, error)
- func (s *Session) SetTabLabel(label string) error
- func (s *Session) SwitchTab(idOrLabel string) error
- func (s *Session) Tabs() []TabInfo
- func (s *Session) Tree() *snapshot.Tree
- func (s *Session) Upload(ref string, paths []string) error
- func (s *Session) Wait(d time.Duration, text string) error
- type TabInfo
Constants ¶
This section is empty.
Variables ¶
var ErrNoSnapshot = errors.New("no page snapshot yet on the current tab; call navigate first")
ErrNoSnapshot is returned when the current tab has no cached page tree.
Functions ¶
func ValidateURL ¶
ValidateURL checks a navigation URL is safe. By default only http/https are allowed; file/javascript/data/about/blob require allowInsecure (opt-in) so an agent can't be steered to read local files or execute javascript: URIs. Relative URLs (no scheme) are rejected.
Types ¶
type Config ¶
type Config struct {
Headless bool
Timeout time.Duration // >0 bounds the first tab (debug CLI); 0 = long-lived (MCP server)
UserDataDir string // persistent profile dir; "" = a throwaway temp profile (the MCP server defaults this to <os config dir>/agent-browser for persistence unless --no-persist)
Proxy string // proxy server URL (e.g. http://user:pass@host:port); "" = none
UserAgent string // override the User-Agent; "" = Chrome default
ViewportW int // window width; 0 = 1366
ViewportH int // window height; 0 = 768
Stealth bool // apply anti-detection flags + init script + jittered mouse (default true)
}
Config configures a Session.
type Session ¶
type Session struct {
// AllowInsecureSchemes opts in to file/javascript/data/about/blob URLs.
AllowInsecureSchemes bool
// AllowEval controls the eval tool (arbitrary page JS). On by default;
// the operator can disable it with the --no-eval flag.
AllowEval bool
// contains filtered or unexported fields
}
Session is a persistent Chrome browser with a current tab and optional additional tabs.
func (*Session) BuildTree ¶
BuildTree pulls the accessibility tree for the current tab and caches it.
func (*Session) ClickAndSee ¶
func (s *Session) ClickAndSee(ref string, settle time.Duration) (*snapshot.Delta, *snapshot.Tree, error)
ClickAndSee clicks a ref (real mouse) and returns the delta + new tree.
func (*Session) CloseTab ¶
CloseTab closes the tab with the given id (or label). The last tab cannot be closed (the session must always have one).
func (*Session) Eval ¶
Eval runs arbitrary JS in the current tab and returns the raw JSON result. Gated by AllowEval (on by default; operator can disable with --no-eval).
func (*Session) FillAndSee ¶
func (s *Session) FillAndSee(ref, value string, settle time.Duration) (*snapshot.Delta, *snapshot.Tree, error)
FillAndSee sets an input value (dispatches input+change) and returns delta.
func (*Session) FillText ¶
FillText fetches the current tab's visible text (walking same-origin iframes) and attaches it to the cached tree so a full-level Render includes it. Use before Render(LevelFull). Returns ErrNoSnapshot if there is no cached tree.
func (*Session) HoverAndSee ¶
func (s *Session) HoverAndSee(ref string, settle time.Duration) (*snapshot.Delta, *snapshot.Tree, error)
HoverAndSee hovers an element by ref and returns the delta (e.g. a hover menu appearing as Added elements).
func (*Session) Navigate ¶
Navigate opens a URL on the current tab and waits for the body. Invalidates the cached tree.
func (*Session) NavigateAndSee ¶
NavigateAndSee navigates the current tab and returns its new tree. Atomic.
func (*Session) NewTab ¶
NewTab opens a new tab (navigating to url if non-empty), makes it current, and returns its tree (nil if url is empty).
func (*Session) PressKeyAndSee ¶
func (s *Session) PressKeyAndSee(key, modifiers string, settle time.Duration) (*snapshot.Delta, *snapshot.Tree, error)
PressKeyAndSee dispatches a real keyDown + keyUp (CDP Input.dispatchKeyEvent) on the focused element and returns the delta. Real key events fire native default actions (Enter submits, Escape closes, Tab moves focus, a char inserts) - synthetic JS KeyboardEvents do not.
func (*Session) Read ¶
Read returns url + title, plus a ref's text (if ref given) or body text. For the body (no ref), offset skips that many chars (pagination).
func (*Session) Screenshot ¶
Screenshot captures the current tab's viewport as a PNG.
func (*Session) ScrollAndSee ¶
func (s *Session) ScrollAndSee(dx, dy int, settle time.Duration) (*snapshot.Delta, *snapshot.Tree, error)
ScrollAndSee scrolls by dx/dy CSS pixels and returns the delta.
func (*Session) SelectAndSee ¶
func (s *Session) SelectAndSee(ref, value string, settle time.Duration) (*snapshot.Delta, *snapshot.Tree, error)
SelectAndSee sets a <select> value and returns the delta.
func (*Session) SetTabLabel ¶
SetTabLabel sets a label on the current tab (optional, for memorable names).
Source Files