Skip to main content

Apple

The tvlabs connect command does not yet support Apple devices. Applications must be installed through the TV Labs web application or CLI upload.

Prerequisites​

Before starting, ensure you have:

  1. An Apple Developer account enrolled in the Apple Developer Program
  2. A Mac with Xcode installed for building and signing your application

Connecting​

The tvlabs connect command does not currently support Apple devices. Application installation and device interaction is done through the TV Labs web application.

Installing​

Application installation depends on your distribution method. Both methods use the TV Labs web application to install builds onto the device.

Ad Hoc Distribution​

For Ad Hoc distribution, the device must be registered in your Apple Developer Portal. To register TV Labs devices:

  1. Contact TV Labs for the list of device UDIDs for the devices you need
  2. Add each UDID to your Apple Developer Portal under Certificates, Identifiers & Profiles > Devices
  3. Regenerate your provisioning profile to include the new devices
  4. Build and sign your .ipa with the updated provisioning profile
  5. Upload the signed .ipa through the TV Labs web application or with tvlabs upload

Enterprise Distribution​

Enterprise (in-house) application builds are supported and can be sideloaded and automatically trusted via MDM installation. Please note that MDM installation depends on Apple Push Notification Service (APNS), which can vary the time it takes for the device to receive the sideload request.

info

See the Sideloading guide for more details on uploading builds through the TV Labs web application.

TestFlight​

To install applications via TestFlight, the following requirements must be met:

  1. Your TV Labs account must have dedicated devices purchased
  2. The dedicated device must be signed in with an Apple ID that you own.
  3. The TestFlight app must be installed from the App Store on the device

Once these requirements are met, invite the Apple ID associated with the device to your TestFlight build through App Store Connect. The build will then be available to install through the TestFlight app on the device. TV labs does not manage TestFlight installations.

Running Bundled Automations​

If you have a pre-built .xctest UI-test bundle, you can run it against an app installed on a TV Labs Apple device using the webdriver script mobile: runXCTest. This invokes the test runner that ships inside your .xctrunner build on the device and streams test events back through the WebDriver session.

For example:

await driver.executeScript('mobile: runXCTest', [
  {
    testRunnerBundleId: 'com.company.example.xctrunner',
    appUnderTestBundleId: 'com.company.example',
    xctestBundleId: 'ai.company.exampleUITests',
    env: { SANDBOX_EMAIL: 'dummy', SANDBOX_PASSWORD: 'dummy' },
  },
]);

The fields are:

  • testRunnerBundleId — Bundle ID of the installed .xctrunner app (e.g. your.org.uitests.xctrunner).
  • appUnderTestBundleId — Bundle ID of the app the tests target.
  • xctestBundleId — Bundle ID of the .xctest plugin embedded inside the runner. This is read from PlugIns/<Name>.xctest/Info.plist and is not the same as testRunnerBundleId.
  • env — Optional environment variables passed to the XCTest process.

This script only runs successfully on tvlabs' internally-developed webdriver stack. In order to opt-into this stack, you must provide additionally capabilities:

"tvlabs:ff:use_grove_drivers": true,
"tvlabs:ff:use_grove_webdriver": true,

tvlabs-provided Automations​

tvlabs bundles an ai.tvlabs.automations.xctrunner on all our Apple devices that include XCUITest-driven automations. One automation in this bundle is the ability to sign into or out of a sandbox account. If you plan to use this bundle, please contact us.

This automation will drive the device through the login screen and fill in the provided credentials you provide. Supply the credentials via the env key when executing the automation. We can run the automation via the mobile: runXCTest script:

// iOS
const SETTINGS_BUNDLE = 'com.apple.Preferences';
// tvOS
const SETTINGS_BUNDLE = 'com.apple.TVSettings';

await driver.executeScript('mobile: runXCTest', [
  {
    testRunnerBundleId: 'ai.tvlabs.automationsUITests.xctrunner',
    appUnderTestBundleId: SETTINGS_BUNDLE,
    xctestBundleId: 'ai.tvlabs.automationsUITests',
    env: { SANDBOX_EMAIL: 'placeholder', SANDBOX_PASSWORD: 'placeholder' },
  },
]);
info

The session must have a timeout of 60 seconds in order to allow the automation to finish on slower devices. You can configure this by providing newCommandTimeout: 60 in the session capabilities.

info

If the account is protected by 2FA, then the automation will successfully end, and you will pick up your webdriver script at the 2FA screen.

Troubleshooting​

If application installation fails with a provisioning error, verify that the device UDID is included in your provisioning profile and that the profile has not expired.

If application installation fails, ensure that the device storage is not full.

For further assistance, please contact TV Labs for support.