How to Configure Proxy Settings in Ocaramba: A Complete Guide

To configure proxy settings in Ocaramba, populate the proxy, httpProxy, sslProxy, or socksproxy keys in appsettings.json, which the framework automatically reads through BaseConfiguration and injects into Selenium driver options via DriverContextHelper.CurrentProxy().

Ocaramba is an open-source .NET test automation framework maintained by Accenture that simplifies Selenium WebDriver configuration through JSON-based settings. Configuring proxy settings in Ocaramba requires understanding how the framework bridges configuration files with Selenium's Proxy class across different browser drivers.

Understanding Ocaramba's Proxy Architecture

The proxy configuration pipeline in Ocaramba consists of three coordinated components that transform JSON settings into Selenium driver capabilities.

Configuration Layer (BaseConfiguration.cs)

All proxy values originate from the static BaseConfiguration class in OcarambaLite/BaseConfiguration.cs. This class exposes four distinct properties that map directly to appsettings.json keys:

• BaseConfiguration.Proxy (lines 180-190): Serves as a fallback value for all proxy protocols when specific overrides are not provided.
• BaseConfiguration.HttpProxy (lines 196-206): Dedicated HTTP proxy address.
• BaseConfiguration.SslProxy (lines 212-222): Dedicated HTTPS proxy address.
• BaseConfiguration.SocksProxy (lines 228-238): SOCKS proxy address.

Proxy Construction (DriverContextHelper.cs)

The DriverContextHelper class constructs the Selenium Proxy object through the CurrentProxy() method (lines 185-191). This method implements a fallback hierarchy:

// File: OcarambaLite/DriverContextHelper.cs
private Proxy CurrentProxy()
{
    Proxy proxy = new Proxy
    {
        HttpProxy = BaseConfiguration.HttpProxy ?? BaseConfiguration.Proxy,
        SslProxy  = BaseConfiguration.SslProxy  ?? BaseConfiguration.Proxy,
        SocksProxy = BaseConfiguration.SocksProxy ?? BaseConfiguration.Proxy,
    };
    return proxy;
}

Driver Assignment (DriverContext.cs)

Each browser driver receives the constructed proxy object through specific options assignments in OcarambaLite/DriverContext.cs:

• Firefox (lines 266-270): options.Proxy = this.CurrentProxy();
• Chrome (lines 363-367): options.Proxy = this.CurrentProxy();
• Internet Explorer (lines 462-466): options.Proxy = this.CurrentProxy();
• Edge (lines 498-504): options.Proxy = this.CurrentProxy();

Step-by-Step Configuration

Basic Proxy Setup in appsettings.json

Create or modify the appsettings.json file in your test project root to include the proxy configuration under the appSettings section:

{
  "appSettings": {
    "proxy": "http://proxy.company.com:8080"
  }
}

Setting the proxy key alone configures a single proxy address for all protocols (HTTP, HTTPS, and SOCKS).

Protocol-Specific Proxy Overrides

For scenarios requiring different proxies per protocol, use the specific configuration keys. These override the general proxy value for their respective protocols:

{
  "appSettings": {
    "proxy": "http://fallback-proxy.company.com:8080",
    "httpProxy": "http://http-proxy.company.com:8080",
    "sslProxy": "http://ssl-proxy.company.com:8443",
    "socksproxy": "socks5://socks-proxy.company.com:1080"
  }
}

According to the CurrentProxy() implementation in DriverContextHelper.cs, the framework applies the coalescing operator (??) to check for specific values before falling back to the general proxy setting.

Environment-Specific Configuration

Ocaramba supports environment-specific configuration files using the ASP.NET Core configuration pattern. Create files following the appsettings.{Environment}.json naming convention:

// appsettings.Development.json
{
  "appSettings": {
    "proxy": "http://dev-proxy.company.com:8080"
  }
}

Set the ASPNETCORE_ENVIRONMENT environment variable before test execution to load the appropriate override:

export ASPNETCORE_ENVIRONMENT=Development

Browser-Specific Considerations

Safari Limitations

Safari does not support the Selenium Proxy object configuration used by other browsers. The CheckIfProxySetForSafari() method in DriverContextHelper.cs (lines 194-200) explicitly throws a NotSupportedException if BaseConfiguration.Proxy is defined when using Safari.

To configure a proxy for Safari testing, you must pass the proxy via command-line arguments when starting the SafariDriver:

safaridriver --port=4444 --proxy=http://proxy.company.com:8080

Remove or comment out the proxy settings in appsettings.json when executing Safari tests to avoid the framework exception.

Summary

• Configuration Source: Ocaramba reads proxy settings from appsettings.json via the BaseConfiguration class properties: Proxy, HttpProxy, SslProxy, and SocksProxy.
• Fallback Hierarchy: The CurrentProxy() method in DriverContextHelper.cs uses specific protocol settings when available, falling back to the general proxy value.
• Automatic Injection: Firefox, Chrome, Internet Explorer, and Edge automatically receive the configured proxy through their driver options in DriverContext.cs.
• Safari Exception: Safari requires command-line proxy configuration; setting BaseConfiguration.Proxy while using Safari triggers a NotSupportedException.

Frequently Asked Questions

Where does Ocaramba read proxy settings from?

Ocaramba reads proxy settings from the appSettings section of appsettings.json (and environment-specific variants like appsettings.Development.json) through the static BaseConfiguration class in OcarambaLite/BaseConfiguration.cs. The framework looks for keys named proxy, httpProxy, sslProxy, and socksproxy.

Can I use different proxies for HTTP and HTTPS traffic?

Yes. Configure the httpProxy key for HTTP traffic and the sslProxy key for HTTPS traffic in appsettings.json. According to the CurrentProxy() implementation in DriverContextHelper.cs, these specific values take precedence over the general proxy setting for their respective protocols.

Why does Safari throw an exception when I set a proxy?

Safari does not support Selenium's programmatic proxy configuration. The CheckIfProxySetForSafari() method in DriverContextHelper.cs (lines 194-200) deliberately throws a NotSupportedException if any proxy configuration is detected when initializing Safari. You must configure Safari proxies through command-line arguments when launching safaridriver instead.

How do I override proxy settings for different test environments?

Create environment-specific JSON files (e.g., appsettings.Staging.json, appsettings.Production.json) with environment-specific proxy values. Set the ASPNETCORE_ENVIRONMENT environment variable to match the suffix of your configuration file name before running tests. Ocaramba automatically loads the matching file and overrides base settings.

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