Skip to main content

XCTest overview

This SDK allows seamless integration of visual checkpoints into your XCTest unit tests, enabling image-based validation using Eyes.

Installation​

Using Swift Package Manager​

  1. In Xcode, select File > Add Package Dependencies....

  2. Enter the GitHub repository URL for the EyesImages SDK:

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

  3. In the Add to Target column, select your unit test target and click Add Package.

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 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 at https://eyes.applitools.com, you need to assign the server URL to the XCTest 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.close(). The steps in the test are calls to eyes.check() between the eyes.open() and eyes.close() calls.

A test is structured as follows:

eyes.open(...)
  [step 1]
  [step 2]
  ...
try eyes.close()

Common methods​

Open​

Creates an Eyes test and starts a session with the Applitools server.

Syntax​

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

Example​

eyes.open(withApplicationName: "Hello World!", testName: "My first test using Eyes Images SDK")

Check​

Uploads a user-generated image, or captures a screenshot, and adds it to the Eyes test.

Example 1 - Upload a user generated image​

eyes.check(withTag: "Hello", andSettings: Target.image(myImage))

Example 2 - Capture a screenshot​

try await eyes.check(withTag: "Hello", andSettings: Target.window())

Close​

Closes the Eyes test and validates all screenshots. Make sure to call this method at the end of each test, corresponding to the initial open call.

try eyes.close()

Visual tests and baselines​

Using the open, check, and close methods of Eyes creates visual tests in Applitools Eyes. A visual test compares a sequence of screenshots against a baseline. The baseline is determined based on:

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

The baseline is automatically created during the first test execution with specific parameter values. 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 and viewport size combination, a baseline will be created. Any subsequent execution with the same values will compare screenshots against this baseline. The test is finalized after running eyes.close(), and the results of the test are returned as a TestResultsSummary object.

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