Merge pull request #292 from telekom/feature/support-selenium-4

Feature/support selenium 4

.gitignore

@@ -1,15 +1,13 @@
 test-report
 **/report-testsundertest-*
 .gradle
-gradle
 *.iml
 .idea
 target
 licenses
 *.zip
 out
 build
-gradlew
 /bin/
 /.classpath
 /.project

build.gradle

@@ -20,8 +20,10 @@ ext {
     core = project(':core')
     report = project(':report-ng')
 
-    seleniumVersion = '3.141.59'
-    guavaVersion = "28.1-jre"
+    seleniumVersion = '4.10.0'
+//    seleniumVersion = '4.6.0'
+    // Must be the same like in Selenium 4
+    guavaVersion = "31.1-jre"
 
     moduleVersion = '2-SNAPSHOT'
     if (System.properties.containsKey('ttVersion')) {

core/build.gradle

@@ -29,10 +29,10 @@ dependencies {
     implementation 'com.opencsv:opencsv:3.9'
     // </CSVTestDataReader>
 
-    // <ExceptionUtils>
-    // Comes already implicit from reflections
-    // implementation 'org.javassist:javassist:3.20.0-GA'
-    // </ExceptionUtils>
+
+    // Selenium 4.6 comes with 'io.netty:netty-transport-native-epoll:4.1.84.Final'
+    // -> Dependency error Could not find netty-transport-native-epoll-4.1.84.Final-linux-x86_64.jar (io.netty:netty-transport-native-epoll:4.1.84.Final).
+    api 'org.seleniumhq.selenium:selenium-java:' + seleniumVersion
 
     api('org.testng:testng:7.8.0')
     //  {

core/src/main/java/eu/tsystems/mms/tic/testframework/constants/Browsers.java

@@ -28,7 +28,5 @@ public class Browsers {
     public static final String ie = "ie";
     public static final String edge = "edge";
     public static final String safari = "safari";
-    public static final String phantomjs = "phantomjs";
-    public static final String htmlunit = "htmlunit";
     public static final String chromeHeadless = "chromeHeadless";
 }

core/src/main/java/eu/tsystems/mms/tic/testframework/constants/TesterraProperties.java

@@ -23,6 +23,8 @@
 
 import eu.tsystems.mms.tic.testframework.common.Testerra.Properties;
 
+import java.util.function.Predicate;
+
 /**
  * Class holding keys of all properties.
  *
@@ -49,7 +51,10 @@ private TesterraProperties() {
 
     /**
      * WDM: Timeout / Duration Setting for Window Switching
+     *
+     * @deprecated Use {@link IWebDriverManager#switchToWindow(Predicate)} and {@link CONTROL#waitFor(int, Predicate)} instead
      */
+    @Deprecated
     public static final String WEBDRIVER_WINDOW_SWITCH_MAX_DURATION = "tt.wdm.timeouts.seconds.window.switch.duration";
 
     /**

core/src/main/java/eu/tsystems/mms/tic/testframework/report/model/context/SessionContext.java

@@ -42,6 +42,7 @@ public class SessionContext extends AbstractContext {
 
     public SessionContext(WebDriverRequest webDriverRequest) {
         try {
+            // Store a clone of current WebDriverRequest to prevent changes and keep the real request settings for every session
             setWebDriverRequest(webDriverRequest.clone());
         } catch (CloneNotSupportedException e) {
             throw new RuntimeException(e);

core/src/main/java/eu/tsystems/mms/tic/testframework/webdrivermanager/WebDriverRequest.java

@@ -1,16 +1,17 @@
 package eu.tsystems.mms.tic.testframework.webdrivermanager;
 
+import org.openqa.selenium.Capabilities;
+
 import java.net.URL;
-import java.util.Map;
 import java.util.Optional;
 
 public interface WebDriverRequest extends Cloneable {
     String DEFAULT_SESSION_KEY = "default";
     String getSessionKey();
     String getBrowser();
     String getBrowserVersion();
-    Optional<String> getPlatformName();
-    Map<String, Object> getCapabilities();
+    String getPlatformName();
+    Capabilities getCapabilities();
 
     boolean getShutdownAfterTest();
     boolean getShutdownAfterTestFailed();
@@ -20,5 +21,6 @@ public interface WebDriverRequest extends Cloneable {
     void setShutdownAfterExecution(boolean shutdownAfterExecution);
 
     Optional<URL> getServerUrl();
+
     WebDriverRequest clone() throws CloneNotSupportedException;
 }

docs/build.gradle

@@ -57,6 +57,7 @@ asciidoctor {
             revnumber: "${version}",
             nofooter: true,
             'source-highlighter': 'highlightjs',
+//            'highlightjs-theme': 'atom-one-dark',
             'highlightjs-theme': 'atom-one-light',
             highlightjsdir: 'highlight',
             icons: 'font',

docs/src/docs/best-practices.adoc

@@ -9,3 +9,4 @@ include::best-practices/multiple-profiles.adoc[leveloffset=+1]
 include::best-practices/multiple-environments.adoc[leveloffset=+1]
 include::best-practices/project-setup.adoc[leveloffset=+1]
 include::best-practices/debugging.adoc[leveloffset=+1]
+include::best-practices/chrome-dev-tools.adoc.adoc[leveloffset=+1]

docs/src/docs/best-practices/chrome-dev-tools.adoc.adoc

@@ -0,0 +1,79 @@
+= Access to Chrome dev tools
+
+[NOTE]
+====
+* The following examples are working with Selenium 4 server. If you are using another grid like Selenoid the usage could be different.
+* Only Chrome browser supports access to development tools.
+====
+
+== Emulate geo location
+
+Examples are based on https://www.selenium.dev/documentation/webdriver/bidirectional/chrome_devtools/.
+
+.Local webdriver
+[source,java]
+----
+WebDriver webDriver = WEB_DRIVER_MANAGER.getWebDriver();
+
+ChromeDriver chromeDriver = WEB_DRIVER_MANAGER
+        .unwrapWebDriver(webDriver, ChromeDriver.class).get();
+
+DevTools devTools = chromeDriver.getDevTools();
+devTools.createSession();
+devTools.send(Emulation.setGeolocationOverride(
+        Optional.of(52.52084),
+        Optional.of(13.40943),
+        Optional.of(1)));
+
+webDriver.get("https://my-location.org/");      // page gets the new geo location information
+----
+
+.Remote webdriver (e.g. of a grid)
+[source,java]
+----
+WebDriver webDriver = WEB_DRIVER_MANAGER.getWebDriver();
+
+RemoteWebDriver remoteWebDriver = WEB_DRIVER_MANAGER
+        .unwrapWebDriver(webDriver, RemoteWebDriver.class).get();
+webDriver = new Augmenter().augment(remoteWebDriver);
+
+DevTools devTools = ((HasDevTools) webDriver).getDevTools();
+devTools.createSession();
+
+devTools.send(Emulation.setGeolocationOverride(
+        Optional.of(52.52084),
+        Optional.of(13.40943),
+        Optional.of(1)));
+
+webDriver.get("https://my-location.org/");
+----
+
+== Basic authentication
+
+[source,java]
+----
+WebDriver webDriver = WEB_DRIVER_MANAGER.getWebDriver();
+WebDriver remoteWebDriver = WEB_DRIVER_MANAGER.unwrapWebDriver(webDriver, RemoteWebDriver.class).get();
+
+AtomicReference<DevTools> devToolsAtomicReference = new AtomicReference<>();
+
+remoteWebDriver = new Augmenter()
+        .addDriverAugmentation(
+                "chrome",
+                HasAuthentication.class,
+                (caps, exec) -> (whenThisMatches, useTheseCredentials) -> {
+                    devToolsAtomicReference.get().createSessionIfThereIsNotOne();
+                    devToolsAtomicReference.get().getDomains()
+                            .network()
+                            .addAuthHandler(whenThisMatches, useTheseCredentials);
+                })
+        .augment(remoteWebDriver);
+
+DevTools devTools = ((HasDevTools) remoteWebDriver).getDevTools();
+devTools.createSession();
+devToolsAtomicReference.set(devTools);
+
+// Set credentials and call the page with 'basic authentication' protection
+((HasAuthentication) remoteWebDriver).register(UsernameAndPassword.of("admin", "admin"));
+webDriver.get("https://the-internet.herokuapp.com/basic_auth");
+----

docs/src/docs/browser-caps.adoc

@@ -2,12 +2,10 @@
 
 You can customize your WebDriver session by setting capabilities in the following ways:
 
-- <<Global capabilities>> that affect every WebDriver session created
+- Global capabilities that affect every WebDriver session created and can be set by <<User agent configuration>>
 - <<Request capabilities>> that affect only WebDrivers for a given request
-- <<User agent configuration>> that affect only WebDrivers for a specified browser
 
 When creating a new WebDriver, these capabilities get merged together in this exact order.
 
-include::browsercaps/common-browser-caps.adoc[leveloffset=+1]
 include::browsercaps/setting-browser-caps.adoc[leveloffset=+1]
 include::browsercaps/proxy-setup.adoc[leveloffset=+1]

docs/src/docs/browsercaps/proxy-setup.adoc

@@ -10,7 +10,6 @@ The following code setups a proxy based on the <<Using a proxy,System's proxy co
 [source,java]
 ----
 import org.testng.annotations.BeforeSuite;
-import org.openqa.selenium.remote.DesiredCapabilities;
 import eu.tsystems.mms.tic.testframework.webdrivermanager.WebDriverManagerUtils;
 import eu.tsystems.mms.tic.testframework.webdrivermanager.WebDriverProxyUtils;
 import org.openqa.selenium.Proxy;
@@ -20,15 +19,7 @@ public abstract class AbstractTest extends TesterraTest {
     @BeforeSuite
     public void proxySetup() {
         WebDriverProxyUtils utils = new WebDriverProxyUtils();
-        /**
-        * Global browser proxy configuration
-        */
-        Proxy defaultProxy = utils.getDefaultHttpProxy();
-        WEB_DRIVER_MANAGER.setGlobalCapability(CapabilityType.PROXY, defaultProxy);
-
-        /**
-        * Browser specific proxy configuration
-        */
+
         Proxy otherProxy = utils.createHttpProxyFromUrl(
             new URL("http://proxyUser:secretPassword@my-proxy:3128")
         );

docs/src/docs/browsercaps/setting-browser-caps.adoc

@@ -2,6 +2,8 @@
 
 The user agent configuration is most precise, because it provides explicit browser options based on the Selenium driver.
 
+The setting applies to all created sessions for a browser type (_global_).
+
 [source, java]
 ----
 import eu.tsystems.mms.tic.testframework.useragents.FirefoxConfig;
@@ -11,7 +13,23 @@ WEB_DRIVER_MANAGER.setUserAgentConfig(Browsers.firefox, (FirefoxConfig) options
 });
 ----
 
-NOTE: Have a look into <<Browser specific knowledge>> for specific browser options.
+Non-standard capabilities need a vendor prefix and can be set as follows:
+
+[source,java]
+----
+Map<String, Object> customCaps = new HashMap<>();
+customCaps.put("foo", "bar");
+
+WEB_DRIVER_MANAGER.setUserAgentConfig(Browsers.firefox, (FirefoxConfig) options -> {
+    options.setCapability("custom:caps", customCaps);
+});
+----
+
+[NOTE]
+====
+* Have a look into <<Browser specific knowledge>> for specific browser options.
+* See https://www.w3.org/TR/webdriver1/#capabilities[here] a list of W3C conform capabilities.
+====
 
 = Request capabilities
 
@@ -21,19 +39,24 @@ Some WebDriverRequests support setting capabilities, like the `DesktopWebDriverR
 [source,java]
 ----
 DesktopWebDriverRequest request = new DesktopWebDriverRequest();
-DesiredCapabilities caps = request.getDesiredCapabilities();
+MutableCapabilities caps = request.getMutableCapabilities();
 caps.setCapability(CapabilityType.ACCEPT_INSECURE_CERTS, true);
+
 // Start your session with the DesktopWebDriverRequest object
 WebDriver webDriver = WEB_DRIVER_MANAGER.getWebDriver(request);
 ----
 
 [NOTE]
 =====
-Have a look into <<Browser specific knowledge>> for specific browser options. +
-Find some more details for `DesktopWebDriverRequest` at <<_request_configuration>>.
+* Have a look into <<Browser specific knowledge>> for specific browser options.
+* Find some more details for `DesktopWebDriverRequest` at <<_request_configuration>>.
+* Since Selenium 4 browser options should use instead of `DesiredCapabilties` (https://www.selenium.dev/documentation/webdriver/getting_started/upgrade_to_selenium_4). +
+Therefore `request.getDesiredCapabilities()` is deprecated.
 =====
 
-= Global capabilities
+= Global capabilities with `WEB_DRIVER_MANAGER` (*@deprecated*)
+
+NOTE: This feature is deprecated, please use <<User agent configuration>>
 
 You can customize your browser session by setting capabilities for every browser type.
 

docs/src/docs/index.adoc

@@ -31,6 +31,7 @@ include::execution.adoc[leveloffset=+1]
 include::reports.adoc[leveloffset=+1]
 include::modules.adoc[leveloffset=+1]
 include::utilities.adoc[leveloffset=+1]
+include::selenium4.adoc[leveloffset=+1]
 
 '''
 = Extending Testerra

docs/src/docs/known-issues.adoc

@@ -1,4 +1,5 @@
 = Known issues
+include::properties/property-attributes.adoc[]
 
 Because we depend on other frameworks and tools like TestNG and Selenium we may encounter issues that we want to fix, but are bound to releases and fixes in our dependencies.
 
@@ -10,4 +11,8 @@ Every known issue in our dependencies that will lead to an error, an unexpected
 
 CAUTION: Never close WebDriver sessions calling `WebDriver.quit()`. This may encounter problems or some kind of unexpected issues, because the session is not marked as closed in `WebDriverManager` 's session store.
 
+=== Selenium 4 and browser version
+
+Using a standalone Selenium 4 server (no grid) you must not set browser version via `{browser_setting}` or `{browser_version}`. Your local Selenium 4 server has no information about the versions of your installed browsers and cannot handle version information in your Webdriver request.
+
 

docs/src/docs/properties/webdriver-props.adoc

@@ -15,8 +15,6 @@ The following types of browsers are supported:
 * ie
 * edge
 * safari
-* phantomjs
-* htmlunit
 * chromeHeadless
 
 | {browser} | na.

docs/src/docs/selenium4.adoc

@@ -0,0 +1,5 @@
+= Selenium 4
+
+include::selenium4/selenium4-common.adoc[leveloffset=+1]
+include::selenium4/selenium4-changes.adoc[leveloffset=+1]
+include::selenium4/selenium4-cdp.adoc[leveloffset=+1]