How to Use WaitForAngular in Ocaramba: Automatic Angular Synchronization

WaitForAngular in Ocaramba is an IWebDriver extension method that pauses test execution until Angular’s pending HTTP requests complete, and can be invoked manually or enabled globally via SynchronizeWithAngular for automatic synchronization before every element interaction.

The Ocaramba framework, an open-source C# test automation library maintained by Accenture, provides built-in support for Angular applications through the WaitForAngular mechanism. This feature ensures that Selenium WebDriver never interacts with a page while Angular is still processing asynchronous $http requests, eliminating race conditions in end-to-end tests.

How WaitForAngular Works

The implementation relies on a JavaScript polling mechanism that checks Angular’s internal state. When enabled, Ocaramba automatically intercepts element lookup calls to ensure the page is stable before proceeding.

Core Components

• WebDriverExtensions.WaitForAngular – Located in [OcarambaLite/Extensions/WebDriverExtensions.cs](https://github.com/accenture/ocaramba/blob/master/OcarambaLite/Extensions/WebDriverExtensions.cs#L73-L95), this method executes a JavaScript snippet that verifies window.angular exists and checks the length of $http.pendingRequests. It uses WebDriverWait with a configurable timeout (defaulting to BaseConfiguration.MediumTimeout), retrying until the pending request count reaches zero or the timeout expires.

• DriversCustomSettings – Defined in [OcarambaLite/DriversCustomSettings.cs](https://github.com/accenture/ocaramba/blob/master/OcarambaLite/DriversCustomSettings.cs#L31-L66), this class maintains a dictionary mapping each IWebDriver instance to a Boolean flag indicating whether Angular synchronization is enabled. The flag is manipulated via SetAngularSynchronizationForDriver and read via IsDriverSynchronizationWithAngular.

• SearchContextExtensions – Found in [OcarambaLite/Extensions/SearchContextExtensions.cs](https://github.com/accenture/ocaramba/blob/master/OcarambaLite/Extensions/SearchContextExtensions.cs#L28-L33), Ocaramba’s element-search helpers (such as GetElement) check the synchronization flag before every lookup. When enabled, they automatically invoke driver.WaitForAngular() to ensure the DOM is ready for interaction.

How to Use WaitForAngular

You can invoke WaitForAngular explicitly for one-off waits or enable automatic synchronization globally for an entire test session.

Manual One-Off Wait

Call the extension method directly after navigating to an Angular page or triggering an asynchronous operation. The default timeout uses BaseConfiguration.MediumTimeout, but you can specify a custom value in seconds.

using Ocaramba.Extensions;

// Wait with default timeout
driver.WaitForAngular();

// Wait with custom 30-second timeout
driver.WaitForAngular(30);

Enable Automatic Synchronization

To automatically wait for Angular before every element interaction, enable synchronization via the SynchronizeWithAngular wrapper. Once activated, all Ocaramba extension methods (like GetElement and GetElements) will invoke WaitForAngular internally.

// Enable global Angular synchronization
driver.SynchronizeWithAngular(true);

// Subsequent element lookups automatically wait for Angular
var loginButton = driver.GetElement(PageObjects.LoginButton, 10);
loginButton.Click();  // Safe: Ocaramba waited for pending requests to finish

Disable Synchronization

When navigating to non-Angular pages or when you no longer need automatic waiting, disable the flag to prevent unnecessary JavaScript execution.

// Turn off automatic Angular synchronization
driver.SynchronizeWithAngular(false);

// Element searches will no longer invoke WaitForAngular automatically

Complete NUnit Test Example

The following example demonstrates a full test class that enables Angular synchronization during setup, allowing test methods to interact with elements without explicit waits.

using NUnit.Framework;
using OpenQA.Selenium;
using OpenQA.Selenium.Chrome;
using Ocaramba.Extensions;

[TestFixture]
public class AngularSearchTests
{
    private IWebDriver driver;

    [SetUp]
    public void SetUp()
    {
        driver = new ChromeDriver();
        driver.Navigate().GoToUrl("https://my-angular-app.example.com");
        
        // Enable automatic Angular synchronization for this driver
        driver.SynchronizeWithAngular(true);
    }

    [Test]
    public void SearchShouldReturnResults()
    {
        // GetElement automatically waits for Angular due to synchronization setting
        var searchBox = driver.GetElement(PageObjects.SearchBox, 5);
        searchBox.SendKeys("ocaramba");
        
        driver.GetElement(PageObjects.SearchButton, 5).Click();

        // No explicit WaitForAngular needed here
        var results = driver.GetElements(PageObjects.SearchResultItems, 10);
        Assert.IsNotEmpty(results);
    }

    [TearDown]
    public void TearDown()
    {
        driver.Quit();
    }
}

Summary

• WaitForAngular is an extension method in WebDriverExtensions.cs that polls window.angular until $http.pendingRequests is empty.
• Automatic synchronization is controlled via DriversCustomSettings and enabled through driver.SynchronizeWithAngular(true).
• When enabled, element lookups in SearchContextExtensions.cs automatically invoke WaitForAngular before returning elements.
• You can override the default timeout by passing an integer parameter to WaitForAngular(seconds).
• Always disable synchronization (SynchronizeWithAngular(false)) when testing non-Angular pages to avoid JavaScript errors.

Frequently Asked Questions

What is the default timeout for WaitForAngular in Ocaramba?

The default timeout is determined by BaseConfiguration.MediumTimeout. You can override this by passing a custom integer value representing seconds to the WaitForAngular(int timeout) overload.

How does Ocaramba detect when Angular is ready?

According to the source code in WebDriverExtensions.cs, Ocaramba executes a JavaScript command that checks for the existence of window.angular and evaluates the length of $http.pendingRequests. The method returns true only when the pending request array is empty, indicating the application is stable.

Can I use WaitForAngular with non-Angular applications?

No, attempting to use WaitForAngular on non-Angular pages will cause errors because the JavaScript relies on the global window.angular object. For non-Angular sites, disable synchronization via driver.SynchronizeWithAngular(false) or use standard Selenium WebDriver waits.

Where is the WaitForAngular implementation located in the source code?

The primary implementation resides in [OcarambaLite/Extensions/WebDriverExtensions.cs](https://github.com/accenture/ocaramba/blob/master/OcarambaLite/Extensions/WebDriverExtensions.cs#L73-L95). The synchronization state management is handled in [OcarambaLite/DriversCustomSettings.cs](https://github.com/accenture/ocaramba/blob/master/OcarambaLite/DriversCustomSettings.cs#L31-L66), and the automatic invocation logic is found in [OcarambaLite/Extensions/SearchContextExtensions.cs](https://github.com/accenture/ocaramba/blob/master/OcarambaLite/Extensions/SearchContextExtensions.cs#L28-L33).

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