[py][bidi]: Add bidi webExtension module (#15749)

* add bidi webextension module
* add tests
* use bazel runfiles
* add webextension in api docs

---------

Co-authored-by: Corey Goldberg <[email protected]>

Author: navin772

common/extensions/BUILD.bazel

@@ -32,6 +32,9 @@ exports_files(
         "webextensions-selenium-example.xpi",
         "webextensions-selenium-example.zip",
         "webextensions-selenium-example-unsigned.zip",
+        "webextensions-selenium-example.crx",
+        "webextensions-selenium-example",
+        "webextensions-selenium-example-signed",
     ],
     visibility = [
         "//java/test/org/openqa/selenium/firefox:__pkg__",

py/BUILD.bazel

@@ -1,3 +1,4 @@
+load("@aspect_bazel_lib//lib:copy_directory.bzl", "copy_directory")
 load("@aspect_rules_lint//format:defs.bzl", "format_multirun")
 load("@bazel_skylib//rules:select_file.bzl", "select_file")
 load("@py_dev_requirements//:requirements.bzl", "requirement")
@@ -96,6 +97,7 @@ TEST_DEPS = [
     requirement("sortedcontainers"),
     requirement("sniffio"),
     requirement("zipp"),
+    "@rules_python//python/runfiles",
 ]
 
 copy_file(
@@ -164,6 +166,24 @@ copy_file(
     out = "test/extensions/webextensions-selenium-example-unsigned.zip",
 )
 
+copy_file(
+    name = "webextensions-selenium-example-crx",
+    src = "//common/extensions:webextensions-selenium-example.crx",
+    out = "test/extensions/webextensions-selenium-example.crx",
+)
+
+copy_directory(
+    name = "webextensions-selenium-example-dir",
+    src = "//common/extensions:webextensions-selenium-example",
+    out = "test/extensions/webextensions-selenium-example",
+)
+
+copy_directory(
+    name = "webextensions-selenium-example-signed-dir",
+    src = "//common/extensions:webextensions-selenium-example-signed",
+    out = "test/extensions/webextensions-selenium-example-signed",
+)
+
 select_file(
     name = "global-license",
     srcs = "//:license",
@@ -339,6 +359,9 @@ py_library(
         "pyproject.toml",
         "test/selenium/webdriver/common/test_file.txt",
         "test/selenium/webdriver/common/test_file2.txt",
+        ":webextensions-selenium-example-crx",
+        ":webextensions-selenium-example-dir",
+        ":webextensions-selenium-example-signed-dir",
         ":webextensions-selenium-example-unsigned-zip",
         ":webextensions-selenium-example-xpi",
         ":webextensions-selenium-example-zip",

py/docs/source/api.rst

@@ -39,6 +39,7 @@ Webdriver.common
    selenium.webdriver.common.bidi.network
    selenium.webdriver.common.bidi.script
    selenium.webdriver.common.bidi.session
+   selenium.webdriver.common.bidi.webextension
    selenium.webdriver.common.by
    selenium.webdriver.common.desired_capabilities
    selenium.webdriver.common.driver_finder

py/selenium/webdriver/common/bidi/webextension.py

@@ -0,0 +1,74 @@
+# 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.
+
+from typing import Dict, Union
+
+from selenium.webdriver.common.bidi.common import command_builder
+
+
+class WebExtension:
+    """
+    BiDi implementation of the webExtension module.
+    """
+
+    def __init__(self, conn):
+        self.conn = conn
+
+    def install(self, path=None, archive_path=None, base64_value=None) -> Dict:
+        """Installs a web extension in the remote end.
+
+        You must provide exactly one of the parameters.
+
+        Parameters:
+        -----------
+            path: Path to an extension directory
+            archive_path: Path to an extension archive file
+            base64_value: Base64 encoded string of the extension archive
+
+        Returns:
+        -------
+            Dict: A dictionary containing the extension ID.
+        """
+        if sum(x is not None for x in (path, archive_path, base64_value)) != 1:
+            raise ValueError("Exactly one of path, archive_path, or base64_value must be provided")
+
+        if path is not None:
+            extension_data = {"type": "path", "path": path}
+        elif archive_path is not None:
+            extension_data = {"type": "archivePath", "path": archive_path}
+        elif base64_value is not None:
+            extension_data = {"type": "base64", "value": base64_value}
+
+        params = {"extensionData": extension_data}
+        result = self.conn.execute(command_builder("webExtension.install", params))
+        return result
+
+    def uninstall(self, extension_id_or_result: Union[str, Dict]) -> None:
+        """Uninstalls a web extension from the remote end.
+
+        Parameters:
+        -----------
+            extension_id_or_result: Either the extension ID as a string or the result dictionary
+                                   from a previous install() call containing the extension ID.
+        """
+        if isinstance(extension_id_or_result, dict):
+            extension_id = extension_id_or_result.get("extension")
+        else:
+            extension_id = extension_id_or_result
+
+        params = {"extension": extension_id}
+        self.conn.execute(command_builder("webExtension.uninstall", params))

py/selenium/webdriver/remote/webdriver.py

@@ -45,6 +45,7 @@
 from selenium.webdriver.common.bidi.script import Script
 from selenium.webdriver.common.bidi.session import Session
 from selenium.webdriver.common.bidi.storage import Storage
+from selenium.webdriver.common.bidi.webextension import WebExtension
 from selenium.webdriver.common.by import By
 from selenium.webdriver.common.options import ArgOptions, BaseOptions
 from selenium.webdriver.common.print_page_options import PrintOptions
@@ -263,6 +264,7 @@ def __init__(
         self._bidi_session = None
         self._browsing_context = None
         self._storage = None
+        self._webextension = None
 
     def __repr__(self):
         return f'<{type(self).__module__}.{type(self).__name__} (session="{self.session_id}")>'
@@ -1337,6 +1339,28 @@ def storage(self):
 
         return self._storage
 
+    @property
+    def webextension(self):
+        """Returns a webextension module object for BiDi webextension commands.
+
+        Returns:
+        --------
+        WebExtension: an object containing access to BiDi webextension commands.
+
+        Examples:
+        ---------
+        >>> extension_path = "/path/to/extension"
+        >>> extension_result = driver.webextension.install(path=extension_path)
+        >>> driver.webextension.uninstall(extension_result)
+        """
+        if not self._websocket_connection:
+            self._start_bidi()
+
+        if self._webextension is None:
+            self._webextension = WebExtension(self._websocket_connection)
+
+        return self._webextension
+
     def _get_cdp_details(self):
         import json
 

py/test/selenium/webdriver/common/bidi_webextension_tests.py

@@ -0,0 +1,123 @@
+# 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.
+
+import base64
+import os
+import pytest
+
+from python.runfiles import Runfiles
+from selenium.webdriver.common.by import By
+from selenium.webdriver.support.wait import WebDriverWait
+
+
+EXTENSION_ID = "[email protected]"
+EXTENSION_PATH = "webextensions-selenium-example-signed"
+EXTENSION_ARCHIVE_PATH = "webextensions-selenium-example.xpi"
+
+# Use bazel Runfiles to locate the test extension directory
+r = Runfiles.Create()
+extensions = r.Rlocation("selenium/py/test/extensions")
+
+
+def install_extension(driver, **kwargs):
+    result = driver.webextension.install(**kwargs)
+    assert result.get("extension") == EXTENSION_ID
+    return result
+
+
+def verify_extension_injection(driver, pages):
+    pages.load("blank.html")
+    injected = WebDriverWait(driver, timeout=2).until(
+        lambda dr: dr.find_element(By.ID, "webextensions-selenium-example")
+    )
+    assert injected.text == "Content injected by webextensions-selenium-example"
+
+
+def uninstall_extension_and_verify_extension_uninstalled(driver, extension_info):
+    driver.webextension.uninstall(extension_info)
+
+    context_id = driver.current_window_handle
+    driver.browsing_context.reload(context_id)
+    assert len(driver.find_elements(By.ID, "webextensions-selenium-example")) == 0
+
+
+def test_webextension_initialized(driver):
+    """Test that the webextension module is initialized properly."""
+    assert driver.webextension is not None
+
+
+@pytest.mark.xfail_chrome
+@pytest.mark.xfail_edge
+def test_install_extension_path(driver, pages):
+    """Test installing an extension from a directory path."""
+    path = os.path.join(extensions, EXTENSION_PATH)
+
+    ext_info = install_extension(driver, path=path)
+    verify_extension_injection(driver, pages)
+    uninstall_extension_and_verify_extension_uninstalled(driver, ext_info)
+
+
+@pytest.mark.xfail_chrome
+@pytest.mark.xfail_edge
+def test_install_archive_extension_path(driver, pages):
+    """Test installing an extension from an archive path."""
+    path = os.path.join(extensions, EXTENSION_ARCHIVE_PATH)
+
+    ext_info = install_extension(driver, archive_path=path)
+    verify_extension_injection(driver, pages)
+    uninstall_extension_and_verify_extension_uninstalled(driver, ext_info)
+
+
+@pytest.mark.xfail_chrome
+@pytest.mark.xfail_edge
+def test_install_base64_extension_path(driver, pages):
+    """Test installing an extension from a base64 encoded string."""
+    path = os.path.join(extensions, EXTENSION_ARCHIVE_PATH)
+
+    with open(path, "rb") as file:
+        base64_encoded = base64.b64encode(file.read()).decode("utf-8")
+
+    ext_info = install_extension(driver, base64_value=base64_encoded)
+
+    # TODO: the extension is installed but the script is not injected, check and fix
+    # verify_extension_injection(driver, pages)
+
+    uninstall_extension_and_verify_extension_uninstalled(driver, ext_info)
+
+
+@pytest.mark.xfail_chrome
+@pytest.mark.xfail_edge
+def test_install_unsigned_extension(driver, pages):
+    """Test installing an unsigned extension."""
+    path = os.path.join(extensions, "webextensions-selenium-example")
+
+    ext_info = install_extension(driver, path=path)
+    verify_extension_injection(driver, pages)
+    uninstall_extension_and_verify_extension_uninstalled(driver, ext_info)
+
+
+@pytest.mark.xfail_chrome
+@pytest.mark.xfail_edge
+def test_install_with_extension_id_uninstall(driver, pages):
+    """Test uninstalling an extension using just the extension ID."""
+    path = os.path.join(extensions, EXTENSION_PATH)
+
+    ext_info = install_extension(driver, path=path)
+    extension_id = ext_info.get("extension")
+
+    # Uninstall using the extension ID
+    uninstall_extension_and_verify_extension_uninstalled(driver, extension_id)

py/test/selenium/webdriver/firefox/ff_installs_addons_tests.py

@@ -78,7 +78,7 @@ def test_install_uninstall_unsigned_addon_zip(driver, pages):
 def test_install_uninstall_signed_addon_dir(driver, pages):
     zip = os.path.join(extensions, "webextensions-selenium-example.zip")
 
-    target = os.path.join(extensions, "webextensions-selenium-example")
+    target = os.path.join(extensions, "webextensions-selenium-example-unzip")
     with zipfile.ZipFile(zip, "r") as zip_ref:
         zip_ref.extractall(target)
 
@@ -98,7 +98,7 @@ def test_install_uninstall_signed_addon_dir(driver, pages):
 
 def test_install_uninstall_unsigned_addon_dir(driver, pages):
     zip = os.path.join(extensions, "webextensions-selenium-example-unsigned.zip")
-    target = os.path.join(extensions, "webextensions-selenium-example-unsigned")
+    target = os.path.join(extensions, "webextensions-selenium-example-unsigned-unzip")
     with zipfile.ZipFile(zip, "r") as zip_ref:
         zip_ref.extractall(target)