Configuring your CI for the Eyes GitHub integration

The article Using Eyes with GitHub describes configurations that need to be set up in the Test Manager to use Eyes with GitHub. The current article describes the configuration that needs to be set up in the CI system you use with GitHub. The configuration consists of two steps:

  • Setting up the start of the build: Setup that is done by the CI as part of the build before the Eyes tests are executed. This sets environment variables that are read by the Eyes SDK to obtain the information required by Eyes to execute the test.
  • Synchronizing multiple concurrent builds: If the CI runs a build using multiple concurrent instances, then it needs to notify Eyes when all of the instances have terminated.

Setting up the start of the build

Eyes needs two values in order to run the visual tests in the builds:

  • Your Eyes API Key: This is passed by setting the environment variable APPLITOOLS_API_KEY to the value of your Eyes API key. To obtain the value of your Eyes API key, see How to obtain your API key.
  • The batch ID: In a standalone Eyes test, the result of each test execution appears in a separate batch in the Test Manager. When multiple Eyes tests are executed using a supported CI, all of the test results appear together in a single batch. This is achieved by associating them with a common batch ID. The batch ID is passed to Eyes by settings the APPLITOOLS_BATCH_ID environment variable to a value generated by the CI.

For detailed configuration instructions for your CI, click on the relevant link below:

How to prepare your code

The configuration described in the previous section sets up the values of the environment variables APPLITOOLS_API_KEY and APPLITOOLS_BATCH_ID to provide the API key and batch ID respectively. Recent versions of the Eyes SDK read these environment variables to obtain this information. If you are using an older version of the SDK that does not do this, then we recommend updating your SDK to the latest version. If this is not possible, then add the following code to your test after the eyes instance variable has been instantiated and before the test is opened:


                                

If you are using a version of the SDK that reads these environment variables, then ensure that your code does not make any calls to the following methods, since doing so would overwrite the automated handling:

Synchronizing multiple concurrent builds

By setting the APPLITOOLS_BATCH_ID environment variable, as described in the previous section, you instruct Eyes to put the results of all tests in a particular CI build in the same Test Manager batch. If your CI runs multiple builds concurrently, then you need to follow two more steps :

  • In the GitHub integration page of the Test Manager, follow the instructions to disable automatic batch closing described in the article How to configure the Eyes GitHub integration. This is a one-time configuration that needs to be done by each team for each repository that has concurrent builds.
  • You need to indicate to Eyes when all of the concurrent builds have completed. You do this by sending the Eyes server an HTTP command. How you do this depends on your environment. For example, on a Linux-based system you can do it as follows:
    
    eyesserver="eyesapi.applitools.com"  # set this to your Eyes server name.
    githubserver="your_gituhub_server"   # as entered in the Eyes/github integration screen e.g. github.com
    apikey=$APPLITOOLS_API_KEY
    batchid=$APPLITOOLS_BATCH_ID         # this was previously set to the CommitSha	
    url="https://$eyesserver/api/externals/github/servers/$githubserver/commit/$batchid/complete?apiKey=$apiKey"
    header="Content-Type: application/json --data `{\"serverId\": \"$githubserver", \"commitSha\": \"$batchid\"}`"	
    extraInfo="-H $header  -v -L"
    
    curl -X POST $url $extraInfo
    
    

    Note that various values represented here as "$xxxx" are values set in other parts of the integration:

    • $eyesserver: The URL of your eyes server - the same value that you set when defining the Eyes server when you run visual Eyes tests (or the default shown in the snippet above).
    • $githubserver: The GitHub server you entered on the Eyes/GitHub integration screen as described in How to configure the Eyes GitHub integration.
    • $apikey: The same API key you use when running visual Eyes tests.
    • $batchid: The unique value that defines the batch. It is the value assigned to the APPLITOOLS_BATCH_ID environment variable, as described in the section Setting up the start of the build above.