TestNGSupport.md

Introduction

In addition to its JUnit 4 support, Selenium Foundation also includes support for TestNG. This support is built upon TestNG 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.

TestNG Required Configuration

Add a service loader run watcher configuration file in the META-INF/services folder:

org.testng.ITestNGListener

com.nordstrom.automation.testng.ListenerChain

TestNG Required Elements

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.

Outline of Required Elements

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. This facility is activated by the service loader configuration specified above.
• The @LinkedListeners annotation:
  To attach listeners to an active ListenerChain, mark your test class with the @LinkedListeners annotation. The TestNgBase class is marked with a @LinkedListeners annotation that specifies four listeners that manage several core features of Selenium Foundation:
  • 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:
    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 the captureArtifact(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 the captureArtifact(ITestResult) method.

Automatic Retry of Failed Tests

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.

Demonstrated Features

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.

Driver Acquisition and Hand-Off

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 = getInitialPage();
    MainMenuPage mainMenuPage = loginPage.logInAs(USER.StandardUser);
    // update initial page for test method
    setInitialPage(mainMenuPage);
}

@Test
public void testMenuFeatures() {
    MainMenuPage mainMenuPage = getInitialPage();
    ...
}

Written with StackEdit.