Run the Demo

Requirements

To run the demo you will need to complete the steps described in Getting Started.

If Firefox is not available on your machine you will also need to install it.

Note: I recommend quitting all running instances of the Firefox browser before running the demo. Sometimes Selenium has trouble launching Firefox when an instance is already running.

All commands in this document must to be launched from the root of Selenium Grid binary distribution directory (probably named selenium-grid-0.9.x).

Running the Tests in Sequence on Firefox on a Single Machine

Go to the selenium distribution directory and launch in a new terminal:

ant launch-hub

Check out that the Hub is running by looking at its console in a browser:

http://localhost:4444/console

In a new terminal on the same machine, launch:

ant launch-remote-control

In a browser, go back to the Hub’s console at http://localhost:4444/console. Now you should have one remote control listed as available. You should see something like:

Then run in a new terminal:

ant run-demo-in-sequence

Four Selenium tests will then run in sequence against your remote control. Take note of how long it took to run the whole test suite – this will give you a baseline. To be honest, there is nothing really exciting about this part of the demo. You can achieve exactly the same thing with a traditional remote control. This is just to get you started, since the whole point of the Selenium grid is to run tests in parallel. That’s exactly what we are going to do next.

Note: if you want to understand what the selenium test is about, or what is going on under the cover, have a look at the demo sub-project in the source code.

Running the Tests in Parallel on Firefox on a Single Machine

First make sure that you already have the Hub and a remote control running. If not, follow the instructions described in the Running the Tests in Sequence section.

Now let’s start three more remote control instances. Launch them in separate terminals:

    ant -Dport=5556 launch-remote-control
    ant -Dport=5557 launch-remote-control
    ant -Dport=5558 launch-remote-control

You should now see a total of four remote controls available in the Hub console http://localhost:4444/console:

Launch the tests in parallel in a new terminal:

ant run-demo-in-parallel

The total run time should be significantly lower than when running the test in sequence.

You can then experiment with bringing down one or two remote controls and check that the total run time is directly proportional to the number of available remote controls.

Running the Tests in Parallel on Multiple Machines

Until now we have been running the hub and the remote controls on the same machine. This was quick and easy to set up, but ultimately we want to run the remote controls on multiple machines. Now let’s try to distribute the whole grid on 3 different machines.

Let’s consider the following setup:

In this setup one machine (hub.openqa.org) will run the Hub and drive the selenium tests. The two other machines will run the remote controls (2 remote controls per machine).

If you cannot assign neat host names like rc1.openqa.org for your tests, specity the appropriate TCP/IP number instead.

On each machine, run commands similar to the ones described in the diagram above. Of course you will need to change the host names (or TCP/IP number) to match the one for your own machine.

This setup illustrates that you can run the hub and the remote controls on arbitrary machines. When you do so though, you need to provide a lot more information when launching a remote control. You need to launch it with:

ant -Dport=<port> -Dhost=<hostname> -DhubURL=<hub url> launch-remote-control

Where:

port Port that the remote control will be listening at. Must be unique on the machine the remote control runs on. hostname Hostname or IP address of the machine the remote control runs on. Must be visible from the Hub machine. Note: this information could be inferred as it is always referring to the machine the remote control runs on. It might not be required in future versions of the Selenium Grid. hub url Which hub the remote control should register/unregister to. If the hub is running on hostname my.hub.com, this URL will be http://my.hub.com:4444

Once you are successful in replicating a setup similar to the one described above, point your browser to the Hub console (http://hub.openqa.org:4444/console). Check that all the remote controls did register properly. Available remote controls list should be similar to:

You can then launch the tests and enjoy the dance of browsers popping up on the two machines:

ant run-demo-in-parallel

The total run time is likely to be slighly higher than when running the tests in parallel on the same machine but still significantly faster than when running the tests in sequence. As you scale the number of remote controls upward to the point of stressing a single RC machine, as you would expect, the performance advantage moves towards a distributed environment.

Running the Tests with Remote Controls Providing Different Environments

Until now we have distributed the remote controls, but all of them were equivalent. For instance, when the Selenium test was openning a new session for the Firefox browser, it had no idea whether it ended up running on Windows, Linux or Mac OS.

Maybe this is exactly what you want to achieve. However it might end up being hard to figure out that a specific Selenium test is failing one time out of ten just because it exercises a bug only happening on Mac OS. In any case, if you want better control over the environment your tests run on, you can use the Selenium Hub Environments.

The idea is simple:

1. When you start a Remote Control you define which environment it provides to the Hub. Let’s say Firefox on Windows:

   ant -Denvironment=”Firefox on Windows” launch-remote-control

2. In your Selenium test, when instantiating the Selenium driver, pass the Hub environment in lieu of the browser string:

For instance, if you are writing your tests in Java change the following:

new DefaultSelenium("localhost", 4444, **'*firefox'**, 'http://amazon.com');

to:

new DefaultSelenium("localhost", 4444, **'Firefox on Windows'**, 'http://amazon.com');

The Selenium Hub will then make sure to provide the test with a remote control that registered with this specific Hub environment. It will also substitute the browser string on the fly before invoking the actual remote control. In this way you can use any official distribution of the Selenium control in your Grid – no modifications are required.

Let’s be a little bit more concrete and consider the following setup:

In this setup rc1.openqa.org starts 2 remote controls providing the Firefox on Windows Hub Environment. In contrast, rc2.openqa.org registers 2 remote controls providing the Firefox on Mac Hub Environment.

Now try to replicate the setup described above. Keep in mind that the remote controls can register with whatever environment they fancy. It is their reponsibility to play nice with the Hub. This means that even if you are running the demo on Linux, you can totally start remote controls pretending to provide the Firefox on Windows or Firefox on Mac environment.

Once all this is started, take a look at the Selenium Hub console. You should see something like:

We are now going to run in parallel a Selenium test suite that runs the same test but requiring different browsers. The test suite consists of 2 tests requesting explicitly the Firefox on Windows environment and one test requesting the Firefox on Mac environment.

So the first 2 tests will run only on the machine registering its remote controls as providing Firefox on Windows. The last one will run only on the machine registering its remote controls as providing Firefox on Mac. You can make sure that this is what is hapenning by running:

ant run-demo-for-multiple-environments

What's Next?

You are now familiar with Selenium Grid usage and concepts. In case you have not done it yet, take a look at the demo code (you will find it in the demo sub-folder of the source distribution). Then deploy your own Selenium Grid at work and get it to run your functional suite in a fraction of the original time. You do not need a million machines to get started. Five powerful machines running 10+ remote controls each should suffice to divide your build time by 50!