DriverContext and Browser Lifecycle

The DriverContext class is the central orchestrator of the Ocaramba framework. It manages the lifecycle of the Selenium IWebDriver or Appium AppiumDriver, handles browser-specific initializations, and provides integrated utilities for diagnostics such as screenshots, page source capture, and JavaScript error logging.

DriverContext Lifecycle

The lifecycle of a driver in Ocaramba is typically tied to the execution of a single test case. The DriverContext is initialized at the start of a test and disposed of at the end.

Initialization (Start)

The Start() method (and its overloads) is responsible for reading the configuration and instating the appropriate IWebDriver instance OcarambaLite/DriverContext.cs228-240

1. Configuration Loading: It retrieves settings from BaseConfiguration, which reads from appsettings.json and environment-specific JSON files (e.g., appsettings.Linux.json) using Microsoft.Extensions.Configuration OcarambaLite/BaseConfiguration.cs44-52
2. Browser Selection: Based on BaseConfiguration.TestBrowser, it determines which browser-specific logic to execute OcarambaLite/BaseConfiguration.cs65-83
3. Event Wrapping: By default, the raw driver is wrapped in a MyEventFiringWebDriver to enable automatic logging of browser actions like navigation and clicking OcarambaLite/DriverContext.cs302-306

Termination (Stop)

The Stop() method ensures that the browser process and the driver service are cleaned up correctly OcarambaLite/DriverContext.cs461-480

• It calls driver.Quit() to close all windows and exit the driver OcarambaLite/DriverContext.cs466
• It stops associated driver services (e.g., ChromeDriverService OcarambaLite/DriverContext.cs65 EdgeDriverService OcarambaLite/DriverContext.cs67) to prevent orphaned processes OcarambaLite/DriverContext.cs471-479

Driver Initialization Flow

The following diagram illustrates the flow from Start() to the creation of a specific driver instance, mapping high-level actions to code entities.

Title: Driver Initialization Data Flow

Sources: OcarambaLite/DriverContext.cs228-306 OcarambaLite/BaseConfiguration.cs65-83 OcarambaLite/BrowserType.cs28-99

Browser-Specific Initialization

Ocaramba supports multiple browsers, each with specific configuration logic handled within DriverContext.

Browser	Method	Key Features
Chrome	InitChromeDriver()	Supports ChromeOptions, headless mode, and ChromeDriverService OcarambaLite/DriverContext.cs65
Firefox	InitFirefoxDriver()	Handles Firefox profiles via PathToFirefoxProfile OcarambaLite/BaseConfiguration.cs111-127
Edge	InitEdgeDriver()	Configures EdgeOptions and manages EdgeDriverService OcarambaLite/DriverContext.cs67
Internet Explorer	InitIEDriver()	Specifically handles BrowserType.IE and BrowserType.InternetExplorer OcarambaLite/BrowserType.cs43-48

Remote and Cloud Providers

For execution on Selenium Grid or cloud providers like BrowserStack, Ocaramba uses RemoteWebDriver.

• RemoteWebDriver: Initialized via InitRemoteWebDriver(), using configurations from BaseConfiguration.
• BrowserStack: Identified by BrowserType.BrowserStack OcarambaLite/BrowserType.cs98 Capabilities are injected via DriverOptionsSet events OcarambaLite/DriverContext.cs74 allowing users to customize the remote session before the driver is instantiated OcarambaLite/DriverOptionsSetEventArgs.cs31-46

Appium Mobile Driver

Ocaramba supports mobile automation through AppiumDriver OcarambaLite/DriverContext.cs39 The framework can switch between native and web contexts:

• SwitchToWebView(): Iterates through available contexts to find and switch to a "WEBVIEW" using a wait for BaseConfiguration.MediumTimeout OcarambaLite/DriverContext.cs182-202
• SwitchToNative(): Switches the context back to "NATIVE_APP" OcarambaLite/DriverContext.cs214-218

EventFiringWebDriver Wrapper

The MyEventFiringWebDriver class extends Selenium's EventFiringWebDriver to provide automated logging OcarambaLite/Logger/MyEventFiringWebDriver.cs33-34 It hooks into several WebDriver events:

• Navigation: Logs the target URL in OnNavigating OcarambaLite/Logger/MyEventFiringWebDriver.cs50-54
• Element Actions: Logs element details (ID, Name, Class, Type, Text) during OnElementClicking and OnElementValueChanging OcarambaLite/Logger/MyEventFiringWebDriver.cs60-74 OcarambaLite/Logger/MyEventFiringWebDriver.cs121-135
• Finding Elements: Logs the locator used in OnFindingElement OcarambaLite/Logger/MyEventFiringWebDriver.cs90-94

Title: Event Logging Integration

Sources: OcarambaLite/Logger/MyEventFiringWebDriver.cs50-54 OcarambaLite/DriverContext.cs154-160

Diagnostics and Error Handling

Screenshot Capture

Ocaramba provides multiple ways to capture screenshots:

1. Full Page: TakeAndSaveScreenshot() captures the current browser view and saves it to the folder defined by BaseConfiguration.ScreenShotFolder OcarambaLite/DriverContextHelper.cs119-129 OcarambaLite/DriverContext.cs97-103
2. Naming Convention: Screenshots are named using {Title}_{Date}_browser.png, with invalid characters sanitized OcarambaLite/DriverContextHelper.cs56-63
3. Automatic on Failure: If a test fails, screenshots are triggered by TakeAndSaveScreenshot() if BaseConfiguration.SeleniumScreenShotEnabled is true OcarambaLite/DriverContextHelper.cs123-126

Page Source and JS Errors

• SavePageSource: Saves the current HTML. It automatically injects a <base> tag with the configured BaseConfiguration.Host to ensure relative links work when viewing the offline file OcarambaLite/DriverContextHelper.cs88-113
• LogJavaScriptErrors: Queries the browser's LogType.Browser to find and log JavaScript errors that occurred during execution, filtered by BaseConfiguration.JavaScriptErrorTypes OcarambaLite/DriverContextHelper.cs135-149

Diagnostic Data Flow

The following diagram shows how DriverContext interacts with the file system and configuration for diagnostics.

Title: Diagnostic Output Mapping

Sources: OcarambaLite/DriverContext.cs97-125 OcarambaLite/DriverContextHelper.cs54-113

Summary of Key Classes

Class	Role
DriverContext	Primary container for IWebDriver, PerformanceHelper, and TestLogger OcarambaLite/DriverContext.cs51-84
BaseConfiguration	Static helper to access appsettings.json keys like browser, timeouts, and folders OcarambaLite/BaseConfiguration.cs38-52
MyEventFiringWebDriver	Custom wrapper that triggers NLog events for Selenium actions OcarambaLite/Logger/MyEventFiringWebDriver.cs33
DriversCustomSettings	Manages driver-specific settings like Angular synchronization OcarambaLite/DriversCustomSettings.cs31-68
TestLogger	Wrapper for NLog to manage test-specific logging sessions OcarambaLite/DriverContext.cs138-149

Sources: OcarambaLite/DriverContext.cs OcarambaLite/BaseConfiguration.cs OcarambaLite/Logger/MyEventFiringWebDriver.cs OcarambaLite/DriversCustomSettings.cs