[java] Make selenium.debug/webdriver.verbose configure the real logger (Mechanism Only)

java/src/org/openqa/selenium/internal/Debug.java

@@ -17,37 +17,50 @@
 
 package org.openqa.selenium.internal;
 
+import java.util.Arrays;
 import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.logging.ConsoleHandler;
+import java.util.logging.Filter;
+import java.util.logging.Handler;
 import java.util.logging.Level;
 import java.util.logging.Logger;
-import java.util.logging.SimpleFormatter;
-import java.util.logging.StreamHandler;
+import org.jspecify.annotations.Nullable;
 
 /** Used to provide information about whether Selenium is running under debug mode. */
 public class Debug {
 
-  private static final boolean IS_DEBUG;
   private static final AtomicBoolean DEBUG_WARNING_LOGGED = new AtomicBoolean(false);
   private static final Logger SELENIUM_LOGGER = Logger.getLogger("org.openqa.selenium");
-  private static boolean loggerConfigured = false;
 
-  static {
-    IS_DEBUG =
-        Boolean.getBoolean("selenium.debug") || Boolean.getBoolean("selenium.webdriver.verbose");
-  }
+  private static boolean loggerConfigured = false;
+  private static @Nullable Handler installedHandler;
+  private static @Nullable Level previousLevel;
+  private static @Nullable Level levelSetByDebug;
 
   private Debug() {
     // Utility class
   }
 
+  /** Returns whether either Selenium debug system property is currently enabled. */
   public static boolean isDebugging() {
-    return IS_DEBUG;
+    return Boolean.getBoolean("selenium.debug") || Boolean.getBoolean("selenium.webdriver.verbose");
   }
 
+  /**
+   * Returns the legacy level selected by the current debug system properties.
+   *
+   * @deprecated Log at a fixed severity and use {@link #configureLogger()} to expose debug output.
+   */
+  @Deprecated(forRemoval = true)
   public static Level getDebugLogLevel() {
     return isDebugging() ? Level.INFO : Level.FINE;
   }
 
+  static synchronized boolean isHandlerCurrentlyInstalled() {
+    return installedHandler != null
+        && Arrays.asList(SELENIUM_LOGGER.getHandlers()).contains(installedHandler);
+  }
+
   public static boolean isDebugAll() {
     boolean everything = Boolean.parseBoolean(System.getenv("SE_DEBUG"));
     if (everything && DEBUG_WARNING_LOGGED.compareAndSet(false, true)) {
@@ -59,16 +72,76 @@ public static boolean isDebugAll() {
     return everything;
   }
 
-  public static void configureLogger() {
-    if (!isDebugAll() || loggerConfigured) {
+  private static Level effectiveLevel(Logger logger) {
+    for (Logger current = logger; current != null; current = current.getParent()) {
+      Level level = current.getLevel();
+      if (level != null) {
+        return level;
+      }
+    }
+    return Level.INFO;
+  }
+
+  /**
+   * Applies the current Selenium debug switches to the {@code org.openqa.selenium} logger. Selenium
+   * owns the added handler and restores only logger state that it changed. Repeated calls also
+   * repair an externally removed handler or a less-verbose logger level.
+   */
+  public static synchronized void configureLogger() {
+    boolean shouldDebug = isDebugAll() || isDebugging();
+    Handler currentHandler = installedHandler;
+    boolean handlerInstalled =
+        currentHandler != null
+            && Arrays.asList(SELENIUM_LOGGER.getHandlers()).contains(currentHandler);
+    Level currentEffectiveLevel = effectiveLevel(SELENIUM_LOGGER);
+    if (shouldDebug == loggerConfigured
+        && (!shouldDebug
+            || (handlerInstalled
+                && currentHandler != null
+                && currentEffectiveLevel.intValue() <= Level.FINE.intValue()
+                && currentHandler.getLevel().intValue() <= currentEffectiveLevel.intValue()))) {
       return;
     }
 
-    SELENIUM_LOGGER.setLevel(Level.FINE);
+    if (shouldDebug) {
+      if (!loggerConfigured) {
+        previousLevel = SELENIUM_LOGGER.getLevel();
+        levelSetByDebug = null;
+      }
+
+      if (currentEffectiveLevel.intValue() > Level.FINE.intValue()) {
+        SELENIUM_LOGGER.setLevel(Level.FINE);
+        levelSetByDebug = Level.FINE;
+        currentEffectiveLevel = Level.FINE;
+      }
+
+      if (handlerInstalled && currentHandler != null) {
+        currentHandler.setLevel(currentEffectiveLevel);
+      } else {
+        if (currentHandler != null) {
+          SELENIUM_LOGGER.removeHandler(currentHandler);
+          currentHandler.close();
+        }
+        Handler handler = new ConsoleHandler();
+        handler.setLevel(currentEffectiveLevel);
+        Filter belowInfo = record -> record.getLevel().intValue() < Level.INFO.intValue();
+        handler.setFilter(belowInfo);
+        SELENIUM_LOGGER.addHandler(handler);
+        installedHandler = handler;
+      }
+    } else {
+      if (currentHandler != null) {
+        SELENIUM_LOGGER.removeHandler(currentHandler);
+        currentHandler.close();
+        installedHandler = null;
+      }
+      if (levelSetByDebug != null && levelSetByDebug.equals(SELENIUM_LOGGER.getLevel())) {
+        SELENIUM_LOGGER.setLevel(previousLevel);
+      }
+      previousLevel = null;
+      levelSetByDebug = null;
+    }
 
-    StreamHandler handler = new StreamHandler(System.err, new SimpleFormatter());
-    handler.setLevel(Level.FINE);
-    SELENIUM_LOGGER.addHandler(handler);
-    loggerConfigured = true;
+    loggerConfigured = shouldDebug;
   }
 }

java/src/org/openqa/selenium/remote/RemoteWebDriver.java

@@ -122,8 +122,9 @@ public class RemoteWebDriver
         PrintsPage,
         TakesScreenshot {
 
+  // Configure before subclass constructor arguments can trigger driver discovery logs.
   static {
-    org.openqa.selenium.internal.Debug.configureLogger();
+    Debug.configureLogger();
   }
 
   private static final Logger LOG = Logger.getLogger(RemoteWebDriver.class.getName());
@@ -207,6 +208,7 @@ public RemoteWebDriver(
       CommandExecutor executor, Capabilities capabilities, ClientConfig clientConfig) {
     this.clientConfig = Require.nonNull("Client config", clientConfig);
     this.executor = Require.nonNull("Command executor", executor);
+    Debug.configureLogger();
     this.capabilities = requireNonNullElseGet(capabilities, () -> new ImmutableCapabilities());
 
     try {

java/test/org/openqa/selenium/internal/BUILD.bazel

@@ -9,5 +9,7 @@ java_test_suite(
         "//java/src/org/openqa/selenium:core",
         artifact("org.assertj:assertj-core"),
         artifact("org.junit.jupiter:junit-jupiter-api"),
+        artifact("uk.org.webcompere:system-stubs-core"),
+        artifact("uk.org.webcompere:system-stubs-jupiter"),
     ] + JUNIT5_DEPS,
 )