Skip to content

tvOS Support

tvOS is supported since XCUITest driver bundled with Appium 1.13.0+

Warning Apple TV 4K is not supported because appium-ios-device library, that we use to support low-level communication with devices, only supports devices connected via USB.

Setup

You can run tests for tvOS by changing the platformName capability to tvOS like it is done below.

{
    "automationName": "XCUITest",
    "platformName": "tvOS", // here
    "platformVersion": "12.2",
    "deviceName": "Apple TV",
    ...
}

Note Make sure tvOS simulator exists in your simulator list if you would like to run your test on tvOS simulators, e.g. xcrun simctl list | grep "com.apple.CoreSimulator.SimRuntime.tvOS" command shows some results

Limitations

Gesture commands do not work for tvOS. Some commands such as pasteboard do not work as well.

We can handle focus on tvOS by simply pressing keys such as up/down/left/right/home. tvOS performs actions on the focused element. You can get the value of the focus attribute via Attributes API. Get active element API returns the focused element.

Basic Actions

pressButton and getting the focused element by get active element are basic actions for tvOS. Consider using wait methods since tvOS also has animation.

# Ruby
element = @driver.find_element :accessibility_id, 'element on the app'
# Returns true if the element is focused, otherwise false
element.focused #=> 'true'
# Appium moves the focus to the element by pressing the corresponding keys and clicking the element
element.click
# Get the app state
@driver.app_state('test.package.name') # => :running_in_foreground
# Press keys
@driver.execute_script 'mobile: pressButton', { name: 'Home' }
# Move focus and get the focused element
@driver.execute_script 'mobile: pressButton', { name: 'Up' }
# Get a focused element
element = @driver.switch_to.active_element
element.label #=> "Settings"

# Python
element = driver.find_element_by_accessibility_id('element on the app')
element.get_attribute('focused')
element.click()
driver.query_app_state('test.package.name')
driver.execute_script('mobile: pressButton', { 'name': 'Home' })
driver.execute_script('mobile: pressButton', { 'name': 'Up' })
element = driver.switch_to.active_element
element.get_attribute('label')

// Java
WebElement element = driver.findElementByAccessibilityId("element on the app");
element.getAttribute("focused");
element.click();
driver.queryAppState("test.package.name");
driver.executeScript("mobile: pressButton", ImmutableMap.of("name", "Home"));
driver.executeScript("mobile: pressButton", ImmutableMap.of("name", "Up"));
element = driver.switchTo().activeElement();
element.getAttribute("label");

// webdriver.io example
const element = $('~SomeAccessibilityId');
element.getAttribute('focused');
element.click();
driver.execute('mobile: pressButton', {name: 'Home'});
driver.execute('mobile: pressButton', {name: 'Up'});
const activeElement = driver.getActiveElement();
activeElement.getAttribute('label');

// WD example
const element = await driver.elementByAccessibilityId('element on the app');
await element.getAttribute('focused');
await element.click();
await driver.execute('mobile: pressButton', {name: 'Home'});
await driver.execute('mobile: pressButton', {name: 'Up'});
const activeElement = await driver.active();
await activeElement.getAttribute('label');

More actions

tvOS provides remote controller based actions. Appium provides Buttons actions via mobile: pressButton. These are menu, up/down/left/right, home, playpause and select. Available actions are enumerated in the error message if you send unsupported button name to the server.

Appium calculates up/down/left/right and select sequence automatically if the combination of find element/s and click is provided. You should not care about which keys should be pressed to reach an arbitrary element every time.

You can also handle setting a focus or starting/pausing a playback pressing button actions. menu button works as back for iOS context in tvOS.

Resources