# Browser testing with Docker

Gondola is designed to easily run inside a Docker container. In this tutorial, we'll learn how to scale up your browser testing environment using Docker & Docker Compose

# Prerequisites

  • You are familiar with Docker & the container concept.
  • You have a Docker-ready environment, let's verify that by:
    • Running docker run --rm hello-world in the terminal. You should see the hello message from Docker.
    • Then run docker-compose --version and you should see which version Docker-Compose is installed. On some systems, you'll have to set it up after installing Docker.
  • You have a runnable test project, in this example, we'll use the WebDriver ABT sample project.

# Docker service design for Gondola runner

Gondola leverages the WebDriver protocol to run its tests. Therefore, to run a test, you need to have some services setup:

Create a file called docker-compose.yml with following contents same folder in your test project as gondola.json

version: '3'

# This docker-compose file needs two environment variables to be able to run
#   - BROWSER     allowed value: firefox, chrome and opera (not tested)
#   - G_LS_TOKEN  the your Gondola License Token
#                 to learn how to generate one, see https://docs.gondolatest.com/subscription/#generating-a-token

  # A selenium standalone service with the specified $BROWSER (firefox, chrome, opera)
  #   and its driver. See more at https://github.com/SeleniumHQ/docker-selenium/#standalone
    image: selenium/standalone-${BROWSER}:3
      - SCREEN_WIDTH=1366
      - SCREEN_HEIGHT=768
      - SCREEN_DEPTH=24
      - SCREEN_DPI=74
    # This port allows us to VNC into the container to see how the test would run on a browser.
    # You should comment this out in your production pipeline to avoid port conflicts.
    #  - "6900:5900"
  # This service will install the required packages
    image: node:lts-slim
      - .:/src
    working_dir: /src
    command: bash -c "rm -rf node_modules && npm ci"

  # This service will compile a Gondola test script when called
    image: node:lts-slim
      - .:/src
    working_dir: /src
    command: bash -c "npm run compile"

  # This service will run a Gondola test script when called
    image: node:lts-slim
      - webdriver
      - G_LS_TOKEN=${G_LS_TOKEN}
      - .:/src
    working_dir: /src
    command: npm run test -- --override "{\"helpers\":{\"WebDriver\":{\"browser\":\"$BROWSER\",\"host\":\"webdriver\"}}}"

# Updating your test project

Since this project's template is setup for running locally on a user's desktop, we need to adjust the project's configuration file (gondola.json) a little bit for the Docker container.

  • Disable the service @wdio\selenium-standlone by setting the field plugins/wdio/enabled to false
"plugins": {
        "wdio": {
            "services": [
            "enabled": false
  • Disable the framework for opening the test results automatically after a test run (since the Docker container has neither a browser nor GUI to show the results) by setting the field mocha/reporterOptions/autoOpen to false
"mocha": {
        "reporterOptions": {
            "autoOpen": false,

# Running your test

First, we need to initialize the test project by running the command:

docker-compose run --rm gondola.builder

Second, let's prepare two environment variables by running commands below in your currently open terminal:

  • BROWSER variable, allowed values are: chrome, firefox and opera (not fully tested yet)

You also need to provide a license token (--licenseToken) by using the terminal:

Then compile your tests by using the command:

docker-compose run --rm gondola.compiler

Finally, we run the tests by running the command:

docker-compose run --rm gondola.tester

You should see the running status in your terminal. When the tests have completed, the report will be located in the results folder.

After you've run your tests, use following command to clean up your environment (this is due to a bug with Docker Compose that retains the linked container after running):

docker-compose down


Linux: docker-compose needs to run as root account. If you don’t want to run docker-compose using sudo, you can refer to manage docker as non-root user

# What's next?

With a little additional configuration, it's easy to integrate Gondola tests into your current development pipeline. An example of CircleCI integration can be found at this public Github repository which is holds the source code of our demo site.

Last Updated: 9/22/2020, 2:10:13 AM