Run Selenium Grid and Connect to Botium Box

This article is an introductory guide to running your own Selenium Grid and connect it to the Botium Box.

The Selenium Grid

A Selenium Grid is a set of connected Selenium nodes each running your Selenium tests on a different kind of operating system on a different kind of web browser in a different version.

We are using docker-selenium to boot our own Selenium Grid on our own server.

You need docker and docker-compose - both are required for Selenium Grid and for Botium Box.

Create the Docker Compose Configuration

Create a text file docker-compose-selenium.yml with this content:


1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 version: "3" services: selenium-hub: image: selenium/hub:latest container_name: selenium-hub ports: - "4444:4444" chrome: image: selenium/node-chrome:latest depends_on: - selenium-hub environment: - HUB_HOST=selenium-hub - HUB_PORT=4444 firefox: image: selenium/node-firefox:latest depends_on: - selenium-hub environment: - HUB_HOST=selenium-hub - HUB_PORT=4444

This is a rather simple Selenium Grid with:

  • a Selenium Hub, the entry point to the grid

  • a node running the latest Chrome

  • a node running the latest Firefox

You can extend it however you want.

If you have troubles with this simple Selenium Grid, we suggest to consult the support forums at the project page. We at Botium are no Selenium experts.

Start the Selenium Grid

This command pulls the required docker images and starts the Selenium Grid in the background:

1 docker-compose -f docker-compose-selenium.yml up -d

You can view the log output:

1 docker-compose -f docker-compose-selenium.yml logs -f

Verify Selenium Grid Status

With your web browser, point to to bring up the Grid console. You will see something like this:

If you are working in Docker Toolbox, you have to replace the IP-Address with your Docker Toolbox IP address (run docker-machine ip in a command line window to get the IP)

Add Device Emulator for Appium Tests

You can add another docker container the docker-compose-selenium.yml for running tests on a device emulators:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 samsung_galaxy_S8: image: budtmo/docker-android-x86-11.0 depends_on: - selenium-hub ports: - "6080:6080" environment: - DEVICE=Samsung Galaxy S8 - CONNECT_TO_GRID=true - APPIUM=true - SELENIUM_HOST=selenium-hub - SELENIUM_PORT=4444 - MOBILE_WEB_TEST=false - AUTO_RECORD=false

For details on configuration and supported device emulators, have a look at the project repository.

You can view the emulator in action by accessing it via http://localhost:6080

Botium Box Configuration

Now that your own private Selenium Grid is running, you have to tell Botium Box about the installed browsers and connect to the Selenium Grid.

Device Sets - Browsers and Smartphones

The resources folder of the Botium Box distribution has some files named after the supported Selenium endpoint providers. Those files list the available browser configurations (capabilities) for each endpoint provider:

  • INTEGRATED.json for the bundled headless chrome browser

  • LOCALSELENIUM.json for the Selenium Grid connector

Device cloud providers usually provide an online list with available browser configurations and queried by Botium Box automatically. For example, for Saucelabs, you don’t have to configure the list manually. If you want to add your own device configuration to this list, you can list your custom device selectors in a file named after the device provider and place it in the resources folder:







This approach makes sense if you don’t want to select a specific device but rather one device of a device family - for example, if you want to test against any Android 8.0 device emulator on Saucelabs, you can add a file named SAUCELABS.json to the resources folder, and use this device selector in your Device Set configuration (see below):

1 2 3 4 5 6 7 8 9 10 11 12 [ { "name": "Any Android 8.0 Smartphone Emulator", "value": { "type": "MOBILEAPP", "capabilities": { "appium:platformName": "Android", "appium:platformVersion": "8.0" } } } ]

Open the LOCALSELENIUM.json and add the browser capabilities we are running in our Selenium Grid:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 [ { "name": "Google Chrome", "value": { "type": "DESKTOP", "capabilities": { "browserName": "chrome" } } }, { "name": "Mozilla Firefox", "value": { "type": "DESKTOP", "capabilities": { "browserName": "firefox" } } }, { "name": "Android Smartphone Emulator", "value": { "type": "MOBILEAPP", "capabilities": { "appium:platformName": "Android" } } } ]

Botium Box is caching the device lists for some time, so if your changes are not reflected in the UI you either wait for an hour, or you restart Botium Box server.

The structure is self-explaining:

  • It is a JSON array

  • Each entry is for one named browser/device configuration

  • The capabilities entry contains the Selenium/Appium capabilities

In the example above, there are three configurations matching the Selenium Grid setup

  • one for Google Chrome

  • one for Mozilla Firefox

  • and a third one for the Android emulator

Connect Botium Box - Register as Device Provider

In Botium Box, a Device Provider is basically a Selenium endpoint:

  • a standalone, in-process Selenium driver

  • a Selenium server started as separate process and/or on a separate server (as in this article)

  • a Selenium endpoint of a device cloud provider as Saucelabs, Browserstack or Experitest

In Settings / Device Providers register your Selenium Grid, use the IP address you used above for showing the Selenium Grid Console in the browser. Make sure to add the /wd/hub path to the URL.

Register Device Set

A Device Set in Botium Box is a collection of Web Browser configurations you want the test cases to run on. What kind of browsers are supported depends on the selected device provider:

  • Operating systems (Windows, Linux flavours, MacOS, …)

  • Browser vendors (Internet Explorer, Edge, Google Chrome, Safari, Firefox, …)

  • Device types (Desktop, Tablets, Smartphones)

  • Browser versions

For a local Selenium server as in this article, the list of possible browser definitions is defined in LOCALSELENIUM.json - device cloud providers as Saucelabs, Browserstack and Experitest typically have several thousands of possible browser versions from all vendors on all operating systems and device types available.

Under Device Labs menu you can organize your Selenium Grid browsers in Device Sets.

Use Device Set

Now you can use the Botium Webdriver connector and the Device Set to test your website chatbot widget in your Selenium Grid browsers.

You can find a sample chatbot configuration for a simple Web widget interface in the Botium Box Samples repository on Github - see here how to install.

You can start an instant test session in the Test Results menu - whenever selecting a chatbot using the Botium Webdriver connector, selecting a device set to run the test session on is mandatory.

For re-using this selection use the Quickstart menu to create a test project definition. On the last page of the wizard select the device sets.

Each test case of the selected test sets will now run on all browser definitions in the selected device sets.


The device cloud providers supported by Botium Box have their own APIs to list the available browser configurations, for your local Selenium Grid or device cloud providers not yet integrated deeply with Botium Box you have to define it on your own.