Selenium Foundation is an automation framework designed to extend and enhance the capabilities provided by Selenium (WebDriver).
Selenium Foundation includes support for both Selenium 2 and Selenium 3. This project has transitioned from Maven to Gradle so that both configurations can be handled by a single project definition file.
The Maven group ID is com.nordstrom.ui-tools, and the artifact ID is selenium-foundation. Artifacts whose versions have the s2 suffix support the Selenium 2 API. Artifacts whose versions have the s3 suffix support the Selenium 3 API.
To add a dependency on Selenium Foundation for Maven, use the following:
<dependency>
<groupId>com.nordstrom.ui-tools</groupId>
<artifactId>selenium-foundation</artifactId>
<!-- either Selenium 2 support: -->
<version>18.3.0-s2</version>
<!-- or Selenium 3 support: -->
<version>18.3.0-s3</version>
</dependency>To add a dependency for Gradle:
dependencies {
// either Selenium 2 support:
compile 'com.nordstrom.ui-tools:selenium-foundation:18.3.0-s2'
// or Selenium 3 support:
compile 'com.nordstrom.ui-tools:selenium-foundation:18.3.0-s3'
}For Eclipse, we recommend enabling Gradle integration through the official BuildShip plugin. By default, this project will build it's Selenium 3 configuration. To build the Selenium 2 configuration, add this program argument to the run configuration for the build task:
-Pprofile=selenium2
Both configurations of Selenium Foundation can by built from the command line.
gradle build# build Selenium 3 configuration
gradle build -Pprofile=selenium2# build Selenium 2 configuration
Use the install task to install SNAPSHOT builds in your local Maven repository:
gradle install# build Selenium 3 configuration
gradle install -Pprofile=selenium2# build Selenium 2 configuration
Although Gradle is used to produce official releases, Selenium Foundation also includes a fully-functional Maven POM file.
mvn package -Pselenium3# build Selenium 3 configuration
mvn package -Pselenium2# build Selenium 2 configuration
Note that the version number in this POM file is merely a placeholder - a token that gets replaced during the normal build process. Finalized, functional POMs can be found within the Selenium Foundation JARs themselves at META-INF\maven\com.nordstrom.ui-tools\selenium-foundation\pom.xml
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 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 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, and FrameMap) 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. Feature parity is enabled by several core abstractions, and through features provided by the TestNG Foundation and JUnit Foundation libraries.
There are several required elements that must be included in every TestNG test class to activate the features of Selenium Foundation. To assist you in this process, we've included the TestNgBase class as a starter. This class includes all of the required elements outlined below, and adds the ScreenshotCapture and PageSourceCapture listeners.
TestNgBase is an abstract class that implements the TestBase interface, which provides a common abstraction for both TestNG and JUnit 4 tests.
The following is an outline of the elements that must be included in every TestNG test that uses Selenium Foundation:
- ListenerChain:
ListenerChain is a TestNG listener that enables you to add other listeners at runtime and guarantees the order in which they're invoked. This is similar in behavior to a JUnit 4 rule chain. - The @LinkedListeners annotation:
To attach listeners to an active ListenerChain, mark your test class with the@LinkedListenersannotation. The TestNgBase class is marked with a@LinkedListenersannotation that specifies four listeners that manage several core features of Selenium Foundation:- ScreenshotCapture:
ScreenshotCapture is a TestNG listener that automatically captures screenshots in the event of test failures. Tests are also able to request on-demand screenshot capture through thecaptureArtifact(ITestResult)method. - PageSourceCapture:
PageSourceCapture is a TestNG listener that automatically captures page source in the event of test failures. Tests are also able to request on-demand page source capture through thecaptureArtifact(ITestResult)method. - DriverListener:
DriverListener is a TestNG listener that manages driver sessions and local Selenium Grid servers. - ExecutionFlowController:
ExecutionFlowController is a TestNG listener that propagates test context attributes:
[before method] → [test method] → [after method]
- ScreenshotCapture:
The @LinkedListeners annotation is processed by the ListenerChain, which must be activated so that the other core listeners will be connected and functioning correctly. Although you can use the standard TestNG @Listeners annotation to activate ListenerChain, we recommend that you use the ServiceLoader mechanism for this purpose in your actual project. This is the technique employed by the test suite of the Selenium Foundation project. For details, see Selenium Foundation Test Support.
Selenium Foundation includes a context-specific extension of the RetryManager analyzer of TestNG Foundation. This retry analyzer considers any test that fails due to a WebDriverException to be retriable. By default, this retry analyzer is disabled. To enable automatic retry of WebDriverException failures, specify a positive value for the MAX_RETRY setting of TestNG Foundation:
| testng.properties |
|---|
| testng.max.retry=2 |
The base class for this retry analyzer enables you to add your own analyzers through the ServiceLoader. You can also entirely replace this analyzer with your own. See the TestNG Foundation documentation for more details.
The QuickStart class demonstrates several important Selenium Foundation features:
- InitialPage:
InitialPage is a Java annotation that enables you to specify the initial page class and/or URL that should be loaded at the start of the test method. This can be applied to each test individually, or it can be applied at the class level to specify the default page for all tests in the class. It can also be applied to@Before...configuration methods to provide driver sessions opened to the desired page. - SeleniumConfig:
SeleniumConfig declares settings and methods related to Selenium WebDriver and Grid configuration. This class is built on the Settings API, composed of defaults, stored values, and System properties. - SeleniumSettings:
SeleniumSettings declares the constants, property names, and default values for the settings managed by SeleniumConfig. Defaults can be overridden via System properties or the settings.propeties file in your user "home" directory. See ESSENTIAL SETTINGS below for more details. - ReporterAppender:
ReporterAppender is a Logback appender for TestNG Reporter. The Selenium Foundation project ships with a logback.xml file that attaches this appender. See the complete logback-testng information page here. TestBase.optionalOf(Object):
This static utility method wraps the specified object in an Optional object. If the object to be wrapped is 'null', this method returns an empty optional.
In the preceding section, driver sessions are acquired automatically for each test or requested implicitly by applying the @InitialPage annotation. The core functionality used to initiate driver sessions implicitly can also be invoked ad hoc to acquire drivers explicitly:
WebDriver driver = GridUtility.getDriver();This method uses the configured settings for Selenium Grid and desired browser from the current test execution context to instantiate a new driver session.
If the @InitialPage annotation is applied to a @BeforeMethod configuration method, the driver instantiated for this method is automatically handed off to the test that follows. The initial page as specified for the configuration method is handed off as well. If actions performed by your configuration method trigger page transitions, you need to store the final page accessed by the configuration method as the initial page for the test method:
@BeforeMethod
@InitialPage(LoginPage.class)
public void logInBeforeTest() {
LoginPage loginPage = (LoginPage) getInitialPage();
MainMenuPage mainMenuPage = loginPage.logInAs(USER.StandardUser);
// update initial page for test method
setInitialPage(mainMenuPage);
}
@Test
public void testMenuFeatures() {
MainMenuPage mainMenuPage = (MainMenuPage) getInitialPage();
...
}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.
| Constant | Property Name | Default |
|---|---|---|
| BROWSER_NAME | selenium.browser.name | (none) * |
| TARGET_HOST | selenium.target.host | localhost |
| TARGET_PATH | selenium.target.path | / |
* NOTE: By default, HtmlUnit is selected as the browser. For easier override, this is specified through BROWSER_CAPS instead of BROWSER_NAME. For details, see Manipulate Settings with SeleniumConfig.
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.
In addition to the TestNG support documented above, Selenium Foundation also includes support for JUnit 4. This support is built upon JUnit Foundation, which provides the framework for method interception (used for driver management), artifact capture (used to acquire screenshots and page source), and automatic retry of failed tests.
There are several required elements that must be included in every JUnit 4 test class to activate the features of Selenium Foundation. To assist you in this process, we've included the JUnitBase class as a starter. This class includes all of the required elements outlined below.
JUnitBase is an abstract class that implements the TestBase interface, which provides a common abstraction for both TestNG and JUnit 4 tests.
The following is an outline of the elements that must be included in every JUnit 4 project that uses Selenium Foundation:
- JUnit Foundation event notifications:
The JUnit support provided by Selenium Foundation relies on event notifications published by JUnit Foundation. Notifications are enabled by a Java agent, which uses bytecode enhancement to install hooks on test and configuration methods.
<plugins>
<!-- This provides the path to the Java agent -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>3.1.1</version>
<executions>
<execution>
<id>getClasspathFilenames</id>
<goals>
<goal>properties</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.22.0</version>
<configuration>
<argLine>-javaagent:${com.nordstrom.tools:junit-foundation:jar}</argLine>
</configuration>
</plugin>
</plugins>ext {
junitFoundation = configurations.compile.resolvedConfiguration.resolvedArtifacts.find { it.name == 'junit-foundation' }
}
test.doFirst {
jvmArgs "-javaagent:${junitFoundation.file}"
}- DriverWatcher:
DriverWatcher implements the JUnit Foundation MethodWatcher interface to manage driver sessions. It provides initial page support, and it also supplies a JUnit 4 TestWatcher:DriverWatcher.getTestWatcher():
The test rule returned by this static method is responsible for closing the driver attached to the current test method.
- DriverListener:
DriverListener implements the JUnit Foundation ShutdownListener interface to shut down the local Selenium Grid serves at the end of the run. - RuleChain:
Use RuleChain for attaching test rules that must be applied in a specific order. The JUnitBase class includes a RuleChain that specifies three watchers that manage core features of Selenium Foundation:- ScreenshotCapture:
ScreenshotCapture is a JUnit 4 test watcher that automatically captures a screenshot in the event of test failure. - PageSourceCapture:
PageSourceCapture is a JUnit 4 test watcher that automatically captures page source in the event of test failures. - DriverWatcher:
As described previously, the test watcher returned byDriverWatcher.getTestWatcher()closes the driver attached to the current test method.
- ScreenshotCapture:
Selenium Foundation includes an implementation of the JUnitRetryAnalyzer interface of JUnit Foundation. This retry analyzer considers any test that fails due to a WebDriverException to be retriable. By default, this retry analyzer is disabled. To enable automatic retry of WebDriverException failures:
- Add a service loader retry analyzer configuration file in the META-INF/services folder:
com.nordstrom.automation.selenium.junit.RetryAnalyzer
- Specify a positive value for the MAX_RETRY setting of JUnit Foundation:
| junit.properties |
|---|
| junit.max.retry=2 |
In this example, these two configurations will enable JUnit Foundation to retry tests that fail with WebDriverException twice before counting them as failures. See the JUnit Foundation documentation for more details.
The JUnitBase class demonstrates several features of the Selenium Foundation API:
TestBase.optionalOf(Object):
This static utility method wraps the specified object in an Optional object. If the object to be wrapped is 'null', this method returns an empty optional.RuleChainWalker.getAttachedRule(RuleChain, Class<T extends TestRule>):
This static utility method gets reference to an instance of the specified test rule type on the supplied rule chain. In JUnitBase, this is used to acquire a reference to the ScreenshotCapture watcher for capturing on-demand screenshot artifacts.ScreenshotCapture.getAtomIdentity():
This instance method of ScreenshotCapture enables test code to acquire the AtomIdentity object for the current JUnit 4 test method. This object can be interrogated for many useful propeties of the test method, including test class instance, Description object, and instance parameters.ScreenshotCapture.getDescription():
This instance method of ScreenshotCapture enables test code to acquire the Description object for the current JUnit 4 test method. This object can be interrogated for many useful propeties of the test method, including method name, attached annotations, and containing class.
All of the features of Selenium Foundation are available regardless of which testing framework you choose - either TestNG or JUnit 4. 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).