How to Use Ocaramba with BrowserStack: Cloud Testing Configuration

Set the browser key to BrowserStack in 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 (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 (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 (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 selects BrowserStack as the target browser and defines the remote hub endpoint:

{
  "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 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:

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 demonstrates a standard Ocaramba test that executes on BrowserStack:

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:

# 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 orchestrates automated BrowserStack testing using the official browserstack/github-action@v1. This action reads 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 handles instantiation of the RemoteWebDriver with ChromeOptions and the hub URL from appsettings.json.
• Configuration-Driven: Authentication and platform matrices are defined in browserstack.yml, while the framework target is set in 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. While the SetupBrowserStack() method currently initializes a ChromeOptions object, the actual browser rendered depends on the platforms configuration in 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 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 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 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.

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