Last updated February 21, 2024

On browser testing / UAT

Heroku CI provides support for browser testing, or “user acceptance testing” (UAT) by providing options for installing browsers in your test run dyno. Users can choose between Google Chrome stable, beta, and unstable release channels supported by the --headless flag.

It’s important to note that while we provide options for installing browsers, it is the developers responsibility to drive the browser. Each language, web framework, and/or test framework tends to have it’s own prescription on how to drive and run tests in a browser (most commonly, this is done with Selenium). Most of these solutions can be supported with Heroku CI. We will be adding UAT tech stacks and set-ups below as they are tested and proven.

Browsers available

While we offer a few browsers to accommodate various needs, we strongly urge you to consider Google Chrome with --headless support first. It’s stable, has strong parity with user browsers, and is designed to enable this kind of testing.

Google Chrome

Google developers publish a special release of the browser, Chrome for Testing, to support automated browser testing including a version-aligned Chromedriver, the Selenium WebDriver adapter.

Google Chrome supports a --headless command line option, optimal for UAT as it uses your browser, so that it doesn’t waste cycles rendering content to the screen.

To use Google Chrome for Heroku CI runs, add the buildpack heroku-community/chrome-for-testing to the environments.test.buildpacks section of app.json. For example, if you were using Chrome for Node.js tests:

{
  "environments": {
    "test": {
      "buildpacks": [
        { "url": "heroku-community/chrome-for-testing" },
        { "url": "heroku/nodejs" }
      ]
    }
  }
}

Now, chrome & chromedriver (from the stable release channel by default) will be available in your test run. See the buildpack documentation for additional details.

PhantomJS

PhantomJS is a headless browser built on NodeJS. It’s smaller and easier to install than Chrome, so it’s been a common choice for UAT for quite some time. Please note that Heroku CI runs can be configured to use PhantomJS, but we do not presently offer direct support for it, for two reasons: 1) It’s installed via a 3rd party buildpack, and 2) PhantomJS is no longer maintained.

To use PhantomJS for Heroku CI runs, add the buildpack to the environments.test.buildpacks section of your app.json. For example, if you were using PhantomJS in Ruby tests:

{
  "environments": {
    "test": {
      "buildpacks": [
        { "url": "heroku/ruby" },
        { "url": "https://github.com/stomita/heroku-buildpack-phantomjs" }
      ]
    }
  }
}

If you are using NodeJS, you may want to consider using the phantomjs-prebuilt instead.

Testing with Selenium

Heroku CI supports testing an app with Selenium via the Chrome for Testing buildpack mentioned above. To run Selenium in Heroku CI, you’ll need:

1. Chromedriver - installed by Chrome for Testing buildpack
2. Language binding to Selenium - the WebDriver adapter, select according to the language the app requires.
3. Selenium driver options in the app’s test code - see Selenium documentation as well as the language-specific driver docs.