browsers

package
v0.1.1 Latest Latest
Warning

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

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package browsers finds and drives the browsers that run the YPY test suites: Chrome or Chromium through the DevTools protocol (chromedp), Safari through safaridriver and Firefox through geckodriver (the WebDriver HTTP protocol).

A browser that is not available is not an error of the run: Open returns an *Unavailable value that carries the instruction to make it available, and the caller reports it as skipped.

Index

Constants

View Source
const (
	Chrome  = "chrome"
	Safari  = "safari"
	Firefox = "firefox"
)

Names of the supported browsers, as they are spelled on the command line.

Variables

All lists the supported browsers in report order.

Functions

func ChromeAllocator

func ChromeAllocator(parent context.Context, opts Options) (ctx context.Context, cancel context.CancelFunc, path string, err error)

ChromeAllocator starts Chrome and returns a chromedp context bound to the browser. Its first tab is open. The caller must call cancel.

func FindChrome

func FindChrome(explicit string, env func(string) string) (string, error)

FindChrome returns the Chrome or Chromium executable: the explicit path, then $CHROME_BIN, then the usual install locations and the PATH.

func FirefoxReady

func FirefoxReady(env func(string) string) (bool, string)

FirefoxReady says whether Firefox can be driven here: geckodriver on the PATH and a Firefox executable. When it cannot, the string is the one-line reason.

func IsWebDriver

func IsWebDriver(b Browser) bool

IsWebDriver says whether b is driven through the WebDriver protocol (Firefox and Safari), so that OpenWDPage works on it.

func OpenTab

func OpenTab(ctx context.Context, b Browser, dialog func(message string) bool) (tab context.Context, crashed <-chan struct{}, stop func(), logs func() []string, err error)

OpenTab is the end to end harness's view of Chrome: open a tab with the same settings as the test pages.

func ParseList

func ParseList(s string) ([]string, error)

ParseList splits a comma separated list of browser names and validates it.

func RetryableClick

func RetryableClick(err error) bool

RetryableClick says whether a failed click may work a moment later: the element is not there yet, is being replaced or is not shown yet.

Types

type Browser

type Browser interface {
	// Name is the command line name: chrome, safari or firefox.
	Name() string
	// Label is a human name with the version when known.
	Label() string
	// MaxParallel is how many pages may run at once (0 means no limit).
	MaxParallel() int
	// RunPage opens url in a fresh page and returns when done is closed, ctx
	// ends or the page dies. The page is closed before it returns.
	RunPage(ctx context.Context, url string, done <-chan struct{}) PageReport
	// Close stops the browser and its driver.
	Close() error
}

Browser runs one page at a time per call; RunPage may be called from several goroutines up to MaxParallel.

func Open

func Open(ctx context.Context, name string, opts Options) (Browser, error)

Open starts the named browser. When the browser is not available it returns an *Unavailable error.

type Options

type Options struct {
	// ChromePath is the Chrome or Chromium executable; empty means discover it.
	ChromePath string
	// Headed shows the browser window (Chrome only; Safari always shows one).
	Headed bool
	// Logs collects the console output of every page (Chrome only).
	Logs bool
	// ChromeFlags adds command line switches to Chrome (Chrome only): the key is
	// the switch without the leading dashes, the value a string or a bool.
	ChromeFlags map[string]any
	// KeepDialogs leaves an alert, confirm or prompt open for the caller to
	// answer (WebDriver browsers; the default dismisses it at once). The end to
	// end suite sets it so that a scenario can choose the answer.
	KeepDialogs bool
	// Env reads an environment variable; nil means "no variables".
	Env func(string) string
}

Options configure how a browser is found and started.

type PageReport

type PageReport struct {
	// Logs are console lines (only when Options.Logs is set).
	Logs []string
	// Err is set when the page could not be opened, crashed or the run was
	// canceled before the page finished.
	Err error
}

PageReport is what a browser tells about a page it ran.

type Unavailable

type Unavailable struct {
	Browser string
	// Reason is one line: what is missing.
	Reason string
	// Hint is the exact instruction for the person at the keyboard.
	Hint string
}

Unavailable says a browser cannot be used here and how to fix it.

func (*Unavailable) Error

func (u *Unavailable) Error() string

type WDPage

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

WDPage is one window of a WebDriver browser, used by the end to end suite. Firefox and Safari allow a single session, so a WDPage holds the browser until Close: one page at a time.

func OpenWDPage

func OpenWDPage(ctx context.Context, b Browser) (*WDPage, error)

OpenWDPage waits for the browser to be free and opens a fresh window in it (own history), falling back to the session's window when the driver cannot open another one.

func (*WDPage) AlertAnswer

func (p *WDPage) AlertAnswer(ctx context.Context, accept bool) error

AlertAnswer accepts or dismisses the open dialog.

func (*WDPage) AlertText

func (p *WDPage) AlertText(ctx context.Context) (string, bool)

AlertText returns the message of the open alert, confirm or prompt, and whether there is one.

func (*WDPage) Back

func (p *WDPage) Back(ctx context.Context) error

Back goes one entry back in the history.

func (*WDPage) Click

func (p *WDPage) Click(ctx context.Context, css string) error

Click clicks the element's center with the pointer, after scrolling it into view.

func (*WDPage) Close

func (p *WDPage) Close()

Close dismisses a dialog left open, clears the storage the page used, closes its window and frees the browser for the next page.

func (*WDPage) Execute

func (p *WDPage) Execute(ctx context.Context, body string) (json.RawMessage, error)

Execute runs the body of a script with the callback `done` in scope (it is the async form of "execute script"), and returns what it passed to done.

func (*WDPage) Forward

func (p *WDPage) Forward(ctx context.Context) error

Forward goes one entry forward in the history.

func (*WDPage) Keys

func (p *WDPage) Keys(ctx context.Context, text string) error

Keys types the text, key by key, into the element that has the focus. A key is a WebDriver key code point (Enter is "").

func (*WDPage) Navigate

func (p *WDPage) Navigate(ctx context.Context, url string) error

Navigate loads the address and returns after the load event.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL