Skip to main content

XCTest overview

This SDK allows you to add visual checkpoints to your XCTest unit tests so that the images can be tested using Eyes.

For information about installing and configuring this SDK, see Comparing Screenshots in XCTest with Applitools on the Applitools Tutorial site.

Installation​

Using Swift Package Manager​

In Xcode, select File > Add Packages... then add the GitHub URL of EyesImages:

https://github.com/applitools/eyes-images-swift-package.git

Getting started​

To get started with this SDK, you need to set the following:

Entering the Applitools API key​

To authenticate via the Applitools server and run tests, you need to assign the API key provided from Applitools Eyes to the EyesImages Eyes instance. For details how to retrieve your API key, see the Applitools documentation. 

let eyes = Eyes()
eyes.apiKey = <API_key>

Eyes server URL​

If the Eyes server is not deployed in https://eyes.applitools.com, you need to assign the Server URL to the EyesImages Eyes instance before running tests.

The server URL of your Applitools Eyes dashboard is in the format https://<MY_COMPANY>.applitools.com

eyes.serverURL = <YOUR_SERVER_URL>

A test in Applitools Eyes always starts with an eyes.open() call and ends with eyes.closeAsync(). The steps in the test are calls to eyes.check() between the eyes.open() and eyes.closeAsync() calls.

A test is structured as follows:

eyes.open(...)
  [step 1]
  [step 2]
  ...
eyes.closeAsync()

Common methods​

Open​

Creates an Eyes test. This will start a session with the Applitools server.

Syntax​

eyes.open(withApplicationName: appName, testName: testName)

Example​

eyes.open(withApplicationName: "Hello World iOS", testName: "iOS Screenshot test!")

Check​

Generates a screenshot of the current page and add it to the Eyes test.

eyes.check(image, tag: "Main Screen")

For a description of common actions with this class, see check Settings

closeAsync​

Closes the Eyes test but does not wait for the Eyes server to return a result. This command enables your system to continue running tests while Eyes completes its comparisons in the background. You should call this command at the end of each test, symmetrically to eyes.open.

eyes.closeAsync()

getAllTestResults​

After executing all Eyes tests, your code should call eyes.getAllTestResults() to retrieve all test results as a TestResultsSummary and close the batch.

eyes.getAllTestResults()

close​

Closes the Eyes test and waits for the Eyes Server to return a single result. The close command then returns a TestResults object with detailed test result data. This method takes an optional boolean parameter, if false it will not throw an exception if the test found differences (default is true). You should call this command at the end of each test, symmetrically to eyes.open.

info

This is a legacy API as it only returns a single result. We recommend using eyes.closeAsync and eyes.getAllTestResults instead of this API.

try eyes.close()

Visual tests and baselines​

By using the open, check, and closeAsync methods on Eyes, you are creating visual tests in Applitools Eyes. A visual test is a sequence of screenshots, compared with a baseline. The baseline is also a sequence of screenshots. The specific baseline to compare against is found by using the values for:

  • App name
  • Test name
  • Operating system version
  • Viewport size (defined by device size and orientation)

The baseline is created automatically when running a test with specific values for these 4 parameters for the first time. For example, if you run a test on iOS 16 and specify the app name and test name via eyes.open(withApplicationName:"some app", testName:"some test"), the first time the test runs with these parameters, on this specific operating system version / viewport size combination, a baseline will be created. Any subsequent execution with the same values will compare screenshots against this baseline. The test will actually be created after running eyes.closeAsync(), and the results of the test are returned by eyes.getAllTestResults() as a TestResultsSummary object.

For more information, see How Eyes compares checkpoints and baseline images