Integration

Info

Please note that in order to have access to console and network logs of the app which is being tested, you would need to complete the integration of AppeliumFeedback into the tested app first. The two SDKs work together in order to ensure all logs are collected and available in test reports.

Carthage

To integrate AppeliumTests SDK into your Xcode project using Carthage, add this like to your Cartfile:

binary "https://api.appelium.com/v1/sdkArchives/AppeliumTestsKit.json"

After that you can simply run:

carthage update --platform iOS --use-xcframeworks

Then drag the AppeliumTestsKit.xcframework into your Xcode project.

Usage

Since the UI Tests on iOS are not a self-contained app, they don't have such an obvious entry point as application:didFinishLaunchingWithOptions:.

To work around this, we can use a mechanism provided by the NSPrincipalClass.

1. In your UI Tests target, create a simple class called UITestsSetup:

   import AppeliumTestsKit
   
   class UITestsSetup: NSObject {
   
       override init() {
           super.init()
   
           AppeliumTests.start(apiKey: <#api key#>)
   
           // Optionally set the name and/or the version of the backend environment
           AppeliumFeedback.setApplicationEnvironment(name: "STAGING", version: "2.0")
       }
   
   }
   

Tip

Previously the framework name didn't have Kit suffix, but this was running into Swift ambiguous type lookup issue (SR-14195)

You can create an api key or find an existing one here.

1. In the Info.plist file of your UI Tests bundle add the following key:

   <key>NSPrincipalClass</key>
   <string>UITests.UITestsSetup</string>
   

   Note the UITests. prefix - it is the name of the Swift module where we created the UITestsSetup class. By default, this will match the name of your UI Tests target.

Now you can run the tests and observe the results in the Dashboard.

Customize test plan name

Info

If you have a setup with multiple test plans and would like to have this setup be mirrored in Appelium Dashboard, you can set an environment variable on your Scheme or Test Plan:

1. Navigate to your Scheme or Test Plan (depending on which one are you using)
2. Set APPELIUM_TEST_PLAN environment variable (some examples: Regressions, Complete, PR, etc.)

Tests execution on multiple machines in parallel

Info

If you are running your UI tests in parallel on a single machine (Mac Mini, Mac Book etc), you can skip this part - there is nothing more you need to set up.

If you are running tests on multiple host machines and leveraging build-for-testing, and test-without-building APIs, you would need to pass a UUID that will be used for grouping all those test executions together.

1. If you are using the native xcodebuild command, you can generate a random UUID and pass it in:

   UUID=`uuidgen`
   
   xcodebuild test-without-building \
       -xctestrun "/path/to/mytests.xctestrun" \
       -parallel-testing-enabled "YES" \
       APPELIUM_TEST_EXECUTION_UUID="$UUID"
   

   or, if you are using Fastlane, you can pass the UUID or the Test Plan name into scan command:

   uuid = `uuidgen`.chomp
   
   platform :ios do
     lane :tests do
       scan(
           build_for_testing: false,
           ...
         xcargs: "APPELIUM_TEST_EXECUTION_UUID=#{uuid} APPELIUM_TEST_PLAN=\"MY PLAN\""
       )
     end
   end
   

2. Once you have passed the UUID into the xcodebuild command, you can expose it to the XCTestRunner. This can be done using the environment variables of your Scheme or Test Plan:
   1. Navigate to your Scheme or Test Plan (depending on which one are you using)
   2. In the Environment Variables section add: Name: APPELIUM_TEST_EXECUTION_UUID Value: $(APPELIUM_TEST_EXECUTION_UUID)

Tip

You can use this approach for passing other variables into your tests. Some examples could be the backend endpoint URL that you wish your tests to connect to, or you can have a custom Appelium API key for a different use case like nightly tests vs basic tests or even tests that you run on the Pull Request level.

Direct Links to Test Execution

You can leverage the APPELIUM_TEST_EXECUTION_UUID described above for generating direct URLs to your test executions.

Using the UUID variable from the code snippet above, and WORKSPACE_NAME which you can find by navigating to your home page on Dashboard (the path component after https://dashboard.appelium.com ), you can construct the following URL:

https://dashboard.appelium.com/${WORKSPACE_NAME}/resolve?testsCorrelationUuid=${UUID}