# How to Use Ocaramba with BrowserStack: Cloud Testing Configuration

> Learn how to use Ocaramba with BrowserStack for cloud testing. Configure settings to run your Ocaramba tests on BrowserStack without changing your test logic.

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

---

**Set the `browser` key to `BrowserStack` in [`appsettings.json`](https://github.com/accenture/ocaramba/blob/main/appsettings.json) and provide a valid `RemoteWebDriverHub` URL to execute Ocaramba tests on BrowserStack's cloud infrastructure without modifying test logic.**

The **accenture/ocaramba** test automation framework provides native integration with BrowserStack for cross-browser testing. When you use Ocaramba with BrowserStack, the framework treats the cloud provider as a specialized `BrowserType` that instantiates a `RemoteWebDriver` pointing to BrowserStack's Selenium hub, enabling execution on real devices and browsers using your existing page-object test suites.

## How Ocaramba Integrates with BrowserStack

The integration follows a driver-factory pattern where BrowserStack is handled as a first-class browser option within the framework's configuration system.

### Browser Type Selection

Ocaramba defines BrowserStack as a supported browser type in the `BrowserType` enumeration. In [`OcarambaLite/BrowserType.cs`](https://github.com/accenture/ocaramba/blob/main/OcarambaLite/BrowserType.cs) (lines 95-99), the enum value `BrowserStack` is declared alongside local browser options. When the framework initializes, it reads the `browser` entry from the test project's configuration and maps it to `BaseConfiguration.TestBrowser`, setting the value to `BrowserType.BrowserStack` when the configuration specifies `"BrowserStack"`.

### Driver Startup Logic

The `DriverContext.Start()` method in [`OcarambaLite/DriverContext.cs`](https://github.com/accenture/ocaramba/blob/main/OcarambaLite/DriverContext.cs) (lines 648-651) contains a switch statement that routes execution based on `BaseConfiguration.TestBrowser`. When the enum value is `BrowserStack`, the framework invokes the `SetupBrowserStack()` method rather than instantiating a local Chrome, Firefox, or Edge driver.

### RemoteWebDriver Initialization

The `SetupBrowserStack()` method, located in [`OcarambaLite/DriverContext.cs`](https://github.com/accenture/ocaramba/blob/main/OcarambaLite/DriverContext.cs) (lines 66-71), constructs a `ChromeOptions` object, fixes the browser version to `"latest"`, and creates a `RemoteWebDriver` instance targeting `BaseConfiguration.RemoteWebDriverHub`. This hub URL typically points to `http://hub-cloud.browserstack.com/wd/hub` for direct cloud execution or a local tunnel endpoint when running through the BrowserStack Local binary.

## Configuration Files for BrowserStack Testing

All BrowserStack-specific parameters—including authentication credentials, platform matrix, and debugging options—are externalized into configuration files that the framework consumes at runtime.

### appsettings.json Setup

The primary configuration file [`Ocaramba.Tests.BrowserStack/appsettings.json`](https://github.com/accenture/ocaramba/blob/main/Ocaramba.Tests.BrowserStack/appsettings.json) selects BrowserStack as the target browser and defines the remote hub endpoint:

```json
{
  "appSettings": {
    "browser": "BrowserStack",
    "RemoteWebDriverHub": "http://hub-cloud.browserstack.com/wd/hub",
    "longTimeout": "30",
    "shortTimeout": "3"
  }
}

```

This configuration instructs Ocaramba to bypass local driver creation and use the remote WebDriver protocol for all test execution.

### browserstack.yml for CI/CD

The [`browserstack.yml`](https://github.com/accenture/ocaramba/blob/main/browserstack.yml) file in `Ocaramba.Tests.BrowserStack/` defines the platform matrix and authentication for CI pipelines. This YAML is consumed by the BrowserStack GitHub Action, which injects credentials via environment variables (`BROWSERSTACK_USERNAME`, `BROWSERSTACK_ACCESS_KEY`) and manages the Local tunnel:

```yaml
userName: ${BROWSERSTACK_USERNAME}
accessKey: ${BROWSERSTACK_ACCESS_KEY}

projectName: BrowserStack Ocaramba Tests
buildName: gha-${GITHUB_RUN_NUMBER}
buildIdentifier: "#${BUILD_NUMBER}"
testObservability: true

platforms:
  - browserName: Edge
    os: Windows
    osVersion: 11
    browserVersion: latest
  - browserName: Safari
    os: OS X
    osVersion: Monterey
    browserVersion: 15.6
  - browserName: chrome
    osVersion: 13.0
    deviceName: Samsung Galaxy S23 Ultra

browserstackLocal: true
debug: false
networkLogs: true
consoleLogs: errors
logLevel: debug

```

The `platforms` array specifies the cross-browser matrix, while `browserstackLocal: true` enables testing against internal staging environments through the BrowserStack Local tunnel.

## Writing and Executing Tests

Tests written for local execution require zero code changes to run on BrowserStack. The framework handles the underlying driver differences transparently.

### Sample NUnit Test

The file [`Ocaramba.Tests.BrowserStack/Tests/HerokuappTestsNUnit.cs`](https://github.com/accenture/ocaramba/blob/main/Ocaramba.Tests.BrowserStack/Tests/HerokuappTestsNUnit.cs) demonstrates a standard Ocaramba test that executes on BrowserStack:

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

namespace Ocaramba.Tests.BrowserStack.Tests
{
    [TestFixture]
    public class HerokuappTestsNUnit : ProjectTestBase
    {
        [Test]
        public void VerifyTitleOnHerokuApp()
        {
            // Navigate to the test site (configured via appsettings.json)
            NavigateToUrl();
            // Simple Ocaramba page-object verification
            Assert.AreEqual("The Internet", Driver.Title);
        }
    }
}

```

Because the test inherits from `ProjectTestBase`, it automatically utilizes the `DriverContext` configured for BrowserStack execution, enabling the same page-object methods and assertions used in local testing.

### Local Execution

To run the suite locally against BrowserStack without CI infrastructure, export your credentials and execute the test assembly:

```bash

# Export BrowserStack credentials

export BROWSERSTACK_USERNAME=your_user
export BROWSERSTACK_ACCESS_KEY=your_key

# Ensure the remote hub URL matches the one in appsettings.json

dotnet test Ocaramba.Tests.BrowserStack/Ocaramba.Tests.BrowserStack.csproj

```

The `RemoteWebDriver` connects directly to BrowserStack's cloud hub using the provided authentication.

### GitHub Actions Integration

The repository's [`.github/workflows/github-actions.yml`](https://github.com/accenture/ocaramba/blob/main/.github/workflows/github-actions.yml) orchestrates automated BrowserStack testing using the official `browserstack/github-action@v1`. This action reads [`browserstack.yml`](https://github.com/accenture/ocaramba/blob/main/browserstack.yml), starts the Local tunnel if configured, and injects the necessary environment variables. When `DriverContext.Stop()` is invoked after test completion, the remote session terminates and the GitHub Action automatically shuts down the Local tunnel process.

## Summary

- **BrowserStack as BrowserType**: Ocaramba treats BrowserStack as a native `BrowserType` enum value, enabling selection via configuration rather than code changes.
- **RemoteWebDriver Factory**: The `SetupBrowserStack()` method in [`DriverContext.cs`](https://github.com/accenture/ocaramba/blob/main/DriverContext.cs) handles instantiation of the `RemoteWebDriver` with `ChromeOptions` and the hub URL from [`appsettings.json`](https://github.com/accenture/ocaramba/blob/main/appsettings.json).
- **Configuration-Driven**: Authentication and platform matrices are defined in [`browserstack.yml`](https://github.com/accenture/ocaramba/blob/main/browserstack.yml), while the framework target is set in [`appsettings.json`](https://github.com/accenture/ocaramba/blob/main/appsettings.json).
- **Zero-Code Migration**: Existing page-object tests run unchanged on BrowserStack because `DriverContext` abstracts the underlying driver implementation.
- **CI/CD Ready**: Native GitHub Actions support via the BrowserStack Action enables automated tunnel management and parallel execution across the defined platform matrix.

## Frequently Asked Questions

### What browser types does Ocaramba support for BrowserStack testing?

Ocaramba supports BrowserStack as a dedicated `BrowserType.BrowserStack` value defined in [`OcarambaLite/BrowserType.cs`](https://github.com/accenture/ocaramba/blob/main/OcarambaLite/BrowserType.cs). While the `SetupBrowserStack()` method currently initializes a `ChromeOptions` object, the actual browser rendered depends on the `platforms` configuration in [`browserstack.yml`](https://github.com/accenture/ocaramba/blob/main/browserstack.yml), allowing tests to run on Edge, Safari, Firefox, Chrome, and mobile devices regardless of the local options object.

### Do I need to modify my existing test code to run on BrowserStack?

No. Tests inheriting from `ProjectTestBase` use the same `NavigateToUrl()`, element locators, and assertion methods on BrowserStack as they do locally. The framework's `DriverContext` transparently swaps the local WebDriver for a `RemoteWebDriver` when [`appsettings.json`](https://github.com/accenture/ocaramba/blob/main/appsettings.json) specifies `"browser": "BrowserStack"`, requiring no changes to page-object logic or test assertions.

### How does Ocaramba handle BrowserStack authentication?

The framework expects credentials via environment variables `BROWSERSTACK_USERNAME` and `BROWSERSTACK_ACCESS_KEY`. In CI environments, the BrowserStack GitHub Action injects these variables from repository secrets. For local runs, you must export these variables in your shell before executing `dotnet test`. The [`browserstack.yml`](https://github.com/accenture/ocaramba/blob/main/browserstack.yml) references these variables using `${BROWSERSTACK_USERNAME}` syntax.

### Can I test internal staging sites that are not publicly accessible?

Yes. Set `browserstackLocal: true` in [`browserstack.yml`](https://github.com/accenture/ocaramba/blob/main/browserstack.yml) to enable the BrowserStack Local tunnel. When running through the GitHub Action, the tunnel starts automatically and routes traffic from BrowserStack's cloud to your internal network. For local execution, you must start the BrowserStack Local binary manually or use the BrowserStack Local NPM binary to establish the tunnel before running tests.