WIP Proposed changes to Selenium/WebDriver module for ongoing compatibility

Co-authored with @kiview, this PR started out with some minor (hacky) workarounds but evolved into a rethink of what features are sensible for us to keep on trying to make work given:
* existence of Selenium 4.0.0, with some breaking API changes
* some mutable tags being used for Selenium Docker images, and the (IMHO correct) recommendations by the Selenium team that more exactly pinnable tags should be used in our use case.

Very WIP - all of this could change.

Primary changes:
- Selenium 4.0.0 compatibility fixes
    - Remove in-code workaround for Chrome GPU issue, which created coupling to a Selenium 3.x API
    - Remove support for Selenium 2.x, as supporting 3 major versions of the library becomes infeasible
    - Use non-debug docker images automatically for Selenium 4.x, as `-debug` images are not required (and apparently not available for Firefox)

- Remove `provided` scope dependencies, since we already require some Selenium JARs to be on the classpath. Gradle `implementation` scope is used despite Selenium classes being in our API - this is a slight and deliberate abuse, but seems better than us potentially forcing an upgrade of Selenium by updating our dependency version.
    - TODO: update docs
    - TODO: further testing of the assumption that this will not have real impacts to users.

- Steps to phase out implicit docker image detection and to remove API methods that are coupled to Selenium classes
    - Deprecate constructors that do not supply a user-pinnable Docker image
    - Deprecate constructors/methods that involve Capabilities and RemoteWebDriver
    - Suggest alternative approaches for obtaining a WebDriver instance, predicated on future removal of APIs that are coupled to Selenium classes
    - Have *not* deprecated the `determineClasspathSeleniumVersion` convenience method that can be used to identify Selenium version on the classpath, as this may be something that users want to use
    - TODO: plenty of docs, examples and migration notes
    - TODO: specific documentation around best-practices for selecting a pinnable Selenium image
    - TODO: phase out implicit use of Chrome

Author: rnorth

modules/selenium/build.gradle

@@ -3,10 +3,10 @@ description = "Testcontainers :: Selenium"
 dependencies {
     api project(':testcontainers')
 
-    provided 'org.seleniumhq.selenium:selenium-remote-driver:3.141.59'
-    provided 'org.seleniumhq.selenium:selenium-chrome-driver:3.141.59'
-    testImplementation 'org.seleniumhq.selenium:selenium-firefox-driver:3.141.59'
-    testImplementation 'org.seleniumhq.selenium:selenium-support:3.141.59'
+    implementation 'org.seleniumhq.selenium:selenium-remote-driver:4.0.0'
+    implementation 'org.seleniumhq.selenium:selenium-chrome-driver:4.0.0'
+    implementation 'org.seleniumhq.selenium:selenium-firefox-driver:4.0.0'
+    implementation 'org.seleniumhq.selenium:selenium-support:4.0.0'
 
     testImplementation 'org.mortbay.jetty:jetty:6.1.26'
     testImplementation project(':nginx')

modules/selenium/src/main/java/org/testcontainers/containers/BrowserWebDriverContainer.java

@@ -44,13 +44,15 @@
  */
 public class BrowserWebDriverContainer<SELF extends BrowserWebDriverContainer<SELF>> extends GenericContainer<SELF> implements LinkableContainer, TestLifecycleAware {
 
-    private static final DockerImageName CHROME_IMAGE = DockerImageName.parse("selenium/standalone-chrome-debug");
-    private static final DockerImageName FIREFOX_IMAGE = DockerImageName.parse("selenium/standalone-firefox-debug");
+    private static final DockerImageName CHROME_IMAGE = DockerImageName.parse("selenium/standalone-chrome");
+    private static final DockerImageName FIREFOX_IMAGE = DockerImageName.parse("selenium/standalone-firefox");
+    private static final DockerImageName CHROME_DEBUG_IMAGE = DockerImageName.parse("selenium/standalone-chrome-debug");
+    private static final DockerImageName FIREFOX_DEBUG_IMAGE = DockerImageName.parse("selenium/standalone-firefox-debug");
     private static final DockerImageName[] COMPATIBLE_IMAGES = new DockerImageName[] {
+        CHROME_DEBUG_IMAGE,
+        FIREFOX_DEBUG_IMAGE,
         CHROME_IMAGE,
-        FIREFOX_IMAGE,
-        DockerImageName.parse("selenium/standalone-chrome"),
-        DockerImageName.parse("selenium/standalone-firefox")
+        FIREFOX_IMAGE
     };
 
     private static final String DEFAULT_PASSWORD = "secret";
@@ -75,6 +77,10 @@ public class BrowserWebDriverContainer<SELF extends BrowserWebDriverContainer<SE
 
     private static final Logger LOGGER = LoggerFactory.getLogger(BrowserWebDriverContainer.class);
 
+    /**
+     * @deprecated please use {@link BrowserWebDriverContainer#BrowserWebDriverContainer(DockerImageName)}
+     */
+    @Deprecated
     public BrowserWebDriverContainer() {
         super();
         final WaitStrategy logWaitStrategy = new LogMessageWaitStrategy()
@@ -92,7 +98,10 @@ public BrowserWebDriverContainer() {
     /**
      * Constructor taking a specific webdriver container name and tag
      * @param dockerImageName Name of the selenium docker image
+     *
+     * @deprecated please use {@link BrowserWebDriverContainer#BrowserWebDriverContainer(DockerImageName)}
      */
+    @Deprecated
     public BrowserWebDriverContainer(String dockerImageName) {
         this(DockerImageName.parse(dockerImageName));
     }
@@ -103,17 +112,16 @@ public BrowserWebDriverContainer(String dockerImageName) {
      */
     public BrowserWebDriverContainer(DockerImageName dockerImageName) {
         super(dockerImageName);
-
         // we assert compatibility with the chrome/firefox image later, after capabilities are processed
 
         final WaitStrategy logWaitStrategy = new LogMessageWaitStrategy()
-                .withRegEx(".*(RemoteWebDriver instances should connect to|Selenium Server is up and running|Started Selenium Standalone).*\n")
-                .withStartupTimeout(Duration.of(15, SECONDS));
+            .withRegEx(".*(RemoteWebDriver instances should connect to|Selenium Server is up and running|Started Selenium Standalone).*\n")
+            .withStartupTimeout(Duration.of(15, SECONDS));
 
         this.waitStrategy = new WaitAllStrategy()
-                .withStrategy(logWaitStrategy)
-                .withStrategy(new HostPortWaitStrategy())
-                .withStartupTimeout(Duration.of(15, SECONDS));
+            .withStrategy(logWaitStrategy)
+            .withStrategy(new HostPortWaitStrategy())
+            .withStartupTimeout(Duration.of(15, SECONDS));
 
         this.withRecordingFileFactory(new DefaultRecordingFileFactory());
 
@@ -128,8 +136,9 @@ public SELF withCapabilities(Capabilities capabilities) {
     }
 
     /**
-     * @deprecated Use withCapabilities(Capabilities capabilities) instead:
-     * withCapabilities(new FirefoxOptions())
+     * @deprecated please use {@link BrowserWebDriverContainer#getSeleniumAddress()} to obtain the selenium server URL,
+     * and call the {@link RemoteWebDriver} constructor ({@link RemoteWebDriver#RemoteWebDriver(URL, Capabilities)}),
+     * passing in the URL and {@link Capabilities} object instead.
      *
      * @param capabilities DesiredCapabilities
      * @return SELF
@@ -153,26 +162,8 @@ protected Set<Integer> getLivenessCheckPorts() {
 
     @Override
     protected void configure() {
-
         String seleniumVersion = SeleniumUtils.determineClasspathSeleniumVersion();
 
-        if (capabilities == null) {
-            if (seleniumVersion.startsWith("2.")) {
-                logger().info("No capabilities provided, falling back to DesiredCapabilities.chrome()");
-                capabilities = DesiredCapabilities.chrome();
-            } else {
-                logger().info("No capabilities provided, falling back to ChromeOptions");
-                capabilities = new ChromeOptions();
-            }
-        }
-
-        // Hack for new selenium-chrome image that contains Chrome 92.
-        // If not disabled, container startup will fail in most cases and consume excessive amounts of CPU.
-        if (capabilities instanceof ChromeOptions) {
-            ChromeOptions options = (ChromeOptions) this.capabilities;
-            options.addArguments("--disable-gpu");
-        }
-
         if (recordingMode != VncRecordingMode.SKIP) {
 
             if (vncRecordingDirectory == null) {
@@ -200,6 +191,13 @@ protected void configure() {
             super.setDockerImageName(customImageName.asCanonicalNameString());
         } else {
             DockerImageName standardImageForCapabilities = getStandardImageForCapabilities(capabilities, seleniumVersion);
+            logger().warn(
+                "Image name for selenium image has not been set, and one will be inferred automatically based " +
+                    "on capabilities ({}). Inferred image: {}. This feature is deprecated and will be removed " +
+                    "in the future.",
+                standardImageForCapabilities.asCanonicalNameString(),
+                this.capabilities
+            );
             super.setDockerImageName(standardImageForCapabilities.asCanonicalNameString());
         }
 
@@ -233,34 +231,46 @@ protected void configure() {
      * @param seleniumVersion the version of selenium in use
      * @return an image name for the default standalone Docker image for the appropriate browser
      *
-     * @deprecated note that this method is deprecated and may be removed in the future. The no-args
-     * {@link BrowserWebDriverContainer#BrowserWebDriverContainer()} combined with the
-     * {@link BrowserWebDriverContainer#withCapabilities(Capabilities)} method should be considered. A decision on
-     * removal of this deprecated method will be taken at a future date.
+     * @deprecated note that this method is deprecated and will be removed in the future.
      */
     @Deprecated
     public static String getDockerImageForCapabilities(Capabilities capabilities, String seleniumVersion) {
         return getStandardImageForCapabilities(capabilities, seleniumVersion).asCanonicalNameString();
     }
 
     private static DockerImageName getStandardImageForCapabilities(Capabilities capabilities, String seleniumVersion) {
-        String browserName = capabilities.getBrowserName();
-        switch (browserName) {
-            case BrowserType.CHROME:
-                return CHROME_IMAGE.withTag(seleniumVersion);
-            case BrowserType.FIREFOX:
-                return FIREFOX_IMAGE.withTag(seleniumVersion);
-            default:
-                throw new UnsupportedOperationException("Browser name must be 'chrome' or 'firefox'; provided '" + browserName + "' is not supported");
+        boolean supportsVncWithoutDebugImage = seleniumVersion.startsWith("4.");
+
+        String browserName;
+        if (capabilities == null) {
+            // opinionated default for deprecated path
+            browserName = "chrome";
+        } else {
+            browserName = capabilities.getBrowserName();
+        }
+
+        if (browserName.equals("chrome")) {
+            if (supportsVncWithoutDebugImage) {
+                return CHROME_IMAGE;
+            } else {
+                return CHROME_DEBUG_IMAGE;
+            }
+        } else if (browserName.equals("firefox")) {
+            if (supportsVncWithoutDebugImage) {
+                return FIREFOX_IMAGE;
+            } else {
+                return FIREFOX_DEBUG_IMAGE;
+            }
         }
+
+        throw new UnsupportedOperationException("Browser name must be 'chrome' or 'firefox'; provided '" + browserName + "' is not supported");
     }
 
     public URL getSeleniumAddress() {
         try {
             return new URL("http", getHost(), getMappedPort(SELENIUM_PORT), "/wd/hub");
         } catch (MalformedURLException e) {
-            e.printStackTrace();// TODO
-            return null;
+            throw new RuntimeException("Failed to construct a valid URL!", e);
         }
     }
 
@@ -280,10 +290,6 @@ public int getPort() {
 
     @Override
     protected void containerIsStarted(InspectContainerResponse containerInfo) {
-        driver = Unreliables.retryUntilSuccess(30, TimeUnit.SECONDS,
-                () -> Timeouts.getWithTimeout(10, TimeUnit.SECONDS,
-                        () -> new RemoteWebDriver(getSeleniumAddress(), capabilities)));
-
         if (vncRecordingContainer != null) {
             LOGGER.debug("Starting VNC recording");
             vncRecordingContainer.start();
@@ -296,9 +302,25 @@ protected void containerIsStarted(InspectContainerResponse containerInfo) {
      * All containers and drivers will be automatically shut down after the test method finishes (if used as a @Rule) or the test
      * class (if used as a @ClassRule)
      *
+     * @deprecated please use {@link BrowserWebDriverContainer#getSeleniumAddress()} to obtain the selenium server URL,
+     * and call the {@link RemoteWebDriver} constructor ({@link RemoteWebDriver#RemoteWebDriver(URL, Capabilities)}),
+     * passing in the URL and {@link Capabilities} object instead.
+     *
      * @return a new Remote Web Driver instance
      */
-    public RemoteWebDriver getWebDriver() {
+    @Deprecated
+    public synchronized RemoteWebDriver getWebDriver() {
+        if (driver == null) {
+            if (capabilities == null) {
+                logger().warn("No capabilities provided - this will cause an exception in future versions. Falling back to ChromeOptions");
+                capabilities = new ChromeOptions();
+            }
+
+            driver = Unreliables.retryUntilSuccess(30, TimeUnit.SECONDS,
+                () -> Timeouts.getWithTimeout(10, TimeUnit.SECONDS,
+                    () -> new RemoteWebDriver(getSeleniumAddress(), capabilities)));
+        }
+
         return driver;
     }