GitHub Actions Workflow

The Ocaramba framework utilizes GitHub Actions to automate the continuous integration and delivery (CI/CD) process. The workflow is defined in .github/workflows/github-actions.yml and is responsible for building the core libraries, generating API documentation, executing a comprehensive suite of tests across multiple platforms (Windows, Linux, Docker, Android), and publishing NuGet packages.

Workflow Triggers and Permissions

The workflow is configured to respond to various GitHub events to ensure code quality across all branches and releases.

• Triggers:
  • push: Runs on every push to any branch, excluding changes to README.md .github/workflows/github-actions.yml4-10
  • pull_request: Runs when a PR is opened or updated .github/workflows/github-actions.yml3
  • schedule: A weekly cron job runs every Sunday at 18:00 UTC .github/workflows/github-actions.yml11-12
  • workflow_dispatch: Allows manual execution from the GitHub UI .github/workflows/github-actions.yml2
• Permissions: The workflow requires elevated permissions for writing checks, managing GitHub Pages, and issuing OIDC tokens for secure publishing .github/workflows/github-actions.yml13-19

Stage: Build and Documentation

The build_Stage_BuildOnWindows job is the foundational stage. It prepares the environment, handles versioning, and builds the core framework components.

Solution Pruning Technique

To optimize build times and isolate core library compilation, the workflow uses a PowerShell script to dynamically remove test sub-projects from the Ocaramba.sln file before the dotnet restore and dotnet build commands .github/workflows/github-actions.yml44-63 This ensures that the build stage focuses strictly on OcarambaLite and Ocaramba.

Version Injection and SHFB

• Version Detection: If the workflow is triggered by a tag, it extracts the tag name to set the frameworkVersion .github/workflows/github-actions.yml37-42
• Project Updates: The vers-one/dotnet-project-version-updater action applies this version to .csproj files .github/workflows/github-actions.yml76-82
• Documentation: The Sandcastle Help File Builder (SHFB) project (Ocaramba.Documentation.shfbproj) is updated with the version number and built to generate the API documentation .github/workflows/github-actions.yml83-94 The output is uploaded as a GitHub Pages artifact .github/workflows/github-actions.yml95-100

Workflow Logic Flow

Sources: .github/workflows/github-actions.yml29-116

Stage: Multi-Platform Test Execution

Ocaramba runs tests across diverse environments using parallel jobs. Each job typically uses a specific PowerShell script from the scripts/ directory to orchestrate execution.

Job Name	Environment	Primary Script	Description
test_Stage_RunTestsOnDocker	ubuntu-latest	ExecutingTestsOnDockerGithubActions.ps1	Builds/pushes Docker images and runs tests inside a custom Selenium Docker container .github/workflows/github-actions.yml117-156
test_Stage_RunTestsOnWindows1-6	windows-latest	ExecutingTestsOnWindowsGithubActions*.ps1	Split into 6 parallel jobs to run NUnit, MsTest, Xunit, and Cloud tests .github/workflows/github-actions.yml210-211
test_Stage_RunTestsOnLinux	ubuntu-latest	ExecutingTestsOnLinuxAzure.ps1	Validates framework compatibility on Linux .github/workflows/github-actions.yml185-186
test_Stage_RunTestsOnAndroid	macos-latest	N/A	Uses ReactiveCircus Android Emulator action to run Appium tests .github/workflows/github-actions.yml250-280

Configuration Injection

Before running tests, the workflow invokes set_AppConfig_for_tests.ps1. This script modifies appsettings.json or appsettings.Linux.json to inject environment-specific values like browser types, driver paths, or Remote WebDriver URLs scripts/ExecutingTestsOnWindowsGithubActions5.ps17-11 scripts/ExecutingTestsOnLinuxAzure.ps19-11

Test Orchestration Mapping

Sources: scripts/ExecutingTestsOnWindowsGithubActions4.ps11-16 scripts/ExecutingTestsOnWindowsGithubActions5.ps11-13 scripts/ExecutingTestsOnWindowsGithubActions6.ps11-9

BrowserStack and Cloud Integration

The workflow includes dedicated steps for BrowserStack and SauceLabs.

• BrowserStack: Uses the browserstack-sdk to wrap test execution. It executes using dotnet browserstack-sdk which targets the project DLL scripts/ExecutingTestsOnWindowsGithubActions4.ps16-9 Similar logic is applied for Linux environments scripts/ExecutingTestsOnLinuxBrowserStackGithubActions.ps17-11
• SauceLabs: Injects credentials via environment variables into the RemoteWebDriverHub setting using the configuration script set_AppConfig_for_tests.ps1 before running the CloudProviderCrossBrowser tests scripts/ExecutingTestsOnWindowsGithubActions6.ps15-9

Docker Execution Flow

The Docker stage performs security scans and functional testing within a containerized environment.

1. Security: Runs checkov for image scanning and aquasecurity/trivy-action for vulnerability detection .github/workflows/github-actions.yml133-149
2. Execution: Launches the environment via docker-compose.yml .github/workflows/github-actions.yml154
3. Internal Pruning: Inside the container, the script ExecutingTestsOnDockerGithubActions.ps1 uses sed to prune the solution file before building and running tests scripts/ExecutingTestsOnDockerGithubActions.ps15-7

Docker Entity Association

Sources: .github/workflows/github-actions.yml117-156 scripts/ExecutingTestsOnDockerGithubActions.ps11-12

Artifact Management and Publishing

At the end of the pipeline, results and packages are handled:

1. Test Results: .trx files are collected and published using EnricoMi/publish-unit-test-result-action to provide a summary in the PR .github/workflows/github-actions.yml158-164
2. Logs: The TestOutput directory (containing NLog logs and screenshots) is zipped and uploaded as a GitHub artifact scripts/ExecutingTestsOnDockerGithubActions.ps114 scripts/ExecutingTestsOnWindowsGithubActions4.ps18-9
3. NuGet Release: The release_Stage_PublishNuget job (triggered on tags) downloads the .nupkg and .snupkg artifacts created in the build stage and pushes them to NuGet.org.

Sources: .github/workflows/github-actions.yml1-330 scripts/ExecutingTestsOnWindowsGithubActions4.ps11-16 scripts/ExecutingTestsOnWindowsGithubActions5.ps11-33 scripts/ExecutingTestsOnWindowsGithubActions6.ps11-18 scripts/ExecutingTestsOnDockerGithubActions.ps11-21 scripts/ExecutingTestsOnLinuxBrowserStackGithubActions.ps11-18