QuickStart.java

package com.nordstrom.automation.selenium.examples;

import static org.testng.Assert.assertEquals;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.testng.annotations.Test;

import com.github.sbabcoc.logback.testng.ReporterAppender;
import com.nordstrom.automation.selenium.annotations.InitialPage;
import com.nordstrom.automation.selenium.core.DriverManager;
import com.nordstrom.automation.selenium.support.TestNgBase;
import com.nordstrom.automation.testng.ExecutionFlowController;
import com.nordstrom.automation.testng.LinkedListeners;
import com.nordstrom.automation.testng.ListenerChain;
import com.nordstrom.automation.selenium.SeleniumConfig;
import com.nordstrom.automation.selenium.AbstractSeleniumConfig.SeleniumSettings;

/**
 * <b>INTRODUCTION</b>
 * <p>
 * <b>Selenium Foundation</b> is an automation framework designed to extend and enhance the capabilities provided
 * by <b>Selenium WebDriver</b>.
 * <p>
 * This <b>QuickStart</b> class provides a fully-functional example of a test class built around <b>Selenium
 * Foundation</b>, <b>TestNG Foundation</b>, and the <b>Settings API</b>. It demonstrates how to set up required 
 * elements and introduces several key features that you're likely to use on a regular basis.
 * <p>
 * <b>REQUIRED ELEMENTS</b>
 * <ul>
 *     <li>{@link ListenerChain}: <br>
 *     <b>ListenerChain</b> 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 rule chain.</li>
 *     <li>The {@link LinkedListeners} annotation: <br>
 *     To attach listeners to an active <b>ListenerChain</b>, mark your test class with the <b>LinkedListeners</b>
 *     annotation. <b>QuickStart</b> extends {@link TestNgBase}, which is marked with a <b>LinkedListeners</b>
 *     annotation that specifies two listeners that manage several core features of <b>Selenium Foundation</b>: <ul>
 *         <li>{@link DriverManager}: <br>
 *         <b>DriverManager</b> is a TestNG listener that manages driver sessions and local Selenium Grid servers.</li>
 *         <li>{@link ExecutionFlowController}: <br>
 *         <b>ExecutionFlowController</b> is a TestNG listener that propagates test context attributes: <br>
 *         [<i>before</i> method] &rarr; [test method] &rarr; [<i>after</i> method]</li></ul>
 *     </li>
 * </ul>
 * <p>
 * <b>DEMONSTRATED FEATURES</b>
 * <ul>
 *     <li>{@link InitialPage}: <br>
 *     <b>InitialPage</b> 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 test in the class. It can also be applied
 *     to <b>@Before...</b> configuration methods to provide driver sessions opened to the desired page.</li>
 *     <li>{@link SeleniumConfig}: <br>
 *     <b>SeleniumConfig</b> declares settings and methods related to Selenium WebDriver and Grid configuration.
 *     This class is built on the <b>Settings API</b>, composed of defaults, stored values, and System properties.</li>
 *     <li>{@link SeleniumSettings}: <br>
 *     <b>SeleniumSettings</b> declares the constants, property names, and default values for the settings managed
 *     by <b>SeleniumConfig</b>. Defaults can be overridden via System properties or the <i>settings.propeties</i>
 *     file in your user "home" directory. See <b>ESSENTIAL SETTINGS</b> below for more details.</li>
 *     <li>{@link ReporterAppender}: <br>
 *     <b>ReporterAppender</b> is a <b>Logback</b> appender for TestNG Reporter. The <b>Selenium Foundation</b> project
 *     ships with a <i>logback.xml</i> file that attaches this appender. See the complete <b>logback-testng</b> README
 *     page <a href="https://github.com/sbabcoc/logback-testng">here</a>.</li>
 * </ul>
 * <p>
 * <b>ESSENTIAL SETTINGS</b>
 * <p>
 * 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 <b>Property Name</b> 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 <i>settings.properties</i> file or define a System property.
 * 
 * <table style="text-align: left; border: 1px solid black; border-collapse: collapse;">
 *     <caption>Essential Settings</caption>
 *     <tr>
 *         <th style="text-align: left; border: 1px solid black;">Constant</th>
 *         <th style="text-align: left; border: 1px solid black;">Property Name</th>
 *         <th style="text-align: center; border: 1px solid black;">Default</th>
 *     </tr>
 *     <tr>
 *         <td style="text-align: left; border: 1px solid black;">{@link SeleniumSettings#BROWSER_NAME BROWSER_NAME}</td>
 *         <td style="text-align: left; border: 1px solid black;">selenium.browser.name</td>
 *         <td style="text-align: center; border: 1px solid black;">(none) *</td>
 *     </tr>
 *     <tr>
 *         <td style="text-align: left; border: 1px solid black;">{@link SeleniumSettings#TARGET_HOST TARGET_HOST}</td>
 *         <td style="text-align: left; border: 1px solid black;">selenium.target.host</td>
 *         <td style="text-align: center; border: 1px solid black;">localhost</td>
 *     </tr>
 *     <tr>
 *         <td style="text-align: left; border: 1px solid black;">{@link SeleniumSettings#TARGET_PATH TARGET_PATH}</td>
 *         <td style="text-align: left; border: 1px solid black;">selenium.target.path</td>
 *         <td style="text-align: center; border: 1px solid black;">/</td>
 *     </tr>
 * </table>
 * <p>
 * * <b>NOTE</b>: By default, no target browser is selected. Either {@link SeleniumSettings#BROWSER_NAME BROWSER_NAME}
 * or {@link SeleniumSettings#BROWSER_CAPS BROWSER_CAPS} must be specified for this test to run.
 * For details, see <a href=
 * "https://github.com/sbabcoc/Selenium-Foundation/blob/master/docs/ConfiguringProjectSettings.md">Configuring Project
 * Settings
 * </a>. 
 * <p>
 * <b>OVERRIDING DEFAULTS</b>
 * <p>
 * <b>SeleniumConfig</b> searches a series of locations for a <i>settings.properties</i> 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
 * <b>SeleniumSettings</b> enumeration. Settings that are declared as System properties will override both the defaults
 * assigned by <b>SeleniumSettings</b> and settings declared in <i>settings.properties</i>. For example: 
 * 
 * <table style="text-align: left; border: 1px solid black; border-collapse: collapse;">
 *     <caption>settings.properties</caption>
 *     <tr style="text-align: left; border: 1px solid black;">
 *         <th><i>settings.properties</i></th>
 *     </tr>
 *     <tr>
 *         <td>selenium.target.host=my.server.com</td>
 *     </tr>
 *     <tr>
 *         <td>selenium.browser.name=chrome</td>
 *     </tr>
 * </table>
 * <p>
 * This sample <i>settings.properties</i> file overrides the values of {@link SeleniumSettings#TARGET_HOST TARGET_HOST}
 * and {@link SeleniumSettings#BROWSER_NAME BROWSER_NAME}. The latter can be overridden by System property declaration:
 * 
 * <blockquote>{@code -Dselenium.browser.name=firefox}</blockquote>
 * <p>
 * The hierarchy of evaluation produces the following results:
 * 
 * <blockquote>
 *     <b>BROWSER_NAME</b> = firefox; 
 *     <b>TARGET_HOST</b> = my.server.com; 
 *     <b>TARGET_PATH</b> = /
 * </blockquote>
 * <p>
 * <b>INSTALLING DRIVERS</b>
 * <p>
 * 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 chosen version of <b>Selenium WebDriver</b>, 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.
 * <p>
 * Here are the official homes for several of the major drivers: <ul>
 *     <li>GhostDriver (PhantomJS) - <a href="http://phantomjs.org/download.html">
 *     http://phantomjs.org/download.html</a></li>
 *     <li>ChromeDriver - <a href="https://sites.google.com/a/chromium.org/chromedriver/downloads">
 *     https://sites.google.com/a/chromium.org/chromedriver/downloads</a></li>
 *     <li>IEDriver - <a href="https://github.com/SeleniumHQ/selenium/wiki/InternetExplorerDriver">
 *     https://github.com/SeleniumHQ/selenium/wiki/InternetExplorerDriver</a></li>
 * </ul>
 * <b>NOTE</b>: 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 <a href="https://github.com/SeleniumHQ/selenium/wiki/InternetExplorerDriver#required-configuration">
 * Required Configuration</a> procedure.
 */
@InitialPage(ExamplePage.class)
public class QuickStart extends TestNgRoot {
    
    private static final String PAGE_TITLE = "Example Page";
    private static final Logger LOGGER = LoggerFactory.getLogger(QuickStart.class);
    
    @Test
    public void dummyTest() {
        SeleniumConfig config = SeleniumConfig.getConfig();
        LOGGER.info("The configured browser is: " + config.getCurrentCapabilities().getBrowserName());
        ExamplePage examplePage = (ExamplePage) getInitialPage();
        assertEquals(examplePage.getTitle(), PAGE_TITLE, "Unexpected page title");
    }
}