UIKit

Black-box testing for UIKit via the accessibility layer. Use accessibilityLabel for text and accessibilityIdentifier (gold standard) for id selectors.

Maestro provides native, transparent support for iOS applications built with UIKit. Operating at the visual interaction layer rather than the implementation layer, Maestro interacts with rendered UI components regardless of underlying class hierarchies such as UIButton, UITableView, and UILabel.

Technical advantages

• Zero Instrumentation: Maestro does not require test libraries, delegates, or ViewController exposure. You test the built .app binary, nothing else.

• Implementation Agnostic: Because Maestro validates user-facing features rather than internal code, you can refactor UIKit components to SwiftUI without breaking your tests, provided the visual output remains consistent.

• Black-Box Model: Maestro adopts an arm's length approach, simulating authentic user interactions with the rendered UI without needing access to internal source code.

Element interaction strategies

Maestro interacts with UIKit components by simulating authentic user interactions through the accessibility layer.

Interacting with views by text

Primary interaction in UIKit is often done via visible UI text. Any view with text content (like a UIButton title) can be targeted directly.

// In your UIKit Swift code
let button = UIButton()
button.setTitle("Submit Order", for: .normal)

You can tap this button in your Flow using the visible text:

- tapOn: "Submit Order"

Using accessibility labels and IDs

For non-textual elements like icons, or for disambiguating duplicate elements, leverage iOS accessibility metadata. Maestro translates these properties into specific selectors:

• accessibilityLabel: Maestro translates this to the text selector.

• accessibilityIdentifier: Maestro translates this to the id selector. This is the gold standard for reliable tests.

// In your UIKit Swift code
let button = UIButton()
button.accessibilityIdentifier = "login_button_id"

The corresponding tap command in your Flow would use the id:

- tapOn:
    id: "login_button_id"

Handling lists and complex components

Maestro abstracts away the complexity of coordinate calculations and cell enumeration in UITableView and UICollectionView.

Intelligent scrolling

Instead of manual index or offset calculations, use scrollUntilVisible. Maestro combines visibility detection with continuous swiping to find elements that are currently off-screen.

- scrollUntilVisible:
    element:
        text: "List Item 50"
    direction: DOWN

Known limitations

• Simulators: Full support for local execution on iOS Simulators.

• Physical Devices: Executing tests on physical iOS devices is not supported yet.

Next steps

If you don't know how to create tests with Maestro, access the QuickStart guide to get up and running in minutes.

To learn how to create tests, refer to the Flows documentation. If you want to explore Maestro solutions, consult the appropriate documentation:

• Maestro Studio

• Maestro CLI

• Maestro Cloud