Add ContainerResolver interface (#297)

Author: sbabcoc

selenium4Deps.gradle

@@ -32,8 +32,8 @@ dependencies {
     api 'org.seleniumhq.selenium:selenium-firefox-driver:4.33.0'
     api 'org.seleniumhq.selenium:selenium-opera-driver:4.4.0'
     api 'org.seleniumhq.selenium:selenium-safari-driver:4.33.0'
-    api 'com.nordstrom.ui-tools:htmlunit-remote:4.32.0'
-    api 'org.seleniumhq.selenium:htmlunit3-driver:4.32.0'
+    api 'com.nordstrom.ui-tools:htmlunit-remote:4.33.0'
+    api 'org.seleniumhq.selenium:htmlunit3-driver:4.33.0'
     api 'org.htmlunit:htmlunit:4.12.0'
     api 'com.codeborne:phantomjsdriver:1.5.0'
     api 'org.apache.httpcomponents:httpclient:4.5.14'

src/main/java/com/nordstrom/automation/selenium/annotations/Resolver.java

@@ -0,0 +1,28 @@
+package com.nordstrom.automation.selenium.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import com.nordstrom.automation.selenium.interfaces.ContainerResolver;
+
+/**
+ * This annotation enables you to specify a resolver class for pages and components that vary based on browser window
+ * dimensions (responsive layout) or UI/UX variations (A/B testing). This feature can also select between old and new
+ * versions of site-wide components (e.g. - common navigation) during the transition between versions when some pages
+ * have been updated but others haven't.
+ * 
+ *  @see ContainerResolver
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Resolver {
+    /**
+     * Get the value class of the container resolver.
+     * 
+     * @return container resolver class
+     */
+    @SuppressWarnings("rawtypes")
+    Class<? extends ContainerResolver> value();
+}

src/main/java/com/nordstrom/automation/selenium/examples/ExamplePage.java

@@ -131,7 +131,9 @@ protected enum Using implements ByEnum {
         /** prompt button */
         PROMPT(By.cssSelector("button#prompt")),
         /** result paragraph */
-        RESULT(By.cssSelector("p#result"));
+        RESULT(By.cssSelector("p#result")),
+        /** open tab button */
+        OPEN_TAB(By.cssSelector("button#open-tab"));
 
         private final By locator;
 
@@ -552,6 +554,16 @@ public String getModalResult() {
         return findElement(Using.RESULT).getText();
     }
 
+    /**
+     * Open the example tab.
+     * 
+     * @return tab page object (either {@link TabPageA} or {@link TabPageB})
+     */
+    public TabPage openTab() {
+        findElement(Using.OPEN_TAB).click();
+        return new TabPage(driver).setWindowState(WindowState.WILL_OPEN);
+    }
+    
     /**
      * Set the active Grid hub as the base URI for all relative loads of test pages.
      * 

src/main/java/com/nordstrom/automation/selenium/examples/TabPage.java

@@ -0,0 +1,71 @@
+package com.nordstrom.automation.selenium.examples;
+
+import org.openqa.selenium.By;
+import org.openqa.selenium.WebDriver;
+
+import com.nordstrom.automation.selenium.annotations.Resolver;
+import com.nordstrom.automation.selenium.interfaces.DetectsLoadCompletion;
+import com.nordstrom.automation.selenium.model.Page;
+
+/**
+ * This class is the abstract model for the tab pages opened by the "Open A/B Tab" button on the 'Example' page.
+ * The {@link Resolver} annotation specifies the container resolver that selects the concrete subclass model for
+ * the specific page that gets opened ({@link TabPageA} or {@link TabPageB}).
+ */
+@Resolver(TabPageResolver.class)
+public class TabPage extends Page implements DetectsLoadCompletion {
+    
+    /**
+     * Constructor for tab page view context.
+     * 
+     * @param driver driver object
+     */
+    public TabPage(WebDriver driver) {
+        super(driver);
+    }
+    
+    /**
+     * This enumeration defines element locator constants.
+     */
+    enum Using implements ByEnum {
+        /** page heading locator */
+        HEADING(By.cssSelector("h1"));
+        
+        private final By locator;
+        
+        Using(By locator) {
+            this.locator = locator;
+        }
+
+        @Override
+        public By locator() {
+            return locator;
+        }
+    }
+    
+    /**
+     * Get content of tab page.
+     * 
+     * @return tab page content
+     */
+    public String getPageContent() {
+        return findElement(Using.HEADING).getText();
+    }
+
+    /**
+     * Verify content of tab page.
+     * 
+     * @return {@code true} if verification succeeds; otherwise {@code false}
+     */
+    public boolean verifyContent() {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public boolean isLoadComplete() {
+        return verifyContent();
+    }
+}

src/main/java/com/nordstrom/automation/selenium/examples/TabPageA.java

@@ -0,0 +1,33 @@
+package com.nordstrom.automation.selenium.examples;
+
+import org.openqa.selenium.WebDriver;
+
+import com.nordstrom.automation.selenium.annotations.PageUrl;
+
+/**
+ * This class is the model for the first concrete tab pages opened by the "Open A/B Tab" button on the 'Example'
+ * page.
+ */
+@PageUrl("/grid/admin/FrameA_Servlet")
+public class TabPageA extends TabPage {
+    
+    /** expected content */
+    public static String EXPECT_CONTENT = "Frame A";
+
+    /**
+     * Constructor for tab page view context.
+     * 
+     * @param driver driver object
+     */
+    public TabPageA(WebDriver driver) {
+        super(driver);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public boolean verifyContent() {
+        return getPageContent().equals(EXPECT_CONTENT);
+    }
+}

src/main/java/com/nordstrom/automation/selenium/examples/TabPageB.java

@@ -0,0 +1,33 @@
+package com.nordstrom.automation.selenium.examples;
+
+import org.openqa.selenium.WebDriver;
+
+import com.nordstrom.automation.selenium.annotations.PageUrl;
+
+/**
+ * This class is the model for the second concrete tab pages opened by the "Open A/B Tab" button on the 'Example'
+ * page.
+ */
+@PageUrl("/grid/admin/FrameB_Servlet")
+public class TabPageB extends TabPage {
+    
+    /** expected content */
+    public static String EXPECT_CONTENT = "Frame B";
+
+    /**
+     * Constructor for tab page view context.
+     * 
+     * @param driver driver object
+     */
+    public TabPageB(WebDriver driver) {
+        super(driver);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public boolean verifyContent() {
+        return getPageContent().equals(EXPECT_CONTENT);
+    }
+}

src/main/java/com/nordstrom/automation/selenium/examples/TabPageResolver.java

@@ -0,0 +1,27 @@
+package com.nordstrom.automation.selenium.examples;
+
+import com.nordstrom.automation.selenium.exceptions.UnresolvedContainerTypeException;
+import com.nordstrom.automation.selenium.interfaces.ContainerResolver;
+import com.nordstrom.automation.selenium.model.RobustWebElement;
+
+/**
+ * This class implements the container resolver for the tab pages opened by the "Open A/B Tab" button on the 'Example'
+ * page.
+ */
+public class TabPageResolver implements ContainerResolver<TabPage> {
+    @Override
+    public TabPage resolve(TabPage container) {
+        RobustWebElement element = container.findOptional(TabPage.Using.HEADING);
+        if (element.hasReference()) {
+            String pageContent = element.getText();
+            if (pageContent.equals(TabPageA.EXPECT_CONTENT)) {
+                return new TabPageA(container.getWrappedDriver());
+            }
+            if (pageContent.equals(TabPageB.EXPECT_CONTENT)) {
+                return new TabPageB(container.getWrappedDriver());
+            }
+           throw new UnresolvedContainerTypeException("Unsupported tab page heading: " + pageContent);
+        }
+        throw new UnresolvedContainerTypeException("Tab page heading not found");
+    }
+}

src/main/java/com/nordstrom/automation/selenium/exceptions/ContainerResolverInvocationException.java

@@ -0,0 +1,27 @@
+package com.nordstrom.automation.selenium.exceptions;
+
+import com.nordstrom.automation.selenium.interfaces.ContainerResolver;
+
+/**
+ * This exception is thrown if specified container resolver cannot be instantiated or if
+ * invocation of the {@link ContainerResolver#resolve resolve} method fails.
+ */
+public class ContainerResolverInvocationException extends RuntimeException {
+
+    private static final long serialVersionUID = -422498744356462151L;
+
+    /**
+     * Constructor for "container resolver invocation" exception with specified detail message
+     * and associated cause.
+     * 
+     * @param  message the detail message (which is saved for later retrieval
+     *         by the {@link #getMessage()} method).
+     * @param  cause the cause (which is saved for later retrieval by the
+     *         {@link #getCause()} method). (A {@code null} value is
+     *         permitted, and indicates that the cause is nonexistent or
+     *         unknown.)
+     */
+    public ContainerResolverInvocationException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}

src/main/java/com/nordstrom/automation/selenium/exceptions/UnresolvedContainerTypeException.java

@@ -0,0 +1,25 @@
+package com.nordstrom.automation.selenium.exceptions;
+
+/**
+ * This exception is thrown if the concrete container type cannot be resolved.
+ */
+public class UnresolvedContainerTypeException extends RuntimeException {
+
+    private static final long serialVersionUID = -422498744356462151L;
+
+    /**
+     * Constructor for "unresolved container type" exception with default message.
+     */
+    public UnresolvedContainerTypeException() {
+        super("Concrete container type cannot be resolved");
+    }
+
+    /**
+     * Constructor for "unresolved container type" exception with specified detail message.
+     * 
+     * @param message detail message
+     */
+    public UnresolvedContainerTypeException(String message) {
+        super(message);
+    }
+}

src/main/java/com/nordstrom/automation/selenium/interfaces/ContainerResolver.java

@@ -0,0 +1,27 @@
+package com.nordstrom.automation.selenium.interfaces;
+
+import com.nordstrom.automation.selenium.annotations.Resolver;
+import com.nordstrom.automation.selenium.exceptions.UnresolvedContainerTypeException;
+import com.nordstrom.automation.selenium.model.ComponentContainer;
+
+/**
+ * Implementations of this interface are used to resolve concrete {@link ComponentContainer} types based on current DOM
+ * state. This can be used to handle multiple versions of a page or component in which an equivalent set of features is
+ * presented in multiple ways based on browser window dimensions (responsive layout) or UI/UX variations (A/B testing).
+ * This feature can also select between old and new versions of site-wide components (e.g. - common navigation) during
+ * the transition between versions when some pages have been updated but others haven't.
+ * 
+ * @param <T> context container type
+ * @see Resolver
+ */
+@FunctionalInterface
+public interface ContainerResolver<T extends ComponentContainer> {
+    /**
+     * Resolve this container to its context-specific type.
+     * 
+     * @param container context container object
+     * @return context-specific container object
+     * @throws UnresolvedContainerTypeException if concrete type cannot be resolved
+     */
+    T resolve(T container);
+}