How to run one Appium test on Android and iOS without forking your framework

Your Appium framework runs on Android. Every screen object uses @AndroidFindBy. Point it at an iOS simulator and AppiumFieldDecorator finds no annotations it recognizes — every field stays null, and the session dies before it touches an element.

The reflex is to build a second iOS suite. You don't need one.

AppiumFieldDecorator reads two locator annotations on the same field — @AndroidFindBy and @iOSXCUITFindBy — and resolves the one matching the active driver type at runtime. The Android annotation is read by an AndroidDriver; the iOS annotation by an IOSDriver. The other is skipped.

The article walks through:

One concrete detail: most fields reuse the same accessibility ID across both platforms, so the iOS annotation is often a verbatim copy of the Android one. The work isn't rewriting locators — it's identifying the few elements that truly differ.