Merge branch 'trunk' into release-preparation-4.28.0

Author: VietND96

.github/workflows/update-documentation.yml

@@ -140,10 +140,6 @@ jobs:
         run: |
           git config --local user.email "[email protected]"
           git config --local user.name "Selenium CI Bot"
-      - name: Install specific version of DocFX tool
-        #  Pinning to 2.75.3 to avoid breaking changes in newer versions
-        #  See https://github.com/dotnet/docfx/issues/9855
-        run: dotnet tool install --global --version 2.75.3 docfx
       - name: Update Documentation
         if: needs.determine-language.outputs.language == 'all' || needs.determine-language.outputs.language == 'dotnet'
         run: ./go dotnet:docs

MODULE.bazel

@@ -93,7 +93,7 @@ register_toolchains("@dotnet_toolchains//:all")
 oci = use_extension("@rules_oci//oci:extensions.bzl", "oci")
 oci.pull(
     name = "java_image_base",
-    digest = "sha256:161a1d97d592b3f1919801578c3a47c8e932071168a96267698f4b669c24c76d",
+    digest = "sha256:1df9f3e6a2de0544dd04f1840aa811d334045c9126f9e93d8da45448061ad51e",
     image = "gcr.io/distroless/java17",
 )
 oci.pull(

Rakefile

@@ -777,10 +777,9 @@ namespace :dotnet do
   task :docs, [:skip_update] do |_task, arguments|
     FileUtils.rm_rf('build/docs/api/dotnet/')
     begin
-      # Pinning to 2.75.3 to avoid breaking changes in newer versions
-      # See https://github.com/dotnet/docfx/issues/9855
+      # Pinning to 2.78.2 to avoid breaking changes in newer versions
       sh 'dotnet tool uninstall --global docfx || true'
-      sh 'dotnet tool install --global --version 2.75.3 docfx'
+      sh 'dotnet tool install --global --version 2.78.2 docfx'
       # sh 'dotnet tool update -g docfx'
     rescue StandardError
       puts 'Please ensure that .NET SDK is installed.'

dotnet/docs/docfx.json

@@ -11,7 +11,7 @@
       ],
       "dest": "webdriver",
       "namespaceLayout": "nested",
-      "outputFormat": "apiPage"
+      //"outputFormat": "apiPage" // "apiPage" generation with errors
     },
     {
       "src": [
@@ -24,9 +24,8 @@
       ],
       "dest": "support",
       "namespaceLayout": "nested",
-      "outputFormat": "apiPage"
+      //"outputFormat": "apiPage" // "apiPage" generation with errors
     }
-
   ],
   "build": {
     "content": [

java/src/org/openqa/selenium/PageLoadStrategy.java

@@ -17,6 +17,10 @@
 
 package org.openqa.selenium;
 
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+@NullMarked
 public enum PageLoadStrategy {
   NONE("none"),
   EAGER("eager"),
@@ -33,7 +37,7 @@ public String toString() {
     return String.valueOf(text);
   }
 
-  public static PageLoadStrategy fromString(String text) {
+  public static @Nullable PageLoadStrategy fromString(@Nullable String text) {
     if (text != null) {
       for (PageLoadStrategy b : PageLoadStrategy.values()) {
         if (text.equalsIgnoreCase(b.text)) {

java/src/org/openqa/selenium/UnexpectedAlertBehaviour.java

@@ -17,6 +17,10 @@
 
 package org.openqa.selenium;
 
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+@NullMarked
 public enum UnexpectedAlertBehaviour {
   ACCEPT("accept"),
   DISMISS("dismiss"),
@@ -35,7 +39,7 @@ public String toString() {
     return String.valueOf(text);
   }
 
-  public static UnexpectedAlertBehaviour fromString(String text) {
+  public static @Nullable UnexpectedAlertBehaviour fromString(@Nullable String text) {
     if (text != null) {
       for (UnexpectedAlertBehaviour b : UnexpectedAlertBehaviour.values()) {
         if (text.equalsIgnoreCase(b.text)) {

java/src/org/openqa/selenium/WindowType.java

@@ -17,7 +17,11 @@
 
 package org.openqa.selenium;
 
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
 /** Represents the type of new browser window that may be created. */
+@NullMarked
 public enum WindowType {
   WINDOW("window"),
   TAB("tab"),
@@ -34,7 +38,7 @@ public String toString() {
     return String.valueOf(text);
   }
 
-  public static WindowType fromString(String text) {
+  public static @Nullable WindowType fromString(@Nullable String text) {
     if (text != null) {
       for (WindowType b : WindowType.values()) {
         if (text.equalsIgnoreCase(b.text)) {

java/src/org/openqa/selenium/interactions/Actions.java

@@ -30,6 +30,8 @@
 import java.util.Objects;
 import java.util.Set;
 import java.util.function.IntConsumer;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 import org.openqa.selenium.WebDriver;
 import org.openqa.selenium.WebElement;
 import org.openqa.selenium.interactions.PointerInput.Origin;
@@ -44,16 +46,17 @@
  *
  * <p>Call {@link #perform()} at the end of the method chain to actually perform the actions.
  */
+@NullMarked
 public class Actions {
 
   private final WebDriver driver;
 
   // W3C
   private final Map<InputSource, Sequence> sequences = new HashMap<>();
 
-  private PointerInput activePointer;
-  private KeyInput activeKeyboard;
-  private WheelInput activeWheel;
+  private @Nullable PointerInput activePointer;
+  private @Nullable KeyInput activeKeyboard;
+  private @Nullable WheelInput activeWheel;
   private Duration actionDuration;
 
   public Actions(WebDriver driver) {
@@ -537,21 +540,21 @@ public KeyInput getActiveKeyboard() {
     if (this.activeKeyboard == null) {
       setActiveKeyboard("default keyboard");
     }
-    return this.activeKeyboard;
+    return Require.nonNull("ActiveKeyboard", this.activeKeyboard);
   }
 
   public PointerInput getActivePointer() {
     if (this.activePointer == null) {
       setActivePointer(PointerInput.Kind.MOUSE, "default mouse");
     }
-    return this.activePointer;
+    return Require.nonNull("ActivePointer", this.activePointer);
   }
 
   public WheelInput getActiveWheel() {
     if (this.activeWheel == null) {
       setActiveWheel("default wheel");
     }
-    return this.activeWheel;
+    return Require.nonNull("ActiveWheel", this.activeWheel);
   }
 
   public Duration getActionDuration() {

java/src/org/openqa/selenium/interactions/Pause.java

@@ -22,8 +22,10 @@
 import java.time.Duration;
 import java.util.HashMap;
 import java.util.Map;
+import org.jspecify.annotations.NullMarked;
 
 /** Indicates that a given {@link InputSource} should pause for a given duration. */
+@NullMarked
 public class Pause extends Interaction implements Encodable {
 
   private final Duration duration;

java/src/org/openqa/selenium/interactions/Sequence.java

@@ -22,6 +22,7 @@
 import java.util.LinkedList;
 import java.util.List;
 import java.util.Map;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * A sequence of action objects for a given {@link InputSource} for use with the W3C <a
@@ -30,6 +31,7 @@
  * Interaction}s, with the first item in each sequence being executed at the same time, then the
  * second, and so on, until all interactions in all sequences have been executed.
  */
+@NullMarked
 public class Sequence implements Encodable {
 
   private final List<Encodable> actions = new LinkedList<>();

java/src/org/openqa/selenium/interactions/WheelInput.java

@@ -24,6 +24,8 @@
 import java.util.Map;
 import java.util.Optional;
 import java.util.UUID;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 import org.openqa.selenium.Point;
 import org.openqa.selenium.WebElement;
 import org.openqa.selenium.WrapsElement;
@@ -33,11 +35,12 @@
  * Models a <a href="https://www.w3.org/TR/webdriver/#dfn-wheel-input-source">wheel input
  * source</a>.
  */
+@NullMarked
 public class WheelInput implements InputSource, Encodable {
 
   private final String name;
 
-  public WheelInput(String name) {
+  public WheelInput(@Nullable String name) {
     this.name = Optional.ofNullable(name).orElse(UUID.randomUUID().toString());
   }
 

java/src/org/openqa/selenium/logging/LogEntries.java

@@ -23,13 +23,15 @@
 import java.util.Iterator;
 import java.util.List;
 import java.util.stream.StreamSupport;
+import org.jspecify.annotations.NullMarked;
 import org.openqa.selenium.Beta;
 
 /**
  * Represent a pool of {@link LogEntry}. This class also provides filtering mechanisms based on
  * levels.
  */
 @Beta
+@NullMarked
 public class LogEntries implements Iterable<LogEntry> {
 
   private final List<LogEntry> entries;

java/src/org/openqa/selenium/logging/LogEntry.java

@@ -22,8 +22,10 @@
 import java.util.HashMap;
 import java.util.Map;
 import java.util.logging.Level;
+import org.jspecify.annotations.NullMarked;
 
 /** Represents a single log statement. */
+@NullMarked
 public class LogEntry {
 
   private final Level level;

java/src/org/openqa/selenium/logging/LogLevelMapping.java

@@ -20,13 +20,20 @@
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.Map;
+import java.util.Optional;
 import java.util.logging.Level;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
+@NullMarked
 public class LogLevelMapping {
 
   /** WebDriver log level DEBUG which is mapped to Level.FINE. */
   private static final String DEBUG = "DEBUG";
 
+  // Default the log level to info.
+  private static final Level DEFAULT_LEVEL = Level.INFO;
+
   private static final Map<Integer, Level> levelMap;
 
   static {
@@ -70,15 +77,15 @@ public static String getName(Level level) {
     return normalized == Level.FINE ? DEBUG : normalized.getName();
   }
 
-  public static Level toLevel(String logLevelName) {
+  public static Level toLevel(@Nullable String logLevelName) {
     if (logLevelName == null || logLevelName.isEmpty()) {
-      // Default the log level to info.
-      return Level.INFO;
+      return DEFAULT_LEVEL;
     }
 
     if (logLevelName.equals(DEBUG)) {
       return Level.FINE;
     }
-    return levelMap.get(Level.parse(logLevelName).intValue());
+    return Optional.ofNullable(levelMap.get(Level.parse(logLevelName).intValue()))
+        .orElse(DEFAULT_LEVEL);
   }
 }

java/src/org/openqa/selenium/logging/SessionLogs.java

@@ -24,10 +24,13 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+import org.jspecify.annotations.NullMarked;
 import org.openqa.selenium.Beta;
+import org.openqa.selenium.internal.Require;
 
 /** Contains the logs for a session divided by supported log types. */
 @Beta
+@NullMarked
 public class SessionLogs {
   private final Map<String, LogEntries> logTypeToEntriesMap;
 
@@ -66,7 +69,7 @@ public static SessionLogs fromJSON(Map<String, Object> rawSessionLogs) {
         logEntries.add(
             new LogEntry(
                 LogLevelMapping.toLevel(String.valueOf(rawEntry.get("level"))),
-                ((Number) rawEntry.get("timestamp")).longValue(),
+                Require.nonNull("timestamp", (Number) rawEntry.get("timestamp")).longValue(),
                 String.valueOf(rawEntry.get("message"))));
       }
       sessionLogs.addLog(logType, new LogEntries(logEntries));

java/src/org/openqa/selenium/remote/service/DriverService.java

@@ -508,10 +508,10 @@ public DS build() {
       if (Locale.getDefault(Locale.Category.FORMAT).getLanguage().equals("ar")) {
         throw new NumberFormatException(
             String.format(
-                "Couldn't format the port numbers because the System Language is arabic:"
-                    + " \"--port=%d\", please make sure to add the required arguments"
-                    + " \"-Duser.language=en -Duser.region=US\" to your JVM, for more info please"
-                    + " visit :%n"
+                "Couldn't format the port numbers because the System Language is arabic: \""
+                    + String.format("--port=%d", port)
+                    + "\", please make sure to add the required arguments \"-Duser.language=en"
+                    + " -Duser.region=US\" to your JVM, for more info please visit :\n"
                     + "  https://www.selenium.dev/documentation/webdriver/browsers/",
                 getPort()));
       }

java/test/org/openqa/selenium/logging/LoggingTest.java

@@ -40,6 +40,7 @@ void testLogLevelConversions() {
     assertThat(toLevel("WARNING")).isEqualTo(WARNING);
     assertThat(toLevel("SEVERE")).isEqualTo(SEVERE);
     assertThat(toLevel("OFF")).isEqualTo(OFF);
+    assertThat(toLevel(null)).isEqualTo(INFO);
   }
 
   @Test

py/selenium/webdriver/common/by.py

@@ -22,7 +22,58 @@
 
 
 class By:
-    """Set of supported locator strategies."""
+    """Set of supported locator strategies.
+
+    ID:
+    --
+    Select the element by its ID.
+
+    >>> element = driver.find_element(By.ID, 'myElement')
+
+    XPATH:
+    ------
+    Select the element via XPATH.
+        - absolute path
+        - relative path
+
+    >>> element = driver.find_element(By.XPATH, '//html/body/div')
+
+    LINK_TEXT:
+    ----------
+    Select the link element having the exact text.
+
+    >>> element = driver.find_element(By.LINK_TEXT, 'myLink')
+
+    PARTIAL_LINK_TEXT:
+    ------------------
+    Select the link element having the partial text.
+
+    >>> element = driver.find_element(By.PARTIAL_LINK_TEXT, 'my')
+
+    NAME:
+    ----
+    Select the element by its name attribute.
+
+    >>> element = driver.find_element(By.NAME, 'myElement')
+
+    TAG_NAME:
+    --------
+    Select the element by its tag name.
+
+    >>> element = driver.find_element(By.TAG_NAME, 'div')
+
+    CLASS_NAME:
+    ----------
+    Select the element by its class name.
+
+    >>> element = driver.find_element(By.CLASS_NAME, 'myElement')
+
+    CSS_SELECTOR:
+    -------------
+    Select the element by its CSS selector.
+
+    >>> element = driver.find_element(By.CSS_SELECTOR, 'div.myElement')
+    """
 
     ID = "id"
     XPATH = "xpath"