INTRODUCTION

Selenium Foundation is an automation framework designed to extend and enhance the capabilities provided by Selenium (WebDriver).

* BREAKING NEWS *

• With the release of Selenium Foundation version 28.0.0, we now provide support for the Selenium 4 API. There are still a few rough edges, and HtmlUnitDriver sessions are not yet available from Selenium 4 Grid, but all major functionality is working as expected. The Selenium 4 artifacts are designated with the s4 suffix.
• With the release of Selenium Foundation version 26.3.4, automation of Macintosh native applications via the Mac2 engine of Appium is complete. The latest release of the local-grid-parent project (1.5.0) builds on the local grid feature of Selenium Foundation to launch grid collections that include Mac2 nodes.

Table of Contents

• Selenium API Support
• Dependency Artifact Coordinates
• Building Selenium Foundation
  • Building in Eclipse
  • Building from Command Line
  • Running Browser Unit Tests
• Getting Started
  • Required Configuration
• Highlights
  • Support for Appium Automation Engines
  • Requirements for Appium
  • Automatic Driver Targeting
  • Automatic Targeted Session Configuration
  • Support for Frame-Based Components and Shadow-DOM Hierarchies
  • Landing Page Verification and Model-Directed Navigation
  • Customizable Transition Error Detection
  • Component Collection Classes
  • Automatic Stale Element Reference Protection
  • Optional Elements
  • Page-Load Synchronization
  • Grid-Based Driver Creation
  • Automatic Phase-to-Phase Driver Hand-Off
  • Automatic Capture of Screenshots and Page Source
  • Support for TestNG and JUnit 4
  • Essential Settings
  • Overriding Defaults
  • Installing Drivers

In-Depth Documentation

• Welcome to Selenium Foundation
• Development Environment
• Configuring Project Settings
• Local Grid Configuration
• Customizing Capabilities
• TestNG Support
• JUnit 4 Support
• Target Platform Feature
• Building Page Objects
• Page Components
• Transition Error Detection
• JavaScript Enhancements

Selenium API Support

Selenium Foundation includes supports for both Selenium 4 and Selenium 3. A single Gradle project defines version-specific profiles to produce two separate artifacts.

Dependency Artifact Coordinates

The Maven group ID is com.nordstrom.ui-tools, and the artifact ID is selenium-foundation. Artifacts whose version numbers have the s4 suffix support the Selenium 4 API. Artifacts whose version numbers have the s3 suffix support the Selenium 3 API.

To add a dependency on Selenium Foundation for Maven, use the following:

  <groupId>com.nordstrom.ui-tools</groupId>
  <artifactId>selenium-foundation</artifactId>
  28.0.1-s3

  <groupId>com.nordstrom.ui-tools</groupId>
  <artifactId>selenium-foundation</artifactId>
  28.0.0-s4

To add a dependency for Gradle:

dependencies {
  compile 'com.nordstrom.ui-tools:selenium-foundation:28.0.1-s3'
}

dependencies {
  compile 'com.nordstrom.ui-tools:selenium-foundation:28.0.0-s4'
}

Building Selenium Foundation

In order to build Selenium Foundation, start by setting up your development environment.

Building in Eclipse

For Eclipse, we recommend enabling Gradle integration through the official BuildShip plug-in.

Learn more...

Building from Command Line

To build Selenium Foundation from the command line:

./gradlew build

Use the install task to install SNAPSHOT builds in your local Maven repository:

./gradlew install

Running Browser Unit Tests

By default, the unit tests that run after the build completes are the support feature tests (which don't require a browser). The Gradle project file provides a set of browser profiles, one for each supported browser. By specifying one of these profiles, you activate dependencies, settings, and driver plug-in for the corresponding browser.

./gradlew test -Pbrowsers=espresso # run Android Espresso unit tests
./gradlew test -Pbrowsers=firefox -Ppersonality=firefox.headless # run Mozilla Firefox unit tests in "headless" mode
./gradlew test -Pbrowsers=htmlunit -Ppersonality=htmlunit.nojs # run HtmlUnit unit tests without JavaScript support

The personality property directs Selenium Foundation to run the unit tests on browsers with the specified named capabilities. Available personalities are defined by each driver plug-in, and the list of personalities supported by the current Grid is shown in the console output. For example:

http://192.168.254.20:4445/wd/hub: Personalities => [chrome, chrome.headless]

A complete list of supported browser profiles can be found here,

Getting Started

The QuickStart class provides a fully-functional example of a test class built around Selenium Foundation, TestNG Foundation, and the Settings API. It demonstrates how to set up required elements and introduces several key features that you're likely to use on a regular basis.

Required Configuration

Selenium Foundation supports both TestNG and JUnit 4 frameworks, but the default configuration doesn't activate test lifecycle features for either of them. Choose your platform and apply the corresponding required configuration to your project:

• TestNG Required Configuration
• JUnit 4 Required Configuration

Highlights

Support for Appium Automation Engines

In addition to support for all of the standard Java-based browser drivers, the Local Grid feature of Selenium Foundation provides the ability to drive mobile and desktop applications via Appium. Driver plug-ins are available for all of the major automation engines, with the ability to customize out-of-the-box settings with configurable modifications and command line options.

Requirements for Appium

Unlike the other drivers supported by Selenium Foundation which are implemented in Java, the "engines" provided by Appium are implemented in NodeJS. To launch a Selenium Grid collection that includes Appium nodes, you'll need the following additional tools:

• Platform-specific Node Version Manager: The installation page for npm (below) provides links to recommended version managers.
• NodeJS (node): Currently, I'm running version 17.5.0
• Node Package Manager (npm): Currently, I'm running version 8.13.2
• Node Process Manager (pm2): Currently, I'm running version 5.2.0
• Appium: Currently, I'm running version 1.22.3

Typically, these tools must be on the system file path. However, you can provide specific paths for each of these via Selenium Foundation settings:

• NPM_BINARY_PATH: If unspecified, the PATH is searched
• NODE_BINARY_PATH: If unspecified, the NODE_BINARY_PATH environment variable is checked; if this is undefined, the PATH is searched
• PM2_BINARY_PATH: If unspecified, the PATH is searched
• APPIUM_BINARY_PATH: If unspecified, the APPIUM_BINARY_PATH environment variable is checked; if this is undefined, the PATH is searched

Automatic Driver Targeting

Selenium Foundation provides a complete set of base classes for building well-factored page models. This includes page components and frames. Selenium Foundation allows you to focus on modeling your application (instead of managing which window or frame the driver is addressing) by handling all driver targeting for you. You'll never see driver.switchTo(...) in page model automation built with Selenium Foundation, because the framework automatically ensures that the driver is addressing the window or frame associated with each page model method before it's invoked.

Automatic Targeted Session Configuration

Selenium Foundation provides a target platform feature that enables you to define collections of configurations that can be assigned to specific test methods. Prior to the start of each test, you have the chance to "activate" the assigned platform (e.g. - change screen dimensions).

Support for Frame-Based Components and Shadow-DOM Hierarchies

Selenium Foundation provides base classes for modeling frame-based components and shadow-DOM hierarchies. These base classes handle the specific details of interacting with these DOM features through the underlying Selenium API, managing search context and driver targeting for you. The implementation of your components will be totally dedicated to the functionality of the elements you're modeling - never cluttered with boilerplate code to switch driver focus or traverse into shadow hierarchies.

Landing Page Verification and Model-Directed Navigation

Page classes can be explicitly associated with web application paths through the @PageUrl annotation. These associations can be declared as either fixed paths or patterns, and these declarations are used by Selenium Foundation to verify landing page paths at page transitions. You can also perform direct navigation to web application paths associated with page classes through the @PageUrl annotation.

Customizable Transition Error Detection

In conjunction with automatic landing page verification, Selenium Foundation invokes registered custom transition error detectors. Implement the TransitionErrorDetector interface, then register your detectors in the corresponding service loader configuration file (META-INF/services/com.nordstrom.automation.selenium.interfaces.TransitionErrorDetector).

Examples of the sorts of conditions you may want to detect include error pages (e.g. - page not found) or non-context error messages (e.g. - communication issues, access token timeout). For recoverable conditions, error detectors can also server as error handler. For example, you could implement a detector that automatically logs back in if your test encounters an access timeout.

Component Collection Classes

Selenium Foundation also includes collection classes (ComponentList, ComponentMap, FrameList, FrameMap, ShadowRootList, and ShadowRootMap) that enable you to define collections of components for your page models. For example, you can define a SearchResultTile component and include a map of these tiles keyed by product ID in your SearchResultsPage class. Selenium Foundation collections are lazy-initialized automatically - the composition of the collection is determined when it's instantiated, but each item in the collection is only populated when it's explicitly referenced.

Automatic Stale Element Reference Protection

One of the most impactful features of Selenium Foundation saves your automation from the dreaded StaleElementReferenceException failure. Web element search operations performed within the Selenium Foundation framework return enhanced references, which retain all of the parameters needed to re-acquire the reference if it goes stale. Every web element method call is guarded by an automatic recovery feature. If a reference goes stale, Selenium Foundation re-acquires the reference and re-issues the web element method call that encountered the exception. Your automation continues on normally, blissfully unaware of the disaster that was averted.

Optional Elements

Another useful extension provided by Selenium Foundation is the optional element. This feature enables you to model elements that only exist on the page under specific conditions. For example, you can model an error message that only exists when a form is submitted with no value in a required field. Determining if the element exists is as easy as calling the hasReference() method of the optional element object.

Page-Load Synchronization

Selenium Foundation automatically synchronizes your automation with ordinary page transitions, ensuring that tests don't get tripped up by application hesitation. Synchronizing your automation with dynamic content creation is easily done by implementing a simple interface (DetectsLoadCompletion). This greatly simplifies the modeling of single-page applications and pages rendered with dynamic content loading.

Grid-Based Driver Creation

To avoid divergent behavior between local and remote execution, Selenium Foundation acquires driver sessions for local runs from a local instance of Selenium Grid. In addition to eliminating ordinary behavioral differences, this strategy provides two major benefits:

1. Adding support for a new driver is a simple configuration change - No need to crack open the code!
2. You get explicit control over the maximum number of concurrent sessions, so you can run your tests in parallel without over-taxing your system.

Automatic Phase-to-Phase Driver Hand-Off

Drivers allocated for per-test configuration setup methods (i.e. - @BeforeMethod) are automatically handed off to the tests for which configuration is being performed. Drivers allocated for tests are automatically handed off to per-test configuration cleanup methods (i.e. - @AfterMethod). This hand-off behavior greatly simplifies the implementation of generic setup and cleanup processing that interacts with your application under test.

Automatic Capture of Screenshots and Page Source

To assist in root-cause analysis, Selenium Foundation automatically captures a screenshot and page source for each failed test. By using the ReporterAppender, the log output of each TestNG test is captured as part of the test result object. This information is automatically shown on test result pages in Jenkins. No more digging through intermingled output in console logs!

Support for TestNG and JUnit 4

Selenium Foundation includes support for both TestNG and JUnit 4, enabled by several core abstractions, and through features provided by the TestNG Foundation and JUnit Foundation libraries.

All of the features of Selenium Foundation are available regardless of which testing framework you choose. Once the initial configuration is done, the abstraction provided by the TestBase interface enables your code to be almost entirely framework-agnostic. This is clearly demonstrated in ModelTestCore, which contains the implementations for a collection of tests that are invoked from both TestNG (via ModelTest) and JUnit 4 (via JUnitModelTest).

Learn more about...

• TestNG Support
• JUnit 4 Support

Essential Settings

You'll probably find that the defaults assigned to most settings will suffice in most basic scenarios. However, it's likely that you'll need to override one or more of the following. The Property Name column indicates the name of the System property associated with the setting. To override a setting, you can either add a line for the setting to your settings.properties file or define a System property.

* NOTE: To obtain instances of the "current" browser, you need to specify either BROWSER_CAPS or BROWSER_NAME. For details, see Configuring Project Settings.

Overriding Defaults

SeleniumConfig searches a series of locations for a settings.properties file. This file will typically be stored in your user "home" folder. Any settings declared in this file will override the defaults assigned in the SeleniumSettings enumeration. Settings that are declared as System properties will override both the defaults assigned by SeleniumSettings and settings declared in settings.properties. For example:

This sample settings.properties file overrides the values of TARGET_HOST and BROWSER_NAME. The latter can be overridden by System property declaration:

-Dselenium.browser.name=firefox

The hierarchy of evaluation produces the following results:

BROWSER_NAME = firefox; TARGET_HOST = my.server.com; TARGET_PATH = /

Installing Drivers

Whichever browser you choose to run your automation on, you need to make sure to install the latest driver for that browser compatible with your target version of Selenium WebDriver, along with a compatible release of the browser itself. We recommend that you install the drivers and browsers on the file search path to avoid the need to provide additional configuration details via scenario-specific means.

Here are the official homes for several of the major drivers:

• GhostDriver (PhantomJS) - http://phantomjs.org/download.html
• ChromeDriver - https://sites.google.com/a/chromium.org/chromedriver/downloads
• IEDriver - http://selenium-release.storage.googleapis.com/index.html?path=2.53/

NOTE: GhostDriver and ChromeDriver are simple binary installations, but several system configuration changes must be applied for IEDriver to work properly. For details, visit the InternetExplorerDriver project Wiki on GitHub and follow the Required Configuration procedure.

Written with StackEdit.