+
+
+
+
+
+
+
+
+
+
+
+
+ Elements Lookup Troubleshooting
+
+This article helps to resolve possible issues that may pop up while looking up for elements with XCUITest driver,
+where the desired element is either not found or not visible in the page source at all.
+Since there might be multiple reasons to why an element cannot be found the topic is divided into sections where
+each section contains visible symptoms with the list of their possible resolutions.
+Symptom #1
+The desired element is shown as part of a bigger container and is not distinguishable in the page source tree.
+Sometimes the whole application view with all elements in it is visible as one single container.
+Resolutions To Symptom #1
+Make sure the application under test is accessible
+The XCUITest driver is based on Apple's XCTest framework. And the latter uses the information provided by the system
+accessibility framework to interact with on-screen elements, and to distinguish them. The same approach is used by
+various screen readers, VoiceOver, etc. You may start your journey into what Accessibility is and how to deal
+with it in your applications from the official
+Apple's accessibility guideline.
+Bear in mind, that this tutorial only describes apps based on official Apple frameworks, like UIKit or SwiftUI. If you
+use a different framework to build the application's user interface, for example
+React Native, then consider looking for framework-specific accessibility guidelines.
+It is also possible that the source tree displayed in Xcode accessibility inspector differs from the tree geneerated
+by XCTest. The best possible way to verify the page source generated by the latter is to check the output of the
+debugDescription attribute
+of the corresponding XCUIApplication element. XCUITest driver allows to perform a direct forwarding for this API by
+using the mobile: source execute method with format set
+to description.
+Check if this is a hybrid application
+Hybrid applications are applications that use
+web views in order to represent
+their whole user interface or portions of it.
+Web views is the technology that allows to seamlessly integrate web pages browsing experience
+into native mobile applications. Applications might contain native views mixed with web views, or the whole
+application UI might be just a single web view. And while the built-in web view engine allows limited accessibility
+interactions via ARIA attributes, consider
+switching a driver context instead in order to get full native access to the page DOM.
+Read Automating Hybrid Apps for more details there.
+Make sure the application accessibility tree is not too deep
+Apple's XCTest represents the page source as hierarchical structure (a tree), where each UI element has ancestor and
+descendant relationships to other elements. There are applications having complex UI structure with deeply nested
+views. Such deep structures are known to create problems for XCTest as the latter is unable to work with tree elements
+whose nesting level is deeper than 62. This limitation has to do with how NSDictionary works and cannot be worked
+around. The default maximum nesting level for the XCUITest driver is set to 50 and could be customized by the
+snapshotMaxDepth setting.
+React Native is known to create
+such deep hierarchies and the only viable solution for now is to fix the application
+under test by flattening nested views. Check the corresponding issue
+for more details.
+Deeply nested hierarchies might also be the reason for the element lookup slowness. Read the Diagnosing WebDriverAgent Slowness article to troubleshoot the latter.
+Make sure a valid active application is selected in WebDriverAgent
+Sometimes, even if visually it looks like UI elements belong to the same application, they are referenced by
+absolutely different apps. Moreover, the operating system
+may change elements ownership in different versions. In the UI inspector it looks like visually the element
+is visible, but no "real" accessibility control relies on it. Most frequent candidates for such behavior are:
+- System alerts, for example camera or geolocation permission requests
+- Quick access toolbars, for example the one where Wi-Fi or Bluetooth state could be changed
+- Various RPC sheets, for example the Share To collection
+WebDriverAgent is designed the way it only interacts with a single app hierarchy at the particular
+moment of time. Such application is called active.
+It is possible to switch between applications in runtime using
+mobile: activateApp API or
+to provide a hint for WebDriverAgent on which application to prefer if multiple apps are running
+using the defaultActiveApplication setting.
+Check the Troubleshooting guide and/or
+Switching Between iOS Apps During a Test
+article for more details on how to make such elements available.
+Symptom #2
+The desired element is shown in the page tree, but cannot be found if looked up from an automated test.
+Resolutions To Symptom #2
+Make sure there is no race condition
+Sometimes the automation might too fast or too slow depending on in which state the UI is while the lookup is being
+executed. If it is too fast then consider using lookup timers, e.g. repeat the findElement more than once until
+either the element is found or the timeout occurs. All clients have convenience wrappers for such timers in form of
+expected conditions.
+If the automation is too slow, e.g. the desired element disappears faster than findElement could detect its presence
+then make sure your script is optimized for the maximum performance, e.g. optimal/fast element locators are used,
+the application itself and driver settings are adjusted to perform optimally, etc.
+There might be situations where the automation framework is already optimized, although the desired element is
+a short-living one, for example some notification popup that only appears for a second and then is immediately hidden.
+For such "special" elements consider using approaches different from findElement, for example post-test video recording analysis (video FPS should usually be enough to catch all short-living elements), or introducing special
+application debug settings to change the behavior for such elements and make them stay visible for longer time, or
+using non-UI-related assertions, like logs analysis or direct API calls.
+Make sure the debug environment matches to the testing one
+There are known cases where application interface/behavior might differ in simulators and real devices. It might even differ
+if the screen size or device model/OS version/system setting differs. That is why always make sure your debug
+environment, for example one where Appium Inspector is used,
+is as close as possible to the environment where automated tests are being executed.
+Symptom #3
+The desired element is shown in the page tree, but its property value is not as expected, for example, it
+is shown as visible while one does not see it in the application interface or vice versa.
+Resolutions To Symptom #3
+XCUITest driver has minimum influence to attribute values
+This is a simple and at the same time complicated topic. Since XCUITest driver is based on Apple's XCTest,
+all attribute values are retrieved from the latter. Standard attributes provided by XCTest could be found in
+XCUIElementAttributes
+protocol reference. The full list of attributes supported by XCUITest driver's WebElement
+could be found in the Element Attributes document.
+Most of the above attributes are simple compilations of standard attributes, for example, elementType is
+translated to type by matching the corresponding
+enum value to a string representation, name is compiled from original element's identifier and label depending on what is
+present first. The full list of mapping rules between standard and XCUITest attribute values could be found in
+WebDriverAgent sources.
+Although, some attributes there, like visible or accessible have no direct mapping in XCTest
+and are retrieved directly from the accessibility framework ~~using dark magic~~.
+This means the actual value of these attributes only depends on accessibility internals and is there
+mostly due to ~~legacy~~ convenience purposes, as the original XCTest does not even expose them.
+We'd love to deprecate and remove this legacy burden and only rely on officially supported attributes,
+although historically many people rely on them, so we keep it, even though their values might
+be not reliable and there is no good way to debug this behavior or somehow influence it.
+The final recommendation there would be:
+- If the value of an attribute that directly or indirectly relies on a public XCUIElement attribute
+ is different from what you expect then run a vanilla XCTest with the same app and make sure
+ it's not the same as you see in the XCUITest driver. If it is then the only place to complain
+ would be the Apple support forum or a XCTest bug tracker. If you can confirm the issue lies in
+ WebDriverAgent's mapping logic then feel free to raise an
+ issue to its maintainers.
+- If the value of an attribute that is a "custom" XCUITest attribute, like visible or accessible,
+ is different from what you expect then we, most likely, won't be able to help you. You may try
+ to improve the corresponding WebDriverAgent sources, but keep in mind there are many automation
+ tests around that rely on the current way these attributes are calculated, and we probably don't
+ want to break them.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+