Ocaramba Utility Helpers: A Complete Guide to Test Automation Utilities

The accenture/ocaramba repository provides seven static utility helper classes—WaitHelper, FilesHelper, NameHelper, DateHelper, PerformanceHelper, PrintPerformanceResultsHelper, and SqlHelper—that centralize common test automation tasks such as synchronization, file management, safe naming, performance measurement, and database querying.

These Ocaramba utility helpers are implemented as lightweight, dependency-free static classes located in the OcarambaLite and Ocaramba assemblies. They can be invoked directly from NUnit, MSTest, SpecFlow, or any custom .NET test framework to reduce boilerplate code and improve test reliability.

WaitHelper: Robust Synchronization with Timeouts

The WaitHelper class in OcarambaLite/Helpers/WaitHelper.cs provides centralized waiting logic that polls until a condition becomes true or a timeout expires. Unlike implicit waits, this approach gives explicit control over polling intervals and failure messages.

The primary method signature is:

public static bool Wait(
    Func<bool> condition, 
    TimeSpan timeout, 
    TimeSpan sleepInterval, 
    string message)

This returns true if the condition is met within the timeout window, or false if the operation times out, allowing tests to handle synchronization gracefully without hard-coded Thread.Sleep calls.

FilesHelper: Cross-Platform File Operations

Located in OcarambaLite/Helpers/FilesHelper.cs, this helper manages test artifacts, screenshots, and downloads with methods that respect operating system path separators. Key capabilities include:

• Counting files by extension in a directory
• Waiting for file creation without blocking indefinitely
• Copying, renaming, and deleting files with automatic path handling
• Retrieving the latest file matching a specific pattern

All methods are static and accept a DriverContext or explicit folder path to ensure test isolation across parallel execution.

NameHelper: Safe File and Folder Naming

The NameHelper class in OcarambaLite/Helpers/NameHelper.cs prevents test failures caused by illegal characters or path length violations. It exposes two primary methods:

• RemoveSpecialCharacters(string name) – strips characters that are invalid in Windows or Unix file systems
• ShortenFileName(string fileName, string separator, int maxLength) – truncates long names while preserving readability

This helper is essential when generating screenshots or logs from dynamic test data that may contain user-generated content.

DateHelper: Consistent Timestamp Formatting

Found in OcarambaLite/Helpers/DateHelper.cs, this utility provides standardized date-time formatting for logs and file names. The GetNow and GetNowFormatted methods ensure that timestamps generated during test execution follow a consistent, culture-invariant pattern suitable for CI artifact sorting.

Performance Measurement Helpers

PerformanceHelper

The PerformanceHelper class in OcarambaLite/Helpers/PerformanceHelper.cs collects timing data for specific code blocks. Unlike static helpers, this class is instantiated to maintain state across multiple measurements:

var perf = new PerformanceHelper();
perf.Start();
// Execute code under test
perf.Stop();

The instance stores elapsed times and calculates statistical aggregates including averages and percentiles.

PrintPerformanceResultsHelper

Once measurements are collected, PrintPerformanceResultsHelper (in OcarambaLite/Helpers/PrintPerformanceResultsHelper.cs) formats the output for specific CI systems. Methods like PrintAverageDurationMillisecondsInAppVeyor and corresponding TeamCity formatters enable automatic performance trend tracking in build logs.

SqlHelper: Database Validation

For tests requiring backend verification, the SqlHelper class in Ocaramba/Helpers/SqlHelper.cs executes raw SQL commands against configured connection strings. The ExecuteSqlCommand method supports both scalar results and dictionary-based row retrieval:

int count = SqlHelper.ExecuteSqlCommand(
    "SELECT COUNT(*) FROM Users", 
    connectionString, 
    "Count");

This helper bridges UI automation with data integrity checks, supporting data-driven testing scenarios that validate persistence layers.

Practical Implementation Examples

Synchronizing on File Downloads

Combine WaitHelper with FilesHelper to pause test execution until a download completes:

bool fileReady = WaitHelper.Wait(
    () => FilesHelper.CountFiles(driverContext.DownloadFolder, FileType.Txt) > 0,
    TimeSpan.FromSeconds(30),
    TimeSpan.FromSeconds(1),
    "Download file was not created in time");

Sanitizing Dynamic File Names

Remove illegal characters when saving screenshots based on test case titles:

string rawTitle = "LoginTest/Verified#2023*special?";
string safeName = NameHelper.RemoveSpecialCharacters(rawTitle);
// Result: "LoginTestVerified2023special"

Measuring and Reporting Performance

Capture execution metrics and output them in AppVeyor-compatible format:

var perf = new PerformanceHelper();

perf.Start();
// Navigate through workflow
perf.Stop();

PrintPerformanceResultsHelper.PrintAverageDurationMillisecondsInAppVeyor(perf);

Managing Test Artifacts

Copy the latest HTML page source to a safely named backup:

string source = FilesHelper.GetLastFile(driverContext.PageSourceFolder, FileType.Html);
string shortName = NameHelper.ShortenFileName("extended_validation_scenario.html", "_", 50);
string destination = FilesHelper.RenameFile(source, shortName, driverContext.PageSourceFolder);
FilesHelper.CopyFile(source, destination, driverContext.PageSourceFolder);

Querying Test Data

Validate that a user was created in the database after UI registration:

string sql = "SELECT Username FROM Users WHERE Email = @email";
var parameters = new Dictionary<string, object> { { "@email", testEmail } };
string username = SqlHelper.ExecuteSqlCommand(sql, connectionString, parameters);

Summary

• WaitHelper in OcarambaLite/Helpers/WaitHelper.cs provides explicit synchronization with configurable polling and timeout handling
• FilesHelper in OcarambaLite/Helpers/FilesHelper.cs handles cross-platform file operations including copy, rename, and latest-file retrieval
• NameHelper in OcarambaLite/Helpers/NameHelper.cs ensures OS-safe file naming by removing special characters and enforcing length limits
• DateHelper in OcarambaLite/Helpers/DateHelper.cs supplies consistent timestamp formatting for logs and artifacts
• PerformanceHelper and PrintPerformanceResultsHelper in OcarambaLite/Helpers/ collect timing data and format output for TeamCity and AppVeyor CI systems
• SqlHelper in Ocaramba/Helpers/SqlHelper.cs enables direct database validation via raw SQL command execution

Frequently Asked Questions

How do I wait for a dynamic condition to become true in Ocaramba?

Use the static WaitHelper.Wait method from OcarambaLite/Helpers/WaitHelper.cs. Pass a lambda expression returning a boolean, a TimeSpan for the maximum wait duration, an optional polling interval, and a descriptive error message. The method returns true if the condition is satisfied within the timeout, or false if the wait expires.

Can Ocaramba utility helpers be used outside of Selenium WebDriver tests?

Yes. The helpers in the OcarambaLite.Helpers namespace are static classes with zero external dependencies beyond base .NET libraries. They can be referenced from unit tests, integration tests, console applications, or any .NET project requiring file, date, or timing utilities without pulling in Selenium or database drivers.

What is the difference between ShortenFileName and RemoveSpecialCharacters in NameHelper?

RemoveSpecialCharacters strips illegal path characters such as colons, asterisks, and question marks from a string. ShortenFileName truncates the entire filename to a specified maximum length, inserting a custom separator when truncation occurs. These methods are often chained together to handle user-generated content that might contain both illegal characters and excessive length.

How do I execute SQL queries within my Ocaramba test framework?

Reference the SqlHelper class located in Ocaramba/Helpers/SqlHelper.cs. Call ExecuteSqlCommand with your SQL string, connection string, and an optional command type parameter. The method returns scalar values as the specified type or dictionaries for row-based results, enabling direct database assertions within UI automation workflows.

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