webdriver

package module
Version: v0.0.0-...-da6a603 Latest Latest
Warning

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

Go to latest
Published: Jul 24, 2018 License: MIT Imports: 21 Imported by: 0

README

Chrome WebDriver Client for Go

GoDoc Travis Go Report Card

About

This is a WebDriver client for Go, supporting the WebDriver protocol for Chrome and ChromeDriver.

Installing

Run

go get -u github.com/radutopala/webdriver

to fetch the package.

The package requires a working WebDriver installation, which can include recent versions of a web browser being driven by Selenium WebDriver.

Documentation

The API documentation is at https://godoc.org/github.com/radutopala/webdriver. See the unit tests for better usage information.

Downloading and Pack Dependencies

Download and pack the ChromeDriver binaries:

$ go run download/download.go

You only have to do this once initially and later when version numbers in download.go change.

Testing Locally

Run the tests:

$ go test 
  • There is one top-level test for Chrome and ChromeDriver.

  • There are subtests that are shared between both top-level tests.

  • To run only the top-level tests, pass:

    • -test.run=TestChrome
  • To run a specific subtest, pass -test.run=TestChrome/<subtest> as appropriate. This flag supports regular expressions.

  • If the Chrome binaries or the ChromeDriver binary cannot be found, the corresponding tests will be skipped.

  • The binaries under test can be configured by passing flags to go test. See the available flags with go test --arg --help.

  • Add the argument -test.v to see detailed output from the test automation framework.

Testing With Docker

To ensure hermeticity, we also have tests that run under Docker. You will need an installed and running Docker system.

To run the tests under Docker, run:

$ go test --docker

This will create a new Docker container and run the tests in it. (Note: flags supplied to this invocation are not carried through to the go test invocation within the Docker container).

For debugging Docker directly, run the following commands:

$ docker build -t webdriver testing/
$ docker run --volume=${GOPATH?}:/code --workdir=/code/src/github.com/radutopala/webdriver -it webdriver bash

License

This project is licensed under the MIT license.

Please note that this project is a cut-down version of tebeka/selenium, with ideas from Symfony/Panther, targeting only the Chrome WebDriver implementation.

Documentation

Overview

package webdriver provides a client to drive web browser-based automation and testing with Chrome WebDriver

See the example below for how to get started with this API.

This package can depend on several binaries being available, depending on which browsers will be used and how. Use the methods provided by this API to specify the paths to the dependencies, which will have to be downloaded separately.

Index

Constants

View Source
const (
	// DefaultWaitInterval is the default polling interval for webdriver.Wait
	// function.
	DefaultWaitInterval = 100 * time.Millisecond

	// DefaultWaitTimeout is the default timeout for webdriver.Wait function.
	DefaultWaitTimeout = 60 * time.Second
)
View Source
const (
	ByID              = "id"
	ByXPATH           = "xpath"
	ByLinkText        = "link text"
	ByPartialLinkText = "partial link text"
	ByName            = "name"
	ByTagName         = "tag name"
	ByClassName       = "class name"
	ByCSSSelector     = "css selector"
)

Methods by which to find elements.

View Source
const (
	LeftButton = iota
	MiddleButton
	RightButton
)

Mouse buttons.

View Source
const (
	NullKey       = string('\ue000')
	CancelKey     = string('\ue001')
	HelpKey       = string('\ue002')
	BackspaceKey  = string('\ue003')
	TabKey        = string('\ue004')
	ClearKey      = string('\ue005')
	ReturnKey     = string('\ue006')
	EnterKey      = string('\ue007')
	ShiftKey      = string('\ue008')
	ControlKey    = string('\ue009')
	AltKey        = string('\ue00a')
	PauseKey      = string('\ue00b')
	EscapeKey     = string('\ue00c')
	SpaceKey      = string('\ue00d')
	PageUpKey     = string('\ue00e')
	PageDownKey   = string('\ue00f')
	EndKey        = string('\ue010')
	HomeKey       = string('\ue011')
	LeftArrowKey  = string('\ue012')
	UpArrowKey    = string('\ue013')
	RightArrowKey = string('\ue014')
	DownArrowKey  = string('\ue015')
	InsertKey     = string('\ue016')
	DeleteKey     = string('\ue017')
	SemicolonKey  = string('\ue018')
	EqualsKey     = string('\ue019')
	Numpad0Key    = string('\ue01a')
	Numpad1Key    = string('\ue01b')
	Numpad2Key    = string('\ue01c')
	Numpad3Key    = string('\ue01d')
	Numpad4Key    = string('\ue01e')
	Numpad5Key    = string('\ue01f')
	Numpad6Key    = string('\ue020')
	Numpad7Key    = string('\ue021')
	Numpad8Key    = string('\ue022')
	Numpad9Key    = string('\ue023')
	MultiplyKey   = string('\ue024')
	AddKey        = string('\ue025')
	SeparatorKey  = string('\ue026')
	SubstractKey  = string('\ue027')
	DecimalKey    = string('\ue028')
	DivideKey     = string('\ue029')
	F1Key         = string('\ue031')
	F2Key         = string('\ue032')
	F3Key         = string('\ue033')
	F4Key         = string('\ue034')
	F5Key         = string('\ue035')
	F6Key         = string('\ue036')
	F7Key         = string('\ue037')
	F8Key         = string('\ue038')
	F9Key         = string('\ue039')
	F10Key        = string('\ue03a')
	F11Key        = string('\ue03b')
	F12Key        = string('\ue03c')
	MetaKey       = string('\ue03d')
)

Special keyboard keys, for SendKeys.

View Source
const (
	// Direct connection - no proxy in use.
	Direct ProxyType = "direct"
	// Manual proxy settings configured, e.g. setting a proxy for HTTP, a proxy
	// for FTP, etc.
	Manual = "manual"
	// Autodetect proxy, probably with WPAD
	Autodetect = "autodetect"
	// System settings used.
	System = "system"
	// PAC - Proxy autoconfiguration from a URL.
	PAC = "pac"
)
View Source
const (
	DefaultServicePort = 9515
)
View Source
const DefaultURLPrefix = "http://127.0.0.1:9515"

DefaultURLPrefix is the default HTTP endpoint that offers the WebDriver API.

Variables

View Source
var HTTPClient = http.DefaultClient

HTTPClient is the default client to use to communicate with the WebDriver server.

Functions

func DefaultBinaryPath

func DefaultBinaryPath() string

func SetDebug

func SetDebug(debug bool)

SetDebug sets debug mode

Types

type Capabilities

type Capabilities map[string]interface{}

Capabilities configures both the WebDriver process and the target browsers, with standard and browser-specific options.

func (Capabilities) AddChrome

func (c Capabilities) AddChrome(f chrome.Capabilities)

AddChrome adds Chrome-specific capabilities.

func (Capabilities) AddLogging

func (c Capabilities) AddLogging(l log.Capabilities)

AddLogging adds logging configuration to the capabilities.

func (Capabilities) AddProxy

func (c Capabilities) AddProxy(p Proxy)

AddProxy adds proxy configuration to the capabilities.

func (Capabilities) SetLogLevel

func (c Capabilities) SetLogLevel(typ log.Type, level log.Level)

SetLogLevel sets the logging level of a component. It is a shortcut for passing a log.Capabilities instance to AddLogging.

type Condition

type Condition func(wd WebDriver) (bool, error)

Condition is an alias for a type that is passed as an argument for webdriver.Wait(cond Condition) (error) function.

type Cookie struct {
	Name   string `json:"name"`
	Value  string `json:"value"`
	Path   string `json:"path"`
	Domain string `json:"domain"`
	Secure bool   `json:"secure"`
	Expiry uint   `json:"expiry"`
}

Cookie represents an HTTP cookie.

type Error

type Error struct {
	// Err contains a general error string provided by the server.
	Err string `json:"error"`
	// Message is a detailed, human-readable message specific to the failure.
	Message string `json:"message"`
	// Stacktrace may contain the server-side stacktrace where the error occurred.
	Stacktrace string `json:"stacktrace"`
	// HTTPCode is the HTTP status code returned by the server.
	HTTPCode int
	// LegacyCode is the "Response Status Code" defined in the legacy Selenium
	// WebDriver JSON wire protocol. This code is only produced by older
	// Selenium WebDriver versions, Chromedriver, and InternetExplorerDriver.
	LegacyCode int
}

Error contains information about a failure of a command. See the table of these strings at https://www.w3.org/TR/webdriver/#handling-errors .

This error type is only returned by servers that implement the W3C specification.

func (*Error) Error

func (e *Error) Error() string

Error implements the error interface.

type Point

type Point struct {
	X, Y int
}

Point is a 2D point.

type Proxy

type Proxy struct {
	// Type is the type of proxy to use. This is required to be populated.
	Type ProxyType `json:"proxyType"`

	// AutoconfigURL is the URL to be used for proxy auto configuration. This is
	// required if Type is set to PAC.
	AutoconfigURL string `json:"proxyAutoconfigUrl,omitempty"`

	// The following are used when Type is set to Manual.
	//
	// Note that in Firefox, connections to localhost are not proxied by default,
	// even if a proxy is set. This can be overridden via a preference setting.
	FTP           string `json:"ftpProxy,omitempty"`
	HTTP          string `json:"httpProxy,omitempty"`
	SSL           string `json:"sslProxy,omitempty"`
	SOCKS         string `json:"socksProxy,omitempty"`
	SOCKSUsername string `json:"socksUsername,omitempty"`
	SOCKSPassword string `json:"socksPassword,omitempty"`
	NoProxy       string `json:"noProxy,omitempty"`

	// The W3C draft spec includes port fields as well. According to the
	// specification, ports can also be included in the above addresses. However,
	// in the Geckodriver implementation, the ports must be specified by these
	// additional fields.
	HTTPPort  int `json:"httpProxyPort,omitempty"`
	SSLPort   int `json:"sslProxyPort,omitempty"`
	SocksPort int `json:"socksProxyPort,omitempty"`
}

Proxy specifies configuration for proxies in the browser. Set the key "proxy" in Capabilities to an instance of this type.

type ProxyType

type ProxyType string

ProxyType is an enumeration of the types of proxies available.

type Service

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

Service controls a locally-running subprocess.

func NewService

func NewService(opts ...ServiceOption) (*Service, error)

NewService starts a ChromeDriver instance in the background.

func (*Service) Stop

func (s *Service) Stop() error

Stop shuts down the WebDriver service.

type ServiceOption

type ServiceOption func(*Service) error

ServiceOption configures a Service instance.

func BinaryPath

func BinaryPath(binaryPath string) ServiceOption

Set the Service binary path

func Cmd

func Cmd(cmd *exec.Cmd) ServiceOption

Set the Service Cmd

func Output

func Output(w io.Writer) ServiceOption

Output specifies that the WebDriver service should log to the provided writer.

func Port

func Port(port int) ServiceOption

Set the Service port

type Size

type Size struct {
	Width, Height int
}

Size is a size of HTML element.

type Status

type Status struct {
	// The following fields are used by Selenium and ChromeDriver.
	Java struct {
		Version string
	}
	Build struct {
		Version, Revision, Time string
	}
	OS struct {
		Arch, Name, Version string
	}

	// The following fields are specified by the W3C WebDriver specification and
	// are used by GeckoDriver.
	Ready   bool
	Message string
}

Status contains information returned by the Status method.

type WebDriver

type WebDriver interface {
	// Status returns various pieces of information about the server environment.
	Status() (*Status, error)

	// NewSession starts a new session and returns the session ID.
	NewSession() (string, error)

	// SessionId returns the current session ID
	//
	// Deprecated: This identifier is not Go-style correct. Use SessionID
	// instead.
	SessionId() string

	// SessionID returns the current session ID.
	SessionID() string

	// SwitchSession switches to the given session ID.
	SwitchSession(sessionID string) error

	// Capabilities returns the current session's capabilities.
	Capabilities() (Capabilities, error)

	// SetAsyncScriptTimeout sets the amount of time that asynchronous scripts
	// are permitted to run before they are aborted. The timeout will be rounded
	// to nearest millisecond.
	SetAsyncScriptTimeout(timeout time.Duration) error
	// SetImplicitWaitTimeout sets the amount of time the driver should wait when
	// searching for elements. The timeout will be rounded to nearest millisecond.
	SetImplicitWaitTimeout(timeout time.Duration) error
	// SetPageLoadTimeout sets the amount of time the driver should wait when
	// loading a page. The timeout will be rounded to nearest millisecond.
	SetPageLoadTimeout(timeout time.Duration) error

	// Quit ends the current session. The browser instance will be closed.
	Quit() error

	// CurrentWindowHandle returns the ID of current window handle.
	CurrentWindowHandle() (string, error)
	// WindowHandles returns the IDs of current open windows.
	WindowHandles() ([]string, error)
	// CurrentURL returns the browser's current URL.
	CurrentURL() (string, error)
	// Title returns the current page's title.
	Title() (string, error)
	// PageSource returns the current page's source.
	PageSource() (string, error)
	// Close closes the current window.
	Close() error
	// SwitchFrame switches to the given frame. The frame parameter can be the
	// frame's ID as a string, its WebElement instance as returned by
	// GetElement, or nil to switch to the current top-level browsing context.
	SwitchFrame(frame interface{}) error
	// SwitchWindow switches the context to the specified window.
	SwitchWindow(name string) error
	// CloseWindow closes the specified window.
	CloseWindow(name string) error
	// MaximizeWindow maximizes a window. If the name is empty, the current
	// window will be maximized.
	MaximizeWindow(name string) error
	// ResizeWindow changes the dimensions of a window. If the name is empty, the
	// current window will be maximized.
	ResizeWindow(name string, width, height int) error

	// Get navigates the browser to the provided URL.
	Get(url string) error
	// Forward moves forward in history.
	Forward() error
	// Back moves backward in history.
	Back() error
	// Refresh refreshes the page.
	Refresh() error

	// FindElement finds exactly one element in the current page's DOM.
	FindElement(by, value string) (WebElement, error)
	// FindElement finds potentially many elements in the current page's DOM.
	FindElements(by, value string) ([]WebElement, error)
	// ActiveElement returns the currently active element on the page.
	ActiveElement() (WebElement, error)

	// DecodeElement decodes a single element response.
	DecodeElement([]byte) (WebElement, error)
	// DecodeElements decodes a multi-element response.
	DecodeElements([]byte) ([]WebElement, error)

	// GetCookies returns all of the cookies in the browser's jar.
	GetCookies() ([]Cookie, error)
	// GetCookie returns the named cookie in the jar, if present. This method is
	// only implemented for Firefox.
	GetCookie(name string) (Cookie, error)
	// AddCookie adds a cookie to the browser's jar.
	AddCookie(cookie *Cookie) error
	// DeleteAllCookies deletes all of the cookies in the browser's jar.
	DeleteAllCookies() error
	// DeleteCookie deletes a cookie to the browser's jar.
	DeleteCookie(name string) error

	// Click clicks a mouse button. The button should be one of RightButton,
	// MiddleButton or LeftButton.
	Click(button int) error
	// DoubleClick clicks the left mouse button twice.
	DoubleClick() error
	// ButtonDown causes the left mouse button to be held down.
	ButtonDown() error
	// ButtonUp causes the left mouse button to be released.
	ButtonUp() error

	// SendModifier sends the modifier key to the active element. The modifier
	// can be one of ShiftKey, ControlKey, AltKey, MetaKey.
	//
	// Deprecated: Use KeyDown or KeyUp instead.
	SendModifier(modifier string, isDown bool) error
	// KeyDown sends a sequence of keystrokes to the active element. This method
	// is similar to SendKeys but without the implicit termination. Modifiers are
	// not released at the end of each call.
	KeyDown(keys string) error
	// KeyUp indicates that a previous keystroke sent by KeyDown should be
	// released.
	KeyUp(keys string) error
	// Screenshot takes a screenshot of the browser window.
	Screenshot() ([]byte, error)
	// Log fetches the logs. Log types must be previously configured in the
	// capabilities.
	//
	// NOTE: will return an error (not implemented) on IE11 or Edge drivers.
	Log(typ log.Type) ([]log.Message, error)

	// DismissAlert dismisses current alert.
	DismissAlert() error
	// AcceptAlert accepts the current alert.
	AcceptAlert() error
	// AlertText returns the current alert text.
	AlertText() (string, error)
	// SetAlertText sets the current alert text.
	SetAlertText(text string) error

	// ExecuteScript executes a script.
	ExecuteScript(script string, args []interface{}) (interface{}, error)
	// ExecuteScriptAsync asynchronously executes a script.
	ExecuteScriptAsync(script string, args []interface{}) (interface{}, error)

	// ExecuteScriptRaw executes a script but does not perform JSON decoding.
	ExecuteScriptRaw(script string, args []interface{}) ([]byte, error)
	// ExecuteScriptAsyncRaw asynchronously executes a script but does not
	// perform JSON decoding.
	ExecuteScriptAsyncRaw(script string, args []interface{}) ([]byte, error)

	// WaitWithTimeoutAndInterval waits for the condition to evaluate to true.
	WaitWithTimeoutAndInterval(condition Condition, timeout, interval time.Duration) error

	// WaitWithTimeout works like WaitWithTimeoutAndInterval, but with default polling interval.
	WaitWithTimeout(condition Condition, timeout time.Duration) error

	//Wait works like WaitWithTimeoutAndInterval, but using the default timeout and polling interval.
	Wait(condition Condition) error
}

WebDriver defines methods supported by WebDriver drivers.

func NewRemote

func NewRemote(capabilities Capabilities, urlPrefix string) (WebDriver, error)

NewRemote creates new remote client, this will also start a new session. capabilities provides the desired capabilities. urlPrefix is the URL to the Selenium server, must be prefixed with protocol (http, https, ...).

Providing an empty string for urlPrefix causes the DefaultURLPrefix to be used.

type WebElement

type WebElement interface {
	// Click clicks on the element.
	Click() error
	// SendKeys types into the element.
	SendKeys(keys string) error
	// Submit submits the button.
	Submit() error
	// Clear clears the element.
	Clear() error
	// MoveTo moves the mouse to relative coordinates from center of element, If
	// the element is not visible, it will be scrolled into view.
	MoveTo(xOffset, yOffset int) error

	// FindElement finds a child element.
	FindElement(by, value string) (WebElement, error)
	// FindElement finds multiple children elements.
	FindElements(by, value string) ([]WebElement, error)

	// TagName returns the element's name.
	TagName() (string, error)
	// Text returns the text of the element.
	Text() (string, error)
	// IsSelected returns true if element is selected.
	IsSelected() (bool, error)
	// IsEnabled returns true if the element is enabled.
	IsEnabled() (bool, error)
	// IsDisplayed returns true if the element is displayed.
	IsDisplayed() (bool, error)
	// GetAttribute returns the named attribute of the element.
	GetAttribute(name string) (string, error)
	// Location returns the element's location.
	Location() (*Point, error)
	// LocationInView returns the element's location once it has been scrolled
	// into view.
	LocationInView() (*Point, error)
	// Size returns the element's size.
	Size() (*Size, error)
	// CSSProperty returns the value of the specified CSS property of the
	// element.
	CSSProperty(name string) (string, error)
}

WebElement defines method supported by web elements.

type WebForm

type WebForm struct {
	WebElement
}

func (*WebForm) Get

func (f *WebForm) Get(elem string) (WebElement, error)

func (*WebForm) GetAllElements

func (f *WebForm) GetAllElements() ([]WebElement, error)

func (*WebForm) GetValue

func (f *WebForm) GetValue(we WebElement) (string, error)

func (*WebForm) SetValue

func (f *WebForm) SetValue(elem string, value string) error

Directories

Path Synopsis
Package chrome provides Chrome-specific options for WebDriver.
Package chrome provides Chrome-specific options for WebDriver.
Package log provides logging-related configuration types and constants.
Package log provides logging-related configuration types and constants.
internal
zip
Package zip creates Zip files.
Package zip creates Zip files.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL