How to Configure Appium for Mobile Testing with Ocaramba: A Complete Guide

To configure Appium for mobile testing with Ocaramba, populate the Appium-specific keys in appsettings.json, set "browser": "Appium" to trigger the mobile driver branch, and inherit from ProjectTestBase to receive a fully initialized AndroidDriver or IOSDriver.

Ocaramba is an open-source .NET test automation framework developed by Accenture that unifies Selenium WebDriver execution across web and mobile platforms. When you configure Appium for mobile testing with Ocaramba, you tap into the framework's DriverContext architecture, which handles driver lifecycle management, context switching, and configuration binding without requiring custom boilerplate code.

Configuring Appium Settings in appsettings.json

All Appium-specific values are read from the appSettings section of your project's appsettings.json file. The BaseConfiguration class in OcarambaLite/BaseConfiguration.cs exposes static properties that map directly to these JSON keys, including AppiumPlatformName, AppiumDeviceName, AppiumAppPath, and AppiumServerUrl.

A minimal configuration for Android testing looks like this:

{
  "appSettings": {
    "protocol": "http",
    "host": "Appium",
    "browser": "Appium",
    "AppiumPlatformName": "Android",
    "AppiumDeviceName": "emulator-5554",
    "AppiumAppPath": "/path/to/your/app.apk",
    "AppiumAppPackage": "com.example.myapp",
    "AppiumAppActivity": ".MainActivity",
    "AppiumServerUrl": "http://127.0.0.1:4723/",
    "AppiumAutomationName": "UiAutomator2",
    "chromedriverExecutable": "./path/to/chromedriver"
  }
}

The browser key must be set to "Appium" to trigger the mobile driver initialization path in DriverContext. The framework supports both Android and iOS platforms by reading the AppiumPlatformName value and instantiating the appropriate driver type at runtime.

Driver Initialization with StartAppium

When the test runner requests a browser instance, DriverContext.StartBrowser evaluates the configuration and routes to StartAppium() when "browser": "Appium" is detected. Located in OcarambaLite/DriverContext.cs at lines 761-808, this method constructs an AppiumOptions object and conditionally applies platform-specific capabilities.

The initialization flow follows these steps:

1. Create AppiumOptions: A new AppiumOptions instance is instantiated to hold capabilities.
2. Apply Common Settings: Universal options like chromedriver_autodownload and appium:showChromedriverLog are added.
3. Map Configuration Values: Properties from BaseConfiguration (platform name, device name, app path, automation name, app package/activity) are transferred to the options object.
4. Instantiate Platform Driver: Based on AppiumPlatformName, the method creates either an AndroidDriver or IOSDriver using the server URL and populated options.

If an unsupported platform is specified, StartAppium() throws a NotSupportedException with a descriptive message, providing immediate feedback during test startup rather than at execution time.

Writing Mobile Tests and Switching Contexts

Tests inherit from ProjectTestBase to automatically receive a DriverContext containing the initialized Appium driver. The sample implementation in Ocaramba.Tests.Appium/UnitTest1.cs demonstrates native UI interaction and WebView context switching.

Native App Interaction

Use Appium's mobile selectors to locate elements within the native app context:

[Test]
public void VerifyNativeNavigation()
{
    var page = new AppiumSamplePage(this.DriverContext);
    var driver = (AppiumDriver)this.DriverContext.Driver;
    
    // Scroll to element using Android UI Automator
    driver.FindElement(MobileBy.AndroidUIAutomator(
        "new UiScrollable(new UiSelector().resourceId(\"android:id.list\"))" +
        ".scrollIntoView(new UiSelector().text(\"WebView\"))"
    ));
    
    page.ClickWebView();
}

Switching Between Contexts

Ocaramba abstracts the complexity of switching between native and web contexts through dedicated methods on DriverContext:

// Switch to WebView context for web-based assertions
this.DriverContext.SwitchToWebView();

// Perform Selenium-style interactions on web elements
Assert.That(page.GetElementinWebView().Contains("Selenium sandbox"), Is.True);

// Return to native app context
this.DriverContext.SwitchToNative();

The SwitchToWebView() method changes the Selenium context to the first available WebView, while SwitchToNative() returns control to the native app layer. This allows seamless testing of hybrid applications without manually managing context handles.

Running Appium Tests with Ocaramba

Execute your mobile tests by following these steps:

1. Start the Appium server on the default port:

appium

2. Verify device connectivity by ensuring your emulator or physical device matches the AppiumDeviceName specified in appsettings.json.

3. Build the test project:

dotnet build Ocaramba.Tests.Appium

4. Execute tests:

dotnet test Ocaramba.Tests.Appium

The Ocaramba.Tests.Appium/README.md file contains additional platform-specific instructions for setting up Android emulators, iOS simulators, and necessary environment variables.

Summary

• Configuration: Store Appium parameters in appsettings.json under appSettings; BaseConfiguration.cs automatically binds these values to static properties.
• Driver Creation: Set "browser": "Appium" to trigger DriverContext.StartAppium(), which instantiates AndroidDriver or IOSDriver based on AppiumPlatformName.
• Context Management: Use DriverContext.SwitchToWebView() and SwitchToNative() to toggle between native and web contexts without manual driver manipulation.
• Test Structure: Inherit from ProjectTestBase to receive dependency-injected driver contexts and utilize MobileBy selectors for native element location.

Frequently Asked Questions

What are the required Appium settings in appsettings.json?

You must specify AppiumPlatformName (Android or iOS), AppiumDeviceName, AppiumAppPath (or package/activity for Android), and AppiumServerUrl. Additionally, set "browser": "Appium" to activate the mobile driver branch in DriverContext. Optional settings include AppiumAutomationName and chromedriverExecutable for WebView testing.

How does Ocaramba choose between AndroidDriver and IOSDriver?

The StartAppium() method in DriverContext.cs evaluates the AppiumPlatformName configuration value. If it equals "Android", it instantiates an AndroidDriver; if "iOS", it creates an IOSDriver. Any other value results in a NotSupportedException being thrown during driver initialization.

Can I test hybrid apps with both native and web views?

Yes. Ocaramba provides DriverContext.SwitchToWebView() to change the Selenium context to a WebView, allowing standard Selenium selectors on web content. Use DriverContext.SwitchToNative() to return to the native app context. This is demonstrated in Ocaramba.Tests.Appium/UnitTest1.cs where tests verify content inside a WebView before returning to native navigation.

Where is the Appium configuration logic implemented in the source code?

The configuration binding is implemented in OcarambaLite/BaseConfiguration.cs, while driver instantiation resides in OcarambaLite/DriverContext.cs specifically within the StartAppium() method (lines 761-808). Sample implementations showing practical usage are located in the Ocaramba.Tests.Appium project, including UnitTest1.cs and AppiumSamplePage.cs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}