Edit this Doc tvOS support


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

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

Tips to build WDA for tvOS - Update to the latest Carthage - Be 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" shows results - Newer Carthage raises an error like Could not find any available simulators for tvOS if tvOS simulators do not exist in tvOS build


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.

WebElement element = driver.findElementByAccessibilityId("element on the app");
driver.executeScript("mobile: pressButton", ImmutableMap.of("name", "Home"));
driver.executeScript("mobile: pressButton", ImmutableMap.of("name", "Up"));
element = driver.switchTo().activeElement();
element = driver.find_element_by_accessibility_id('element on the app')
driver.execute_script('mobile: pressButton', { 'name': 'Home' })
driver.execute_script('mobile: pressButton', { 'name': 'Up' })
element = driver.switch_to.active_element
// webdriver.io example
const element = $('~SomeAccessibilityId');
driver.execute('mobile: pressButton', {name: 'Home'});
driver.execute('mobile: pressButton', {name: 'Up'});
const activeElement = driver.getActiveElement();

// 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');
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
# 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"

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.

Test Running Environment