Find deeply nested elements in iOS

Learn how to use the grid sampling feature to find and interact with deeply nested UI elements in iOS apps that standard methods can’t reach.

When you run Appium tests on iOS apps, you might get NoSuchElementException errors, even for elements visible on the screen. This issue often appears in apps with complex view structures, like those built with React Native, and happens because of a limitation in how Appium can access the app’s UI hierarchy.

This guide explains why this happens and how to fix it using our grid sampling feature.

Issue

Your Appium tests fail to find or interact with certain UI elements and throw a NoSuchElementException error, even though the elements are present on the screen.

Cause

This issue stems from a constraint within Apple’s native XCTest framework, sometimes called the 62-level wall. Standard automation methods can’t locate UI elements nested too deeply within the application’s view hierarchy. When Appium requests the page source, the underlying framework doesn’t return these deeply nested elements, making them invisible to your test script.

Resolution

To fix this, you need to enable the grid sampling feature. Instead of relying on the standard page source, this feature divides the screen into a grid and performs targeted searches at each grid point. This allows it to discover elements beyond the typical depth limit.

You can enable grid sampling either when you start a session or during a running test.

Enabling at session start

To activate grid sampling from the beginning of your test session, add the appium:bstackPageSource capability to your test configuration.

Example:

Enable or update during a session

Use the appium:updateSettings command to enable grid sampling or modify its settings during a running test. This is useful if you only need the feature for specific parts of your test.

Example:

Recommended values

To get the best results with grid sampling, use the following settings:

• samplesX & samplesY: Set both values to 15. This provides a good balance between element detection and performance. Using much higher values may slow down command response times.
• maxDepth: Set this value between 75 and 100. This parameter has a minimal impact on performance, so a higher value is safe to use.