# How Does Ocaramba Handle Page Source Saving? Configuration and Implementation Guide

> Learn how Ocaramba handles page source saving using DriverContext.SavePageSource(). Configure saving, inject base tags, and capture source on test failures automatically.

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

---

**Ocaramba handles page source saving through the `DriverContext.SavePageSource()` method in [`DriverContextHelper.cs`](https://github.com/accenture/ocaramba/blob/main/DriverContextHelper.cs), which writes HTML snapshots to a configurable folder, injects a `<base>` tag for link resolution, and integrates with the `Verify.That()` assertion helper to automatically capture page source on test failures.**

The Ocaramba framework (accenture/ocaramba) provides built-in capabilities for capturing HTML page source during automated Selenium tests. Understanding how does Ocaramba handle page source saving helps QA engineers debug UI failures effectively, as the framework can persist the complete DOM state either manually or automatically when assertions fail.

## Configuration Settings for Page Source Saving

Before capturing HTML snapshots, Ocaramba checks configuration values defined in [`OcarambaLite/BaseConfiguration.cs`](https://github.com/accenture/ocaramba/blob/main/OcarambaLite/BaseConfiguration.cs).

### Enabling the Feature with GetPageSourceEnabled

The `BaseConfiguration.GetPageSourceEnabled` property controls whether the framework allows page source saving. According to the source code at lines 716-730, this property reads the `GetPageSourceEnabled` key from appSettings, defaulting to **true** when the configuration key is absent.

### Defining the Output Directory

The destination folder is determined by `BaseConfiguration.PageSourceFolder` (lines 669-679). This property establishes where all HTML files will be written, ensuring the directory exists before file operations occur.

## The SavePageSource Method Architecture

The core implementation resides in [`OcarambaLite/DriverContextHelper.cs`](https://github.com/accenture/ocaramba/blob/main/OcarambaLite/DriverContextHelper.cs), specifically within the `SavePageSource(string fileName)` method spanning lines 88-110.

### Filename Sanitization and Path Construction

When invoked, the method constructs a safe filename and combines it with the configured `PageSourceFolder`. If a file with the same name already exists, Ocaramba deletes it before writing new content.

### HTML Content Preparation with Base Tag Injection

Before persistence, Ocaramba modifies the HTML to ensure local usability. At lines 101-104, the framework injects a `<base>` tag pointing to `BaseConfiguration.Host`. This modification ensures that relative links (CSS, images, JavaScript) resolve correctly when viewing the saved file locally.

### Atomic File Writing and Synchronization

The actual write operation occurs at lines 96-107 using `File.WriteAllText`. To handle asynchronous file-system delays, Ocaramba calls `FilesHelper.WaitForFileOfGivenName`, blocking execution until the file is visible on disk. This guarantees the file exists before subsequent operations or test teardown.

### Logging and CI Integration

Lines 107-109 implement dual logging: the file path is recorded via NLog, and a TeamCity artifact command is printed to the console. This allows CI/CD pipelines to automatically collect page source files as build artifacts without additional configuration.

## Automatic Capture on Verification Failures

Ocaramba integrates page source saving with its assertion framework through `Verify.That()` in [`OcarambaLite/Verify.cs`](https://github.com/accenture/ocaramba/blob/main/OcarambaLite/Verify.cs) (lines 1002-1005). When the `enableSavePageSource` parameter is set to **true** and an assertion throws an exception, the framework automatically invokes `driverContext.SavePageSource(driverContext.TestTitle)`, using the test name as the filename.

## Practical Implementation Examples

Manual invocation provides flexibility for debugging specific application states:

```csharp
using Ocaramba;
using NUnit.Framework;

[TestFixture]
public class SampleTests : ProjectTestBase
{
    [Test]
    public void SearchPage_ShouldContainResults()
    {
        // Navigate to page
        DriverContext.GoToUrl("https://example.com/search?q=ocaramba");

        // Manually save the page source (optional)
        var path = DriverContext.SavePageSource("SearchResults");
        TestContext.WriteLine($"Page source saved to: {path}");

        // Verify something – enable automatic source capture on failure
        Verify.That(DriverContext, () => Assert.IsTrue(
            DriverContext.Driver.PageSource.Contains("Expected text")),
            enableScreenShot: false,
            enableSavePageSource: true);
    }
}

```

The `DriverContext.SavePageSource("SearchResults")` call writes HTML to the folder defined by `BaseConfiguration.PageSourceFolder`. Setting `enableSavePageSource: true` in `Verify.That()` ensures automatic capture if the assertion fails.

## Summary

- **Configuration-driven**: Ocaramba uses `BaseConfiguration.GetPageSourceEnabled` (default: true) and `BaseConfiguration.PageSourceFolder` to control the feature.
- **Safe file handling**: The `SavePageSource` method in [`DriverContextHelper.cs`](https://github.com/accenture/ocaramba/blob/main/DriverContextHelper.cs) sanitizes filenames, handles existing files, and uses `FilesHelper.WaitForFileOfGivenName` for synchronization.
- **Enhanced HTML**: Injected `<base>` tags (referencing `BaseConfiguration.Host`) ensure relative links work in saved files.
- **CI-ready**: Automatic NLog entries and TeamCity artifact commands support continuous integration workflows.
- **Failure integration**: The `Verify.That()` helper automatically triggers page source saving when assertions fail and `enableSavePageSource` is enabled.

## Frequently Asked Questions

### How do I enable page source saving in Ocaramba?

Page source saving is enabled by default via the `GetPageSourceEnabled` setting in [`BaseConfiguration.cs`](https://github.com/accenture/ocaramba/blob/main/BaseConfiguration.cs) (lines 716-730). To disable it, set the `GetPageSourceEnabled` key to `false` in your appSettings configuration file. The framework checks this flag before executing any save operations.

### Where does Ocaramba save the HTML page source files?

Ocaramba writes files to the directory specified by `BaseConfiguration.PageSourceFolder` (lines 669-679 in [`BaseConfiguration.cs`](https://github.com/accenture/ocaramba/blob/main/BaseConfiguration.cs)). If this configuration is not explicitly set, the framework uses a default location relative to the test execution directory. The `SavePageSource` method in [`DriverContextHelper.cs`](https://github.com/accenture/ocaramba/blob/main/DriverContextHelper.cs) handles the actual file path construction.

### Can I automatically capture page source when tests fail?

Yes. Pass `enableSavePageSource: true` to the `Verify.That()` method in [`OcarambaLite/Verify.cs`](https://github.com/accenture/ocaramba/blob/main/OcarambaLite/Verify.cs) (lines 1002-1005). When an assertion within the verification block throws an exception, Ocaramba automatically calls `SavePageSource` using the test title as the filename. This eliminates the need to manually wrap assertions in try-catch blocks.

### Does Ocaramba modify the HTML content before saving?

Yes. Before writing the file, Ocaramba injects a `<base>` tag into the HTML that points to `BaseConfiguration.Host` (lines 101-104 in [`DriverContextHelper.cs`](https://github.com/accenture/ocaramba/blob/main/DriverContextHelper.cs)). This modification ensures that relative URLs for stylesheets, images, and scripts resolve correctly when you open the saved HTML file locally in a browser.