New Functionality for Extendable/Containerized elements

This change adds an abstract extensible element which provide an 'out-of-the-box' way for users to define custom containerized element groupings, or singular elements with specific behaviors. The design uses only classes instead of interfaces with implementing classes to keep usage simplistic and allows for future annotations to enable context specific overriding. The change should be backwards compatible.

Potentially addresses comment in #3680 #3680 (comment)

Author: iFatRain

java/src/org/openqa/selenium/support/BUILD.bazel

@@ -57,5 +57,7 @@ java_library(
     deps = [
         "//java/src/org/openqa/selenium:core",
         "//java/src/org/openqa/selenium/support/ui:components",
+        "//java/src/org/openqa/selenium/support/ui:elements",
+        "//java/src/org/openqa/selenium/remote",
     ],
 )

java/src/org/openqa/selenium/support/pagefactory/DefaultFieldDecorator.java

@@ -31,6 +31,7 @@
 import org.openqa.selenium.support.FindBys;
 import org.openqa.selenium.support.pagefactory.internal.LocatingElementHandler;
 import org.openqa.selenium.support.pagefactory.internal.LocatingElementListHandler;
+import org.openqa.selenium.support.ui.AbstractExtendedElement;
 
 /**
  * Default decorator for use with PageFactory. Will decorate 1) all the WebElement fields and 2)
@@ -48,7 +49,8 @@ public DefaultFieldDecorator(ElementLocatorFactory factory) {
 
   @Override
   public Object decorate(ClassLoader loader, Field field) {
-    if (!(WebElement.class.isAssignableFrom(field.getType()) || isDecoratableList(field))) {
+    Class<?> type = field.getType();
+    if (!(WebElement.class.isAssignableFrom(type) || isDecoratableList(field))) {
       return null;
     }
 
@@ -57,11 +59,20 @@ public Object decorate(ClassLoader loader, Field field) {
       return null;
     }
 
-    if (WebElement.class.isAssignableFrom(field.getType())) {
-      return proxyForLocator(loader, locator);
-    } else if (List.class.isAssignableFrom(field.getType())) {
-      return proxyForListLocator(loader, locator);
-    } else {
+    if (WebElement.class.isAssignableFrom(type)) {
+      WebElement elementProxy = proxyForLocator(loader, locator);
+      if(AbstractExtendedElement.class.isAssignableFrom(type)) {
+        try {
+          return type.getConstructor(WebElement.class).newInstance(elementProxy);
+        } catch (Exception e) {
+          return null;
+        }
+      }
+      return elementProxy;
+    } else if (List.class.isAssignableFrom(type)) {
+      return proxyForListLocator(loader, locator, getErasureType(field));
+    }
+    else {
       return null;
     }
   }
@@ -81,14 +92,28 @@ protected boolean isDecoratableList(Field field) {
     Type listType = ((ParameterizedType) genericType).getActualTypeArguments()[0];
 
     if (!WebElement.class.equals(listType)) {
-      return false;
+      if (listType instanceof Class) {
+        if (!AbstractExtendedElement.class.isAssignableFrom((Class<?>) listType)) {
+          return false;
+        }
+      } else {
+        return false;
+      }
     }
 
     return field.getAnnotation(FindBy.class) != null
         || field.getAnnotation(FindBys.class) != null
         || field.getAnnotation(FindAll.class) != null;
   }
 
+  private Class<?> getErasureType(Field field) {
+    Type genericType = field.getGenericType();
+    if (!(genericType instanceof ParameterizedType)) {
+      return null;
+    }
+    return (Class<?>) ((ParameterizedType) genericType).getActualTypeArguments()[0];
+  }
+
   protected WebElement proxyForLocator(ClassLoader loader, ElementLocator locator) {
     InvocationHandler handler = new LocatingElementHandler(locator);
 
@@ -103,11 +128,11 @@ protected WebElement proxyForLocator(ClassLoader loader, ElementLocator locator)
   }
 
   @SuppressWarnings("unchecked")
-  protected List<WebElement> proxyForListLocator(ClassLoader loader, ElementLocator locator) {
-    InvocationHandler handler = new LocatingElementListHandler(locator);
+  protected <T extends WebElement> List<T> proxyForListLocator(ClassLoader loader, ElementLocator locator, Class<?> type) {
+    InvocationHandler handler = new LocatingElementListHandler(locator, type);
 
-    List<WebElement> proxy;
-    proxy = (List<WebElement>) Proxy.newProxyInstance(loader, new Class[] {List.class}, handler);
+    List<T> proxy;
+    proxy = (List<T>) Proxy.newProxyInstance(loader, new Class[] {List.class}, handler);
     return proxy;
   }
 }

java/src/org/openqa/selenium/support/pagefactory/internal/LocatingElementListHandler.java

@@ -17,26 +17,57 @@
 
 package org.openqa.selenium.support.pagefactory.internal;
 
+import java.lang.reflect.Constructor;
 import java.lang.reflect.InvocationHandler;
 import java.lang.reflect.InvocationTargetException;
 import java.lang.reflect.Method;
+import java.util.ArrayList;
 import java.util.List;
 import org.openqa.selenium.WebElement;
 import org.openqa.selenium.support.pagefactory.ElementLocator;
 
 public class LocatingElementListHandler implements InvocationHandler {
   private final ElementLocator locator;
+  private final Class<?> listType;
+  private boolean isExtendedElement = false;
+  private Constructor<?> cons = null;
+
+  public LocatingElementListHandler(ElementLocator locator, Class<?> listType) {
+    this.locator = locator;
+    this.listType = listType;
+    if(!WebElement.class.equals(listType)) {
+      this.isExtendedElement = true;
+      try {
+        cons = listType.getConstructor(WebElement.class);
+      } catch (NoSuchMethodException e) {
+        throw new RuntimeException("Constructor with WebElement argument not found for list type: "
+                                   + listType.getName());
+      }
+    }
+  }
 
   public LocatingElementListHandler(ElementLocator locator) {
     this.locator = locator;
+    this.listType = WebElement.class;
+    this.isExtendedElement = false;
+    cons = null;
   }
 
   @Override
   public Object invoke(Object object, Method method, Object[] objects) throws Throwable {
+    List<Object> elementList = new ArrayList<>();
     List<WebElement> elements = locator.findElements();
 
+    if(isExtendedElement && null != cons) {
+      for (WebElement element : elements) {
+        Object extension = cons.newInstance(element);
+        elementList.add(listType.cast(extension));
+      }
+    }
     try {
-      return method.invoke(elements, objects);
+        return method.invoke(
+          isExtendedElement ? elementList : elements,
+          objects);
     } catch (InvocationTargetException e) {
       // Unwrap the underlying exception
       throw e.getCause();

java/src/org/openqa/selenium/support/ui/AbstractExtendedElement.java

@@ -0,0 +1,45 @@
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+package org.openqa.selenium.support.ui;
+
+import org.openqa.selenium.WebElement;
+import org.openqa.selenium.WrapsElement;
+import org.openqa.selenium.remote.RemoteWebElement;
+
+public abstract class AbstractExtendedElement extends RemoteWebElement implements WrapsElement {
+
+  private WebElement wrappedElement;
+
+  protected AbstractExtendedElement(WebElement element) {
+    if (null == element) {
+      throw new IllegalArgumentException("Wrapped element must not be null");
+    }
+    this.wrappedElement = element;
+  }
+
+  @Override
+  public WebElement getWrappedElement() {
+    return this.wrappedElement;
+  }
+
+  @Override
+  public String toString() {
+    return this.wrappedElement.toString();
+  }
+
+}

java/src/org/openqa/selenium/support/ui/BUILD.bazel

@@ -28,6 +28,7 @@ java_library(
 java_library(
     name = "elements",
     srcs = [
+        "AbstractExtendedElement.java",
         "ISelect.java",
         "Quotes.java",
         "Select.java",
@@ -38,6 +39,7 @@ java_library(
     ],
     deps = [
         "//java/src/org/openqa/selenium:core",
+        "//java/src/org/openqa/selenium/remote",
     ],
 )
 

java/src/org/openqa/selenium/support/ui/Select.java

@@ -22,10 +22,9 @@
 import org.openqa.selenium.By;
 import org.openqa.selenium.NoSuchElementException;
 import org.openqa.selenium.WebElement;
-import org.openqa.selenium.WrapsElement;
 
 /** Models a SELECT tag, providing helper methods to select and deselect options. */
-public class Select implements ISelect, WrapsElement {
+public class Select extends AbstractExtendedElement implements ISelect {
 
   private final WebElement element;
   private final boolean isMulti;
@@ -38,6 +37,7 @@ public class Select implements ISelect, WrapsElement {
    * @throws UnexpectedTagNameException when element is not a SELECT
    */
   public Select(WebElement element) {
+    super(element);
     String tagName = element.getTagName();
 
     if (!"select".equalsIgnoreCase(tagName)) {

java/test/org/openqa/selenium/support/PageFactoryTest.java

@@ -32,6 +32,7 @@
 import org.openqa.selenium.TimeoutException;
 import org.openqa.selenium.WebDriver;
 import org.openqa.selenium.WebElement;
+import org.openqa.selenium.support.ui.AbstractExtendedElement;
 import org.openqa.selenium.support.ui.ExpectedConditions;
 import org.openqa.selenium.support.ui.TickingClock;
 import org.openqa.selenium.support.ui.Wait;
@@ -55,6 +56,38 @@ void shouldProxyElementsInAnInstantiatedPage() {
     assertThat(page.list).isNotNull();
   }
 
+  @Test
+  void shouldProxyExtendedElements() {
+    PublicPageWithExtendedElements page = new PublicPageWithExtendedElements();
+
+    assertThat(page.q).isNull();
+    assertThat(page.list).isNull();
+    assertThat(page.rendered).isNull();
+    assertThat(page.renderedList).isNull();
+
+    PageFactory.initElements(searchContext, page);
+
+    assertThat(page.q).isNotNull();
+    assertThat(page.list).isNotNull();
+    assertThat(page.rendered).isNotNull();
+    assertThat(page.renderedList).isNotNull();
+  }
+
+  @Test
+  void shouldProxyNestedExtendedElements() {
+    PublicPageWithExtendedElements page = new PublicPageWithExtendedElements();
+
+    assertThat(page.q).isNull();
+
+    PageFactory.initElements(searchContext, page);
+
+    assertThat(page.q).isNotNull();
+
+    assertThat(page.q.a).isNull();
+    PageFactory.initElements(page.q, page.q);
+    assertThat(page.q.a).isNotNull();
+  }
+
   @Test
   void shouldInsertProxiesForPublicWebElements() {
     PublicPage page = PageFactory.initElements(searchContext, PublicPage.class);
@@ -154,33 +187,74 @@ void shouldComplainWhenMoreThanOneFindByAttributeIsSet() {
     GrottyPage page = new GrottyPage();
 
     assertThatExceptionOfType(IllegalArgumentException.class)
-        .isThrownBy(() -> PageFactory.initElements((WebDriver) null, page));
+      .isThrownBy(() -> PageFactory.initElements((WebDriver) null, page));
   }
 
   @Test
   void shouldComplainWhenMoreThanOneFindByShortFormAttributeIsSet() {
     GrottyPage2 page = new GrottyPage2();
 
     assertThatExceptionOfType(IllegalArgumentException.class)
-        .isThrownBy(() -> PageFactory.initElements((WebDriver) null, page));
+      .isThrownBy(() -> PageFactory.initElements((WebDriver) null, page));
   }
 
   @Test
   void shouldNotThrowANoSuchElementExceptionWhenUsedWithAFluentWait() {
     WebDriver driver = mock(WebDriver.class);
     when(driver.findElement(ArgumentMatchers.any()))
-        .thenThrow(new NoSuchElementException("because"));
+      .thenThrow(new NoSuchElementException("because"));
 
     TickingClock clock = new TickingClock();
     Wait<WebDriver> wait =
-        new WebDriverWait(driver, Duration.ofSeconds(1), Duration.ofMillis(1001), clock, clock);
+      new WebDriverWait(driver, Duration.ofSeconds(1), Duration.ofMillis(1001), clock, clock);
 
     PublicPage page = new PublicPage();
     PageFactory.initElements(driver, page);
     WebElement element = page.q;
 
     assertThatExceptionOfType(TimeoutException.class)
-        .isThrownBy(() -> wait.until(ExpectedConditions.visibilityOf(element)));
+      .isThrownBy(() -> wait.until(ExpectedConditions.visibilityOf(element)));
+  }
+
+  public static class ExtendedElement extends AbstractExtendedElement {
+
+    public ExtendedElement(WebElement element) {
+      super(element);
+    }
+
+    @FindBy(name = "a")
+    public OtherExtendedElement a;
+
+    @FindBy(name = "a")
+    public List<OtherExtendedElement> aList;
+
+    @FindBy(name = "a")
+    public WebElement internalRender;
+
+    @FindBy(name = "a")
+    public List<WebElement> internalRenderList;
+  }
+
+
+  public static class OtherExtendedElement extends AbstractExtendedElement {
+
+    public OtherExtendedElement(WebElement element) {
+      super(element);
+    }
+  }
+
+  public static class PublicPageWithExtendedElements {
+    @FindBy(name = "q")
+    public ExtendedElement q;
+
+    @FindBy(name = "q")
+    public List<ExtendedElement> list;
+
+    @FindBy(name = "a")
+    public WebElement rendered;
+
+    @FindBy(name = "a")
+    public List<WebElement> renderedList;
   }
 
   public static class PublicPage {