Browser Testing

Test > Browser Testing

This document describes common methods for running and debugging browser testing in your CircleCI config in the following sections:


Refer to the Pre-Built CircleCI Docker Images and add -browsers: to the image name for a variant that includes Java 8, PhantomJS, Firefox, and Chrome.


Every time you commit and push code, CircleCI automatically runs all of your tests against the browsers you choose. You can configure your browser-based tests to run whenever a change is made, before every deployment, or on a certain branch.


Many automation tools used for browser tests use Selenium WebDriver, a widely-adopted browser driving standard.

Selenium WebDriver provides a common API for programatically driving browsers implemented in several popular languages, including Java, Python, and Ruby. Because Selenium WebDriver provides a unified interface for these browsers, you only need to write your browser tests once. These tests will work across all browsers and platforms. See the Selenium documentation for details on set up. Refer to the Xvfb man page for virtual framebuffer X server documentation.

WebDriver can operate in two modes: local or remote. When run locally, your tests use the Selenium WebDriver library to communicate directly with a browser on the same machine. When run remotely, your tests interact with a Selenium Server, and it is up to the server to drive the browsers.

If Selenium is not included in your primary docker image, install and run Selenium as shown below::

version: 2
      - image: circleci/node-browsers
      - checkout
      - run: mkdir test-reports
      - run:
          name: Download Selenium
          command: curl -O
      - run:
          name: Start Selenium
          command: java -jar selenium-server-standalone-3.5.3.jar -log test-reports/selenium.log
          background: true

Refer to the Install and Run Selenium to Automate Browser Testing section of the 2.0 Project Tutorial for a sample application. Refer to the Knapsack Pro documentation for an example of Capybara/Selenium/Chrome headless CircleCI 2.0 configuration for Ruby on Rails.

As an alternative to configuring your environment for Selenium, Sauce Labs provides a Selenium Server as a service, with a large number of browsers and system combinations available to test. Sauce Labs also has some extra goodies like videos of all test runs.

Sauce Labs

Sauce Labs operates browsers on a network that is separate from CircleCI build containers. To enable the browsers with a way to access the web application you want to test, you can run Selenium WebDriver tests with Sauce Labs on CircleCI using Sauce Labs’ secure tunnel, Sauce Connect.

Sauce Connect allows you to run a test server within the CircleCI build container and expose it (using a URL like localhost:8080) to Sauce Labs’ browsers. If you run your browser tests after deploying to a publicly accessible staging environment, then you can use Sauce Labs in the usual way without worrying about Sauce Connect.

This example config.yml file demonstrates how to run browser tests through Sauce Labs against a test server running within a CircleCI build container.

version: 2
      - image: circleci/python:jessie-node-browsers
      - checkout
      - run: 
          name: Install Sauce
          command: npm install saucelabs
      - run: 
          name: sauce testing
          command: npm run-script sauce
            SAUCE_USERNAME: # Refer to documentation for info
            SAUCE_ACCESS_KEY: # about setting up environment variables for auth secrets
      - run: # Wait for app to be ready
          command: wget --retry-connrefused --no-check-certificate -T 30 http://localhost:5000
      - run: # Run selenium tests
          command: nosetests
      - run: # wait for Sauce Connect to close the tunnel
          command: killall --wait sc  

BrowserStack and Appium

As in the Sauce Labs example above, you could replace the installation of Sauce Labs with an installation of another cross-browser testing platform such as BrowserStack. Then, set the USERNAME and ACCESS_KEY environment variables to those associated with your BrowserStack account.

For mobile applications, it is possible to use Appium or an equivalent platform that also uses the WebDriver protocol by installing Appium in your job and using CircleCI environment variables for the USERNAME and ACCESS_KEY.

Debugging Browser Tests

Integration tests can be hard to debug, especially when they’re running on a remote machine. This section provides some examples of how to debug browser tests on CircleCI.

Using Screenshots and Artifacts

CircleCI may be configured to collect build artifacts and make them available from your build. For example, artifacts enable you to save screenshots as part of your build, and view them when the build finishes. You must explicitly collect those files with the store_artifacts step and specify the path and destination. See the store_artifacts section of the Configuration Reference for an example.

Saving screenshots is straightforward: it’s a built-in feature in WebKit and Selenium, and is supported by most test suites:

Using a Local Browser to Access HTTP server on CircleCI

If you are running a test that runs an HTTP server on CircleCI, it is sometimes helpful to use a browser running on your local machine to debug a failing test. Setting this up is easy with an SSH-enabled run.

  1. Run an SSH build using the Rerun Job with SSH button on the Builds page of the CircleCI app. The command to log into the container over SSH apears, as follows:
    ssh -p 64625 ubuntu@
  2. To add port-forwarding to the command, use the -L flag. The following example forwards requests to http://localhost:3000 to port 8080 on the CircleCI container. This would be useful, for example, if your build runs a debug Ruby on Rails app, which listens on port 8080.
    ssh -p 64625 ubuntu@ -L 3000:localhost:8080
  3. Then, open your browser on your local machine and navigate to http://localhost:8080 to send requests directly to the server running on port 3000 on the CircleCI container. You can also manually start the test server on the CircleCI container (if it is not already running), and you should be able to access the running test server from the browser on your development machine.

This is a very easy way to debug things when setting up Selenium tests, for example.

Interacting With the Browser Over VNC

VNC allows you to view and interact with the browser that is running your tests. This will only work if you’re using a driver that runs a real browser. You will be able to interact with a browser that Selenium controls, but phantomjs is headless — there is nothing to interact with.

  1. Install a VNC viewer. If you’re using macOS, consider Chicken of the VNC. RealVNC is also available on most platforms.

  2. Then start an SSH run to a CircleCI container. When you connect to the machine, add the -L flag and forward the remote port 5901 to the local port 5902:
    daniel@mymac$ ssh -p PORT ubuntu@IP_ADDRESS -L 5902:localhost:5901
  3. You should be connected to the CircleCI container. Now start the VNC server:
    ubuntu@box159:~$ vnc4server -geometry 1280x1024 -depth 24
  4. Enter the password password when it prompts you. Your connection is secured with SSH, so there is no need for a strong password. You do need to enter a password to start the VNC server.

  5. Start your VNC viewer and connect to localhost:5902. Enter the password when it prompts you. You should see a display containing a terminal window. You can ignore any warnings about an insecure or unencrypted connection. Your connection is secured through the SSH tunnel.

  6. Next, be sure to run:
    ubuntu@box159:~$ export DISPLAY=:1.0

    to enable windows to open in the VNC server, rather than the default headless X server.

Now you can run your integration tests from the command line and watch the browser for unexpected behavior. You can even interact with the browser as if the tests were running on your local machine.

For information about Headless Chrome, refer to the Headless Chrome for More Reliable, Efficient Browser Testing CircleCI blog post and the Related Discuss thread.

Sharing CircleCI’s X Server

If you find yourself setting up a VNC server often, then you might want to automate the process. You can use x11vnc to attach a VNC server to X.

  1. Download x11vnc and start it before your tests: ``` steps:
    • run: name: Download and start X command: | sudo apt-get install -y x11vnc x11vnc -forever -nopw: background: true ```
  2. Now when you start an SSH build, you’ll be able to connect to the VNC server while your default test steps run. You can either use a VNC viewer that is capable of SSH tunneling, or set up a tunnel on your own:
    $ ssh -p PORT ubuntu@IP_ADDRESS -L 5900:localhost:5900

X11 forwarding over SSH

CircleCI also supports X11 forwarding over SSH. X11 forwarding is similar to VNC — you can interact with the browser running on CircleCI from your local machine.

  1. Install an X Window System on your computer. If you’re using macOS, consider XQuartz.

  2. With X set up on your system, start an SSH build to a CircleCI VM, using the -X flag to set up forwarding:
    daniel@mymac$ ssh -X -p PORT ubuntu@IP_ADDRESS

    This will start an SSH session with X11 forwarding enabled.

  3. To connect your VM’s display to your machine, set the display environment variable to localhost:10.0
    ubuntu@box10$ export DISPLAY=localhost:10.0
  4. Check that everything is working by starting xclock.
    ubuntu@box10$ xclock

    You can kill xclock with Ctrl+c after it appears on your desktop.

Now you can run your integration tests from the command line and watch the browser for unexpected behavior. You can even interact with the browser as if the tests were running on your local machine.