Setting up the environment

Download the Selenium Server JAR from and run:

$ java -jar /path/to/selenium-server-standalone-2.xx.xx.jar

This starts the server process that your tests will connect to to spawn and control the browser.

Choose the appropriate test layer (see Integration) and create a test case:

import gocept.selenium.wsgi
from mypackage import App

test_layer = gocept.selenium.wsgi.Layer(App())

class TestWSGITestCase(gocept.selenium.wsgi.TestCase):

    layer = test_layer

    def test_something(self):'http://%s/foo.html' % self.selenium.server)

Environment variables

You can set some variables in the environment of your test runner to configure which selenium server gocept.selenium connects to. Selenium Server defaults to localhost:4444, but you can also connect to a selenium grid in your organization by using the following environment variables:

If multiple browsers are connected to your selenium grid, you can choose the browser to run the tests with like this:


For use with Selenium Server’s webdriver interface, the browser needs to be specified differently:


Webdriver supports instantiating the browser directly (instead of going through the Java-based server component). If you want to do this, set:


and specify one of the browser classes defined by the Python bindings, for example:


If you want to use a Firefox binary at a custom path, specify it like this:


By default, the selenium layer will make the HTTP server under test bind to localhost and listen to a random port chosen by the kernel (i.e. instruct it to bind to port 0). This randomly chosen port is then used to point the browser at the application. You may want to influence this behaviour, e.g. when running your selenium tests on a selenium grid:


When you are testing an application on one machine, you can access the running application from another machine if you set GOCEPT_SELENIUM_APP_HOST = instead of the default localhost.

You can control the timeout of waitFor assertions and other selenium actions by setting a timeout in seconds:

GOCEPT_SELENIUM_TIMEOUT=10  (default: 30 seconds)

You can also set the speed with which the tests are run through an environment variable:


This example will introduce a 500 millisecond pause between tests.

Jenkins integration

If you use Jenkins, you might be interested in the JUnit Attachment Plugin, and setting:


This will print information about the screenshot of a failure that the plugin can read and attach the screenshot to the test run.

In the configuration of the jenkins job you need a Post-build Action called Publish JUnit test result report. This action needs an Additional test report feature called Publish test attachments to ask Jenkins to keep the screenshots for you.

Caution: zope.testrunner is not usable for this behavior, you have to use a test runner like py.test.

Tips & Tricks

Using a custom Firefox profile

For debugging purposes it’s helpful to have the Firebug debugger available in the Selenium-controlled browser. To do that, create a new Firefox profile and install Firebug into it. Then you can tell Selenium to use this profile as a profile template when running Firefox:

$ java -jar /path/to/selenium-server-standalone-2.xx.xx.jar -firefoxProfileTemplate ~/.mozilla/firefox/<PROFILE_FOLDER>

When using webdriver, instead set this environment variable for running the tests (not Selenium Server):


Using a nested X Server

On Linux systems, the Selenium-controlled browser tends to steal the window focus, which makes it impossible to do anything else while a Selenium test is running. To prevent this, use Xephyr (successor of Xnest) to start an X server contained in a window, for example:

Xephyr -host-cursor -dpi 100 -wr -screen 1400x900 $display &
export DISPLAY=$display
sleep 2
metacity &  # or any other window manager
x-terminal-emulator -e java -jar /path/to/selenium-server-standalone-2.xx.xx.jar