web

package
v0.2.0-beta.4 Latest Latest
Warning

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

 Go to latest Published: Sep 4, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

Package web is the Chrome DevTools Protocol execution surface.

Spec 02-device-drivers.md §4 defines it: the hierarchy comes from an injected script, actions are pointer and key input, and settling is document.readyState == "complete". Everything a browser has no notion of — apps, permissions, airplane mode, orientation, media — returns device.ErrUnsupported so preflight refuses such a flow before it runs rather than failing halfway through it.

Index

Constants

View Source 
const DefaultSettleTimeout = 10 * time.Second

DefaultSettleTimeout bounds a readyState wait. A page that never completes must report an unconfirmed settle rather than block the run forever.

View Source 
const Platform = device.Platform("web")

Variables

This section is empty.

Functions

func DeclaredCapabilities 

func DeclaredCapabilities() device.Capabilities

DeclaredCapabilities is the non-mutating Web capability document used by both the driver and selected-platform flow preflight.

func DefaultChromeBinary 

func DefaultChromeBinary() string

DefaultChromeBinary is where the browser lives on this platform.

Types

type Chrome 

type Chrome struct {
	BaseURL string
	// contains filtered or unexported fields
}

Chrome is a browser this process started and is responsible for stopping.

func LaunchChrome 

func LaunchChrome(ctx context.Context, options ChromeOptions) (*Chrome, error)

LaunchChrome starts the browser and waits for DevTools to answer.

It waits for the endpoint rather than returning immediately: a driver that attaches before the browser is listening fails with a connection error that reads like a missing browser rather than a race.

func (*Chrome) Stop 

func (chrome *Chrome) Stop() error

Stop ends the browser and removes a profile this launcher created.

The profile is removed whether or not there is still a process to kill: a browser that already exited on its own still leaves its profile behind, and that is disk the run is responsible for.

type ChromeOptions 

type ChromeOptions struct {
	// Binary is the browser executable; empty picks the platform default.
	Binary string
	// Port is the DevTools port to listen on.
	Port int
	// UserDataDir isolates the run's profile.
	UserDataDir string
	// Headless selects --headless=new.
	Headless bool
	// WindowSize is the "width,height" the spec passes through.
	WindowSize string
}

type Driver 

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

Driver drives one attached browser page over CDP.

func NewDriver 

func NewDriver(baseURL string, client *http.Client) *Driver

NewDriver builds a driver for a browser already listening for DevTools on baseURL (for example http://127.0.0.1:9222). A nil client uses the default.

func NewLaunchingDriver 

func NewLaunchingDriver(options ChromeOptions) *Driver

NewLaunchingDriver builds a driver that starts its own browser on Open and stops it on Close. This is what a CLI run needs: it is handed flows, not a DevTools endpoint.

func (*Driver) AddMedia 

func (driver *Driver) AddMedia(context.Context, device.AddMediaRequest) error

func (*Driver) BackPress 

func (driver *Driver) BackPress(ctx context.Context) error

BackPress is browser history, which is what "back" means on the web.

func (*Driver) Capabilities 

func (driver *Driver) Capabilities() device.Capabilities

func (*Driver) ClearAppState 

func (driver *Driver) ClearAppState(context.Context, device.AppRequest) error

func (*Driver) ClearKeychain 

func (driver *Driver) ClearKeychain(context.Context) error

func (*Driver) Close 

func (driver *Driver) Close(context.Context) error

func (*Driver) CollectCrashArtifacts 

func (driver *Driver) CollectCrashArtifacts(
	context.Context, device.ArtifactRequest,
) ([]device.Artifact, error)

func (*Driver) ContentDescriptor 

func (driver *Driver) ContentDescriptor(
	ctx context.Context, _ device.ContentDescriptorRequest,
) (device.TreeNode, error)

ContentDescriptor runs the injected walker and converts its payload.

func (*Driver) DeviceInfo 

func (driver *Driver) DeviceInfo(ctx context.Context) (device.DeviceInfo, error)

func (*Driver) EraseText 

func (driver *Driver) EraseText(ctx context.Context, request device.EraseTextRequest) error

EraseText sends one BACK_SPACE per character (spec §4).

func (*Driver) HideKeyboard 

func (driver *Driver) HideKeyboard(context.Context) error

func (*Driver) InputText 

func (driver *Driver) InputText(ctx context.Context, request device.InputTextRequest) error

InputText types the text as one insertion. Input.insertText is what a page's input handlers see as real typing, including for non-ASCII text a synthetic per-key sequence would mangle.

func (*Driver) IsAirplaneModeEnabled 

func (driver *Driver) IsAirplaneModeEnabled(context.Context) (bool, error)

func (*Driver) IsKeyboardVisible 

func (driver *Driver) IsKeyboardVisible(context.Context, device.KeyboardRequest) (bool, error)

func (*Driver) IsShutdown 

func (driver *Driver) IsShutdown(context.Context) (bool, error)

func (*Driver) KillApp 

func (driver *Driver) KillApp(context.Context, device.AppRequest) error

func (*Driver) LaunchApp 

func (driver *Driver) LaunchApp(ctx context.Context, request device.LaunchAppRequest) error

LaunchApp opens the flow's page.

specs/01-core-engine.md:17 makes `url` the web flow's effective appId, so the target arrives here in AppID. A value that is not an http(s) url is a mobile flow aimed at a browser: navigating to it anyway would resolve it as a relative path and run the whole suite against some other page.

func (*Driver) LongPress 

func (driver *Driver) LongPress(ctx context.Context, request device.LongPressRequest) error

func (*Driver) Name 

func (driver *Driver) Name() string

func (*Driver) Open 

func (driver *Driver) Open(ctx context.Context) error

Open attaches to the browser's page target, starting one first when this driver owns it. 

func (driver *Driver) OpenLink(ctx context.Context, request device.OpenLinkRequest) error

func (*Driver) PressKey 

func (driver *Driver) PressKey(ctx context.Context, request device.PressKeyRequest) error

PressKey maps the neutral key codes a browser can act on. A code with no web meaning (LOCK, HOME on a phone) is refused rather than silently dropped.

func (*Driver) QueryOnDeviceElements 

func (driver *Driver) QueryOnDeviceElements(
	ctx context.Context, request device.QueryRequest,
) ([]device.TreeNode, error)

QueryOnDeviceElements resolves a CSS expression in the page. This is the driver-side resolver a css selector needs: CSS is a query, not a value, so it cannot be matched against a captured attribute.

func (*Driver) ResetProxy 

func (driver *Driver) ResetProxy(context.Context) error

func (*Driver) ScrollVertical 

func (driver *Driver) ScrollVertical(ctx context.Context, request device.ScrollVerticalRequest) error

func (*Driver) SetAirplaneMode 

func (driver *Driver) SetAirplaneMode(context.Context, device.AirplaneModeRequest) error

func (*Driver) SetAndroidChromeDevToolsEnabled 

func (driver *Driver) SetAndroidChromeDevToolsEnabled(
	context.Context, device.ChromeDevToolsRequest,
) error

func (*Driver) SetLocation 

func (driver *Driver) SetLocation(ctx context.Context, location device.Location) error

SetLocation overrides geolocation, which a browser genuinely supports.

func (*Driver) SetOrientation 

func (driver *Driver) SetOrientation(context.Context, device.Orientation) error

func (*Driver) SetPermissions 

func (driver *Driver) SetPermissions(context.Context, device.PermissionsRequest) error

func (*Driver) SetProxy 

func (driver *Driver) SetProxy(context.Context, device.Proxy) error

func (*Driver) StartDeviceLogCapture 

func (driver *Driver) StartDeviceLogCapture(
	context.Context, device.DeviceLogRequest,
) (device.CaptureID, error)

func (*Driver) StartScreenRecording 

func (driver *Driver) StartScreenRecording(
	context.Context, device.ScreenRecordingRequest,
) (device.CaptureID, error)

func (*Driver) StopApp 

func (driver *Driver) StopApp(ctx context.Context, request device.AppRequest) error

StopApp unloads the page.

specs/06-launch-app-semantics.md has launchApp stop the app before starting it unless the flow says otherwise, so every web run reaches this on its way to its first page. about:blank is the browser's version of stopping: it drops the document, its scripts and its timers. Returning nil without navigating would leave the old page live and let a stale assertion pass against it.

func (*Driver) StopDeviceLogCapture 

func (driver *Driver) StopDeviceLogCapture(
	context.Context, device.CaptureID,
) ([]device.Artifact, error)

func (*Driver) Swipe 

func (driver *Driver) Swipe(ctx context.Context, request device.SwipeRequest) error

Swipe is touch input: move to the start, press, move to the end, release (spec §4). Direction-only and element-anchored swipes are resolved against the viewport before dispatch.

func (*Driver) TakeScreenshot 

func (driver *Driver) TakeScreenshot(
	ctx context.Context, _ device.ScreenshotRequest,
) ([]byte, error)

func (*Driver) Tap 

func (driver *Driver) Tap(ctx context.Context, request device.TapRequest) error

Tap is the full pointer sequence: a page listening for mousedown/mouseup never sees a click sent as one event (spec §4 pointer input).

func (*Driver) WaitForAppToSettle 

func (driver *Driver) WaitForAppToSettle(
	ctx context.Context, request device.SettleRequest,
) (*device.ViewHierarchy, error)

WaitForAppToSettle polls document.readyState (spec §4). A nil hierarchy means settling could not be confirmed, which the contract separates from settled.

func (*Driver) WaitUntilScreenIsStatic 

func (driver *Driver) WaitUntilScreenIsStatic(
	ctx context.Context, request device.ScreenStaticRequest,
) (bool, error)

Source Files

View all Source files

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.