Using Eyes with Atlassian Bamboo CI

This article explains how to install and use the Applitools Eyes plug-in for the Atlassian Bamboo CI system.

The Eyes plug-in provides the following functionality:

This article assumes that you already have Bamboo installed on your system and that you know how to use it. Note that depending on your version of Bamboo, some of the necessary steps or screenshots may be different from those described here.

Installing the Applitools plug-in

You can install the Applitools Eyes App from the Atlassian Marketplace for Bamboo. Search for the plug-in using the term "Applitools".

Setting up a Visual test

To integrate Bamboo with an Eyes test there are two steps:
  • Add and configure an Applitools plug-in Bamboo task.
  • Execute the Applitools Eyes test in a way that ensures that the API key and batch information that is set up by the Applitools plug-in is passed to the Eyes test.

How to do this is covered in the next two sections.

Adding an Applitools task

In each job that has a visual test, go to the Tasks panel, click Add task and select the Applitools Task. If you don't see it in the list of task types, make sure you have chosen the "All" task types option.

To open the Applitools task configuration, click on the task and:
  • Enter a task description (optional).
  • Enter your API key (see How to obtain your API key).
  • If you use an on-premise server or private cloud, put the URL in the Applitools server URL field (for example https://eyes.yourcompany.com). If you use the Applitools public cloud, then leave the Applitools server URL field empty.
  • Click Save.
  • Drag the Applitools task so that it is at the top of the list of tasks.

Setting up the test code

The Applitools Bamboo plug-in passes information to the Eyes test by setting up three environment variables:

  • bamboo_APPLITOOLS_API_KEY
  • bamboo_APPLITOOLS_BATCH_ID
  • bamboo_APPLITOOLS_BATCH_NAME

Most versions of the Eyes SDK detect and use these environment variables. If they are supported in the Eyes SDK that you use, then you don't need to change the test. However, you do need to ensure that the test does not set the API key or set the batch directly so that the SDK uses the Bamboo environment variables.

Check that the test code does not use the class$eyes$setapikey class$eyes$setbatch or the equivalent configuration methods/properties. If your test code does make these calls, then you should skip them when the test is invoked by Bamboo (you can test for the existence of the Bamboo environment variables to detect if Bamboo invoked the test).

If you use a version of Eyes SDK that does not recognize these environment variables, then in the log you will see a message that you have not set your API Key. In this case, there are two options to pass the values in these environment variables to your Eyes test:
  • Access the environment variables and configure the test directly in your Eyes test code
  • Assign the Bamboo environment variables to the standard Eyes environment variables in a script and then call your test from within that script.

Both of these options are described below.

Option 1: Modify your test code

In your Eyes test code, add the highlighted lines to your test suite setup code:


                            

If your code already uses the , the , or the similar call from the class, then replace the existing calls with the code above.

Option 2: Set standard Eyes environment variables using a script

If you prefer not to change your test, then the alternative method is to convert the Bamboo environment variables to the standard Applitools environment variables in a script and then call you test program from that script. Two examples of such a script are shown below: one for a Linux Bash script and the second for a windows .bat script. In both cases, the test is invoked using Node.js, and you should replace this with whatever is appropriate for your test platform and language.

This technique will only work if the test does not set these configuration values directly, since the values of the environment variables are only taken into account if the code does not specify the property explicitly.

Linux/Bash shell

            
export APPLITOOLS_BATCH_ID=$bamboo_APPLITOOLS_BATCH_ID
export APPLITOOLS_BATCH_NAME=$bamboo_APPLITOOLS_BATCH_NAME
export APPLITOOLS_API_KEY=$bamboo_APPLITOOLS_API_KEY

        

Windows .bat script

            
setx APPLITOOLS_BATCH_ID "%bamboo_APPLITOOLS_BATCH_ID%"
setx APPLITOOLS_BATCH_NAME "%bamboo_APPLITOOLS_BATCH_NAME%"
setx APPLITOOLS_API_KEY "%bamboo_APPLITOOLS_API_KEY%"

        

Once you have such a script, you need to ensure that Bamboo calls your script instead of calling your test program directly. The next two sections describe two approaches to doing this.

Option 2a: Setup the executable to run the script

With this option, you change the executable that runs the test to run the script instead of running the build tool directly. The script sets up the environment variables as described above and then calls the build tool. You need to do this for each build tool that executes Eyes tests.

  • On the Bamboo administration page, click Server capabilities in the left-hand menu.
  • Click Edit next to the build tool you use (Node.js in this example).
  • Note the current call path to the build tool (e.g. "C:\Program Files\nodejs\node.exe") and then change the path to point to your script (e.g. c:\bin\runnode.bat).
  • Click the update button.
  • In your script, call the build tool by using the original pathname (e.g. "C:\Program Files\nodejs\node.exe").

With this method, the executable is changed for all tasks in all jobs in a single step.

Option 2b: Use a script task to start the test

With this option, instead of using a build tool task to start the test, you use a script task to call a script. The script sets up the environment variables and calls the build tool as described above.

  • If you are changing an existing visual test, then disable the task that currently runs that test.
  • Click Add task.
  • Select the script task type, and fill in the script form as follows:
    • In the Interpreter field select /bin/sh or cmd.exe.
    • In the script location field select the File option.
    • Enter the path of the script file in the Script file field.
    • Put the name of the visual test you want to run in the Argument field.
    • Click Save.

Viewing test results

After your test has run, you can see the result of all the tests in the stage under the Applitools test results tab in the Bamboo window.

You can use the various Eyes Test Manager tools on the Test results page. You can also open the step viewer by clicking one of the test thumbnails. If you open the Test editor (from the step thumbnail menu), then the Eyes Test Manager will be opened in a new browser tab, and you will have access to the full power of the Test Manager.