XCUI overview
This SDK allows you to work with Applitools Eyes using XCUI.
For information about installing and configuring this SDK, see Testing native iOS apps using XCUI on the Applitools Tutorial site.
Installation
Using Swift Package Manager
In Xcode, select File > Add Packages... then add the GitHub URL of EyesXCUI:
https://github.com/applitools/eyes-xcui-swift-package.git
Using CocoaPods
Add EyesXCUI
to your podfile:
target ‘YOUR_APPLICATION_TARGET_NAME’ do
target ‘YOUR_UNIT_TESTING_TARGET_NAME’ do
pod 'EyesXCUI'
end
end
Getting started
To get started with this SDK, you need to set the following:
- Applitools API key
- Eyes server URL - Required only if the Eyes server is not deployed on the Eyes public server.
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 XCUI 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 assigb the Server URL to the XCUI 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>
Recommended practice for using the SDK
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]
...
eyes.close()
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!", testName: "My first test using EyesXCUI SDK!")
Check
Generates a screenshot of the current page and add it to the Eyes test.
Syntax
eyes.check(withTag: tag, andSettings: checkSettings);
Example
eyes.check(withTag: "Hello", andSettings: Target.window().fully())
For a description of common actions with this class, see check Settings
Close
Closes the Eyes test and checks that all screenshots are valid.
It is important to call this at the end of each test, symmetrically to open
.
try eyes.close()
Visual tests and baselines
By using the open
, check
, and close
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.close()
, and the results of the test are returned as a TestResults
object.
For more information, see How Eyes compares checkpoints and baseline images