Applitools Bitbucket Integration | Applitools Documentation

On this page

The Eyes-Bitbucket integration builds on the branching capabilities in Eyes, and on the Bitbucket pull request and commit functionality.

Eyes supports multiple branches, each of which can consist of multiple test baselines. This lets you create a new branch based on an existing branch, make independent updates to the baselines in each branch, compare branches to detect conflicts, and then merge the baselines in each branch.

Bitbucket Integration

Bitbucket integrates with Eyes in the following aspects:

• Eyes tests are automatically configured to use and save baselines in branches whose name is derived from the Git branch names.
• All visual UI tests that are in a specific CI build are automatically batched together, with a batch name that includes the Git commit information.
• The Bitbucket Pull Request panel includes a status indicating the latest visual UI test results and merge status.
• The Bitbucket Commits panel also includes a status indicating the visual UI test result.
• When you initiate a Bitbucket pull-request merge, an Eyes branch merge is automatically triggered.

Setting up the Eyes Bitbucket Integration

You can integrate Bitbucket with Applitools Eyes using the Bitbucket public cloud (bitbucket.org), or a private Bitbucket server.

If the Bitbucket server or data center are deployed behind a company firewall, you need to whitelist inbound HTTPS traffic from the Eyes server to your Bitbucket server. If you use the Eyes Public server, the Eyes server is https://eyes.applitools.com. If you have a dedicated on-prem server, enter a URL in the format https://<My Organization>eyes.applitools.com.

If you cannot whitelist the Eyes server then you should use the Applitools proxy server, for details see Configuring Bitbucket integration with a proxy server.

The Bitbucket repository access token requires full Eyes team administration privileges.

Enabling Bitbucket integration

1. Navigate to the Admin Panel
2. On the Admin panel, click on the Teams tile
3. Click on the name of the team you want to configure.
4. On the Integrations tab, click Bitbucket.
5. If you use the public Bitbucket server, select bitbucket.org. If you use a private Bitbucket server, click Add and enter the URL of the Bitbucket server. You must have authorization to add and remove webhooks for the repositories that you want Eyes to be integrated with.
6. Click the Manage repositories button.
7. If you use a public cloud, click sign in with Bitbucket and give Bitbucket access to the repository. If you use a private Bitbucket server, In the Manage repositories window, enter your PAT and click Apply.

Configuring Your CI

Once you have setup Bitbucket integration, you need to set up your CI to configure the Eyes SDK with information related to the Bitbucket pull request or commit request. To allow the Eyes Batch to integrate data received from the Bitbucket server, you need to set the following Environment variables:

• APPLITOOLS_API_KEY - Your API key. To obtain your key see How to obtain your API key.
• APPLITOOLS_SERVER_URL - The URL of the Eyes server. If you use the public Eyes server, the URL is https://eyes.applitools.com.

You also need to set the following Build configuration:

APPLITOOLS_BATCH_ID - The Commit SHA of the current build. This also must be set as an environment variable before running Eyes tests.

If Eyes cannot recognize the End of Build event, you also need to add a cURL command to notify Eyes when all builds are complete. For details, see Notifying Eyes when a build is complete.

Bitbucket Pipelines

Working With The Bitbucket Integration

Once your system is configured to work with Bitbucket, use your CI and Bitbucket in the usual way. A CI job is normally triggered by a push to your repository, which then runs your visual UI tests.

Pull request workflow

When there is an open pull request, Eyes adds the following functionality to your Bitbucket workflow:

• When your CI initiates a build that includes an Eyes test, Eyes detects that the run is associated with a Bitbucket pull request and searches for a baseline to use as a reference. Eyes checks for a matching baseline in the following order:
  1. On a branch that corresponds to the repository name and source branch defined by the pull request.
  2. If there is no such branch, it creates a branch and populates it with the latest baseline for that test from the repository name and target branch defined by the pull request.
  3. If there is no such baseline, the test is marked as "New".
• Eyes sends Bitbucket status information that is displayed on the Bitbucket Pull requests panel.
• The item labeled tests/applitools/team1 indicates the results of the visual UI test that ran as part of this build.
• The item labeled test/applitools/team1 is a link. Click on the link to open the Test results screen of the Eyes Test Manager, which shows the results of the tests in the most recent build related to that pull request.

Commit push workflow

When a commit is pushed to a branch, Eyes adds the following functionality to your Bitbucket workflow:

• When your CI initiates a build that includes an Eyes test, Eyes detects that the run is associated with a Bitbucket commit and searches for a baseline to use as a reference. Eyes checks for a matching baseline in the following order:
  1. On a branch that corresponds to the repository name and the name of the branch that the commit was pushed to.
  2. If there is no such branch, it creates a branch and populates it with the latest baseline for that test from the repository name and the master branch as defined in APPLITOOLS_PARENT_BRANCH. If the master branch has not been defined it will use the Eyes default branch.
  3. If there is no such baselines the test is marked as "New".

Bitbucket Proxy Service

Eyes/Bitbucket integration requires two ways communication between the Eyes server and the Bitbucket server.

If your Bitbucket server is protected behind a firewall, and you cannot add a custom rule that exposes the relevant Bitbucket APIs so that Eyes can call them, you can use the Eyes-scm application to create webhooks on the relevant Bitbucket repositories. When using Eyes-scm, the Eyes server never calls the Bitbucket APIs directly, all calls are made through the application.

Installing the proxy service

Before installing the proxy service, you must have:

• Node.js installed (version 12 or later)
• The URL of the Eyes server that you use to open the Test Manager
• Your Eyes organization ID, available on the Admin/Account page in the ID field.

Running the proxy service

Use the following command to start the server:

eyes-scm

Configuring repositories and access credentials

Make sure the proxy service is running.

Enabling Applitools logs in Bitbucket Pipelines

For Bitbucket Pipelines, add the following to your .bitbucket-pipelines.yml to enable Applitools logs and store them as artifacts:

- step:
    name: Visual Tests
    script:
      - export APPLITOOLS_SHOW_LOGS=true
      - export APPLITOOLS_LOG_DIR=logs/
      - npm test
    artifacts:
      - logs/**

Example Docker command:

docker run \
  -e APPLITOOLS_SHOW_LOGS=true \
  -e APPLITOOLS_LOG_DIR=/usr/src/app/logs \
  -v ${WORKSPACE}/applitools-logs:/usr/src/app/logs \
  your-image-name