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

Ocaramba handles page source saving through the DriverContext.SavePageSource() method in 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.

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, 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 (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:

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 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 (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). 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 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 (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). This modification ensures that relative URLs for stylesheets, images, and scripts resolve correctly when you open the saved HTML file locally in a browser.

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