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

> Configure Appium for mobile testing with Ocaramba by updating appsettings json and inheriting ProjectTestBase. Get your AndroidDriver or IOSDriver initialized easily.

- Repository: [Accenture/ocaramba](https://github.com/accenture/ocaramba)
- Tags: how-to-guide
- Published: 2026-02-23

---

**To configure Appium for mobile testing with Ocaramba, populate the Appium-specific keys in [`appsettings.json`](https://github.com/accenture/ocaramba/blob/main/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`](https://github.com/accenture/ocaramba/blob/main/appsettings.json) file. The `BaseConfiguration` class in [`OcarambaLite/BaseConfiguration.cs`](https://github.com/accenture/ocaramba/blob/main/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:

```json
{
  "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`](https://github.com/accenture/ocaramba/blob/main/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`](https://github.com/accenture/ocaramba/blob/main/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:

```csharp
[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`:

```csharp
// 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:

```powershell
appium

```

2. **Verify device connectivity** by ensuring your emulator or physical device matches the `AppiumDeviceName` specified in [`appsettings.json`](https://github.com/accenture/ocaramba/blob/main/appsettings.json).

3. **Build the test project**:

```bash
dotnet build Ocaramba.Tests.Appium

```

4. **Execute tests**:

```bash
dotnet test Ocaramba.Tests.Appium

```

The [`Ocaramba.Tests.Appium/README.md`](https://github.com/accenture/ocaramba/blob/main/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`](https://github.com/accenture/ocaramba/blob/main/appsettings.json) under `appSettings`; [`BaseConfiguration.cs`](https://github.com/accenture/ocaramba/blob/main/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`](https://github.com/accenture/ocaramba/blob/main/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`](https://github.com/accenture/ocaramba/blob/main/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`](https://github.com/accenture/ocaramba/blob/main/OcarambaLite/BaseConfiguration.cs), while driver instantiation resides in [`OcarambaLite/DriverContext.cs`](https://github.com/accenture/ocaramba/blob/main/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`](https://github.com/accenture/ocaramba/blob/main/UnitTest1.cs) and [`AppiumSamplePage.cs`](https://github.com/accenture/ocaramba/blob/main/AppiumSamplePage.cs).