Angular Application Testing

This page documents the Ocaramba.Tests.Angular project and the framework's specialized support for testing Angular-based web applications. Ocaramba provides built-in synchronization mechanisms to handle the asynchronous nature of Angular (formerly known as Protractor-like synchronization) without requiring external dependencies like Protractor.

Angular Synchronization Overview

Testing Angular applications often results in "flaky" tests due to background asynchronous tasks (like $http requests or timeouts). Ocaramba addresses this by injecting JavaScript into the browser to monitor the Angular state and blocking WebDriver execution until the application is stable.

Key Components

Component	Description
SynchronizeWithAngular	A configuration flag in BaseConfiguration and an extension method to enable/disable synchronization globally or per session.
Driver.WaitForAngular()	An extension method that executes JavaScript to wait for Angular's testability API.
DriversCustomSettings	A helper class in OcarambaLite that tracks the synchronization state for specific driver instances.

Data Flow: Synchronization Logic

The following diagram illustrates how Ocaramba intercepts element location requests to ensure Angular is synchronized before interacting with the DOM.

Angular Sync Sequence

Sources: OcarambaLite/Extensions/SearchContextExtensions.cs128-147 Ocaramba.Tests.Angular/PageObjects/ProtractorHomePage.cs26

---

Configuration and Extension Methods

BaseConfiguration

The framework uses configuration files to define default synchronization behavior.

• SynchronizeWithAngular: When set to true in BaseConfiguration, the framework automatically attempts to wait for Angular before every GetElement call.
• Environment Specifics: The Ocaramba.Tests.Angular project includes appsettings.json Ocaramba.Tests.Angular/appsettings.json1-31 and appsettings.Linux.json Ocaramba.Tests.Angular/appsettings.Linux.json1-10 to manage settings across different execution environments.

WebDriver Extensions

The WebDriverExtensions class provides the core logic for interacting with Angular:

• SynchronizeWithAngular(bool enable): Sets a flag for the current driver instance. This is explicitly called in the ProtractorHomePage to initiate synchronization Ocaramba.Tests.Angular/PageObjects/ProtractorHomePage.cs26
• WaitForAngular(): The primary mechanism for synchronization. It injects a JavaScript snippet that checks for Angular testability and waits until all pending asynchronous tasks are finished.

Sources: OcarambaLite/Extensions/SearchContextExtensions.cs128-132 Ocaramba.Tests.Angular/PageObjects/ProtractorHomePage.cs26 Ocaramba.Tests.Angular/Ocaramba.Tests.Angular.csproj35-40

---

Angular Page Objects

The Ocaramba.Tests.Angular project serves as a reference implementation for testing Angular sites. These page objects inherit from ProjectPageBase Ocaramba.Tests.Angular/PageObjects/ProtractorHomePage.cs12

Code Entity Mapping

The following diagram bridges the Page Object classes to their functional roles within the Angular testing suite.

Angular Page Object Space

Sources: Ocaramba.Tests.Angular/PageObjects/ProtractorHomePage.cs12-47 Ocaramba.Tests.Angular/PageObjects/TutorialPage.cs10-34 Ocaramba.Tests.Angular/PageObjects/TableOfContentsPage.cs10-31 Ocaramba.Tests.Angular/PageObjects/ProtractorApiPage.cs8-36

Implementation Details

ProtractorHomePage

This page demonstrates enabling synchronization during the navigation phase.

• OpenProtractorHomePage(): Calls this.Driver.SynchronizeWithAngular(true) before navigating to the URL defined in configuration Ocaramba.Tests.Angular/PageObjects/ProtractorHomePage.cs26-27
• ClickQuickStart(): Uses JavaScriptClick() on the QuickStart element (ID: drop1) Ocaramba.Tests.Angular/PageObjects/ProtractorHomePage.cs20 Ocaramba.Tests.Angular/PageObjects/ProtractorHomePage.cs36-40

ProtractorApiPage

Focuses on verifying elements that appear after Angular state changes.

• Locators: Uses Locator.CssSelector and Locator.XPath to find Angular-specific elements like elementToBeSelected Ocaramba.Tests.Angular/PageObjects/ProtractorApiPage.cs18-20
• IsElementToBeSelectedHeaderDisplayed(): Returns the Displayed property of an element, which internally triggers the Angular wait if synchronization is enabled Ocaramba.Tests.Angular/PageObjects/ProtractorApiPage.cs32-35

TableOfContentsPage

Handles navigation within the Angular documentation structure.

• ClickProtractorApi(): Locates an anchor tag within an Angular scope container ul[class='ng-scope'] Ocaramba.Tests.Angular/PageObjects/TableOfContentsPage.cs18-29

---

Angular Test Execution

The tests are implemented using NUnit and demonstrate a fluent interface for navigating through the Angular application.

Test Case Mapping

Sources: Ocaramba.Tests.Angular/Tests/AngularTestNunit.cs31-47

Technical Summary of Synchronization Implementation

Class	Method	Role
SearchContextExtensions	GetElement	Entry point for all element interactions; checks if WaitForAngular is needed OcarambaLite/Extensions/SearchContextExtensions.cs128-132
WebDriverExtensions	WaitForAngular	Executes the JavaScript wait script against the browser.
ProtractorHomePage	OpenProtractorHomePage	Explicitly enables Angular synchronization for the driver session Ocaramba.Tests.Angular/PageObjects/ProtractorHomePage.cs26

Sources:

• OcarambaLite/Extensions/SearchContextExtensions.cs128-132
• Ocaramba.Tests.Angular/PageObjects/ProtractorHomePage.cs12-47
• Ocaramba.Tests.Angular/PageObjects/ProtractorApiPage.cs8-36
• Ocaramba.Tests.Angular/PageObjects/TableOfContentsPage.cs10-31
• Ocaramba.Tests.Angular/PageObjects/TutorialPage.cs10-34
• Ocaramba.Tests.Angular/Tests/AngularTestNunit.cs31-47