> For the complete documentation index, see [llms.txt](https://docs.qapilot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qapilot.io/detailed-documentation/test-plan-executions/cross-os-execution-guidelines-android-ios.md).

# Cross OS Execution Guidelines (Android ↔ iOS)

To ensure accurate issue reporting and reduced false failures during Cross-OS execution, here are a set of checks that help teams debug in a structured manner 

### 1. Verify Application Behaviour

* Confirm that the application behaviour is functionally equivalent on both Android and iOS.
* Certain flows, UI elements, navigation patterns, and interactions may differ across platforms by design.
* Validate that the expected iOS behavior aligns with the intended implementation before proceeding with further investigation.

### 2. Check Element Identification Changes

* If a step executes successfully on Android but fails on iOS, verify whether any recent application changes have impacted:
  * Accessibility identifiers
  * Element attributes
  * UI hierarchy or structure
  * Element visibility or interaction patterns
* Confirm with the development team whether platform-specific UI updates were introduced.
* Update the locator or re-record the affected step if required.

### 3. Coordinate-Based Taps

* Steps recorded using Tap by Coordinates may behave differently across Android and iOS due to differences in:
  * Screen resolutions
  * Device dimensions
  * UI layouts and scaling
* For such failures:
  * Verify whether the target element can be interacted with directly on iOS.
  * Re-record the step for iOS if necessary.
  * Maintain platform-specific actions when required.

### 4. Android "Go Back" Keyword Handling

* The Go Back keyword is supported on Android but is not supported on iOS.
* For steps using Go Back:
  * Retain the existing Android step and configure its Step State as Android.
  * Add an equivalent iOS navigation step and configure its Step State as iOS.
* During execution:
  * Android executes only the Android-specific step.
  * iOS skips the Android step and executes the iOS-specific navigation step.

### 5. Platform-Specific Step Management

* When a workflow requires different actions across platforms:
  * Create separate Android and iOS steps.
  * Configure the appropriate Step State (Android/iOS).
  * Avoid modifying a working Android step when the issue is isolated to iOS.
* This approach improves maintainability and prevents regressions in platform-specific flows.

### 6. iOS Page Object and Element Mapping Enhancements

During Android → iOS Cross-OS execution:

* The iOS page object (XPath and associated element attributes) is stored in the database only when the corresponding step executes successfully.
* If a step fails before element mapping is completed, the iOS locator information may not be available for review or maintenance.
* Swipe behavior may vary between Android and iOS due to differences in device resolutions, screen sizes, and UI layouts. As a result, additional swipe actions or platform-specific steps may be required to ensure consistent execution.
* For Cross-OS execution, AI is used to generate iOS XPaths from the Android recording. Therefore, AI will still be invoked for XPath generation even if AI Healing is disabled at the step level. If AI is to be completely bypassed for a specific step, set the step attribute `disable_autohealing = T`

Following these guidelines will help minimize false failures, streamline issue investigation, and improve Cross-OS execution reliability across Android and iOS platforms.