Local and Docker Execution

This page explains how to run Ocaramba tests in different environments, focusing on local browser execution and containerized execution using Docker. Ocaramba supports a variety of browsers and provides a robust infrastructure for running tests within a Debian-based container environment, integrated with Selenium Grid and supporting applications.

Local Execution

Local execution allows engineers to run and debug tests directly on their workstations. Ocaramba supports Chrome, Firefox, Edge, and Internet Explorer for local runs. The browser lifecycle is managed by the DriverContext, which initializes the appropriate WebDriver based on the configuration provided in appsettings.json OcarambaLite/DriverContextHelper.cs45-46

Supported Local Browsers

• Chrome: Requires chromedriver to be present in the system path or specified in configuration.
• Firefox: Uses geckodriver and supports custom profiles.
• Edge: Uses the Chromium-based msedgedriver.
• Internet Explorer: Supported primarily for legacy scenarios via IEDriverServer.

Docker Execution

Ocaramba provides a comprehensive Docker setup to ensure tests run consistently across different environments (e.g., local dev machines vs. CI/CD agents). The Docker environment is built on Debian and includes all necessary browsers and drivers.

Dockerfile Infrastructure

The primary Dockerfile Dockerfile1-98 defines the test execution environment:

• Base Image: mcr.microsoft.com/dotnet/sdk:8.0 Dockerfile1
• Browsers: Installs google-chrome-stable Dockerfile14 microsoft-edge-stable Dockerfile24 and the latest firefox Dockerfile67-70
• Drivers: Automatically fetches and installs the matching versions of chromedriver Dockerfile39-63 edgedriver Dockerfile28-35 and geckodriver Dockerfile74-85
• Environment: Sets ASPNETCORE_ENVIRONMENT=Linux Dockerfile87 which triggers Ocaramba to look for appsettings.Linux.json for platform-specific overrides.
• User Security: Runs as a non-root user ocaramba Dockerfile91-92
• Health Check: Monitors the environment using dotnet --info Dockerfile97-98

Docker Build and Composition

The framework uses a multi-stage approach for building and running:

1. DockerfileBuild: A specialized Dockerfile used for building the solution within a container environment docker-compose.yml7
2. docker-compose.yml: Orchestrates the test container (ocaramba_selenium_container) and a sample application (the-internet) for integration testing docker-compose.yml1-17
3. Selenium Grid: An additional docker-compose.yml in the NUnit project provides a full selenium-hub with chrome and firefox nodes for distributed testing Ocaramba.Tests.NUnit/docker-compose.yml1-34

Code-to-Entity Mapping: Docker Infrastructure

The following diagram maps the Docker configuration files to their roles in the execution lifecycle.

Docker Execution Components

Sources: Dockerfile1-98 docker-compose.yml1-17 Ocaramba.Tests.NUnit/docker-compose.yml1-41 Dockerfile87

Execution Scripts and Data Flow

Orchestration is handled via PowerShell scripts located in the scripts/ directory. These scripts manage environment variables, configuration injection, and test execution.

Script	Purpose
ExecutingTestsOnDockerGithubActions.ps1	Orchestrates Docker execution by building the solution inside the container, injecting config via set_AppConfig_for_tests.ps1, and running dotnet vstest scripts/ExecutingTestsOnDockerGithubActions.ps11-12
ExecutingTestsOnWindowsGithubActions5.ps1	Runs tests against a Selenium Grid. It sets ASPNETCORE_ENVIRONMENT=Linux scripts/ExecutingTestsOnWindowsGithubActions5.ps11 and configures RemoteWebDriverHub to point to localhost:4444 scripts/ExecutingTestsOnWindowsGithubActions5.ps17
ExecutingTestsOnLinuxAzure.ps1	Sets ASPNETCORE_ENVIRONMENT=Linux and executes NUnit tests against a local host scripts/ExecutingTestsOnLinuxAzure.ps15-11
set_AppConfig_for_tests.ps1	A utility script used by orchestration scripts to dynamically update appsettings.json or appsettings.Linux.json with driver paths and hub URLs scripts/ExecutingTestsOnDockerGithubActions.ps16

Data Flow: Test Execution in Docker

When running in Docker, the framework handles artifacts like screenshots and logs by saving them to internal directories and then copying them to the host.

Test Artifact Flow

Sources: OcarambaLite/DriverContextHelper.cs54-113 scripts/ExecutingTestsOnDockerGithubActions.ps17-9 Dockerfile87

Artifact Management

During execution (local or Docker), Ocaramba automatically captures diagnostic information on failure:

• Screenshots: Saved using SaveScreenshot OcarambaLite/DriverContextHelper.cs54-81
• Page Source: Captured as HTML if BaseConfiguration.GetPageSourceEnabled is true OcarambaLite/DriverContextHelper.cs88-113 It injects a <base> tag to ensure relative links in the captured HTML work correctly by referencing the configured BaseConfiguration.Host OcarambaLite/DriverContextHelper.cs103
• JS Errors: The LogJavaScriptErrors method retrieves logs from the browser's LogType.Browser and filters them based on configured error types OcarambaLite/DriverContextHelper.cs135-150

Logging and Reporting

Tests log to both the console and files. For example, the Appium integration uses nlog.config to target ${basedir}/TestOutput/TestAppium.log Ocaramba.Tests.Appium/nlog.config11 In Docker execution, these logs are collected from the container's /tmp/TestOutput and compressed into a zip archive for CI artifact retention scripts/ExecutingTestsOnDockerGithubActions.ps18-14

Sources:

• Dockerfile 1-98
• docker-compose.yml 1-17
• Ocaramba.Tests.NUnit/docker-compose.yml 1-41
• OcarambaLite/DriverContextHelper.cs 45-150
• Ocaramba.Tests.Appium/nlog.config 1-23
• scripts/ExecutingTestsOnDockerGithubActions.ps1 1-22
• scripts/ExecutingTestsOnWindowsGithubActions5.ps1 1-34
• scripts/ExecutingTestsOnLinuxAzure.ps1 1-21