tebeka/selenium

The full API documentation for the selenium package is available via GoDoc at: https://godoc.org/github.com/tebeka/selenium.

For practical usage examples, refer to the example_test.go file in the repository or examine the unit tests for sauce, selenium, and service.

To run tests in a hermetic environment using Docker, ensure Docker is installed and running, then execute:

go test --docker

For manual debugging within a container, you can build and run the testing image manually:

docker build -t go-selenium testing/
docker run --volume=$(pwd):/code --workdir=/code -it go-selenium bash
# Inside the container:
root@6c7951e41db6:/code# testing/docker-test.sh

You can execute tests against browsers hosted in the Sauce Labs cloud. You will need your Sauce Labs username and access_key.

Run the following command, replacing the placeholders with your credentials:

go test --test.run=TestSauce --test.timeout=20m \
  --experimental_enable_sauce \
  --sauce_user_name=[username goes here] \
  --sauce_access_key=[access key goes here]

Test results can be viewed in the Sauce Labs Dashboard.

The repository provides a utility to download ChromeDriver, Firefox, Selenium WebDriver JARs, and the Sauce Connect proxy binary. This is primarily intended for testing purposes. Run the following commands from the root of the repository:

cd vendor
go run init.go --alsologtostderr --download_browsers --download_latest
cd ..

It is recommended to re-run this periodically to ensure you have up-to-date versions of these binaries.

To run the project's tests on your local machine, ensure you have xvfb and Java installed (e.g., sudo apt-get install xvfb openjdk-11-jre on Debian-based systems).

Run all tests using:

go test

Running specific browser tests

You can target specific browser/driver combinations using the -test.run flag with regular expressions:

• Chrome/ChromeDriver: -test.run=TestChrome
• Firefox/Selenium 3: -test.run=TestFirefoxSelenium3
• Firefox/Geckodriver: -test.run=TestFirefoxGeckoDriver
• HTMLUnit: -test.run=TestHTMLUnit

To see detailed output from the test automation framework, add the -test.v flag.

To fetch the selenium WebDriver client for Go, use the following command:

go get -t -d github.com/tebeka/selenium

Note that this package requires a working WebDriver installation (e.g., Selenium WebDriver, Geckodriver, or ChromeDriver) and a compatible web browser to function.

Use the Proxy struct to configure browser proxy settings. Set the Type field to one of the ProxyType constants:

• Direct: No proxy used.
• Manual: Use specific proxy addresses (e.g., HTTP, SSL, SOCKS). Note that for Geckodriver, ports must be specified in the dedicated port fields (e.g., HTTPPort, SSLPort, SocksPort).
• Autodetect: Autodetect proxy (e.g., via WPAD).
• System: Use system settings.
• PAC: Proxy autoconfiguration from a URL (requires AutoconfigURL).

Fields for Manual type include HTTP, HTTPS, FTP, SOCKS, SOCKSVersion, SOCKSUsername, SOCKSPassword, and NoProxy (a list of strings).

You can manage an X virtual frame buffer independently of a Service using the FrameBuffer type.

• NewFrameBuffer(): Starts an X virtual frame buffer with default options.
• NewFrameBufferWithOptions(options FrameBufferOptions): Starts an X virtual frame buffer with custom ScreenSize (format: "{width}x{height}[x{depth}]", e.g., "1024x768x24").
• FrameBuffer.Stop(): Kills the background process and removes the temporary X authorization file.
• FrameBuffer.Display: The X11 display number (without the preceding colon).
• FrameBuffer.AuthPath: The path to the X11 authorization file.

You can run JavaScript within the browser context using several methods:

• ExecuteScript(script string, args []interface{}) (interface{}, error): Executes a script and returns the decoded result.
• ExecuteScriptAsync(script string, args []interface{}) (interface{}, error): Asynchronously executes a script.
• ExecuteScriptRaw(script string, args []interface{}) ([]byte, error): Executes a script without performing JSON decoding.
• ExecuteScriptAsyncRaw(script string, args []interface{}) ([]byte, error): Asynchronously executes a script without JSON decoding.

When calling NewSeleniumService, NewChromeDriverService, or NewGeckoDriverService, you can pass several ServiceOption functions to configure the background process:

• GeckoDriver(path string): Sets the path to the geckodriver binary (required for NewSeleniumService).
• ChromeDriver(path string): Sets the path to the chromedriver binary (required for NewSeleniumService).
• JavaPath(path string): Specifies the path to the JRE.
• HTMLUnit(path string): Specifies the path to the HTMLUnit driver JAR.
• Output(w io.Writer): Redirects the service's stdout/stderr to the provided writer.
• Display(d, xauthPath string): Sets the DISPLAY environment variable and the XAUTHORITY path (format for d is 'x' or 'x.y').