# How Ocaramba Supports Remote WebDriver and Selenium Grid Execution

> Learn how Ocaramba enables seamless Remote WebDriver and Selenium Grid execution by treating them as configurable BrowserTypes. No code changes needed.

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

---

**Ocaramba treats remote Selenium Grid and cloud-based providers as configurable BrowserTypes, instantiating RemoteWebDriver instances through environment-specific settings without requiring code changes.**

The **accenture/ocaramba** framework abstracts remote execution through a unified driver factory that reads hub URLs and capabilities from configuration files. By selecting `BrowserType.RemoteWebDriver` in your test settings, you redirect execution from local browsers to any Selenium Grid or cloud service such as Sauce Labs, TestingBot, or BrowserStack. This architecture allows teams to switch between local debugging and distributed cloud execution simply by updating [`appsettings.json`](https://github.com/accenture/ocaramba/blob/main/appsettings.json).

## Configuration-Driven Remote Execution

Ocaramba decouples test logic from infrastructure through centralized configuration management. The framework pulls connection details from standard .NET configuration providers, enabling environment-specific overrides.

### Defining the Hub URL in BaseConfiguration

The hub address is read from the `BaseConfiguration.RemoteWebDriverHub` property in **OcarambaLite/BaseConfiguration.cs** (lines 433‑445). This static property retrieves the URL from your [`appsettings.json`](https://github.com/accenture/ocaramba/blob/main/appsettings.json) file:

```json
{
  "RemoteWebDriverHub": "http://localhost:4444/wd/hub"
}

```

When this value is populated, Ocaramba routes all driver creation requests to the specified endpoint rather than launching local browser processes.

### BrowserType Enumeration

Remote execution is explicitly declared through the `BrowserType` enum defined in **OcarambaLite/BrowserType.cs** (lines 55‑58). The framework recognizes `RemoteWebDriver` as a first-class browser option alongside Chrome, Firefox, and Edge. Your test runner selects this value via the `TestBrowser` configuration key, triggering the remote instantiation pipeline.

## Driver Instantiation Architecture

When `TestBrowser` is set to `RemoteWebDriver`, Ocaramba delegates driver creation to specialized factory methods that construct appropriate Selenium options and capabilities.

### SetupRemoteWebDriver Method

The core instantiation logic resides in `DriverContext.SetupRemoteWebDriver()` within **OcarambaLite/DriverContext.cs** (lines 815‑864). This method executes the following sequence:

1. Retrieves custom capabilities from the `DriverCapabilities` configuration section
2. Determines the concrete browser type via `GetBrowserTypeForRemoteDriver()`
3. Creates browser-specific options (e.g., `ChromeOptions`, `FirefoxOptions`)
4. Merges configuration values into the options object
5. Instantiates `RemoteWebDriver` with the hub URL and capabilities:

```csharp
this.driver = new RemoteWebDriver(
    BaseConfiguration.RemoteWebDriverHub,
    this.SetDriverOptions(chromeOptions).ToCapabilities());

```

### Browser-Specific Options Creation

For each supported browser—Chrome, Firefox, Safari, Edge, or Internet Explorer—`SetupRemoteWebDriver()` generates the corresponding Selenium `*Options` class. These options objects encapsulate browser version requirements, platform specifications, and vendor-specific settings before conversion to WebDriver capabilities.

### Capability Merging via DriverContextHelper

The `SetRemoteDriverBrowserOptions` method in **OcarambaLite/DriverContextHelper.cs** (lines 94‑101) handles the injection of custom capabilities into browser options. This helper detects provider-specific requirements based on the hub URL and wraps capabilities under the correct namespace (e.g., `sauce:options` or `tb:options`).

## Cloud Provider Integration

Ocaramba includes specialized handling for major cloud testing platforms, automating authentication and session management.

### Sauce Labs and TestingBot Handling

When the hub URL contains identifiers for Sauce Labs or TestingBot, `SetRemoteDriverBrowserOptions` automatically structures capabilities under the provider-specific keys. For Sauce Labs, credentials and test metadata are wrapped under `sauce:options`:

```csharp
// In appsettings.json under "DriverCapabilities"
{
  "sauce:options": {
    "username": "YOUR_USER",
    "accessKey": "YOUR_KEY",
    "name": "Ocaramba Sauce Test"
  },
  "browserName": "chrome",
  "platformName": "Windows 10"
}

```

This automatic wrapping eliminates manual capability construction and ensures compatibility with each platform's protocol requirements.

### BrowserStack Specific Implementation

BrowserStack receives dedicated treatment through `SetupBrowserStack()` in **OcarambaLite/DriverContext.cs** (lines 866‑870). This method constructs `ChromeOptions`, sets the desired browser version, and instantiates `RemoteWebDriver` with BrowserStack-specific configurations. The separation allows for future platform-specific optimizations without affecting the generic remote driver path.

### Session Reporting and Test Lifecycle

The **Ocaramba.Tests.CloudProviderCrossBrowser/ProjectTestBase.cs** file demonstrates production-grade cloud integration (lines 100‑112). After test initialization, the base class extracts the remote session ID and optionally names the BrowserStack session for traceability. During teardown (lines 126‑138), the framework reports pass/fail status back to Sauce Labs or BrowserStack via their respective REST APIs, enabling accurate test dashboards without manual intervention.

## Practical Configuration Examples

### Basic Selenium Grid Configuration

Configure your [`appsettings.json`](https://github.com/accenture/ocaramba/blob/main/appsettings.json) to point to a local or corporate Selenium Grid:

```json
{
  "TestBrowser": "RemoteWebDriver",
  "RemoteWebDriverHub": "http://localhost:4444/wd/hub",
  "DriverCapabilities": {
    "browserName": "chrome",
    "platformName": "ANY"
  },
  "environments": {
    "ChromeRemote": {
      "browser": "Chrome"
    }
  }
}

```

### NUnit Test Implementation

Inherit from `ProjectTestBase` to leverage automatic driver management:

```csharp
using Ocaramba;
using NUnit.Framework;

[TestFixture]
public class RemoteGridTests : ProjectTestBase
{
    [Test]
    public void OpenGoogle_Remote()
    {
        driverContext.Driver.Navigate().GoToUrl("https://www.google.com");
        Assert.That(driverContext.Driver.Title, Does.Contain("Google"));
    }
}

```

The `driverContext` is initialized by the base class based on your configuration, requiring no additional setup code for remote execution.

## Summary

- **Configuration-centric design**: Hub URLs and capabilities are externalized to [`appsettings.json`](https://github.com/accenture/ocaramba/blob/main/appsettings.json) via `BaseConfiguration.RemoteWebDriverHub`.
- **Unified BrowserType**: `RemoteWebDriver` is treated as a standard browser option in **OcarambaLite/BrowserType.cs**.
- **Factory architecture**: `DriverContext.SetupRemoteWebDriver()` orchestrates browser option creation and `RemoteWebDriver` instantiation.
- **Automatic provider detection**: **DriverContextHelper.cs** handles capability namespaces for Sauce Labs and TestingBot automatically.
- **Zero-code switching**: Change from local to grid execution by updating configuration values, with no modifications to test logic required.

## Frequently Asked Questions

### How do I configure Ocaramba to run tests on Selenium Grid?

Set the `TestBrowser` configuration value to `RemoteWebDriver` and specify the hub URL in the `RemoteWebDriverHub` setting within your [`appsettings.json`](https://github.com/accenture/ocaramba/blob/main/appsettings.json) file. The framework reads these values through `BaseConfiguration` and instantiates `RemoteWebDriver` pointing to your grid endpoint.

### What cloud providers are supported by Ocaramba?

Ocaramba provides explicit support for **Sauce Labs**, **TestingBot**, and **BrowserStack** through specialized capability handling in [`DriverContextHelper.cs`](https://github.com/accenture/ocaramba/blob/main/DriverContextHelper.cs) and dedicated setup methods in [`DriverContext.cs`](https://github.com/accenture/ocaramba/blob/main/DriverContext.cs). The framework automatically detects these providers by analyzing the hub URL and formats capabilities accordingly.

### Can I run the same test locally and remotely without code changes?

Yes. Because Ocaramba determines driver type from configuration, you can run identical test code against local Chrome by setting `TestBrowser` to `Chrome`, or against a remote grid by changing it to `RemoteWebDriver`. No recompilation or conditional logic is required in your test classes.

### How does Ocaramba handle authentication for Sauce Labs or BrowserStack?

Authentication credentials are passed through the `DriverCapabilities` configuration section. For Sauce Labs, include your username and access key under the `sauce:options` key. The framework automatically wraps these values under the correct capability namespace when the hub URL contains "saucelabs", ensuring secure credential transmission to the cloud provider.