Selenium Grid: Configuring Machines

I posted a couple of days ago about trying to get Selenium Grid to work. I've made some progress and wanted to get it down in case there's someone else out there trying to do what I'm trying to do. Most of this is sourced from elsewhere on the web - thanks to everyone who wrote a blog post, instruction set, document!

Goal

I have several Selenium tests that currently run in a single environment on a single browser. My application is Ruby on Rails. I'd like to make them run on all the browsers the product claims to support: Windows (IE, Firefox) and OS X (Safari, Firefox). Once this is basically functional we'll add the nice to haves: running in parallel, running multiple projects (each of which has its own tests), and some form of unified reporting.

Setup

I'm developing on OS X (Leopard). The build system is Linux. I'm using VMWare to run Windows clients. If you're on other platforms, well, I hope this at least points you in the right direction!

I'm assuming you've got Selenium tests running locally already.

Grid Pieces

Selenium Grid consists of several pieces:

• Remote Controls: These are the things that actually run the tests. If you're currently using Selenium RC, you're using this.
• Hub: This is the thing that is aware of the available remote controls and picks one to run a given test. The Hub knows a few things about the remote controls: the type (*chrome, *iehta, "Firefox on Windows"), the port, and the URL. It picks which one to use based on type.
• Selenium tests: These are the tests themselves. They're not actually part of the Grid, but it's useful to consider.

Configuring The Hub

First thing's first. You have to configure your Hub. To do this:

1. Go get Selenium Grid.
2. Install Selenium Grid. I put it in /Applications/selenium-grid.
3. Configure the grid and make sure it builds. I used these instructions. Note that you need to have Java and Ant.
4. Launch the hub by CDing into /Applications/selenium-grid and writing "ant launch-hub".

At this point, you should be able to point your browser to http://localhost:4444/console and see the Hub running. You'll see a list of available environments. That's controlled from a configuration file: /Applications/selenium-grid/grid_configuration.yml. Feel free to modify the file to add new environments or delete environments you don't need. Just restart the Hub when you're done.

Be careful here. At the time I wrote this, Firefox 3 on Windows just didn't work, and Safari 3 didn't work reliably.

Configuring Each Remote Control

Each remote control is essentially standalone. I think of these as basically standing around and waiting for the Hub to give them something to do. Repeat this for each remote control you want to configure:

1. Download Selenium RC
2. Download Selenium Grid. I'm not completely convinced this is necessary, but I didn't get it working without it, and if it just sits there, well, no harm.
3. Install Selenium RC. I used the instructions here.
4. Configure Selenium RC to use the default port (3000). Be sure it's actually running.

Pointing the Hub At a Remote Control

Once you have a remote control ready and running you can point your Hub at it.

1. On the machine running the Hub, leave the Hub running.
2. Open a terminal, cd into /Applications/selenium-grid
3. Start the remote control from the hub with: ant -Dport=5556 -Denvironment="*chrome" -Dhost=10.0.1.197 -DhubURL=http://10.0.1.206:4444 launch-remote-control.

For each remote control, set the port to something different; you can't have two remote controls using the same port.

• -Dport is the port that the Hub will use to talk to the remote control. This must be unique.
  
• -Denvironment is the environment you'll be using. Set it to something in the available environments list (check the Hub console in the browser).
• -Dhost is the IP address (or name) of the machine that is running the remote control.
• -DhubURL is the full URL (including http:// and the port) of the machine that's running the Hub

Run the Test

Now we get to the part where we actually use this thing we've created. We're in Rails, so we're going to do this as a rake task. Here's the actual rake task file that we'll put in lib/tasks:

================================

require(File.join(File.dirname(__FILE__), '../..', 'config', 'boot'))
require 'rake'
require 'rake/testtask'
require 'rake/rdoctask'
require 'tasks/rails'

@osx_browsers = ["*firefox", "*chrome"] #should be safari instead of firefox, but safari doesn't work in the grid yet
@win_browsers = []
@platforms = {"win"=>"Windows", "osx"=>"OS X", "linux"=>"Linux"}

namespace :test do

task :run_browsers do
unless ENV.include?("platform") && @platforms.has_key?(ENV['platform'])
  raise "A platform is required!  usage: rake test:run_all_environments platform=[win|osx]"
else
 platform = ENV['platform']
 case platform
 when 'win' then
   browsers = @win_browsers
 when 'osx' then
   browsers = @osx_browsers
 end

 puts "Running tests for the #{@platforms[platform]} platform"
 browsers.each do |browser|
   puts "Running tests in the #{browser} browser"
   ENV["Browser"] = browser
   ENV["TEST_DIR"] = 'test/selenium'
   Rake::Task["test:selenium"].invoke #run all the selenium tests within the grid context
 end
end
end

task :sanity_check do
verify "You must install RubyGems to run this example : http://rubygems.org" do
 require "rubygems"
end
end

end

def verify(error_message)
begin
 yield
rescue Exception
 STDERR.puts <<-EOS   ******************************************************************* #{error_message}  ******************************************************************* EOS         raise    end end

==============================

To call the rake task, just:

1. start your Rails server (script/server) 
2. Run rake test:run_browsers platform=osx

If you've done everything right, then you'll see your tests start to run on each of the browsers you've defined.

Let's look at what this rakefile does:

• Defines each of the browsers on each platform (OS type). This is the same as the name you put in -Denvironment. Make sure you have a remote control set up for each environment.
• The sanity check probably isn't strictly necessary, but why take chances?
• You'll notice that I'm calling another rake task. This is whatever task you've defined to run your Selenium tests. I find this easier than calling them separately; you can keep up with any special config you're doing that way.

Conclusion

And that's basically it. I hope this helps!