On This Page
This document describes common methods for running and debugging browser testing in your CircleCI config.
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.
Refer to the Pre-built CircleCI convenience images and add
-browsers: to the image name for a variant that includes Java 8, Geckodriver, Firefox, and Chrome. Add
-browsers-legacy to the image name for a variant which includes PhantomJS.
Many automation tools used for browser tests use Selenium WebDriver, a widely-adopted browser driving standard.
Selenium WebDriver provides a common API for programmatically 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.1 jobs: build: docker: - image: cimg/node:16.13.1-browsers auth: username: mydockerhub-user password: $DOCKERHUB_PASSWORD # context / project UI env-var reference steps: - checkout - run: mkdir test-reports - run: name: Download Selenium command: curl -O http://selenium-release.storage.googleapis.com/3.5/selenium-server-standalone-3.5.3.jar - run: name: Start Selenium command: java -jar selenium-server-standalone-3.5.3.jar -log test-reports/selenium.log background: true
As an alternative to configuring your environment for Selenium, you could move to cloud-based platforms such as LambdaTest, Sauce Labs, or BrowserStack. These cross browser testing clouds provide you with a ready-made infrastructure so you don’t have to spend time configuring a Selenium environment.
LambdaTest now integrates with CircleCI to boost your go-to-market delivery. Perform automated cross browser testing with LambdaTest to ensure your development code renders seamlessly through an online Selenium grid providing 2000+ real browsers running through machines, on the cloud. Perform automation testing in parallel with LambdaTest’s Selenium grid to drastically trim down your test cycles.
LambdaTest provides an SSH (Secure Shell) tunnel connection, Lambda Tunnel, to help you perform cross browser testing of your locally stored web pages. With Lambda Tunnel, you can see how your website will look to your audience before making it live, by executing a test server inside your CircleCI build container to perform automated cross-browser testing on the range of browsers offered by Selenium Grid on LambdaTest.
LambdaTest has developed a CircleCI orb for browser compatibility testing that enables you to open a Lambda Tunnel before performing any browser testing, easing the process of integrating LambdaTest with CircleCI. Use the orb to quickly set up a Lambda tunnel and the define your test steps.
version: 2.1 orbs: lambda-tunnel: email@example.com jobs: lambdatest/with_tunnel: tunnel_name: <your-tunnel-name> steps: - <your-test-steps>
Sauce Labs has an extensive network of operating system and browser combinations you can test your web application against. Sauce Labs supports automated web app testing using Selenium WebDriver scripts as well as through
saucectl with the JS framework of your choice, and then integrating the saucectl-run orb in your CircleCI workflow.
- Add your
SAUCE_ACCESS_KEYas environment variables in your Circle CI project.
- Modify your CircleCI project
config.ymlto include the saucectl-run orb and then call the orb as a job in your workflow.
version: 2.1 orbs: saucectl: firstname.lastname@example.org jobs: test-cypress: docker: - image: cimg/node:lts auth: username: mydockerhub-user password: $DOCKERHUB_PASSWORD # context / project UI env-var reference steps: - checkout - setup_remote_docker: version: 20.10.2 - saucectl/saucectl-run workflows: default_workflow: jobs: - test-cypress
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.
To simplify this process, you may use a CircleCI-certified orb to perform many different tests, including running all Cypress tests without posting the results to your Cypress dashboard. The example below shows a CircleCI-certified orb that enables you to run all Cypress tests without publishing results to a dashboard.
version: 2.1 orbs: cypress: cypress-io/cypress@1 workflows: build: jobs: - cypress/run: no-workspace: true
There are other Cypress orb examples that you can use in your configuration workflows. For more information about these other orbs, refer to the Cypress Orbs page in the CircleCI Orbs Registry.
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 job, and view them when the job finishes. You must explicitly collect those files with the
store_artifacts step and specify the
destination. See the store_artifacts section of the Configuring CircleCI document for an example.
Saving screenshots is straightforward: it’s a built-in feature in WebKit and Selenium, and is supported by most test suites:
- Manually, using Selenium directly
- Automatically on failure, using Cucumber
- Automatically on failure, using Behat and Mink
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.
- Run an SSH build using the Rerun Job with SSH button on the Job page of the CircleCI app. The command to log into the container over SSH is as follows:
ssh -p 64625 email@example.com
- To add port-forwarding to the command, use the
-Lflag. The following example forwards requests to
http://localhost:3000on your local browser to port
8080on the CircleCI container. This would be useful, for example, if your job runs a debug Ruby on Rails app, which listens on port 8080. After you run this, if you go to your local browser and request http://localhost:3000, you should see whatever is being served on port 8080 of the container.
8080to be the port you are running on the CircleCI container.
ssh -p 64625 firstname.lastname@example.org -L 3000:localhost:8080
- Then, open your browser on your local machine and navigate to
http://localhost:3000to send requests directly to the server running on port
8080on 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 only works if you are using a driver that runs a real browser. You can interact with a browser that Selenium controls, but PhantomJS is headless, so there is nothing to interact with.
Install a VNC viewer. If you’re using macOS, consider Chicken of the VNC. RealVNC is also available on most platforms.
- Open a Terminal window, start an SSH run to a CircleCI container and forward the remote port 5901 to the local port 5902.
ssh -p PORT ubuntu@IP_ADDRESS -L 5902:localhost:5901
- Install the
metacitypackages. You can use
metacityto move the browser around and return to your Terminal window.
sudo apt install vnc4server metacity
- After connecting to the CircleCI container, start the VNC server.
ubuntu@box159:~$ vncserver -geometry 1280x1024 -depth 24
Since your connection is secured with SSH, there is no need for a strong password. However, you still need a password, so enter
passwordat the prompt.
Start your VNC viewer and connect to
localhost:5902. Enter your
passwordat the prompt.
You should see a display containing a terminal window. Since your connection is secured through the SSH tunnel, ignore any warnings about an insecure or unencrypted connection.
- To allow windows to open in the VNC server, set the
DISPLAYvariable. Without this command, windows would open in the default (headless) X server.
ubuntu@box159:~$ export DISPLAY=:1.0
metacityin the background.
ubuntu@box159:~$ metacity &
firefoxin the background.
ubuntu@box159:~$ firefox &
Now, you can run 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.
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.
x11vncand start it before your tests:
steps: - run: name: Download and start X command: | sudo apt-get install -y x11vnc x11vnc -forever -nopw background: true
- 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.
Install an X Window System on your computer. If you’re using macOS, consider XQuartz.
- With X set up on your system, start an SSH build to a CircleCI VM, using the
-Xflag to set up forwarding:
daniel@mymac$ ssh -X -p PORT ubuntu@IP_ADDRESS
This will start an SSH session with X11 forwarding enabled.
- To connect your VM’s display to your machine, set the display environment variable to
ubuntu@box10$ export DISPLAY=localhost:10.0
- Check that everything is working by starting xclock.
You can kill xclock with
Ctrl+cafter 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.
Help make this document better
This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.
You can also visit our support site to find support articles, community forums, and training resources.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.