# Ocaramba Utility Helpers: A Complete Guide to Test Automation Utilities

> Explore Ocaramba utility helpers for test automation. Discover WaitHelper FilesHelper NameHelper DateHelper PerformanceHelper PrintPerformanceResultsHelper and SqlHelper for efficient testing.

- Repository: [Accenture/ocaramba](https://github.com/accenture/ocaramba)
- Tags: how-to-guide
- Published: 2026-02-23

---

**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`](https://github.com/accenture/ocaramba/blob/main/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:

```csharp
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`](https://github.com/accenture/ocaramba/blob/main/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`](https://github.com/accenture/ocaramba/blob/main/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`](https://github.com/accenture/ocaramba/blob/main/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`](https://github.com/accenture/ocaramba/blob/main/OcarambaLite/Helpers/PerformanceHelper.cs) collects timing data for specific code blocks. Unlike static helpers, this class is instantiated to maintain state across multiple measurements:

```csharp
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`](https://github.com/accenture/ocaramba/blob/main/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`](https://github.com/accenture/ocaramba/blob/main/Ocaramba/Helpers/SqlHelper.cs) executes raw SQL commands against configured connection strings. The `ExecuteSqlCommand` method supports both scalar results and dictionary-based row retrieval:

```csharp
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:

```csharp
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:

```csharp
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:

```csharp
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:

```csharp
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:

```csharp
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`](https://github.com/accenture/ocaramba/blob/main/OcarambaLite/Helpers/WaitHelper.cs) provides explicit synchronization with configurable polling and timeout handling
- **`FilesHelper`** in [`OcarambaLite/Helpers/FilesHelper.cs`](https://github.com/accenture/ocaramba/blob/main/OcarambaLite/Helpers/FilesHelper.cs) handles cross-platform file operations including copy, rename, and latest-file retrieval
- **`NameHelper`** in [`OcarambaLite/Helpers/NameHelper.cs`](https://github.com/accenture/ocaramba/blob/main/OcarambaLite/Helpers/NameHelper.cs) ensures OS-safe file naming by removing special characters and enforcing length limits
- **`DateHelper`** in [`OcarambaLite/Helpers/DateHelper.cs`](https://github.com/accenture/ocaramba/blob/main/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`](https://github.com/accenture/ocaramba/blob/main/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`](https://github.com/accenture/ocaramba/blob/main/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`](https://github.com/accenture/ocaramba/blob/main/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.