Merge pull request #17 from seleniumhq-community/pr/prefix-browserVersion-cap

Normalize [browserVersion] for grid compatibility

Author: sbabcoc

README.md

@@ -44,4 +44,14 @@ java -jar selenium-server-<version>.jar --ext htmlunit-remote-<version>-grid-ext
 ```
 The `grid-extension` artifact provides all of the specifications and service providers required to enable **Selenium 4 Grid** to supply remote sessions of **HtmlUnitDriver**. This artifact combines `htmlunit-remote` with `htmlunit3-driver`, `htmlunit`, and all of their unique dependencies.
 
+### Specification of [browserVersion]
+
+In **HtmlUnit Driver**, you can use the standard `browserVersion` capability to select a specific browser emulation profile. This works as expected in local operation but will cause driver acquisition to fail in remote configurations. The reason for this is that `browserVersion` is an _identity_ value that the Selenium Grid distributor expects to match against the stereotype of a compatible node. In **HtmlUnit Driver**, `browserVersion` is a _configuration_ value, so this capability should not be considered for slot matching.
+
+**HtmlUnit Remote** adds a vendor-specific capability for selecting a specific browser emulation profile: `garg:browserVersion`.  If you use the standard **HtmlUnitDriverOptions** class to build your driver specification, this issue is handled for you automatically. If you specify driver capabilities directly, be sure to use this new vendor-specific capability name.
+
+```
+{"browserName": "htmlunit", "garg:browserVersion": "firefox-115"}
+```
+
 > Written with [StackEdit](https://stackedit.io/).

pom.xml

@@ -5,7 +5,7 @@
 
   <groupId>com.nordstrom.ui-tools</groupId>
   <artifactId>htmlunit-remote</artifactId>
-  <version>4.38.1-SNAPSHOT</version>
+  <version>4.39.0-SNAPSHOT</version>
 
   <name>htmlunit-remote</name>
   <description>This is the remote wrapper for HtmlUnitDriver</description>
@@ -32,8 +32,8 @@
     <maven.build.timestamp.format>yyyy-MM-dd HH:mm</maven.build.timestamp.format>
     <maven.compiler.source>11</maven.compiler.source>
     <maven.compiler.target>11</maven.compiler.target>
-    <selenium.version>4.38.0</selenium.version>
-    <htmlunit.version>4.38.0</htmlunit.version>
+    <selenium.version>4.39.0</selenium.version>
+    <htmlunit.version>4.39.0</htmlunit.version>
     <junit.version>4.13.2</junit.version>
     <checkstyle.version>10.15.0</checkstyle.version>
     <spotbugs.version>4.8.4</spotbugs.version>

src/main/java/org/openqa/selenium/htmlunit/remote/HtmlUnitDriverInfo.java

@@ -24,13 +24,16 @@
 
 import org.openqa.selenium.Capabilities;
 import org.openqa.selenium.ImmutableCapabilities;
+import org.openqa.selenium.MutableCapabilities;
 import org.openqa.selenium.SessionNotCreatedException;
 import org.openqa.selenium.WebDriver;
 import org.openqa.selenium.WebDriverInfo;
 import org.openqa.selenium.htmlunit.HtmlUnitDriver;
 import org.openqa.selenium.htmlunit.options.HtmlUnitDriverOptions;
+import org.openqa.selenium.remote.CapabilityType;
 
 import com.google.auto.service.AutoService;
+import com.google.common.annotations.VisibleForTesting;
 
 /**
  * Describes an {@link HtmlUnitDriver} instance. This allows services to query the system at
@@ -117,6 +120,38 @@ public Optional<WebDriver> createDriver(final Capabilities capabilities) throws
             return Optional.empty();
         }
 
-        return Optional.of(new HtmlUnitDriver(new HtmlUnitDriverOptions().merge(capabilities)));
+        Capabilities normalized = normalizeBrowserVersion(capabilities);
+        return Optional.of(new HtmlUnitDriver(new HtmlUnitDriverOptions().merge(normalized)));
+    }
+
+    /**
+     * The following implementation ensures grid-compatible handling of
+     * the [browserVersion] capability. If the standard [browserVersion]
+     * capability is defined, it's removed. If the [garg:browserVersion]
+     * is undefined, the original value of [browserVersion] is adopted.
+     * 
+     * @param capabilities {@link Capabilities} object to normalize
+     * @return grid-compatible capabilities with normalized [browserVersion]
+     */
+    @VisibleForTesting
+    static MutableCapabilities normalizeBrowserVersion(final Capabilities capabilities) {
+        // create mutable Capabilities object
+        MutableCapabilities mutable = new MutableCapabilities(capabilities);
+        // get standard [browserVersion] if non-null
+        Optional.ofNullable(mutable.getBrowserVersion())
+            // filter out if value is empty
+            .filter(versionVal -> !versionVal.isEmpty())
+            // if value exists
+            .ifPresent(versionVal -> {
+                // if vendor-specific browser version is undefined
+                if (mutable.getCapability(HtmlUnitDriverOptions.BROWSER_VERSION) == null) {
+                    // set value of vendor-specific browser version
+                    mutable.setCapability(HtmlUnitDriverOptions.BROWSER_VERSION, versionVal);
+                }
+                // remove standard [browserVersion] capability
+                mutable.setCapability(CapabilityType.BROWSER_VERSION, (String) null);
+            }
+        );
+        return mutable;
     }
 }

src/test/java/org/openqa/selenium/htmlunit/remote/HtmlUnitDriverInfoTest.java

@@ -0,0 +1,56 @@
+package org.openqa.selenium.htmlunit.remote;
+
+import static org.junit.Assert.assertEquals;
+
+import org.junit.Test;
+import org.openqa.selenium.Capabilities;
+import org.openqa.selenium.htmlunit.options.HtmlUnitDriverOptions;
+import org.openqa.selenium.remote.Browser;
+import org.openqa.selenium.remote.CapabilityType;
+import org.openqa.selenium.remote.DesiredCapabilities;
+
+public class HtmlUnitDriverInfoTest {
+    
+    @Test
+    public void testNormalizationOfStandardCapabilities() {
+        DesiredCapabilities desired =
+                // set [browserName] and [browserVersion]
+                new DesiredCapabilities(Browser.HTMLUNIT.browserName(), Browser.EDGE.browserName(), null);
+        
+        Capabilities capabilities = HtmlUnitDriverInfo.normalizeBrowserVersion(desired);
+        assertEquals(Browser.HTMLUNIT.browserName(), capabilities.getBrowserName());
+        assertEquals(null, capabilities.getCapability(CapabilityType.BROWSER_VERSION));
+        assertEquals(Browser.EDGE.browserName(), capabilities.getCapability(HtmlUnitDriverOptions.BROWSER_VERSION));
+    }
+
+    @Test
+    public void testNormalizationOfVendorSpecificCapabilities() {
+        DesiredCapabilities desired =
+                // set [browserName]
+                new DesiredCapabilities(Browser.HTMLUNIT.browserName(), null, null);
+        
+        // set [garg:browserVersion]
+        desired.setCapability(HtmlUnitDriverOptions.BROWSER_VERSION, Browser.FIREFOX.browserName());
+        
+        Capabilities capabilities = HtmlUnitDriverInfo.normalizeBrowserVersion(desired);
+        assertEquals(Browser.HTMLUNIT.browserName(), capabilities.getBrowserName());
+        assertEquals(null, capabilities.getCapability(CapabilityType.BROWSER_VERSION));
+        assertEquals(Browser.FIREFOX.browserName(), capabilities.getCapability(HtmlUnitDriverOptions.BROWSER_VERSION));
+    }
+
+    @Test
+    public void testVendorSpecificBrowserVersionOverride() {
+        DesiredCapabilities desired =
+                // set [browserName] and [browserVersion]
+                new DesiredCapabilities(Browser.HTMLUNIT.browserName(), Browser.IE.browserName(), null);
+        
+        // set [garg:browserVersion]
+        desired.setCapability(HtmlUnitDriverOptions.BROWSER_VERSION, Browser.CHROME.browserName());
+        
+        Capabilities capabilities = HtmlUnitDriverInfo.normalizeBrowserVersion(desired);
+        assertEquals(Browser.HTMLUNIT.browserName(), capabilities.getBrowserName());
+        assertEquals(null, capabilities.getCapability(CapabilityType.BROWSER_VERSION));
+        assertEquals(Browser.CHROME.browserName(), capabilities.getCapability(HtmlUnitDriverOptions.BROWSER_VERSION));
+    }
+
+}