Selenium Foundation is an automation framework designed to extend and enhance the capabilities provided by Selenium (WebDriver).
- With the release of Selenium Foundation version 28.2.0, we now provide support for Appium sessions via Seleniun 4 Grid. The auto-generated configuration connects the Appium server to the local grid via a relay node.
- NOTE: To properly support HtmlUnitDriver, Appium, and Safari, this release includes new custom slot matcher (Selenium 4) and capabilities matcher (Selenium 3). These matchers are activated via a new setting, which can be easily overridden should the need arise.
- With the release of Selenium Foundation version 28.1.1, we now provide support for remote HtmlUnitDriver sessions with HtmlUnit Remote. The project unit tests for Selenium Foundation have been switched back to running under this "headless" browser.
- 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.
- Selenium API Support
- Dependency Artifact Coordinates
- Building Selenium Foundation
- Getting Started
- 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
- 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 Foundation includes supports for both Selenium 4 and Selenium 3. A single Gradle project defines version-specific profiles to produce two separate artifacts.
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:
| Selenium 3 | Selenium 4 |
|---|---|
<dependency> |
<dependency> |
To add a dependency for Gradle:
| Platform | Dependency |
|---|---|
| Selenium 3 | dependencies { |
| Selenium 4 | dependencies { |
In order to build Selenium Foundation, start by setting up your development environment.
For Eclipse, we recommend enabling Gradle integration through the official BuildShip plug-in.
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
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,
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.
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:
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.
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 22.7.0
- Node Package Manager (npm): Currently, I'm running version 10.8.2
- Node Process Manager (pm2): Currently, I'm running version 5.4.2
- Appium: Currently, I'm running version 2.11.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
PATHis searched - NODE_BINARY_PATH: If unspecified, the
NODE_BINARY_PATHenvironment variable is checked; if this is undefined, thePATHis searched - PM2_BINARY_PATH: If unspecified, the
PATHis searched - APPIUM_BINARY_PATH: If unspecified, the
APPIUM_BINARY_PATHenvironment variable is checked; if this is undefined, thePATHis searched
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.
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).
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.
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.
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.
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.
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.
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.
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.
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:
- Adding support for a new driver is a simple configuration change - No need to crack open the code!
- You get explicit control over the maximum number of concurrent sessions, so you can run your tests in parallel without over-taxing your system.
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.
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!
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).
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.
| Setting | Property Name | Default |
|---|---|---|
BROWSER_NAME |
selenium.browser.name |
(none) * |
TARGET_HOST |
selenium.target.host |
localhost |
TARGET_PATH |
selenium.target.path |
/ |
* NOTE: To obtain instances of the "current" browser, you need to specify either BROWSER_CAPS or BROWSER_NAME. For details, see Configuring Project Settings.
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:
| settings.properties |
|---|
| selenium.target.host=my.server.com |
| selenium.browser.name=chrome |
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 = /
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.