Core Initialization and Configuration

The framework begins with a central controller class that wraps standard WebDriver instances. Rather than instantiating drivers internally, this design expects an already configured driver object to be passed during construction. This promotes loose coupling and easier testing. Key configuration parameters include a strategy registry for locators, a blocklist for intercepting unwanted pop-ups, a session timestamp for logging, and a global wait duration.

from datetime import datetime
from appium.webdriver.common.appiumby import AppiumBy

class AutomationController:
    def __init__(self, web_driver_instance) -> None:
        self.driver = web_driver_instance
        self.locator_registry = AppiumBy
        self.blocklist_interceptors = []
        self.session_start_time = datetime.now().strftime("%Y%m%d%H%M%S")
        self.default_wait_duration = 20

Element Discovery Routines

All locator methods prioritize resilience against UI obstructions. When a standard lookup fails, the system automatically checks for elements defined in the blocklist before raising a failure exception.

Single Element Retrieval

Searches the layout for the first matching target. If obscured by a modal, it attempts to clear the blocklist first.

• strategy: Locator type (e.g., ID, XPATH, ACCESSIBILITY_ID)
• query: Selector string Returns the first matched node.

Mandatory Presence Polling

Continuously polls the page until the target appears in the layout tree.

• strategy: Locator type
• query: Selector string

Scroll-Until-Visible Search

Attempts location, then scrolls by predefined offsets until the node renders or the timeout expires.

• strategy: Locator type
• query: Selector string
• start_point: Tuple of (x, y) scroll origin
• end_point: Tuple of (x, y) scroll destination

Mandatory Disappearance Polling

Waits until a previously visible element detaches from the DOM.

• strategy: Locator type
• query: Selector string

Batch Lookup

Collects all matching nodes into a list. Unlike strict finders, this returns an empty array rather than crashing if nothing matches. Blocklist clearance is attempted first to rule out overlay interference.

• strategy: Locator type
• query: Selector string

Interaction and Manipulation Commands

These routines handle user gestures and data entry while accounting for view state changes.

Attribute Extraction

Fetches a specific property value from the first matched node.

• strategy: Locator type
• query: Selector string
• prop_name: Target attribute key

Smart Click Execution

Validates clickability before proceeding. If the clickable property evaluates to false, it falls back to coordinate-based tapping. Standard HTML nodes lacking this property bypass the check and trigger a native click event.

• node: Resolved WebElement instance

Sequential Multi-Tap

Iterates through a collection of locator tuples and activates each target in order.

• targets: List of (strategy, query) pairs

Coordinate Tapping

Simulates a direct touch input at exact screen coordinates.

• x_val: Horizontal position
• y_val: Vertical position

Text Injection

Inputs characters directly into a form field. Includes automatic overlay handling to prevent blocking inputs from failing mid-stream.

• node: Target enput field
• input_data: String payload

Viewpotr and Context Management

Controls navigation states and exports diagnostic data.

DOM Snapshot Export

Dumps the current render tree to a specified file path. Directories are created automatically if missing.

• output_path: Target file location

Screen Capture

Saves a PNG screenshot of the current viewport. Auto-creates parent directories.

• output_path: Target file location

Context Swapping

Shifts focus to the most recently activated frame or application context.

Advanced Gesture and Navigation Features

Complex Path Swiping

Executes multi-point swipe gestures using absolute coordinates. Requires native views; ineffective within web containers.

• trajectory_points: List of (x, y) checkpoints defining the cursor path. The driver interpolates between points to simulate finger movement.

URL Navigation

Loads a remote address. Restricted to mobile browser contexts; unsupported in hybrid webviews or native screens.

• target_url: Valid HTTP/HTTPS endpoint

Browser Configuration Notes When automating mobile browsers, Capabilities must explicitly define:

• browserName: Target browser engine (e.g., Browser, Chrome)
• chromedriverExecutableDir: Directory housing version-specific ChromeDriver binaries. Mobile environments require tailored drivers due to OS fragmentation. Setting this overrides the system default lookup path.
• showChromedriverLog: Boolean flag to dump low-level driver tracebacks for debugging.

Tab Switching

Redirects execution flow to the newest opened window or tab.

Internal Utility Functions

Private helpers designed to standardize routine operations. Direct invocation is discouraged.

Bounding Box Calculator

Computes the geometric center of a resolved node and returns it as an (x, y) tuple. Essential for fallback tap actions when standard click events fail.

• node: Resolved element

Input Chain Builder

Instantiates W3C-compliant action chains with specified interaction modes. Wraps underlying protocol calls. Enable raw W3C execution by setting use_w3c_protocol=True.

• interaction_mode: Input type selector
• use_w3c_protocol: Boolean flag for underlying protocol access

Randomized Delay

Pauses execution for a random interval between 0 and default_wait_duration.

Scroll Visibility Handler

Orchestrates the logic behind scroll-until-visible searches. Combines explicit waits with iterative coordinate shifts.

• strategy: Locator type
• query: Selector string
• start_point: Scroll origin tuple
• end_point: Scroll destination tuple

Overlay Interception Decorator

Automatically detects and dismisses blocklisted pop-ups before executing a primary action. If a NoSuchElementException occurs, the decorator scans for blocklisted nodes. If none exist, the original exception propagates.

Integration Pattern

The package distributes via PyPI. After verifying the Appium server lifecycle, install using:

pip install appium-oc

Implementation typically involves extending the base controller to inherit its method pool:

from appium_oc.controller import AutomationController

class TestSuiteBase(AutomationController):
    def __init__(self, driver_config=None):
        super().__init__(driver_config)

Diagnostic and Environment Tools

• WebView Inspection: Requires explicit context attachment before inspecting HTML structures embedded in native apps.
• Client-Side Logging: Captures execution stack traces and Python-side warnings during script runtime.
• Server Trace Collection: Route daemon outputs to console and persistent storage simultaneously:

  appium --log <path/to/output.log> 2>&1 | tee -a <path/to/output.log>
  

• Device Log Streaming: Filter Appium-related device streams:

  adb logcat | grep -i appium
  

• Emulator Management:
  • List registered virtual devices: emulator -list-avds
  • Launch specific instance: emulator -avds <device_profile_name>