Element Location and WebDriver Extensions

This page details the mechanisms Ocaramba uses to locate elements and extend the standard Selenium IWebDriver and IWebElement interfaces. The framework provides a robust layer on top of Selenium to handle common synchronization issues, such as AJAX loading, Angular synchronization, and stale element exceptions.

Element Location System

Ocaramba abstracts Selenium's By selectors into the ElementLocator class and a Locator enumeration. This allows for more readable page objects and provides a foundation for advanced features like locator formatting.

Locator Enum

The Locator enum defines the standard search strategies supported by the framework, including Id, ClassName, CssSelector, LinkText, Name, PartialLinkText, TagName, and XPath OcarambaLite/Locator.cs33-68 It also includes Appium-specific strategies such as AccessibilityId, AndroidUIAutomator, IOSNsPredicate, and IOSClassChain OcarambaLite/Locator.cs71-77

ElementLocator Class

The ElementLocator class stores a search strategy and a value. It is typically used within Page Objects to define elements Ocaramba.Tests.PageObjects/PageObjects/TheInternet/IFramePage.cs38-42

Key Features:

• ToBy(): An extension method in LocatorExtensions that converts the ElementLocator into a Selenium By or Appium MobileBy object OcarambaLite/Extensions/LocatorExtensions.cs43-96
• Format(): Allows for dynamic locators by replacing placeholders in the locator string (e.g., //div[text()='{0}']) using string.Format OcarambaLite/Types/ElementLocator.cs115-121

Code Entity Association: Locators

The following diagram illustrates how natural language locator definitions map to the internal code structures.

Locator Definition Flow

Sources: OcarambaLite/Locator.cs28-79 OcarambaLite/Types/ElementLocator.cs32-121 OcarambaLite/Extensions/LocatorExtensions.cs32-98

---

SearchContext Extensions (GetElement)

The SearchContextExtensions class provides the primary way to interact with elements. It extends ISearchContext (implemented by both IWebDriver and IWebElement), allowing these methods to be called on the driver or from within another element.

GetElement Implementation

The GetElement method is the core of Ocaramba's element retrieval. It includes:

1. Angular Synchronization: If DriversCustomSettings.IsDriverSynchronizationWithAngular is true, it calls driver.WaitForAngular() before searching OcarambaLite/Extensions/SearchContextExtensions.cs129-132
2. Built-in Waits: Uses WebDriverWait with configurable timeouts (defaulting to BaseConfiguration.LongTimeout or BaseConfiguration.ShortTimeout) OcarambaLite/Extensions/SearchContextExtensions.cs56-57
3. Stale Element Retry: Automatically ignores StaleElementReferenceException by adding it to the wait's ignore list OcarambaLite/Extensions/SearchContextExtensions.cs137-144
4. Custom Conditions: Supports custom predicates (e.g., e => e.Displayed && e.Enabled) to ensure the element is ready for interaction OcarambaLite/Extensions/SearchContextExtensions.cs126-147

GetElements Implementation

The GetElements method returns a ReadOnlyCollection<IWebElement>. It can also accept conditions and timeouts to wait for a collection of elements to meet specific criteria OcarambaLite/Extensions/SearchContextExtensions.cs181-205

Sources: OcarambaLite/Extensions/SearchContextExtensions.cs40-205 OcarambaLite/Extensions/LocatorExtensions.cs43-96

---

WebDriver Extensions

The WebDriverExtensions class provides utility methods for common browser interactions that are not natively part of the IWebDriver interface.

Method	Description
NavigateTo(Uri)	Navigates to a URL and handles IE certificate warnings OcarambaLite/Extensions/WebDriverExtensions.cs60-65
WaitForAjax()	Uses JavaScript to wait until jQuery.active == 0 OcarambaLite/Extensions/WebDriverExtensions.cs71-97
JavaScriptAlert()	Returns a JavaScriptAlert handle for simple alert/confirm management OcarambaLite/Extensions/WebDriverExtensions.cs50-53
IsElementPresent()	Returns a boolean indicating if an element exists and is displayed within a custom timeout OcarambaLite/Extensions/WebDriverExtensions.cs111-126
IsPageTitle()	Checks if the current page title matches the expected string within a timeout OcarambaLite/Extensions/WebDriverExtensions.cs140-155
WaitUntilElementIsNoLongerFound()	Polls until an element is removed from the DOM or hidden OcarambaLite/Extensions/WebDriverExtensions.cs166-171

WebDriver Interaction Flow

This diagram shows how WebDriverExtensions bridge the gap between high-level test actions and the underlying Selenium/JavaScript execution.

WebDriver Extension Execution

Sources: OcarambaLite/Extensions/WebDriverExtensions.cs38-171 OcarambaLite/WebElements/JavaScriptAlert.cs30-60

---

WebElement Extensions

Extensions for IWebElement focus on simplifying common interactions and improving reliability via JavaScript execution.

• JavaScriptClick(): Clicks an element using JavaScript, bypassing standard Selenium click interception issues OcarambaLite/Extensions/WebElementExtensions.cs77-86
• SetAttribute(): Directly modifies a DOM attribute of an element using JavaScript OcarambaLite/Extensions/WebElementExtensions.cs58-71
• GetTextContent(): Retrieves the textContent attribute of an element, which includes hidden text not normally returned by IWebElement.Text OcarambaLite/Extensions/WebElementExtensions.cs96-106
• IsElementTextEqualsToExpected(): Performs a string comparison between the element's text and an expected value OcarambaLite/Extensions/WebElementExtensions.cs41-44

Element-Level Screenshots

The TakeScreenShot helper allows capturing a specific element rather than the entire browser window. It casts the IWebElement to ITakesScreenshot to call GetScreenshot() OcarambaLite/Helpers/TakeScreenShot.cs50-59

Sources: OcarambaLite/Extensions/WebElementExtensions.cs31-108 OcarambaLite/Helpers/TakeScreenShot.cs33-60 Ocaramba.Tests.PageObjects/PageObjects/TheInternet/IFramePage.cs49-71

---

Mobile Extensions (Appium)

For mobile testing, Ocaramba supports specialized locators and context switching within Page Objects and tests.

• Mobile Locators: LocatorExtensions.ToBy handles AccessibilityId, AndroidUIAutomator, and iOS-specific class chains OcarambaLite/Extensions/LocatorExtensions.cs72-89
• Context Switching: Tests can switch between native and web contexts using DriverContext methods like SwitchToWebView() and SwitchToNative() Ocaramba.Tests.Appium/UnitTest1.cs37-39
• Appium Sample Usage: The AppiumSamplePage demonstrates using ElementLocator with Locator.AccessibilityId to interact with mobile elements Ocaramba.Tests.Appium/AppiumSamplePage.cs15-16

Sources: OcarambaLite/Extensions/LocatorExtensions.cs72-89 Ocaramba.Tests.Appium/AppiumSamplePage.cs13-64 Ocaramba.Tests.Appium/UnitTest1.cs11-45