Browser Testing

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


Refer to thePre-Built CircleCI Docker Images一种nd add-browsers:to the image name for a variant that includes Java 8, Geckodriver, Firefox, and Chrome. Add-browsers-legacy到包括幻影的变体的图像名称。


每次你承诺,推动代码,CircleCI汽车matically 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 theSelenium documentationfor details on set up. Refer to theXvfb man pagefor 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::

2职位builddocker-图片circleci/node:jessie-browsers一种uth用户名mydockerhub-user.password$DOCKERHUB_PASSWORD# context / project UI env-var referencesteps-checkout-runmkdir测试报告-runname下载Seleniumcommandcurl - o。com/3.5/selenium-server-standalone-3.5.3.jar-runname开始Seleniumcommandjava -jar selenium-server-standalone-3.5.3.jar -log test-reports/selenium.logbackgroundtrue

Refer to the安装和运行Selenium以自动化浏览器测试section of the 2.0 Project Tutorial for a sample application. Refer to theKnapsack Pro documentationfor an example of Capybara/Selenium/Chrome headless CircleCI 2.0 configuration for Ruby on Rails.

有关使用无头铬的更多信息,请参阅Circleci博客帖子Headless Chrome for More Reliable, Efficient Browser Testing一种nd the related讨论线程

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 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 aCircleCI orbfor 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

2。1orbslambda-tunnellambdatest/lambda-tunnel@0.0.1职位lambdatest / with_tunnel.tunnel_namesteps-


调味料实验室operates browsers on a network that is separate from CircleCI build containers. To allow the browsers access the web application you want to test, run Selenium WebDriver tests with Sauce Labs on CircleCI using Sauce Labs’ secure tunnel调味酱连接

调味酱Connect允许您在Circleci构建容器中运行测试服务器并公开它(使用类似URLlocalhost:8080)to Sauce Labs’ browsers. If you run your browser tests after deploying to a publicly accessible staging environment, you can use Sauce Labs in the usual way without worrying about Sauce Connect.

This exampleconfig.ymlfile shows how to run browser tests through Sauce Labs against a test server running within a CircleCI build container.

2职位builddocker-图片circleci/python:jessie-node-browsers一种uth用户名mydockerhub-user.password$DOCKERHUB_PASSWORD# context / project UI env-var referencesteps-checkout-runname安装酱汁实验室并设置隧道backgroundtruecommand|curl -o saucelabs.tar.gztar -xzf sc-*bin / sc -u $ {saucelabs_user} -k $ {saucelabs_key}wget --retry-connrefused --no-check-certifice -t 60 localhost:4445#等待应用程序准备好-run# base image is python, so we run `nosetests`, an extension of `unittest`command最终-runnameShut Down Sauce Connect Tunnelcommand|kill -9 `cat /tmp/`



2。1orbssauce-connectsaucelabs/sauce-connect@1.0.1workflows浏览器_Tests.职位-sauce-connect/with_proxynameChrome Testssteps-runmvn verify -B -Dsauce.browser=chrome -Dsauce.tunnel="chrome"tunnel_identifier-sauce-connect/with_proxynameSafari测试steps-runmvn验证-b -dsauce.browser = safari -dsauce.tunnel =“safari”tunnel_identifiersafari

For more detailed information about the Sauce Labs orb and how you can use the orb in your workflows, refer to the调味吧实验室页面在CircleCI Orbs Registry

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_KEYEN.vironment variablesto those associated with your BrowserStack account.

对于移动应用程序,可以使用Appium或等效平台来通过在您的作业中安装Appium并使用Circleci来使用Webdriver协议EN.vironment variablesfor the USERNAME and ACCESS_KEY.

Another browser testing solution you can use in your Javascript end-to-end testing is。与Selenium-architected浏览器测试解决方案不同,使用赛普拉斯时,您可以在与应用程序中相同的运行循环运行测试。为简化此过程,您可以使用Circleci认证的ORB执行许多不同的测试,包括运行所有赛普拉斯测试,而无需将结果发布到屏幕仪表板。下面的示例显示了Circleci认证的ORB,使您可以运行所有赛普拉斯测试,而无需将结果发布到仪表板。


There are other Cypress orb examples that you can use in your configuration workflows. For more information about these other orbs, refer to the柏Orbs页面在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 collectbuild artifacts一种nd 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 thestore_artifactsstep and specify the路径一种nddestination。看看store_artifacts配置Circleci文档的一部分。

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


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 theJob pageCircleci应用程序。使用SSH apears登录容器的命令如下:
    SSH -P 64625 Ubuntu@
  2. 要将端口转发添加到命令,请使用-Lflag. The following example forwards requests tohttp://localhost:3000在您的本地浏览器到港口8080在Circleci容器上。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.


SSH -P 64625 Ubuntu@ 3000:localhost:8080
  1. Then, open your browser on your local machine and navigate tohttp://localhost:3000to send requests directly to the server running on port8080在Circleci容器上。您还可以在Circleci容器上手动启动测试服务器(如果尚未运行),您应该能够从开发机上的浏览器访问运行的测试服务器。

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.

  1. Install a VNC viewer. If you’re using macOS, considerVNC的鸡RealVNCis also available on most platforms.

  2. Open a Terminal window,start an SSH runto a CircleCI container and forward the remote port 5901 to the local port 5902.

ssh-pPort Ubuntu @ ip_address-L5902:localhost:5901
  1. Install thevnc4server一种ndmetacitypackages. You can usemetacity要移动浏览器并返回终端窗口。
sudo一种ptinstallvnc4server metacity
  1. 连接到Circleci容器后,启动VNC服务器。
  1. Since your connection is secured with SSH, there is no need for a strong password. However, you still need一种password, so enterpassword一种t the prompt.

  2. 启动VNC查看器并连接到localhost:5902。Enter yourpassword一种t the prompt.

  3. 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.

  4. To allow windows to open in the VNC server, set theDISPLAYvariable. Without this command, windows would open in the default (headless) X server.

  1. 开始metacity在背景中。
ubuntu@box159:~$metacity &
  1. 开始firefox在背景中。
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

如果您发现自己经常设置VNC服务器,那么您可能希望自动执行该过程。您可以使用x11vncto attach a VNC server to X.

  1. 下载x11vnc并在测试之前启动它:
steps: - run: name: Download and start X command: | sudo apt-get install -y x11vnc x11vnc -forever -nopw background: true
  1. Now when youstart 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端口Ubuntu @ ip_address -l 5900:localhost:5900

X11 forwarding over SSH

Circleci还支持X11转发SSH。X11转发类似于VNC - 您可以与本地计算机上的Circleci上运行的浏览器进行交互。

  1. 在计算机上安装X窗口系统。如果您正在使用MacOS,请考虑[XQuartz](。

  2. With X set up on your system,start an SSH build到Circleci VM,使用-Xflag to set up forwarding:

daniel@mymac$ ssh -X -p PORT ubuntu@IP_ADDRESS

This will start an SSH session with X11 forwarding enabled.

  1. To connect your VM’s display to your machine, set the display environment variable tolocalhost:10.0
ubuntu@box10$ export DISPLAY=localhost:10.0
  1. 检查一切都不按章工作g by starting xclock.
Ubuntu @ box10 $ xclock


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.


Project Walkthrough