sbo-selenium 0.7.2

Browser engines

If you are running tests using docker, you don’t need to worry about this part.

If you are not using docker, to run tests using a particular browser, the browser driver needs to be present. To drive Chrome via Selenium, you’ll need to install both Chrome itself and then chromedriver:

1. Download the correct ChromeDriver from http://chromedriver.storage.googleapis.com/index.html 2. Put the binary, chromedriver, somewhere on your path (ex: /usr/local/bin/chromedriver)

On Mac OS X, if you have Homebrew installed you can instead run brew install chromedriver.

To test Mobile Safari in the iPhone simulator, you’ll first need to do the following:

• Install Xcode

• From the Downloads tab of the Xcode Preferences dialog, install “Command Line Tools” and one of the iOS Simulator components (probably the latest one)

• Download and run Appium

• Check the “Use Mobile Safari” checkbox

• If you want to test in the iPad form factor, check the “Force Device” checkbox and make sure “iPad” is selected next to it

• Click the “Launch” button

To test Opera or Safari, you’ll need to download the Selenium standalone server jar file and configure the path to it in the SELENIUM_JAR_PATH setting described below.

Note that all of these browsers and more can be tested using Sauce OnDemand; see below for details.

Running Tests Locally

Tests can be run via the “selenium” management command:

./manage.py selenium --settings=myapp.selenium_settings

To run the default set of sbo-selenium tests:

./manage.py selenium

Or to specify which test(s) to run rather than using the defaults specified in the settings file:

./manage.py selenium myapp.tests.selenium.test_module:TestClass.test_method myotherapp/tests/selenium --settings=myapp.selenium_settings

Having a separate settings file for the Selenium tests isn’t a requirement, but in practice you’ll probably want to use different settings for the tests than you do for development (for example, to make sure that DEBUG=False). If you don’t want to type out the settings parameter each time, a simple shell script should do the trick:

#!/bin/sh
./manage.py selenium $@ --settings=myapp.selenium_settings

All the usual methods that the test runner uses to identify tests should work:

directory/of/tests
python.module
python.module:TestClass
python.module:TestClass.test_method

(Note that a specifying a package, like myapp.tests.selenium when the actual tests are defined in modules within that package, does NOT work.)

By default, tests are run in the browser specified by SELENIUM_DEFAULT_BROWSER. You can use the -b or --browser parameter to change this:

./manage.py selenium -b firefox
./manage.py selenium --browser=safari

Valid browser names are “chrome”, “firefox”, “htmlunit”, “ios”, “opera”, “phantomjs”, and “safari” (“ipad”, “iphone”, and “ipod” are treated as synonyms for “ios”, the form factor is chosen in Appium).

If you want to specify a specific Selenium server to use as a command executor (whether running on localhost, a specific remote server, a Docker container, etc.), you can use the --command-executor parameter:

./manage.py selenium -b firefox --command-executor=http://127.0.0.1:4444/wd/hub

Note that if you are using a command executor in a Docker container, a remote host, etc., you should not rely on localhost or 127.0.0.1 in DJANGO_LIVE_TEST_SERVER_ADDRESS and must add the IP address which will be used to access the server to ALLOWED_HOSTS. You can either specify the real IP address (rarely ideal) or try to deduce it via code like the following:

import socket
IP_ADDRESS = socket.gethostbyname(socket.gethostname())
ALLOWED_HOSTS = ['localhost', IP_ADDRESS]
DJANGO_LIVE_TEST_SERVER_ADDRESS = '{}:9090'.format(IP_ADDRESS)

You can also specify the number of times to run the tests (for example, if you have a test that is failing intermittently for some reason and want to run it a few times to increase the odds of encountering the error):

./manage.py selenium -n 5

Running Tests in a Docker Container

As a convenience, you can use the --docker parameter to automatically start a standalone Selenium server in a Docker container for chrome or firefox tests. For this to work, the terminal must already be configured for docker commands to work. The container will be stopped automatically at the end of the test run. By default it uses the 2.53.0 image from https://hub.docker.com/r/selenium/ and is exposed on port 4444, but this can be customized via the Django settings described above.:

./manage.py selenium --settings=myapp.selenium_settings --docker
./manage.py selenium --docker

Note that if you’re running Docker containers in a virtual machine via docker-machine or such and using tox, you’ll need to allow some environment variables to be passed through to the tox environment by adding the following to the appropriate environment in tox.ini:

passenv =
    DOCKER_*
    HOME

Running Tests at Sauce Labs

Instead of running tests in a local browser, they can be run on one in a virtual machine hosted at Sauce Labs. Support for this in sbo-selenium is designed to play nicely with the Jenkins Sauce OnDemand plugin. For running tests in Jenkins, just install that plugin and configure it for the job you want to run. On a local machine, you’ll need to set the SELENIUM_SAUCE_* Django settings described above and use a couple of command-line parameters in addition to the -b browser name setting mentioned previously:

• --platform - The name and version of the operating system to use.

• --browser-version - The version number of the browser to use.

The valid values for these can be found on the Sauce Labs website.

There’s also a --tunnel-identifier parameter which can be used to utilize a named Sauce Connect tunnel; this is particularly useful if you intend to run multiple Connect instances against the same account simultaneously (like on multiple Jenkins slave nodes). For more about what these tunnels are and when to use them, see the Sauce Labs documentation on the topic.