Merge branch 'trunk' into docstring-webextensions

Author: shbenzer

CONTRIBUTING.md

@@ -62,11 +62,11 @@ on Github.
 
 This document will guide you through the contribution process.
 
-### Step 1: Fork
+### Step 1: Fork & Clone
 
 Fork the project [on Github](https://github.com/seleniumhq/selenium)
-and check out your copy locally. Use `--depth 1` for a quick check out.
-The repository is ~2GB and checking the whole history takes a while.
+and clone the repository locally. Use `--depth 1` for a quick clone.
+The repository is over 2GB and cloning the whole history takes a while.
 
 ```shell
 % git clone [email protected]:username/selenium.git --depth 1
@@ -76,7 +76,7 @@ The repository is ~2GB and checking the whole history takes a while.
 
 #### Dependencies
 
-We bundle dependencies in the _third-party/_ directory that is not
+We bundle dependencies in the _third-party/_ directory that are not
 part of the proper project. Any changes to files in this directory or
 its subdirectories should be sent upstream to the respective projects.
 Please don't send your patch to us as we cannot accept it.

java/src/org/openqa/selenium/Keys.java

@@ -23,13 +23,26 @@
 
 /**
  * Representations of pressable keys that aren't text. These are stored in the Unicode PUA (Private
- * Use Area) code points, 0xE000-0xF8FF.
+ * Use Area) code points, 0xE000–0xF8FF. These values are used internally by WebDriver to simulate
+ * keyboard input where standard Unicode characters are insufficient, such as modifier and control
+ * keys.
  *
- * @see <a
- *     href="http://www.google.com.au/search?&amp;q=unicode+pua&amp;btnK=Search">http://www.google.com.au/search?&amp;q=unicode+pua&amp;btnK=Search</a>
+ * <p>The codes follow conventions partially established by the W3C WebDriver specification and the
+ * Selenium project. Some values (e.g., RIGHT_SHIFT, RIGHT_COMMAND) are used in ChromeDriver but are
+ * not currently part of the W3C spec. Others (e.g., OPTION, FN) are symbolic and reserved for
+ * possible future mapping.
+ *
+ * <p>For consistency across platforms and drivers, values should be verified before assuming native
+ * support.
+ *
+ * @see <a href="https://www.w3.org/TR/webdriver/#keyboard-actions">W3C WebDriver Keyboard
+ *     Actions</a>
+ * @see <a href="http://www.google.com.au/search?&q=unicode+pua&btnK=Search">Unicode PUA
+ *     Overview</a>
  */
 @NullMarked
 public enum Keys implements CharSequence {
+  // Basic control characters
   NULL('\uE000'),
   CANCEL('\uE001'), // ^break
   HELP('\uE002'),
@@ -99,6 +112,16 @@ public enum Keys implements CharSequence {
   META('\uE03D'),
   COMMAND(Keys.META),
 
+  // Extended macOS/ChromeDriver keys (based on observed Chrome usage)
+  RIGHT_SHIFT('\uE050'), // aligns with ChromeDriver usage
+  RIGHT_CONTROL('\uE051'),
+  RIGHT_ALT('\uE052'),
+  RIGHT_COMMAND('\uE053'),
+
+  // Symbolic macOS keys not yet standardized
+  OPTION('\uE050'), // TODO: verify Unicode value with WebDriver spec
+  FN('\uE051'), // TODO: symbolic only; confirm or remove in future
+
   ZENKAKU_HANKAKU('\uE040');
 
   private final char keyCode;
@@ -122,7 +145,6 @@ public char charAt(int index) {
     if (index == 0) {
       return keyCode;
     }
-
     return 0;
   }
 
@@ -136,7 +158,6 @@ public CharSequence subSequence(int start, int end) {
     if (start == 0 && end == 1) {
       return String.valueOf(keyCode);
     }
-
     throw new IndexOutOfBoundsException();
   }
 
@@ -147,11 +168,9 @@ public String toString() {
 
   /**
    * Simulate pressing many keys at once in a "chord". Takes a sequence of Keys.XXXX or strings;
-   * appends each of the values to a string, and adds the chord termination key (Keys.NULL) and
-   * returns the resultant string.
+   * appends each to a string, adds the chord termination key (Keys.NULL), and returns it.
    *
-   * <p>Note: When the low-level webdriver key handlers see Keys.NULL, active modifier keys
-   * (CTRL/ALT/SHIFT/etc) release via a keyup event.
+   * <p>Note: Keys.NULL signals release of modifier keys like CTRL/ALT/SHIFT via keyup events.
    *
    * @param value characters to send
    * @return String representation of the char sequence
@@ -161,35 +180,32 @@ public static String chord(CharSequence... value) {
   }
 
   /**
-   * @see #chord(CharSequence...)
+   * Overload of {@link #chord(CharSequence...)} that accepts an iterable.
+   *
    * @param value characters to send
    * @return String representation of the char sequence
    */
   public static String chord(Iterable<CharSequence> value) {
     StringBuilder builder = new StringBuilder();
-
     for (CharSequence seq : value) {
       builder.append(seq);
     }
-
     builder.append(Keys.NULL);
     return builder.toString();
   }
 
   /**
-   * Get the special key representation, {@link Keys}, of the supplied character if there is one. If
-   * there is no special key tied to this character, null will be returned.
+   * Retrieves the {@link Keys} enum constant corresponding to the given Unicode character.
    *
    * @param key unicode character code
-   * @return special key linked to the character code, or null if character is not a special key
+   * @return special key linked to the character code, or null if not found
    */
   public static @Nullable Keys getKeyFromUnicode(char key) {
     for (Keys unicodeKey : values()) {
       if (unicodeKey.charAt(0) == key) {
         return unicodeKey;
       }
     }
-
     return null;
   }
 }

java/src/org/openqa/selenium/bidi/browsingcontext/HistoryUpdated.java

@@ -0,0 +1,92 @@
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+package org.openqa.selenium.bidi.browsingcontext;
+
+import static java.util.Collections.unmodifiableMap;
+
+import java.util.Map;
+import java.util.TreeMap;
+import org.openqa.selenium.json.JsonInput;
+
+public class HistoryUpdated {
+
+  private final String browsingContextId;
+
+  private final int timestamp;
+
+  private final String url;
+
+  private HistoryUpdated(String browsingContextId, int timestamp, String url) {
+    this.browsingContextId = browsingContextId;
+    this.timestamp = timestamp;
+    this.url = url;
+  }
+
+  public static HistoryUpdated fromJson(JsonInput input) {
+    String browsingContextId = null;
+    int timestamp = 0;
+    String url = null;
+
+    input.beginObject();
+    while (input.hasNext()) {
+      switch (input.nextName()) {
+        case "context":
+          browsingContextId = input.read(String.class);
+          break;
+
+        case "timestamp":
+          timestamp = input.read(int.class);
+          break;
+
+        case "url":
+          url = input.read(String.class);
+          break;
+
+        default:
+          input.skipValue();
+          break;
+      }
+    }
+
+    input.endObject();
+
+    return new HistoryUpdated(browsingContextId, timestamp, url);
+  }
+
+  public String getBrowsingContextId() {
+    return browsingContextId;
+  }
+
+  public int getTimestamp() {
+    return timestamp;
+  }
+
+  public String getUrl() {
+    return url;
+  }
+
+  private Map<String, Object> toJson() {
+    Map<String, Object> toReturn = new TreeMap<>();
+
+    toReturn.put("browsingContextId", this.getBrowsingContextId());
+    toReturn.put("timestamp", this.getTimestamp());
+    toReturn.put("url", this.getUrl());
+
+    return unmodifiableMap(toReturn);
+  }
+}

java/src/org/openqa/selenium/bidi/module/BUILD.bazel

@@ -25,6 +25,7 @@ java_library(
         "//java/src/org/openqa/selenium/bidi/permissions",
         "//java/src/org/openqa/selenium/bidi/script",
         "//java/src/org/openqa/selenium/bidi/storage",
+        "//java/src/org/openqa/selenium/bidi/webextension",
         "//java/src/org/openqa/selenium/json",
         "//java/src/org/openqa/selenium/remote/http",
         artifact("com.google.auto.service:auto-service-annotations"),

java/src/org/openqa/selenium/bidi/module/BrowsingContextInspector.java

@@ -29,6 +29,7 @@
 import org.openqa.selenium.bidi.Event;
 import org.openqa.selenium.bidi.HasBiDi;
 import org.openqa.selenium.bidi.browsingcontext.BrowsingContextInfo;
+import org.openqa.selenium.bidi.browsingcontext.HistoryUpdated;
 import org.openqa.selenium.bidi.browsingcontext.NavigationInfo;
 import org.openqa.selenium.bidi.browsingcontext.UserPromptClosed;
 import org.openqa.selenium.bidi.browsingcontext.UserPromptOpened;
@@ -88,6 +89,16 @@ public class BrowsingContextInspector implements AutoCloseable {
             }
           });
 
+  private final Event<HistoryUpdated> historyUpdated =
+      new Event<>(
+          "browsingContext.historyUpdated",
+          params -> {
+            try (StringReader reader = new StringReader(JSON.toJson(params));
+                JsonInput input = JSON.newInput(reader)) {
+              return input.read(HistoryUpdated.class);
+            }
+          });
+
   public BrowsingContextInspector(WebDriver driver) {
     this(new HashSet<>(), driver);
   }
@@ -172,6 +183,14 @@ public void onUserPromptOpened(Consumer<UserPromptOpened> consumer) {
     }
   }
 
+  public void onHistoryUpdated(Consumer<HistoryUpdated> consumer) {
+    if (browsingContextIds.isEmpty()) {
+      this.bidi.addListener(historyUpdated, consumer);
+    } else {
+      this.bidi.addListener(browsingContextIds, historyUpdated, consumer);
+    }
+  }
+
   private void addNavigationEventListener(String name, Consumer<NavigationInfo> consumer) {
     Event<NavigationInfo> navigationEvent = new Event<>(name, navigationInfoMapper);
 
@@ -190,6 +209,7 @@ public void close() {
     this.bidi.clearListener(browsingContextDestroyed);
     this.bidi.clearListener(userPromptOpened);
     this.bidi.clearListener(userPromptClosed);
+    this.bidi.clearListener(historyUpdated);
 
     navigationEventSet.forEach(this.bidi::clearListener);
   }

java/src/org/openqa/selenium/bidi/webextension/BUILD.bazel

@@ -0,0 +1,25 @@
+load("@rules_jvm_external//:defs.bzl", "artifact")
+load("//java:defs.bzl", "java_library")
+
+java_library(
+    name = "webextension",
+    srcs = glob(
+        [
+            "*.java",
+        ],
+    ),
+    visibility = [
+        "//java/src/org/openqa/selenium/bidi:__subpackages__",
+        "//java/src/org/openqa/selenium/firefox:__subpackages__",
+        "//java/src/org/openqa/selenium/remote:__pkg__",
+        "//java/test/org/openqa/selenium/bidi:__subpackages__",
+        "//java/test/org/openqa/selenium/grid:__subpackages__",
+    ],
+    deps = [
+        "//java/src/org/openqa/selenium:core",
+        "//java/src/org/openqa/selenium/bidi",
+        "//java/src/org/openqa/selenium/json",
+        "//java/src/org/openqa/selenium/remote/http",
+        artifact("com.google.auto.service:auto-service-annotations"),
+    ],
+)

java/src/org/openqa/selenium/bidi/webextension/ExtensionArchivePath.java

@@ -0,0 +1,34 @@
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+package org.openqa.selenium.bidi.webextension;
+
+import java.util.Map;
+
+public class ExtensionArchivePath extends ExtensionData {
+  private final String path;
+
+  public ExtensionArchivePath(String path) {
+    this.path = path;
+  }
+
+  @Override
+  public Map<String, Object> toMap() {
+    String type = "archivePath";
+    return Map.of("extensionData", Map.of("type", type, "path", path));
+  }
+}

java/src/org/openqa/selenium/bidi/webextension/ExtensionBase64Encoded.java

@@ -0,0 +1,34 @@
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+package org.openqa.selenium.bidi.webextension;
+
+import java.util.Map;
+
+public class ExtensionBase64Encoded extends ExtensionData {
+  private final String value;
+
+  public ExtensionBase64Encoded(String value) {
+    this.value = value;
+  }
+
+  @Override
+  public Map<String, Object> toMap() {
+    String type = "base64";
+    return Map.of("extensionData", Map.of("type", type, "value", value));
+  }
+}