Continuous Integration with Screener

Overview

Integrate Screener into your Continuous Integration (CI) process, automatically triggering test runs and passing/failing builds based on visual changes detected. In this way, you can be sure your latest code changes do not contain any unexpected regressions.

 

Screener CI Script

Screener provides a CI Script that integrates into your CI tool. This script waits for running tests to finish, and then will output the results. If visual regressions are found, it will fail the build. Otherwise, if no regressions are found, it will pass the build.

The CI Script has 3 required parameters:

ParameterDescription
API KeyYour project's API key is available at the bottom of your Project Dashboard:

Test Group IDYour Test Group ID is available from the Test Group's Dashboard:

Build NumberThe current build number from your CI tool.
Environment Variables: 

We recommend adding the API Key and Test Group ID parameters as environment variables to your CI tool:

  • SCREENER_API_KEY
  • SCREENER_GROUP_ID

The Build Number should already be available as an environment variable in your CI tool. Please refer to your CI tool documentation for what variable name it may be.



WebDriver Tests

Assuming you have already integrated Screener into your WebDriver tests.

In your WebDriver test, you will need to add the Build Number to your desiredCapabilities object via a "build" property, for the CI script to reference. Here is an example:

capabilities: {
  browserName: 'chrome',
  build: process.env.BUILD_NUMBER,
  screener: {
    ...
  }
}

Screener Tests

Running a Screener Test using the CI Script will automatically trigger a test run against the Test Group ID passed into it.

Note: If you do not want Screener to fail your build, you can alternatively trigger a Screener test run via our API and receive email notifications when visual changes are found.

CI Tool Examples

Contact us if you need help integrating Screener into your CI, or if you would like an example that we do not have listed here.



CircleCI Example

circle.yml
dependencies:
  override:
    # Install Screener CI Script
    - curl -O https://s3-us-west-2.amazonaws.com/screener-files/ci/v2.1/screener-ci.zip
    - unzip -o screener-ci.zip


test:
  override:
    # Run Screener Tests
    - ./screener-ci.sh $SCREENER_API_KEY $SCREENER_GROUP_ID $CIRCLE_BUILD_NUM

Jenkins Example


Jenkins Setup Instructions for Linux / Mac OS X:
  1. Create a new job in Jenkins (Freestyle project)
  2. Configure the job:
    1. Under the "Build" heading, click "Add build step" and select "Execute shell"
    2. Copy the commands below, and paste into the "Command" textarea
      • This step assumes Screener Environment Variables have already been set in Jenkins (can use EnvInject plugin). Or replace the Screener Environment Variables below with actual values.
  3. Click "Save"
# Install Screener CI Script
curl -O https://s3-us-west-2.amazonaws.com/screener-files/ci/v2.1/screener-ci.zip
unzip -o screener-ci.zip


# Run Screener CI Script
./screener-ci.sh $SCREENER_API_KEY $SCREENER_GROUP_ID $BUILD_NUMBER
Note: The Windows script depends on cURL being installed, and in the PATH. Or add the curl.exe file into the Jenkins workspace job folder.
Jenkins Setup Instructions for Windows:
  1. Create a new job in Jenkins (Freestyle project)
  2. Configure the job:
    1. Under the "Build" heading, click "Add build step" and select "Execute Windows batch command"
    2. Copy the commands below, and paste into the "Command" textarea
      • This step assumes Screener Environment Variables have already been set in Jenkins (can use EnvInject plugin). Or replace the Screener Environment Variables below with actual values.
  3. Click "Save"
curl -O http://s3-us-west-2.amazonaws.com/screener-files/ci/v2.1/screener-ci.bat
screener-ci.bat %SCREENER_API_KEY% %SCREENER_GROUP_ID% %BUILD_NUMBER%

Travis CI Example

.travis.yml
install:
  # Install Screener CI Script
  - curl -O https://s3-us-west-2.amazonaws.com/screener-files/ci/v2.1/screener-ci.zip
  - unzip -o screener-ci.zip


script:
  # Run Screener Tests
  - ./screener-ci.sh $SCREENER_API_KEY $SCREENER_GROUP_ID $TRAVIS_BUILD_NUMBER

General Example

Below is an example of how to download and run the CI Script on Linux or Windows. The Environment Variables will need to be replaced to match your own.


# Install Screener CI Script
curl -O https://s3-us-west-2.amazonaws.com/screener-files/ci/v2.1/screener-ci.zip
unzip -o screener-ci.zip


# Run Screener CI Script
./screener-ci.sh $SCREENER_API_KEY $SCREENER_GROUP_ID $BUILD_NUMBER
Note: The Windows script depends on cURL being installed, and in the PATH.
curl -O http://s3-us-west-2.amazonaws.com/screener-files/ci/v2.1/screener-ci.bat
screener-ci.bat %SCREENER_API_KEY% %SCREENER_GROUP_ID% %BUILD_NUMBER%