feat: tvos 17+ workaround with `skipDeviceCheck` #2194

KazuCocoa · 2023-11-07T07:05:34Z

[update Mar 1st, 2024]

This skip device check would reduce device preparation time by 1 sec on my local test, so it may be good to add as part of performance improvement for a real device that manages devices on its own.

Note that commands that need to communicate with the device directly (usbmuxd) do not work. This is expected. This PR aims to make tvOS work over WDA at least while it may have issues with communication method not via WDA.

This is currently what we could do as a workaround for appium/appium#19343.

appium/appium#19343 (comment) is my findings for my local apple tv. xcodebuild itself did not work (was not able to find the network connected tvOS 17 device), thus the primary usage should be with webDriverAgentUrl

For tvOS 17+: necessary caps:

  "appium:skipDeviceCheck": true,
  "appium:skipLogCapture": true

btw, this skip reduces 1 sec or less's new session creation duration for real devices.
I wondered if this could be similar to appium:skipDeviceInitialization in uia2.

[Update Mar 23th]

Remove Frameworks/XC** framework from WebDriverAgentRunner_tvOS-Runner.app

$ xcrun devicectl device install --device 9DA168DB-A406-4350-A1AF-125411E55394 /Users/kazu/Library/Developer/Xcode/DerivedData/WebDriverAgent-ezumztihszjoxgacuhatrhxoklbh/Build/Products/Debug-appletvos/WebDriverAgentRunner_tvOS-Runner.app
$ xcrun devicectl device process launch --device 9DA168DB-A406-4350-A1AF-125411E55394 --activate --environment-variables '{"USE_PORT": "8100"}'  com.kazucocoa.WebDriverAgentRunner.xctrunner

Then, set "appium:webDriverAgentUrl": "http://192.168.5.0:8001" capability with this branch's caps. Then, we can start WDA without Xcode.

9DA168DB-A406-4350-A1AF-125411E55394 is identifier by xcrun devicectl list devices.
The path to WebDriverAgentRunner_tvOS-Runner.app is the result of Xcode. It is signed properly already, so it should be already confirmed the build works on a tvOS device.

mykola-mokhnach · 2023-11-07T12:37:11Z

To me it looks like we are just trying to workaround a xcodebuild bug. Perhaps, it has also to do with appium/appium#19381

Maybe it would be better to just wait for a fix from Apple rather then adding workarounds thus increasing the tech debt?

KazuCocoa · 2023-11-07T16:46:22Z

Yes, it's reasonable. Ideally, (and hopefully) Apple will expose udid to the macOS system wide as same as USB connected devices (as same as older tvOS versions such as 16).

Or at least once Apple fixes xcodebuild, we can also use this pr at least... (I know of this is actually not good idea)

mykola-mokhnach · 2023-11-07T19:35:33Z

I was thinking about doing something like

if (xcodeVersion.major === 17 && xcodeVersion.minor >= 0 && xcodeVersion.minor < 2 && isTvOS) {
  skipIdCheck;
  runXcodebuildWithoutId;
}

but even by having the above ugly workaround many other endpoints that work with udid would most likely fail

quidow · 2023-12-02T12:18:28Z

Hey, thank you so much for publishing this workaround, it literally saved the start of my project. I also wanted to mention one thing that I noticed, maybe you will find it helpful.
So if we go to Settings -> Remotes and Devices -> Remote App and Devices on the device with tvOS 17 installed, then it's IPv6 becomes available and I can see it in the idevice_id output. And as long as we stay on that screen, we can use its address as udid and Appium is able to establish a session without the workaround. But the issue is that as soon as we leave that screen, the device becomes unavailable again.

KazuCocoa · 2024-01-03T17:29:45Z

note: i wondered if we could get device info via WDA instead of host in some cases for webDriverAgentUrl usage for example. Maybe we checked device os version and a few we've got via appium-ios-device

adriandumitrascu19 · 2024-01-04T11:04:43Z

@KazuCocoa this workaround would work with a physical device ? I am currently blocked with 17.2 on my apple tv

KazuCocoa · 2024-01-04T18:01:55Z

This change itself yes, would work.

xcodebuild itself had an issue that could not find a wireless connected tvOS device.
appium/appium#19381 I haven't tested recent Xcode versions, but possibly even with this change, xcodebuild (Apple's command) itself won't work.

quidow · 2024-01-04T20:41:23Z

I don't really get what xcodebuild issue you are talking about.
I was able to automate the test session launch and run WDA on AppleTV 4K using this:

xcodebuild build-for-testing test-without-building -project WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner_tvOS -destination 'id={self.__device_udid}'

KazuCocoa · 2024-01-04T20:50:13Z

Then, you could use this branch with local installation.
https://appium.io/docs/en/2.4/cli/extensions/#install

e.g.

appium driver install --source=local /path/to/this/repository

which is regular usage of Appium v2

adriandumitrascu19 · 2024-01-08T09:01:21Z

@quidow are you able to start a session with the appium inspector on a physical device ?

quidow · 2024-01-08T09:09:31Z

@quidow are you able to start a session with the appium inspector on a physical device ?

No, in order to use Appium Inspector I need to run WDA first.

adriandumitrascu19 · 2024-01-08T09:32:59Z

@quidow Can you help me out please?

Run WDA first.
Open appium inspector but... I am not able to start a session with the physical because I receive the error: Failed to create session. An unknown server-side error occurred while processing the command. Original error: Unknown device or simulator UDID: '9ec9b7b0de4f70dbe2e6bb93d75e957ef047b711'

I am using:
appium 2.3.0
[email protected]
apple tv tvOS version 17.2
Xcode 15.1

quidow · 2024-01-08T10:25:44Z

@quidow Can you help me out please?

Run WDA first.

Open appium inspector but... I am not able to start a session with the physical because I receive the error: Failed to create session. An unknown server-side error occurred while processing the command. Original error: Unknown device or simulator UDID: '9ec9b7b0de4f70dbe2e6bb93d75e957ef047b711'

I am using: appium 2.3.0 [email protected] apple tv tvOS version 17.2 Xcode 15.1

Can you share your Appium capabilities?
Did you build and install Appium driver from this PR?

adriandumitrascu19 · 2024-01-08T10:52:46Z

@quidow Can you help me out please?

Run WDA first.

Open appium inspector but... I am not able to start a session with the physical because I receive the error: Failed to create session. An unknown server-side error occurred while processing the command. Original error: Unknown device or simulator UDID: '9ec9b7b0de4f70dbe2e6bb93d75e957ef047b711'

I am using: appium 2.3.0 [email protected] apple tv tvOS version 17.2 Xcode 15.1

Can you share your Appium capabilities?

Did you build and install Appium driver from this PR?

I have added the appium:skipDeviceCheck and set it to true
can you help please?

{
"platformName": "tvOS",
"appium:platformVersion": "17.2",
"appium:bundleId": "my-app",
"appium:automationName": "XCUITest",
"appium:noReset": true,
"appium:deviceName": "Apple TV 4K",
"appium:derivedDataPath": "/Users/adriandumitrascu/Library/Developer/Xcode/DerivedData/WebDriverAgent-atygjtlzhmclcddyzjqfzjhqdaoh",
"appium:udid": "9ec9b7b0de4f70dbe2e6bb93d75e957ef047b711",
"appium:skipDeviceCheck": "true"
}

checked out appium-xcuitest-driver
switched to this branch and pulled

quidow · 2024-01-08T11:23:44Z

@adriandumitrascu19 I see that you run WDA from this branch, but did you install the Appium driver from this branch as well?

Then, you could use this branch with local installation. https://appium.io/docs/en/2.4/cli/extensions/#install

e.g.
appium driver install --source=local /path/to/this/repository
which is regular usage of Appium v2

quidow · 2024-01-08T11:30:44Z

I have added the appium:skipDeviceCheck and set it to true but I am not familiar with the second solution proposed to use with appium:webDriverAgentUrl to avoid device communication. can you help please?

{
"platformName": "tvOS",
"appium:platformVersion": "17.2",
"appium:bundleId": "de.telekom.magenta.tv.PRODUCTION5",
"appium:automationName": "XCUITest",
"appium:noReset": true,
"appium:deviceName": "Apple TV 4K",
"appium:derivedDataPath": "/Users/adriandumitrascu/Library/Developer/Xcode/DerivedData/WebDriverAgent-atygjtlzhmclcddyzjqfzjhqdaoh",
"appium:udid": "9ec9b7b0de4f70dbe2e6bb93d75e957ef047b711",
"appium:skipDeviceCheck": "true"
}

checked out appium-xcuitest-driver switched to this branch and pulled

"appium:webDriverAgentUrl": "http://192.168.1.104:8100",
"appium:skipDeviceCheck": true,

192.168.1.104 - the local IP of my AppleTV
8100 - the default WDA port
"appium:skipDeviceCheck": true, - make sure that you set true as a boolean value, but not a string

adriandumitrascu19 · 2024-01-08T12:07:23Z

@adriandumitrascu19 I see that you run WDA from this branch, but did you install the Appium driver from this branch as well?
Then, you could use this branch with local installation. https://appium.io/docs/en/2.4/cli/extensions/#install
e.g.
appium driver install --source=local /path/to/this/repository

regular usage of Appium v2

quidow · 2024-01-08T15:29:12Z

@adriandumitrascu19 so now it works?

adriandumitrascu19 · 2024-01-08T15:32:03Z

@adriandumitrascu19 so now it works?

so with the actual setup (from above) I am able to start the appium session only if I remove the appium:bundleId. I can then start my app and inspect the elements but if I want to run a test suite that needs the bundleId it is not working. Any thoughts ?

adriandumitrascu19 · 2025-01-13T09:41:21Z

Please use the capabilities described in this PR's description

So I need to have appium-xcuitest-driver set to tvos-ios17-workaround2 branch ?
I need to modify the following caps ?
a. appium:forceAppLaunch?
b.appium:useNativeCachingStrategy?
c. appium:appLaunchStateTimeoutSec?
d. appium:skipDeviceCheck?

Much appreciated if you can help me.

Unfortunately npm install fails...

adriandumitrascu19 · 2025-01-13T10:11:38Z

npm install fails with the latest updates in this branch.

yes, it fails

KazuCocoa · 2025-01-14T06:59:57Z

Yes.
Please check the description. So far, I only addressed two capabilities below:

  "appium:skipDeviceCheck": true,
  "appium:skipLogCapture": true

Our CI and my local succeeded in running npm install and link with --source=local. Please attach your error as GIST (to not spam comments)

adriandumitrascu19 · 2025-01-16T10:39:38Z

Yes.

Please check the description. So far, I only addressed two capabilities below:
  "appium:skipDeviceCheck": true,
  "appium:skipLogCapture": true
Our CI and my local succeeded in running npm install and link with --source=local. Please attach your error as GIST (to not spam comments)

https://gist.github.com/adriandumitrascu19/be5e3bfff52d2d9c19d99b7bd3980d4f
Please help :( npm install - worked

KazuCocoa · 2025-01-17T07:33:55Z

ah, ok. As the primary usage should be with webDriverAgentUrl in this description, you should use webDriverAgentUrl https://appium.github.io/appium-xcuitest-driver/latest/guides/attach-to-running-wda/
Then, WDA itself should be running on the device since xcodebuild command itself doesn't work to run Appium/WDA against a TV device.

adriandumitrascu19 · 2025-01-22T10:34:33Z

Hello @KazuCocoa I have left a new comment in my GIST, please help :(

ntsikelel0 · 2025-04-11T14:57:13Z

Hi @KazuCocoa @mykola-mokhnach @adriandumitrascu19 @quidow @Jiyvn, hope you guys are well.

I just wanted to share that I’ve finally managed to launch my app and successfully run tests on a physical Apple TV device using Appium.

Sequence of events:

Initially, I couldn’t launch the app using either Appium Inspector or my test project in IntelliJ.
I then added the capabilities mentioned in this comment: feat: tvos 17+ workaround with skipDeviceCheck #2194 (comment) to both setups.
After that, I was able to launch the app via Appium Inspector. However, launching via IntelliJ still threw errors.
The workaround that finally worked:
- First launch the app manually using Appium Inspector.
- Once the app is successfully launched via Inspector, run the tests from IntelliJ, and it works!

My setup:
Apple TV
tvOS: 18.3 (22K577)
Model: Apple TV 4K (2nd generation)
Capacity: 32 GB

Appium version: 2.17.1
XCUITest driver version: 7.35.1

Xcode version: 16.0 (16A242d)

Please note I did not clone any repos or switch to specific branches as some suggestions in this thread recommend.
I simply used the Appium and xcuitest driver versions available via npm, I suppose production versions, and it worked as is with the capabilities below.

Working Capabilities:

Appium Inspector
{
"platformName": "tvOS",
"appium:automationName": "XCUITest",
"appium:udid": "<YOUR_UDID>",
"appium:bundleId": "com.example.bundleid",
"appium:platformVersion": "18.3",
"appium:showXcodeLog": true,
"appium:skipDeviceCheck": true,
"appium:skipLogCapture": true
}

IntelliJ (Java Project)
DesiredCapabilities capabilities = new DesiredCapabilities();
capabilities.setCapability("platformName", "tvOS");
capabilities.setCapability("automationName", "XCUITest");
capabilities.setCapability("app", System.getProperty("user.dir") + "/path/to/your/app");
capabilities.setCapability("clearSystemFiles", true);
capabilities.setCapability("autoAcceptAlerts", true);
capabilities.setCapability("noReset", false);
capabilities.setCapability("platformVersion", "18.3");
capabilities.setCapability("deviceName", "Apple TV 4K (2nd generation)");
capabilities.setCapability("udid", "<YOUR_UDID>");
capabilities.setCapability("xcodeOrgId", "<YOUR_ORG_ID>");
capabilities.setCapability("xcodeSigningId", "<YOUR_SIGNING_ID>");
capabilities.setCapability("useNewWDA", true);
capabilities.setCapability("showXcodeLog", true);
capabilities.setCapability("appium:skipDeviceCheck", true);
capabilities.setCapability("appium:skipLogCapture", true);

Hope this helps.

adriandumitrascu19 · 2025-10-10T08:16:13Z

@KazuCocoa can you merge master into this branch ? Thannnk you

adriandumitrascu19 · 2025-10-23T10:30:11Z

@KazuCocoa @ntsikelel0 hello guys, do you know, with latest appium, xcuitest, xcode 26. we still need to use this workaround ?
Thank you

KazuCocoa · 2025-10-23T21:51:23Z

I haven't tested, but does xcodebuild CLI command succeed in building/installing the WDA onto a TV without Xcode UI tool?
If yes, this might not be necessary

quidow · 2025-10-23T22:30:44Z

If I remember it correctly, the main issue was that the idevice_id from libimobiledevice doesn't work with AppleTV since the Wi-Fi protocol was changed... Thus it was an error that Appium doesn't see a connected device.

KazuCocoa · 2025-10-23T22:58:26Z

The primary reason in terms of TV is xcodebuild. xcodebuild itself cannot find network-connected devices for tvOS 17+. If WDA is available over the network, at least webDriverAgentUrl will help - it still needs some small adjustment, though.

adriandumitrascu19 · 2025-10-24T07:05:41Z

@KazuCocoa @quidow
Thanks a lot for the quick replies 🙏

I’ve been testing this setup in detail: Xcode 26.0.1 + tvOS 18.2 + Appium 3.1.0 (XCUITest 10.2.2).

From what we observed:
• xcodebuild test from CLI successfully builds and installs WebDriverAgentRunner_tvOS on the Apple TV (so the CLI path itself works).
• However, when using the official Appium XCUITest driver, the device is not detected — Appium throws
Unknown device or simulator UDID / Could not determine iOS SDK version.
• With the custom driver from the tvos-ios17-workaround2 branch (based on this PR’s CoreDeviceService work), Appium can detect and attach to the Apple TV without issues.

It seems the detection part still depends on the CoreDeviceService API, especially for wireless-paired Apple TVs, since the UDID is hidden from libimobiledevice.

Do you think it would make sense to integrate the CoreDeviceService path conditionally for tvOS 18 / Xcode 26 in the main driver, while keeping legacy detection for iOS devices?

I’d be happy to share logs if that helps confirm where the detection breaks — just let me know what scenarios you’d like me to try.

KazuCocoa · 2025-10-24T13:30:22Z

If xcodebuild works, I think it is reasonable to extend webDriverAgentUrl. It will skip some checking also like skipDeviceCheck does. Users will need to run WDA via xcodebuild.

Then, we can re-visit the for tvOS behavior since pre-condition changed so much

KazuCocoa · 2025-11-03T16:32:58Z

appium xcuitest driver 10.4.2+ with APPIUM_XCUITEST_PREFER_DEVICECTL environment variable would help without this PR (we guess)
#2648

KazuCocoa added 6 commits November 1, 2023 21:59

chore: add workaround

9e77d9f

chore: always return true

efb3ff9

chore: add caps

206235d

docs: tweak

e128d07

docs: add note

b881822

Merge branch 'master' into tvos-ios17-workaround2

21a3924

KazuCocoa requested review from jlipps and mykola-mokhnach November 7, 2023 07:06

KazuCocoa marked this pull request as draft November 8, 2023 08:33

Merge branch 'master' into tvos-ios17-workaround2

9a51048

chore: do not check the installed app

143cfb5

Merge branch 'master' into tvos-ios17-workaround2

bf9e95c

KazuCocoa added 2 commits January 24, 2025 11:46

update the option handling

ca7003b

Merge branch 'master' into tvos-ios17-workaround2

2feafa0

KazuCocoa added 2 commits April 13, 2025 22:30

Merge branch 'master' into tvos-ios17-workaround2

f8815a5

Merge branch 'master' into tvos-ios17-workaround2

82de69a

KazuCocoa removed request for jlipps and mykola-mokhnach May 29, 2025 07:41

KazuCocoa added 2 commits May 29, 2025 00:42

Merge branch 'master' into tvos-ios17-workaround2

8b51d89

Merge branch 'master' into tvos-ios17-workaround2

ca73574

KazuCocoa added 2 commits October 10, 2025 08:26

Merge branch 'master' into tvos-ios17-workaround2

6aa6c0f

Merge branch 'master' into tvos-ios17-workaround2

f0db281

Merge branch 'master' into tvos-ios17-workaround2

4b7bbf8

KazuCocoa changed the title ~~feat: tvos 17 workaround with skipDeviceCheck~~ feat: tvos 17+ workaround with skipDeviceCheck Oct 24, 2025

mykola-mokhnach mentioned this pull request Nov 2, 2025

fix: Use devicectl while listing available device udids #2648

Merged

Merge branch 'master' into tvos-ios17-workaround2

f77c540

Uh oh!

feat: tvos 17+ workaround with skipDeviceCheck #2194

Are you sure you want to change the base?

feat: tvos 17+ workaround with skipDeviceCheck #2194

Conversation

KazuCocoa commented Nov 7, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mykola-mokhnach commented Nov 7, 2023

Uh oh!

KazuCocoa commented Nov 7, 2023

Uh oh!

mykola-mokhnach commented Nov 7, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

quidow commented Dec 2, 2023

Uh oh!

KazuCocoa commented Jan 3, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

adriandumitrascu19 commented Jan 4, 2024

Uh oh!

KazuCocoa commented Jan 4, 2024

Uh oh!

quidow commented Jan 4, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

KazuCocoa commented Jan 4, 2024

Uh oh!

adriandumitrascu19 commented Jan 8, 2024

Uh oh!

quidow commented Jan 8, 2024

Uh oh!

adriandumitrascu19 commented Jan 8, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

quidow commented Jan 8, 2024

Uh oh!

adriandumitrascu19 commented Jan 8, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

quidow commented Jan 8, 2024

Uh oh!

quidow commented Jan 8, 2024

Uh oh!

adriandumitrascu19 commented Jan 8, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

quidow commented Jan 8, 2024

Uh oh!

adriandumitrascu19 commented Jan 8, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

adriandumitrascu19 commented Jan 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

adriandumitrascu19 commented Jan 13, 2025

Uh oh!

KazuCocoa commented Jan 14, 2025

Uh oh!

adriandumitrascu19 commented Jan 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

KazuCocoa commented Jan 17, 2025

Uh oh!

adriandumitrascu19 commented Jan 22, 2025

Uh oh!

ntsikelel0 commented Apr 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

adriandumitrascu19 commented Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

adriandumitrascu19 commented Oct 23, 2025

Uh oh!

KazuCocoa commented Oct 23, 2025

Uh oh!

quidow commented Oct 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

feat: tvos 17+ workaround with `skipDeviceCheck` #2194

feat: tvos 17+ workaround with `skipDeviceCheck` #2194

KazuCocoa commented Nov 7, 2023 •

edited

Loading

mykola-mokhnach commented Nov 7, 2023 •

edited

Loading

KazuCocoa commented Jan 3, 2024 •

edited

Loading

quidow commented Jan 4, 2024 •

edited

Loading

adriandumitrascu19 commented Jan 8, 2024 •

edited

Loading

adriandumitrascu19 commented Jan 8, 2024 •

edited

Loading

adriandumitrascu19 commented Jan 8, 2024 •

edited

Loading

adriandumitrascu19 commented Jan 8, 2024 •

edited

Loading

adriandumitrascu19 commented Jan 13, 2025 •

edited

Loading

adriandumitrascu19 commented Jan 16, 2025 •

edited

Loading

ntsikelel0 commented Apr 11, 2025 •

edited

Loading

adriandumitrascu19 commented Oct 10, 2025 •

edited

Loading

quidow commented Oct 23, 2025 •

edited

Loading