Selenium Framework Design in Data-Driven Testing

The premise of data-driven testing is that test methods and test data are separated to allow the adding of new test permutations without changing the test methods, to reduce the amount of code, reduce the amount of maintenance required for testing, and to store common libraries in a central location—those being the page object classes. Data is encapsulated in a central location such as a database, JSON, or CSV file, property file, or an Excel spreadsheet, to name a few. Test methods then allow dynamic data to be passed into them on the fly using parameters and data providers of choice. The test methods themselves become "templates" for positive, negative, boundary, and/or limit testing, extending coverage of the suite of tests with limited code additions.

The Selenium Page Object Model is based on the programming concepts that a page object class should include all aspects of the page under test, such as the elements on the page, the methods for interacting with those elements, variables, and properties associated with the class. Following that concept, there is no data stored in the page object class. The test classes themselves call methods on the page object instances they are testing, but have no knowledge of the granular elements in the class. Finally, the actual test data is encapsulated outside the test class in a central location. In other words, there is an abstract layer created between the tests and the actual page object classes. This reduces the amount of code being written and allows them to be reused in various testing scenarios, thus following the DRY approaches to programming. From a maintenance point of view, changes to methods and locators are made in limited, central places, reducing the amount of time required to maintain ever-changing applications.

DRY approaches to creating page object and test classes simply mean promoting the use of common classes, locators, methods, and inheritance to eliminate and avoid repeating the same actions over and over in multiple places. Instead, abstract base classes are created, containing all common objects and methods, and used as libraries to be called using parameters, which vary based on the data that is passed into them from the test classes. All subclasses derived from these base classes inherit all the common code, objects, locators, and methods, and enforce all of the abstract methods required by the base class. In essence, this approach avoids common copy and paste actions that result in duplicate code in multiple places.

As per Wikipedia (https://en.wikipedia.org/wiki/Data-driven_testing):

Users will learn how to design and build the Java singleton class required to control the Selenium driver of choice for the Application Under Test (AUT).

In order to start building the framework, users must import the required JAR files into their project to use the Selenium WebDriver, AppiumDriver, and TestNG APIs. Additionally, there will be various Java JAR files required, such as Apache, Spring, File I/O, and other utilities as the framework develops:

import io.appium.java_client.AppiumDriver;
import io.appium.java_client.MobileElement;
import io.appium.java_client.android.AndroidDriver;
import io.appium.java_client.ios.IOSDriver;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.edge.EdgeDriver;
import org.openqa.selenium.edge.EdgeOptions;
import org.openqa.selenium.firefox.*;
import org.openqa.selenium.ie.InternetExplorerDriver;
import org.openqa.selenium.remote.DesiredCapabilities;
import org.openqa.selenium.remote.LocalFileDetector;
import org.openqa.selenium.remote.RemoteWebDriver;
import org.openqa.selenium.safari.SafariDriver;
import org.openqa.selenium.safari.SafariOptions;
import org.testng.*;

The class should be named something obvious such as Driver.java, CreateDriver.java, SeleniumDriver.java, and so on. Since this will be a Java singleton class, it will contain a private constructor and a static getInstance method as follows:

/**
 * Selenium Singleton Class
 *
 * @author CarlCocchiaro
 *
 */
@SuppressWarnings("varargs")
public class CreateDriver {

    // constructor
    private CreateDriver() {
    }

    /**
     * getInstance method to retrieve active driver instance
     *
     * @return CreateDriver
     */
    public staticCreateDriver getInstance() {
        if ( instance == null ) {
            instance = new CreateDriver();
        }

        return instance;
    }
}

Initially, when building the class, there will be various private and public variables used that should be declared at the top of the class. This organizes the variables into one place in the file, but of course, this is a coding style guideline. Some of the common variables required to start are as follows:

public class CreateDriver {
    // local variables
    private static CreateDriver instance = null;
    private String browserHandle = null;
    private static final int IMPLICIT_TIMEOUT = 0;

    private ThreadLocal<WebDriver> webDriver =
            new ThreadLocal<WebDriver>();

    private ThreadLocal<AppiumDriver<MobileElement>> mobileDriver =
            new ThreadLocal<AppiumDriver<MobileElement>>();

    private ThreadLocal<String> sessionId =
            new ThreadLocal<String>();

    private ThreadLocal<String> sessionBrowser =
            new ThreadLocal<String>();

    private ThreadLocal<String> sessionPlatform =
            new ThreadLocal<String>();

    private ThreadLocal<String> sessionVersion =
            new ThreadLocal<String>();

    private String getEnv = null;
}

Before introducing the common methods in this driver class, it is prudent to note that requiring JavaDoc for all methods in the class will be helpful for users who are learning the framework. The JavaDoc can be built automatically in Java using a build tool such as Maven, Gradle, or Ant. An example of the JavaDoc format is as follows:

/**
 * This is the setDriver method used to create the Selenium WebDriver
 * or AppiumDriver instance!
 *
 * @param parameter 1
 * @param parameter 2
 * @param parameter 3
 * @param parameter 4
 *
 * @throws Exception
 */

The driver class will be designed with various get and set methods. The main setDriver method can take parameters to determine the browser or mobile type, platform to run on, environment for testing, and a set of optional preferences to allow changing driver behavior on the fly:

@SafeVarargs
public final void setDriver(String browser, 
                            String platform,
                            String environment,
                            Map<String, Object>... optPreferences)

Examples of some of the parameters of setDriver are as follows:

All the methods in this class should pertain to the web or mobile driver. This includes things such as setDriver, getDriver, getCurrentDriver, getSessionID/Browser/Version/Platform, driverWait, driverRefresh, and closeDriver. Each will be outlined in this section:

The following code demonstrates the standard setDriver method:

/**
 * setDriver method
 *
 * @param browser
 * @param environment
 * @param platform
 * @param optPreferences
 * @throws Exception
 */
@SafeVarargs
public final void setDriver(String browser,
                            String environment,
                            String platform,
                            Map<String, Object>... optPreferences)
                            throws Exception {

    DesiredCapabilities caps = null;
    String localHub = "http://127.0.0.1:4723/wd/hub";
    String getPlatform = null;

    switch (browser) {
        case "firefox":
            caps = DesiredCapabilities.firefox();
            webDriver.set(new FirefoxDriver(caps));

            break;
        case "chrome":
            caps = DesiredCapabilities.chrome();
            webDriver.set(new ChromeDriver(caps));

            break;
        case "internet explorer":
            caps = DesiredCapabilities.internetExplorer();
            webDriver.set(new 
                          InternetExplorerDriver(caps));

            break;
        case "safari":
            caps = DesiredCapabilities.safari();
            webDriver.set(new SafariDriver(caps));

            break;
        case "microsoftedge":
            caps = DesiredCapabilities.edge();
            webDriver.set(new EdgeDriver(caps));

            break;
        case "iphone":
        case "ipad":
            if (browser.equalsIgnoreCase("ipad")) {
                caps = DesiredCapabilities.ipad();
            }

            else {
                caps = DesiredCapabilities.iphone();
            }

            mobileDriver.set(new IOSDriver<MobileElement>(
                             new URL(localHub), caps));

            break;
        case "android":
            caps = DesiredCapabilities.android();
            mobileDriver.set(new 
                             AndroidDriver<MobileElement>(
                             new URL(localHub), caps));

            break;
    }
}

Here is the overloaded setDriver method:

/** 
 * overloaded setDriver method to switch driver to specific WebDriver
 * if running concurrent drivers
 *
 * @param driver WebDriver instance to switch to
 */
public void setDriver(WebDriver driver) {
    webDriver.set(driver);

    sessionId.set(((RemoteWebDriver) webDriver.get())
    .getSessionId().toString());

    sessionBrowser.set(((RemoteWebDriver) webDriver.get())
    .getCapabilities().getBrowserName());

    sessionPlatform.set(((RemoteWebDriver) webDriver.get())
    .getCapabilities().getPlatform().toString());

    setBrowserHandle(getDriver().getWindowHandle());
}

/**
 * overloaded setDriver method to switch driver to specific AppiumDriver
 * if running concurrent drivers
 *
 * @param driver AppiumDriver instance to switch to
 */
public void setDriver(AppiumDriver<MobileElement> driver) {
    mobileDriver.set(driver);

    sessionId.set(mobileDriver.get()
    .getSessionId().toString());

    sessionBrowser.set(mobileDriver.get()
    .getCapabilities().getBrowserName());

    sessionPlatform.set(mobileDriver.get()
    .getCapabilities().getPlatform().toString());
}

/**
 * getDriver method will retrieve the active WebDriver
 *
 * @return WebDriver
 */
public WebDriver getDriver() {
    return webDriver.get();
}

/**
 * getDriver method will retrieve the active AppiumDriver
 *
 * @param mobile boolean parameter
 * @return AppiumDriver
 */
public AppiumDriver<MobileElement> getDriver(boolean mobile) {
    return mobileDriver.get();
}

/**
 * getCurrentDriver method will retrieve the active WebDriver
 * or AppiumDriver
 *
 * @return WebDriver
 */
public WebDriver getCurrentDriver() {
    if ( getInstance().getSessionBrowser().contains("iphone") ||
         getInstance().getSessionBrowser().contains("ipad") ||
         getInstance().getSessionBrowser().contains("android") ) {

        return getInstance().getDriver(true);
    }

    else {
        return getInstance().getDriver();
    }
}

/**
 * driverWait method pauses the driver in seconds
 *
 * @param seconds to pause
 */
public void driverWait(long seconds) {
    try {
        Thread.sleep(TimeUnit.SECONDS.toMillis(seconds));
    }

    catch (InterruptedException e) {
        // do something
    }
}

/**
 * driverRefresh method reloads the current browser page
 */
public void driverRefresh() {
    getCurrentDriver().navigate().refresh();
}

/**
 * closeDriver method quits the current active driver
 */
public void closeDriver() {
    try {
        getCurrentDriver().quit();
    }

    catch ( Exception e ) {
        // do something
    }
}

switch (browser) {
    case "firefox":
        caps = DesiredCapabilities.firefox();

FirefoxOptions ffOpts = new FirefoxOptions();
FirefoxProfile ffProfile = new FirefoxProfile();
        ffProfile.setPreference("browser.autofocus",
                                true);

        caps.setCapability(FirefoxDriver.PROFILE,
                           ffProfile);
        caps.setCapability("marionette",
                           true);

        webDriver.set(new FirefoxDriver(caps));

        // Selenium 3.7.x
        // webDriver.set(new FirefoxDriver(ffOpts.merge(caps)));
        }

        break;
}

switch (browser) {
    case "chrome":
        caps = DesiredCapabilities.chrome();

        ChromeOptions chOptions = new ChromeOptions();
Map<String, Object> chromePrefs = 
        new HashMap<String, Object>();

        chromePrefs.put("credentials_enable_service",
                        false);
        chOptions.setExperimentalOption("prefs",
                                        chromePrefs);
        chOptions.addArguments("--disable-plugins", 
                               "--disable-extensions",
                               "--disable-popup-blocking");

        caps.setCapability(ChromeOptions.CAPABILITY,
                           chOptions);
        caps.setCapability("applicationCacheEnabled",
                           false);

        webDriver.set(new ChromeDriver(caps));

        // Selenium 3.7.x
        // webDriver.set(new ChromeDriver(chOptions.merge(caps)));

        break;
    }

For Internet Explorer:

switch (browser) {
    case "internet explorer":
        caps = DesiredCapabilities.internetExplorer();

        InternetExplorerOptions ieOpts =
        new InternetExplorerOptions();
        ieOpts.requireWindowFocus();

ieOpts.merge(caps);
        caps.setCapability("requireWindowFocus",
                           true);

        webDriver.set(new InternetExplorerDriver(caps));

        // Selenium 3.7.x
        // webDriver.set(new InternetExplorerDriver(
                         ieOpts.merge(caps)));

        break;
}

For Safari:

switch (browser) {
    case "safari":
        caps = DesiredCapabilities.safari();

        SafariOptions safariOpts = new SafariOptions();
        safariOpts.setUseCleanSession(true);

        caps.setCapability(SafariOptions.CAPABILITY,
                           safariOpts);
caps.setCapability("autoAcceptAlerts",
                           true);

        webDriver.set(new SafariDriver(caps));

        // Selenium 3.7.x
        // webDriver.set(new SafariDriver(safariOpts.merge(caps)));

        break;
}

For Microsoft Edge:

switch(browser) {
    case "microsoftedge":
        caps = DesiredCapabilities.edge();

        EdgeOptions edgeOpts = new EdgeOptions();
        edgeOpts.setPageLoadStrategy("normal");

        caps.setCapability(EdgeOptions.CAPABILITY,
                           edgeOpts);
caps.setCapability("requireWindowFocus",
                           true);

        webDriver.set(new EdgeDriver(caps));

        // Selenium 3.7.x
        // webDriver.set(new EdgeDriver(edgeOpts.merge(caps)));

        break;
}

There are some specific system properties that need to be set for each driver; specifically, the path to the local driver in the GIT repository of the project. By storing the driver in the project, users will not have to download or install the drivers for each browser when testing locally from their IDE. The path also depends on the OS of the development platform. The following examples are for Windows platforms:

Preferences for iPhone/iPad mobile devices are set using the Desired Capabilities class. Capabilities are set for the iPhone and iPad simulators, or physical devices. The following example shows various capabilities for these iOS devices:

switch(browser) {
    case "iphone": case "ipad":
        if ( browser.equalsIgnoreCase("ipad") ) {
            caps = DesiredCapabilities.ipad();
        }

        else {
            caps = DesiredCapabilities.iphone();
        }

        caps.setCapability("appName",
                           "https://myapp.com/myApp.zip");

        caps.setCapability("udid", 
                           "12345678"); // physical device
caps.setCapability("device",
                           "iPhone"); // or iPad

        mobileDriver.set(new IOSDriver<MobileElement>
                         (new URL("http://127.0.0.1:4723/wd/hub"),
                         caps));

        break;

Android: Preferences for these mobile devices are set using the Desired Capabilities class. Capabilities are set for Android Emulators, or physical devices. The following example shows various capabilities for these Android devices:

switch(browser) {
    case "android":
        caps = DesiredCapabilities.android();

        caps.setCapability("appName",
                           "https://myapp.com/myApp.apk");

        caps.setCapability("udid",
                           "12345678"); // physical device
        caps.setCapability("device",
                           "Android");

        mobileDriver.set(new AndroidDriver<MobileElement>
                         (new URL("http://127.0.0.1:4723/wd/hub"),
                         caps));

        break;

The following example shows how to use the varargs parameter in the setDriver method, which is called optPreferences. This is the setDriver method so far, from what we have built:

@SafeVarargs
public final void setDriver(String browser,
                            String environment,
                            String platform,
Map<String, Object>... optPreferences)
                            throws Exception {

    DesiredCapabilities caps = null;
    String localHub = "http://127.0.0.1:4723/wd/hub";
    String getPlatform = null;

    switch (browser) {
        case "firefox":
            caps = DesiredCapabilities.firefox();
            FirefoxProfile ffProfile = new FirefoxProfile();

            ffProfile.setPreference("browser.autofocus",
                                     true);
            caps.setCapability(FirefoxDriver.PROFILE,
                               ffProfile);
            caps.setCapability("marionette",
                                true);
            System.setProperty("webdriver.gecko.driver",
            "gecko_driver_windows_path/geckodriver.exe");

if ( optPreferences.length > 0 ) {
                processFFProfile(ffProfile, optPreferences);
            }

            webDriver.set(new FirefoxDriver(caps));
            break;
        case "chrome":
            caps = DesiredCapabilities.chrome();
            ChromeOptions chOptions = new ChromeOptions();

            Map<String, Object> chromePrefs =
                                new HashMap<String, Object>();
            chromePrefs.put("credentials_enable_service",
                             false);
            chOptions.setExperimentalOption("prefs",
                                             chromePrefs);
            chOptions.addArguments("--disable-plugins",
                                   "--disable-extensions",
                                   "--disable-popup-blocking");
            caps.setCapability(ChromeOptions.CAPABILITY,
                               chOptions);
            caps.setCapability("applicationCacheEnabled",
                               false);
            System.setProperty("webdriver.chrome.driver",
            "chrome_driver_windows_path/chromedriver.exe");

if ( optPreferences.length > 0 ) {
                processCHOptions(chOptions, optPreferences);
            }

            webDriver.set(new ChromeDriver(caps));
            break;
        case "internet explorer":
            caps = DesiredCapabilities.internetExplorer();

            InternetExplorerOptions ieOpts =
                    new InternetExplorerOptions();

            ieOpts.requireWindowFocus();
            ieOpts.merge(caps);
            caps.setCapability("requireWindowFocus",
                                true);
            System.setProperty("webdriver.ie.driver",
            "ie_driver_windows_path/IEDriverServer.exe");

if ( optPreferences.length > 0 ) {
                processDesiredCaps(caps, optPreferences);
            }

            webDriver.set(new InternetExplorerDriver(caps));
            break;
    }

    // etc...
}

The next example shows how to pass Map into the setDriver method using the varargs parameter:

// first, create a map for the key:value pairs to pass into the driver
Map<String, Object> preferences = new HashMap<String, Object>;

// then put the key:value pairs into the map
preferences.put("applicationCacheEnabled",false);
preferences.put("network.cookie.cookieBehavior", 0);

// then, pass the map into the setDriver method
CreateDriver.getInstance().setDriver("firefox",
                                     "Windows 10",
                                     "local",
preferences);

Finally, the next example shows how to set the optional browser preferences as a JVM argument using the TestNG parameter attribute in the suite XML file:

// pass in the key:value pairs as a runtime argument
-Dbrowserprefs=applicationCacheEnabled:false,
               network.cookie.cookieBehavior:0

// pass in the key:value pairs as a TestNG XML parameter
<test name="Selenium TestNG Test Suite">
    <parameter name="browser" value="chrome" />
    <parameter name="platform" value="Windows 10" />
    <parameter name="browserPrefs" value="intl.accept_languages:fr" />

    <classes>
        <class name="com.myproject.MyTest" />
    </classes>
</test>

// for convenience, create a setPreferences method
// to build the map to pass into the driver
public Map<String, Object> setPreferences() {
    Map<String, Object> prefsMap = new HashMap<String, Object>();
    List<String> allPrefs = Arrays.asList(
                 System.getProperty("browserPrefs").split(",", -1));

    // extract the key/value pairs and pass to map...
    for ( String getPref : allPrefs ) {
        prefsMap.put(getPref.split(":")[0], getPref.split(":")[1]);
    }

    return prefsMap;
}

// set JVM arg, call this method on-the-fly, create new driver
if ( System.getProperty("browserPrefs") != null ) {
    CreateDriver.getInstance().setDriver("firefox",
                                         "Windows 10",
                                         "local",
        CreateDriver.getInstance().setBrowserPrefs()
                                         );
}

Once the optional preferences are passed into the setDriver method, the user then has to process those options. For instance, there may be DesiredCapabilities,  ChromeOptions, or FirefoxProfile preferences that need to be processed. First, for each driver-type instance, there needs to be a check to see if the options have been passed in, then if so, they have to be processed. Each type will be outlined as shown here:

/**
 * Process Desired Capabilities method to override default browser
 * or mobile driver behavior
 * 
 * @param caps - the DesiredCapabilities object
 * @param options - the key: value pair map
 * @throws Exception
 */
private void processDesiredCaps(DesiredCapabilities caps,
                                Map<String,
                                Object>[] options)
                                throws Exception {

    for ( int i = 0; i < options.length; i++ ) {
        Object[] keys = options[i].keySet().toArray();
        Object[] values = options[i].values().toArray();

        for ( int j = 0; j < keys.length; j++ ) {
            if ( values[j] instanceof Integer ) {
                caps.setCapability(keys[j].toString(),
                                  (int) values[j]);
            }
            else if ( values[j] instanceof Boolean) {
                caps.setCapability(keys[j].toString(),
                                  (boolean) values[j]);
            }
            else if ( isStringInt(values[j].toString()) ) {
                caps.setCapability(keys[j].toString(),

                Integer.valueOf(values[j].toString()));
            }
            else if ( Boolean.parseBoolean(values[j].toString()) ) {
                caps.setCapability(keys[j].toString(),

                Boolean.valueOf(values[j].toString()));
            }
            else {
                caps.setCapability(keys[j].toString(),
                                   values[j].toString());
            }
        }
    }
}

/**
 * Process Firefox Profile Preferences method to override default
 * browser driver behavior
 * 
 * @param caps - the FirefoxProfile object
 * @param options - the key: value pair map
 * @throws Exception
 */
private void processFFProfile(FirefoxProfile profile, Map<String, Object>[] options) throws Exception {
    for (int i = 0; i < options.length; i++) {
        Object[] keys = options[i].keySet().toArray();
        Object[] values = options[i].values().toArray();

        // same as Desired Caps except the following difference
        for (int j = 0; j < keys.length; j++) {
            if (values[j] instanceof Integer) {
                profile.setPreference(keys[j].toString(), 
                (int) values[j]);
            }

            // etc...
        }
    }
}

/**
 * Process Chrome Options method to override default browser
 * driver behavior
 * 
 * @param caps - the ChromeOptions object
 * @param options - the key: value pair map
 * @throws Exception
 */
private void processCHOptions(ChromeOptions chOptions, Map<String, Object>[] options) throws Exception {
    for (int i = 0; i < options.length; i++) {
        Object[] keys = options[i].keySet().toArray();
        Object[] values = options[i].values().toArray();

        // same as Desired Caps except the following difference

        for (int j = 0; j < keys.length; j++) {
            if (values[j] instanceof Integer) {
                values[j] = (int) values[j];
                chOptions.setExperimentalOption("prefs", options[i]);
            }

            // etc...
        }
    }
}