Selenium Remote Control: Developer's Guide

Building Selenium Remote Control from the source repository can be a bit tricky. Selenium Remote Control is written in many languages; that means that in order to do a full build of Selenium Remote Control, you'll need to have interpreters installed for each supported language (Java, C#, Python, Ruby, and Perl).

Fortunately, there are ways around this that can make it easier for you if you only want to work on just one part of SRC.

IEDoc.js, IEDoc.xml and XSLT
Developing the Java Selenium Server
Developing the Java RC Client Driver
- The Easy Way
- The Real Way
Java Selenium RC Maven Projects
- Eclipse Projects
Developing the Other Client Drivers
- Developing the .NET Client Driver
- Developing the Ruby Client Driver
- Developing the Python Client Driver
- Developing the Perl Client Driver
Developing a Totally New Client Driver
- Auto-generating Your Client Driver Using XSLT

IEDoc.js, IEDoc.xml and XSLT

Most of the code for the supported client drivers is generated using XSLT. The XML file is generated based on the current latest Selenium Core JavaScript files, so our client drivers never get out of date. This also allows us to embed API documentation into the generated Client Driver code, so we can use standard documentation generation tools like JavaDoc, NDoc, (E|Hap)Pydoc, RDoc or PerlDoc to present end users with documentation with they which will be familiar.

Specifically, "selenium-api.js" is a file in Selenium Core that contains a complete definition of every Selenium command. We've written a tool called "doc.js" that parses selenium-api.js and generates XML output from it (called iedoc.xml, for historical reasons).

For an example of IEDoc.xml, you can look inside the Selenium Server jar itself. (JAR files are just zip files, and can be extracted with any standard unzip tool.) "iedoc.xml" should be embedded inside selenium-server.jar in the /core directory. i.e. selenium-server.jar!/core/iedoc.xml.

You can always get the latest copy of iedoc.xml from the nightly builds of Selenium Core, available on release.openqa.org.

Developing the Java Selenium Server

(Note that If you're just developing one of the RC Client Drivers, you can safely skip this section; you don't have to build your own Selenium Server at all.)
The Java Selenium Server is officially built using Ant and Maven. (We would just use Maven, but there are bugs in Maven that require us to workaround them in Ant.)

We're currently set up to use JDK 1.5.0_07, Maven 2.0.4 and Ant 1.6.5. To verify that you've set them up and installed them correctly, run the following commands from the command line:

> java -version
java version "1.5.0_07"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_07-b03)
Java HotSpot(TM) Client VM (build 1.5.0_07-b03, mixed mode)
> ant -version
Apache Ant version 1.6.5 compiled on June 2 2005
> mvn -version
Maven version: 2.0.2

To build, start by pulling down the Selenium RC source from our Selenium RC source repository(http://svn.openqa.org/svn/selenium-rc/trunk).

In order to acquire a copy of iedoc.xml, we'll need to have a pre-built version of Selenium Core available. By default, we'll look for a build up on maven.openqa.org, but if you're modifying Selenium Core locally, don't forget to run its build.xml Ant script and run the "install-jar" target to make that JAR available for Selenium Server. (Otherwise, we'll just use the version of Server that's available on maven.openqa.org, and ignore your valuable changes.)

From the selenium-rc-trunk directory, you should be able to kick off a build of all the Java stuff from the command-line by typing ant maven. In the course of running the build, we will also attempt to run the automated tests. Those tests should pass; if they don't, it's a bug, and we need to look into that.

Developing the Java RC Client Driver

There are two ways to do development on the Java RC Client Driver: the Easy way and the Real way. (Official Selenium developers have to use the Real way.)

Developing the Java RC Client Driver: The Easy Way

The source code for the Java RC Client Driver is distributed inside the .zip file with every Selenium RC release since 0.8.0. (You can also find the latest nightly build/source up on release.openqa.org). We include Eclipse project files along with the source, so you can easily load up these projects in Eclipse. The only tool you'll need to work this way is Eclipse itself. (No need for Ant or Maven.)

Download the release, unzip it, and Import the project you want to work on in Eclipse. When you're done crafting your fabulous new feature or crucial bug fix, just submit a patch in our JIRA and we'll integrate it and test it with the real system.

Note that in the Java Client Driver, Selenium.java and DefaultSelenium.java are both autogenerated. These files are not checked in (and must not be checked in, or they'll get out of date). So if you submit a patch to us in either of those files, we may not be able to integrate it as easily. We'll still accept it, though!

Developing the Java RC Client Driver: The Real Way

Building the Java RC Client Driver the "Real" way means running the build in Maven, autogenerating its source code using Ant/Maven. You'll need to start by setting up [Ant and Maven] as described in the section on building the Selenium Server.

If you follow the instructions in the Selenium Server section, you'll build both the Server and the RC Client Driver in one fell swoop. However, you don't have to build them both at once. You can go into the trunk/clients/java directory and run "mvn install" from there. If you don't have a locally built Selenium Server installed in your Maven local repository, we'll just fetch the latest one from maven.openqa.org and use that. (Note that if you are developing the Selenium Server or Selenium Core, you need to make sure you install it in the local repository [with "mvn install"] as you build it, or else the Java Client Driver will attempt to use the public versions of selenium-core.jar and selenium-server.jar from maven.openqa.org, instead of your own changes.)

To change Selenium.java or DefaultSelenium.java, you must make these changes in the XSLT file trunk/clients/java/iedoc2java.xml. These .java files are not checked in (and must not be checked in, or they'll get out of date).

Java Selenium RC Maven Projects

There are four Maven projects in the Java part of Selenium Remote Control:

selenium-server-coreless (trunk/server-coreless): Builds selenium-server-coreless.jar; this includes all the code to launch browsers on various operating systems and the client-configured proxy, but doesn't include Selenium Core. (This can be used to test Selenium Core, and was created to avoid a circular dependency.)
selenium-xlator (trunk/xlator): [EXPERIMENTAL] Builds a command-line tool that automatically translates HTML Selenese into Java using the JavaScript baked into Selenium IDE. As of this writing (November 13, 2006, Selenium RC 0.9.0) we don't actually use this xlator; we use our own pure-Java xlator in selenium-server-coreless.
selenium-server (trunk/server): Builds selenium-server.jar; this includes selenium-server-coreless as well as selenium-core. You can use this to run your automated tests.
selenium-java-client-driver (trunk/clients/java): Runs the XSLT to generate DefaultSelenium.java and Selenium.java. Acts as a simple HTTP request system, no more complicated than any of the other drivers.

selenium-server-coreless doesn't depend on any other Selenium project. selenium-server depends on selenium-server-coreless and selenium-core. We assume you're going to get selenium-core from maven.openqa.org; otherwise you'll need to install your own private selenium-core in your Maven local repository with the "install-jar" target in the selenium-core build scripts. selenium-server also depends on Jetty, and Ant itself (we use Ant as a library as well as a build tool). We also use the Codehaus dependency-maven-plugin to republish selenium-server's dependencies within its jar. (Hence, selenium-server depends on selenium-server-coreless, selenium-core, jetty and ant at the "provided" scope, meaning that projects that depend on selenium-server should not explicitly depend on selenium-server's dependencies.)

selenium-java-client-driver depends on selenium-server at build time and at test time (i.e. at the "test" scope) but not at runtime. Philosophically, of course, it depends on the Selenium Server in order to do its work at runtime, but it doesn't (necessarily) need the selenium-server.jar to be loaded up in the same classpath with it: the Selenium Server could easily be installed on another machine entirely and the Java Client Driver would still work. Note that this is not true of the unit tests for selenium-java-client-driver, which assume that the server is available in the classpath for running tests. (We could have written the unit tests without assuming that, but it makes the tests easier to write/run.)

Eclipse Projects

We have checked in Eclipse projects for both our Maven projects, but they won't (can't) work until you've done a successful Maven build first (to pull down dependencies and autogenerate the code for the Java RC Client Driver). The easiest way to do this is to kick off the "ant maven" build at the top level (see above).

Our Eclipse projects also depend directly on the "selenium-core" Eclipse project which is checked into the Selenium Core /selenium/trunk/javascript directory... you'll need to load that up into Eclipse before any of the Selenium RC Eclipse projects will work.

Once you've built the code in Maven and imported the Selenium Core Eclipse project, you should be able to load up all of the Selenium RC Eclipse projects in Eclipse and build everything that way.

Developing the Other Client Drivers

If you're developing the other Client Drivers, (C#, Python, Ruby, Perl) you don't need to build your own Selenium Server jar; in fact, you don't need to do anything at all at the top level... you can do everything you need to do from the trunk/clients subdirectory.

You do however still need a working copy of [Ant], which also acts as our XSLT runner. We'll also need to have some copy of Selenium Server around so the client driver build scripts can automatically extract iedoc.xml from it, as well as automatically start/stop the server in order to run their automated tests. If you don't provide your own, we'll just use the latest version we can find off of maven.openqa.org automatically. (We'll also automatically use any locally built version, if any.)

Developing the .NET Client Driver

The .NET Client Driver is implemented in C#. A solution file is available with every build of Selenium RC that you can open up in Visual Studio .NET 2003, or you can use the NAnt script "solution.build" to kick off the build. (The Ant script turns around and launches the NAnt script.) At this time, the .NET Client Driver is only designed to work on Windows, but as far as we know it should work on Mono, too. If you're interested, I encourage you to take a look at SRC-41 (We should make a Mono-compatible .NET driver).

To automatically generate the sources you need, you can navigate to trunk/clients/dotnet and run:

ant generate-sources

To change ISelenium.cs or DefaultSelenium.cs, you must make these changes in the XSLT file trunk/clients/dotnet/iedoc2csharp.xml. These .cs files are not checked in (and must not be checked in, or they'll get out of date).

To do a full build-and-test from the command line, you can run ant all to do the build; again, you'll need to specify the location of selenium-server.jar if you haven't built it locally with Maven. This will automatically launch NDoc to generate documentation based on iedoc.xml.

Developing the Ruby Client Driver

To build the Ruby Driver, we expect Ruby to appear on your PATH environment variable. (You can also specify a "ruby.executable" property to the Ant script if you'd like to put your Ruby in a non-standard location.)

To automatically generate the sources you need, you can navigate to trunk/clients/ruby and run:

ant generate-sources

To change selenium.rb, you must make these changes in the XSLT file trunk/clients/ruby/iedoc2ruby.xml. selenium.rb is not checked in (and must not be checked in, or it'll get out of date).

To do a full build-and-test from the command line, you can run ant all to do the build; again, you'll need to specify the location of selenium-server.jar if you haven't built it locally with Maven. This will automatically launch RDoc to generate documentation based on iedoc.xml.

Developing the Python Client Driver

To build the Python Driver, we expect Python to appear on your PATH environment variable. (You can also specify a "python.executable" property to the Ant script if you'd like to put your Python in a non-standard location. Also see below for more information about generating doc.)

To automatically generate the sources you need, you can navigate to trunk/clients/python and run:

ant generate-sources

To change selenium.py, you must make these changes in the XSLT file trunk/clients/python/iedoc2python.xml. selenium.py is not checked in (and must not be checked in, or it'll get out of date).

To do a full build-and-test from the command line, you can run ant all to do the build; again, you'll need to specify the location of selenium-server.jar if you haven't built it locally with Maven.

iedoc2python.xml generates inline documentation as reStructuredText; by default, "ant all" will automatically launch epydoc, which is checked into the trunk/clients/python/lib/epydoc directory, which in turn uses docutils, which we also have checked in. You can also build documentation using PyDoc (which comes with Python) if you like, but it doesn't look as beautiful.

Developing the Perl Client Driver

To build the Perl Driver, we expect Perl to appear on your PATH environment variable. (You can also specify a "perl.executable" property to the Ant script if you'd like to put your Perl in a non-standard location.)

To automatically generate the sources you need, you can navigate to trunk/clients/perl and run:

ant generate-sources

Unlike the other client drivers, the Perl driver is generated from XML using Perl, rather than using XSLT. You can find the driver generator in trunk/clients/perl/util/create_www_selenium.pl.

To run the tests for the Perl Driver, you can either run "ant test" from the command line, or you can directly run "perl Makefile.PL". Running Perl on that Makefile will, in turn, autogenerate a single "Makefile" that you can use to build/run the tests. Note that this Makefile is incompatible with cygwin's GNU make; on Windows you should use nmake instead. (Note that nmake comes along with ActiveState Perl; it should already be available in your Perl\bin directory.) Once you've generated your Makefile, you can use "make test" (or "nmake test") to run the tests.

To change WWW/Selenium.pm, you must make these changes in the generator script trunk/clients/perl/create_www_selenium.pl. Selenium.pm is not checked in (and must not be checked in, or it'll get out of date).

To do a full build-and-test from the command line, you can run ant all to do the build; again, you'll need to specify the location of selenium-server.jar if you haven't built it locally with Maven. This will automatically launch pod2html to generate documentation based on iedoc.xml.

Developing a Totally New Client Driver

Writing your own Client Driver is as easy as pie. All you need to automate tasks in the browser is to send HTTP commands to the Selenium Server, and to parse their responses.

Selenium Commands are sent to the server with HTTP Parameters, like this:

http://localhost:4444/selenium-server/driver/?cmd=getNewBrowserSession&1=*firefox&2=http%3A%2F%2Fgoogle.com

If the command is an "Accessor" (a command designed to return data), then the response will begin with "OK," followed by the data to be sent, or it will contain an error message. A normal response to this command might be:

OK,123125245345

You'll need to keep track of that string to use it again later, just like you did in the interactive tutorial.

Some commands can return more complicated values, like arrays of strings. Arrays of strings are encoded in a comma-delimited format... the values themselves are separated by "," characters. If one of the values itself contains a comma, it will prepend a backslash before the comma ("escaping" the comma), like this: "\,". If the value contains a backslash, the Server will escape the backslash, like this: "
".

Normally your workflow will be:

Get a new browser session with "getNewBrowserSession"
Send some commands using that session
close the browser session with "testComplete"

We also have a detailed write-up of the [Selenium Remote Control Client Driver Protocol (SRC-CDP)] full of details, but that should be enough to get you started.

If you're familiar with at least one of the officially supported Client Drivers, you may benefit from viewing their source code as an example.

Auto-generating Your Client Driver Using XSLT

If you want to get fancy, you can automatically generate your Client Driver based on an XML representation of the Selenium API. All of our officially supported Client Drivers automatically generate themselves.

If you want to see examples of XSLT to generate our officially supported drivers, look here: