# webview, **Import:** `dappco.re/go/core/webview`, **Files:** 5 ## Types ### Action Declaration: `type Action interface` Browser action contract used by `ActionSequence`. Methods: - `Execute(ctx context.Context, wv *Webview) error`: Runs the action against the supplied `Webview` and caller-owned context. ### ActionSequence Declaration: `type ActionSequence struct` Represents an ordered list of `Action` values. All fields are unexported. Methods: - `Add(action Action) *ActionSequence`: Appends `action` to the sequence and returns the same sequence for chaining. - `Click(selector string) *ActionSequence`: Appends `ClickAction{Selector: selector}`. - `Execute(ctx context.Context, wv *Webview) error`: Executes actions in insertion order. The first failing action stops execution and is wrapped as `ActionSequence.Execute` with the zero-based action index. - `Navigate(url string) *ActionSequence`: Appends `NavigateAction{URL: url}`. - `Type(selector, text string) *ActionSequence`: Appends `TypeAction{Selector: selector, Text: text}`. - `Wait(d time.Duration) *ActionSequence`: Appends `WaitAction{Duration: d}`. - `WaitForSelector(selector string) *ActionSequence`: Appends `WaitForSelectorAction{Selector: selector}`. ### AngularHelper Declaration: `type AngularHelper struct` Angular-specific helper bound to a `Webview`. All fields are unexported. The helper stores the target `Webview` and a per-operation timeout, which defaults to 30 seconds in `NewAngularHelper`. Methods: - `CallComponentMethod(selector, methodName string, args ...any) (any, error)`: Looks up the Angular component instance for `selector`, verifies that `methodName` is callable, invokes it with JSON-marshalled arguments, ticks `ApplicationRef` when available, and returns the evaluated result. - `DispatchEvent(selector, eventName string, detail any) error`: Dispatches a bubbling `CustomEvent` on the matched element. `detail` is marshalled into the page script, or `null` when omitted. - `GetComponentProperty(selector, propertyName string) (any, error)`: Returns `componentInstance[propertyName]` for the Angular component attached to the matched element. - `GetNgModel(selector string) (any, error)`: Returns `element.value` for `input`, `select`, and `textarea` elements, otherwise `element.value || element.textContent`. Missing elements produce `nil`. - `GetRouterState() (*AngularRouterState, error)`: Walks Angular root elements, resolves the first available Router, and returns its URL, fragment, root params, and root query params. Only string values are copied into the returned maps. - `GetService(serviceName string) (any, error)`: Resolves a service from the first Angular root injector and returns `JSON.parse(JSON.stringify(service))`, so only JSON-serialisable data survives. - `NavigateByRouter(path string) error`: Resolves Angular Router from a root injector, calls `navigateByUrl(path)`, and then waits for Zone.js stability. - `SetComponentProperty(selector, propertyName string, value any) error`: Sets `componentInstance[propertyName]` and ticks `ApplicationRef` when available. - `SetNgModel(selector string, value any) error`: Assigns `element.value`, dispatches bubbling `input` and `change` events, and then ticks `ApplicationRef` on the first Angular root that exposes it. - `SetTimeout(d time.Duration)`: Replaces the helper's default timeout for later Angular operations. - `TriggerChangeDetection() error`: Tries to tick `ApplicationRef` on the first Angular root. The method only reports script-evaluation failures; a `false` result from the script is ignored. - `WaitForAngular() error`: Verifies that the page looks like an Angular application, then waits for Zone.js stability. It first tries an async Zone-based script and falls back to polling every 50 ms until the helper timeout expires. - `WaitForComponent(selector string) error`: Polls every 100 ms until `selector` resolves to an element with an Angular `componentInstance`, or until the helper timeout expires. ### AngularRouterState Declaration: `type AngularRouterState struct` Represents the Angular Router state returned by `AngularHelper.GetRouterState`. Fields: - `URL string`: Current router URL. - `Fragment string`: Current URL fragment when Angular reports one. - `Params map[string]string`: Root route parameters copied from the router state. - `QueryParams map[string]string`: Root query parameters copied from the router state. ### BlurAction Declaration: `type BlurAction struct` Removes focus from an element selected by CSS. Fields: - `Selector string`: CSS selector passed to `document.querySelector`. Methods: - `Execute(ctx context.Context, wv *Webview) error`: Runs `document.querySelector(Selector)?.blur()` through `wv.evaluate`. ### BoundingBox Declaration: `type BoundingBox struct` Represents element coordinates derived from `DOM.getBoxModel`. Fields: - `X float64`: Left edge of the content box. - `Y float64`: Top edge of the content box. - `Width float64`: Width computed from the first and second X coordinates in the CDP content quad. - `Height float64`: Height computed from the first and third Y coordinates in the CDP content quad. ### CDPClient Declaration: `type CDPClient struct` Low-level Chrome DevTools Protocol client backed by a single WebSocket connection. All fields are unexported. Methods: - `Call(ctx context.Context, method string, params map[string]any) (map[string]any, error)`: Clones `params`, assigns a monotonically increasing message ID, writes the request, and waits for the matching CDP response, `ctx.Done()`, or client shutdown. - `Close() error`: Cancels the client context, fails pending calls, closes the WebSocket, waits for the read loop to exit, and returns a wrapped close error only when the socket close itself fails with a non-terminal error. - `CloseTab() error`: Extracts the current target ID from the WebSocket URL, calls `Target.closeTarget`, checks `success` when the field is present, and then closes the client. - `DebugURL() string`: Returns the canonical debug HTTP URL stored on the client. - `NewTab(url string) (*CDPClient, error)`: Creates a target via `/json/new`, validates the returned WebSocket debugger URL, dials it, and returns a new `CDPClient`. - `OnEvent(method string, handler func(map[string]any))`: Registers a handler for a CDP event method name. Event dispatch clones the handler list and event params and invokes each handler in its own goroutine. - `Send(method string, params map[string]any) error`: Clones `params` and writes a fire-and-forget CDP message without waiting for a response. - `WebSocketURL() string`: Returns the target WebSocket URL currently in use. ### CheckAction Declaration: `type CheckAction struct` Synchronises a checkbox state by clicking when the current `checked` state differs from the requested value. Fields: - `Selector string`: CSS selector for the checkbox element. - `Checked bool`: Desired checked state. Methods: - `Execute(ctx context.Context, wv *Webview) error`: Evaluates a script that clicks the element only when `el.checked != Checked`. ### ClearAction Declaration: `type ClearAction struct` Clears the value of an input-like element. Fields: - `Selector string`: CSS selector for the target element. Methods: - `Execute(ctx context.Context, wv *Webview) error`: Sets `el.value = ""` and dispatches bubbling `input` and `change` events when the element exists. ### ClickAction Declaration: `type ClickAction struct` Action wrapper for the `Webview` click implementation. Fields: - `Selector string`: CSS selector for the target element. Methods: - `Execute(ctx context.Context, wv *Webview) error`: Delegates to `wv.click(ctx, Selector)`. ### ConsoleFilter Declaration: `type ConsoleFilter struct` Filter used by `ConsoleWatcher`. Fields: - `Type string`: Exact message-type match. The watcher compares it directly against `ConsoleMessage.Type`. - `Pattern string`: Case-sensitive substring match against `ConsoleMessage.Text`. ### ConsoleHandler Declaration: `type ConsoleHandler func(msg ConsoleMessage)` Callback signature used by `ConsoleWatcher.AddHandler`. ### ConsoleMessage Declaration: `type ConsoleMessage struct` Represents one console message captured from `Runtime.consoleAPICalled`. Fields: - `Type string`: Console message type reported by CDP. - `Text string`: Message text built by joining `args[*].value` with spaces. - `Timestamp time.Time`: Local capture time assigned in Go with `time.Now()`. - `URL string`: URL taken from the first stack-frame entry when present. - `Line int`: Line number taken from the first stack-frame entry when present. - `Column int`: Column number taken from the first stack-frame entry when present. ### ConsoleWatcher Declaration: `type ConsoleWatcher struct` Higher-level console log collector layered on top of `Webview`. All fields are unexported. New watchers start with an empty message buffer and a default limit of 1000 messages. Methods: - `AddFilter(filter ConsoleFilter)`: Appends a filter. When at least one filter exists, `FilteredMessages` and `FilteredMessagesAll` use OR semantics across filters. - `AddHandler(handler ConsoleHandler)`: Registers a callback for future messages captured by this watcher. - `Clear()`: Removes all stored messages. - `ClearFilters()`: Removes every registered filter. - `Count() int`: Returns the current number of stored messages. - `ErrorCount() int`: Counts stored messages where `Type == "error"`. - `Errors() []ConsoleMessage`: Returns a collected slice of error messages. - `ErrorsAll() iter.Seq[ConsoleMessage]`: Returns an iterator that yields stored messages whose type is exactly `"error"`. - `FilteredMessages() []ConsoleMessage`: Returns a collected slice of messages that match the current filter set, or all messages when no filters exist. - `FilteredMessagesAll() iter.Seq[ConsoleMessage]`: Returns an iterator over the current filtered view. - `HasErrors() bool`: Reports whether any stored message has `Type == "error"`. - `Messages() []ConsoleMessage`: Returns a collected slice of all stored messages. - `MessagesAll() iter.Seq[ConsoleMessage]`: Returns an iterator over the stored message buffer. - `SetLimit(limit int)`: Replaces the retention limit used for future appends. Existing messages are only trimmed on later writes. - `WaitForError(ctx context.Context) (*ConsoleMessage, error)`: Equivalent to `WaitForMessage(ctx, ConsoleFilter{Type: "error"})`. - `WaitForMessage(ctx context.Context, filter ConsoleFilter) (*ConsoleMessage, error)`: Returns the first already-stored message that matches `filter`, otherwise registers a temporary handler and waits for the next matching message or `ctx.Done()`. - `Warnings() []ConsoleMessage`: Returns a collected slice of messages whose type is exactly `"warning"`. - `WarningsAll() iter.Seq[ConsoleMessage]`: Returns an iterator over stored messages whose type is exactly `"warning"`. ### DoubleClickAction Declaration: `type DoubleClickAction struct` Double-click action for an element selected by CSS. Fields: - `Selector string`: CSS selector for the target element. Methods: - `Execute(ctx context.Context, wv *Webview) error`: Uses a JavaScript `dblclick` fallback when the element has no bounding box; otherwise sends two `mousePressed` and `mouseReleased` pairs with increasing `clickCount` values at the element centre. ### ElementInfo Declaration: `type ElementInfo struct` Represents DOM metadata returned by `Webview.querySelector` and `Webview.querySelectorAll`. Fields: - `NodeID int`: CDP node ID used for later DOM operations. - `TagName string`: `nodeName` returned by `DOM.describeNode`. - `Attributes map[string]string`: Attributes parsed from the alternating key/value array returned by CDP. - `InnerHTML string`: Declared field for inner HTML content. The current implementation does not populate it. - `InnerText string`: Declared field for inner text content. The current implementation does not populate it. - `BoundingBox *BoundingBox`: Element box derived from `DOM.getBoxModel`. It is `nil` when box lookup fails. ### ExceptionInfo Declaration: `type ExceptionInfo struct` Represents one `Runtime.exceptionThrown` event captured by `ExceptionWatcher`. Fields: - `Text string`: Exception text, overridden by `exception.description` when CDP provides one. - `LineNumber int`: Line number reported by CDP. - `ColumnNumber int`: Column number reported by CDP. - `URL string`: Source URL reported by CDP. - `StackTrace string`: Stack trace formatted in Go as one `at function (url:line:column)` line per call frame. - `Timestamp time.Time`: Local capture time assigned in Go with `time.Now()`. ### ExceptionWatcher Declaration: `type ExceptionWatcher struct` Collector for JavaScript exceptions emitted by the bound `Webview`. All fields are unexported. Methods: - `AddHandler(handler func(ExceptionInfo))`: Registers a callback for future exception events. - `Clear()`: Removes all stored exceptions. - `Count() int`: Returns the current number of stored exceptions. - `Exceptions() []ExceptionInfo`: Returns a collected slice of all stored exceptions. - `ExceptionsAll() iter.Seq[ExceptionInfo]`: Returns an iterator over the stored exception buffer. - `HasExceptions() bool`: Reports whether any exceptions have been captured. - `WaitForException(ctx context.Context) (*ExceptionInfo, error)`: Returns the most recently stored exception immediately when one already exists; otherwise registers a temporary handler and waits for the next exception or `ctx.Done()`. ### FocusAction Declaration: `type FocusAction struct` Moves focus to an element selected by CSS. Fields: - `Selector string`: CSS selector passed to `document.querySelector`. Methods: - `Execute(ctx context.Context, wv *Webview) error`: Runs `document.querySelector(Selector)?.focus()` through `wv.evaluate`. ### HoverAction Declaration: `type HoverAction struct` Moves the mouse pointer over an element. Fields: - `Selector string`: CSS selector for the target element. Methods: - `Execute(ctx context.Context, wv *Webview) error`: Looks up the element, requires a non-nil bounding box, computes the box centre, and sends one `Input.dispatchMouseEvent` call with `type: "mouseMoved"`. ### NavigateAction Declaration: `type NavigateAction struct` Action wrapper for page navigation. Fields: - `URL string`: URL passed to `Page.navigate`. Methods: - `Execute(ctx context.Context, wv *Webview) error`: Calls `Page.navigate` and then waits until `document.readyState == "complete"`. ### Option Declaration: `type Option func(*Webview) error` Functional configuration hook applied by `New`. The exported option constructors are `WithDebugURL`, `WithTimeout`, and `WithConsoleLimit`. ### PressKeyAction Declaration: `type PressKeyAction struct` Key-press action implemented through `Input.dispatchKeyEvent`. Fields: - `Key string`: Key name or character to send. Methods: - `Execute(ctx context.Context, wv *Webview) error`: Uses explicit CDP key metadata for common keys such as `Enter`, `Tab`, arrow keys, `Delete`, and paging keys. For any other string it sends a `keyDown` with `text: Key` followed by a bare `keyUp`. ### RemoveAttributeAction Declaration: `type RemoveAttributeAction struct` Removes a DOM attribute. Fields: - `Selector string`: CSS selector for the target element. - `Attribute string`: Attribute name to remove. Methods: - `Execute(ctx context.Context, wv *Webview) error`: Runs `document.querySelector(Selector)?.removeAttribute(Attribute)` through `wv.evaluate`. ### RightClickAction Declaration: `type RightClickAction struct` Context-click action for an element selected by CSS. Fields: - `Selector string`: CSS selector for the target element. Methods: - `Execute(ctx context.Context, wv *Webview) error`: Uses a JavaScript `contextmenu` fallback when the element has no bounding box; otherwise sends `mousePressed` and `mouseReleased` with `button: "right"` at the element centre. ### ScrollAction Declaration: `type ScrollAction struct` Window scroll action. Fields: - `X int`: Horizontal scroll target passed to `window.scrollTo`. - `Y int`: Vertical scroll target passed to `window.scrollTo`. Methods: - `Execute(ctx context.Context, wv *Webview) error`: Evaluates `window.scrollTo(X, Y)`. ### ScrollIntoViewAction Declaration: `type ScrollIntoViewAction struct` Scrolls a selected element into view. Fields: - `Selector string`: CSS selector for the target element. Methods: - `Execute(ctx context.Context, wv *Webview) error`: Evaluates `document.querySelector(Selector)?.scrollIntoView({behavior: "smooth", block: "center"})`. ### SelectAction Declaration: `type SelectAction struct` Select-element value setter. Fields: - `Selector string`: CSS selector for the target element. - `Value string`: Option value assigned to `el.value`. Methods: - `Execute(ctx context.Context, wv *Webview) error`: Sets `el.value` and dispatches a bubbling `change` event when the element exists. ### SetAttributeAction Declaration: `type SetAttributeAction struct` Sets a DOM attribute on the selected element. Fields: - `Selector string`: CSS selector for the target element. - `Attribute string`: Attribute name to set. - `Value string`: Attribute value passed to `setAttribute`. Methods: - `Execute(ctx context.Context, wv *Webview) error`: Runs `document.querySelector(Selector)?.setAttribute(Attribute, Value)` through `wv.evaluate`. ### SetValueAction Declaration: `type SetValueAction struct` Directly sets an input-like value. Fields: - `Selector string`: CSS selector for the target element. - `Value string`: Value assigned to `el.value`. Methods: - `Execute(ctx context.Context, wv *Webview) error`: Sets `el.value` and dispatches bubbling `input` and `change` events when the element exists. ### TargetInfo Declaration: `type TargetInfo struct` Represents one target entry returned by Chrome's `/json` and `/json/new` endpoints. Fields: - `ID string`: Chrome target ID. - `Type string`: Target type such as `page`. - `Title string`: Target title reported by Chrome. - `URL string`: Target URL reported by Chrome. - `WebSocketDebuggerURL string`: WebSocket debugger URL for the target. ### TypeAction Declaration: `type TypeAction struct` Action wrapper for `Webview` text entry. Fields: - `Selector string`: CSS selector for the target element. - `Text string`: Text sent one rune at a time. Methods: - `Execute(ctx context.Context, wv *Webview) error`: Delegates to `wv.typeText(ctx, Selector, Text)`. ### WaitAction Declaration: `type WaitAction struct` Time-based delay action. Fields: - `Duration time.Duration`: Delay length. Methods: - `Execute(ctx context.Context, wv *Webview) error`: Waits for `Duration` with `time.After`, but returns `ctx.Err()` immediately if the context is cancelled first. ### WaitForSelectorAction Declaration: `type WaitForSelectorAction struct` Action wrapper for selector polling. Fields: - `Selector string`: CSS selector to wait for. Methods: - `Execute(ctx context.Context, wv *Webview) error`: Delegates to `wv.waitForSelector(ctx, Selector)`. ### Webview Declaration: `type Webview struct` High-level browser automation client built on `CDPClient`. All fields are unexported. Instances created by `New` carry a default timeout of 30 seconds and a default console retention limit of 1000 messages. Methods: - `ClearConsole()`: Removes all console messages stored on the `Webview`. - `Click(selector string) error`: Creates a timeout-scoped context and delegates to the internal click path. The internal click logic queries the element, uses a JavaScript `.click()` fallback when there is no bounding box, and otherwise sends left-button press and release events at the element centre. - `Close() error`: Cancels the `Webview` context and closes the underlying `CDPClient` when one exists. - `DragAndDrop(sourceSelector, targetSelector string) error`: Looks up both elements, requires bounding boxes for both, then sends `mousePressed` at the source centre, `mouseMoved` to the target centre, and `mouseReleased` at the target centre. - `Evaluate(script string) (any, error)`: Evaluates JavaScript through `Runtime.evaluate` with `returnByValue: true` and `awaitPromise: true`. When CDP reports `exceptionDetails`, the method returns a wrapped JavaScript error. - `GetConsole() []ConsoleMessage`: Returns a collected slice of stored console messages. - `GetConsoleAll() iter.Seq[ConsoleMessage]`: Returns an iterator over the stored console message buffer. - `GetHTML(selector string) (string, error)`: Returns `document.documentElement.outerHTML` when `selector` is empty; otherwise returns `document.querySelector(selector)?.outerHTML || ""`. - `GetTitle() (string, error)`: Evaluates `document.title` and requires the result to be a string. - `GetURL() (string, error)`: Evaluates `window.location.href` and requires the result to be a string. - `GoBack() error`: Calls `Page.goBackOrForward` with `delta: -1`. - `GoForward() error`: Calls `Page.goBackOrForward` with `delta: 1`. - `Navigate(url string) error`: Calls `Page.navigate` and then polls `document.readyState` every 100 ms until it becomes `"complete"` or the timeout expires. - `QuerySelector(selector string) (*ElementInfo, error)`: Fetches the document root, runs `DOM.querySelector`, errors when the selector does not resolve, and returns `ElementInfo` for the matched node. - `QuerySelectorAll(selector string) ([]*ElementInfo, error)`: Runs `DOM.querySelectorAll` and returns one `ElementInfo` per node ID whose metadata lookup succeeds. Nodes whose metadata fetch fails are skipped. - `QuerySelectorAllAll(selector string) iter.Seq[*ElementInfo]`: Returns an iterator that runs `QuerySelectorAll` under the `Webview` timeout and yields each element. Errors produce an empty iterator. - `Reload() error`: Calls `Page.reload` and then waits for `document.readyState == "complete"`. - `Screenshot() ([]byte, error)`: Calls `Page.captureScreenshot` with `format: "png"`, decodes the returned base64 payload, and returns the PNG bytes. - `SetUserAgent(userAgent string) error`: Calls `Emulation.setUserAgentOverride`. - `SetViewport(width, height int) error`: Calls `Emulation.setDeviceMetricsOverride` with the supplied size, `deviceScaleFactor: 1`, and `mobile: false`. - `Type(selector, text string) error`: Creates a timeout-scoped context and delegates to the internal typing path. The internal logic focuses the element with JavaScript, then sends one `keyDown` with `text` and one `keyUp` per rune in `text`. - `UploadFile(selector string, filePaths []string) error`: Resolves the target node with `QuerySelector` and passes its node ID to `DOM.setFileInputFiles`. - `WaitForSelector(selector string) error`: Polls `!!document.querySelector(selector)` every 100 ms until it becomes true or the timeout expires. ## Functions ### FormatConsoleOutput `func FormatConsoleOutput(messages []ConsoleMessage) string` Formats each message as `HH:MM:SS.mmm [PREFIX] text\n`. Prefixes are `[ERROR]` for `error`, `[WARN]` for `warning`, `[INFO]` for `info`, `[DEBUG]` for `debug`, and `[LOG]` for every other type. ### GetVersion `func GetVersion(debugURL string) (map[string]string, error)` Validates `debugURL`, requests `/json/version`, and decodes the response body into `map[string]string`. ### ListTargets `func ListTargets(debugURL string) ([]TargetInfo, error)` Validates `debugURL`, requests `/json`, and decodes the response body into a slice of `TargetInfo`. ### ListTargetsAll `func ListTargetsAll(debugURL string) iter.Seq[TargetInfo]` Iterator wrapper around `ListTargets`. When `ListTargets` fails, the iterator yields no values. ### New `func New(opts ...Option) (*Webview, error)` Creates a `Webview`, applies `opts` in order, requires an option that installs a `CDPClient`, enables the `Runtime`, `Page`, and `DOM` domains, and subscribes console capture. On any option or initialisation failure it cancels the context and closes the client when one was created. ### NewActionSequence `func NewActionSequence() *ActionSequence` Creates an empty `ActionSequence`. ### NewAngularHelper `func NewAngularHelper(wv *Webview) *AngularHelper` Creates an `AngularHelper` bound to `wv` with a 30-second default timeout. ### NewCDPClient `func NewCDPClient(debugURL string) (*CDPClient, error)` Validates that `debugURL` is an `http` or `https` DevTools root URL with no credentials, query, fragment, or non-root path. The function requests `/json`, picks the first `page` target with a debugger WebSocket URL, creates a new target via `/json/new` when none exists, validates that the WebSocket host matches the debug host, dials the socket, and starts the client's read loop. ### NewConsoleWatcher `func NewConsoleWatcher(wv *Webview) *ConsoleWatcher` Creates a `ConsoleWatcher`, initialises an empty message buffer with a 1000-message limit, and subscribes it to `Runtime.consoleAPICalled` events on `wv.client`. ### NewExceptionWatcher `func NewExceptionWatcher(wv *Webview) *ExceptionWatcher` Creates an `ExceptionWatcher`, initialises an empty exception buffer, and subscribes it to `Runtime.exceptionThrown` events on `wv.client`. ### WithConsoleLimit `func WithConsoleLimit(limit int) Option` Returns an `Option` that replaces `Webview.consoleLimit`. The default used by `New` is 1000. ### WithDebugURL `func WithDebugURL(url string) Option` Returns an `Option` that dials a `CDPClient` immediately and stores it on the `Webview`. ### WithTimeout `func WithTimeout(d time.Duration) Option` Returns an `Option` that replaces the default per-operation timeout used by `Webview` methods.