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
- Variables
- func ChromeAllocator(parent context.Context, opts Options) (ctx context.Context, cancel context.CancelFunc, path string, err error)
- func FindChrome(explicit string, env func(string) string) (string, error)
- func FirefoxReady(env func(string) string) (bool, string)
- func IsWebDriver(b Browser) bool
- func OpenTab(ctx context.Context, b Browser, dialog func(message string) bool) (tab context.Context, crashed <-chan struct{}, stop func(), ...)
- func ParseList(s string) ([]string, error)
- func RetryableClick(err error) bool
- type Browser
- type Options
- type PageReport
- type Unavailable
- type WDPage
- func (p *WDPage) AlertAnswer(ctx context.Context, accept bool) error
- func (p *WDPage) AlertText(ctx context.Context) (string, bool)
- func (p *WDPage) Back(ctx context.Context) error
- func (p *WDPage) Click(ctx context.Context, css string) error
- func (p *WDPage) Close()
- func (p *WDPage) Execute(ctx context.Context, body string) (json.RawMessage, error)
- func (p *WDPage) Forward(ctx context.Context) error
- func (p *WDPage) Keys(ctx context.Context, text string) error
- func (p *WDPage) Navigate(ctx context.Context, url string) error
Constants ¶
const ( Chrome = "chrome" Safari = "safari" Firefox = "firefox" )
Names of the supported browsers, as they are spelled on the command line.
Variables ¶
var All = []string{Chrome, Safari, Firefox}
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 ¶
FindChrome returns the Chrome or Chromium executable: the explicit path, then $CHROME_BIN, then the usual install locations and the PATH.
func FirefoxReady ¶
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 ¶
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 RetryableClick ¶
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.
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 ¶
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 ¶
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 ¶
AlertAnswer accepts or dismisses the open dialog.
func (*WDPage) AlertText ¶
AlertText returns the message of the open alert, confirm or prompt, and whether there is one.
func (*WDPage) Click ¶
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 ¶
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.