[rb] add cross-browser Driver#install_web_extension, deprecating the Firefox classic install_addon methods

Author: titusfortner

rb/lib/selenium/webdriver/chromium/features.rb

@@ -31,6 +31,12 @@ module Features
           get_log: [:post, 'session/:session_id/se/log']
         }.freeze
 
+        # TODO: remove subclass override once chrome supports base64; currently only supports an unpacked local path
+        def install_web_extension(path)
+          result = web_extension.install(extension_data: web_extension.extension_path(path: path))
+          WebExtension.new(result.extension)
+        end
+
         def launch_app(id)
           execute :launch_app, {}, {id: id}
         end

rb/lib/selenium/webdriver/chromium/options.rb

@@ -236,6 +236,10 @@ def process_browser_options(browser_options)
             options['args'] << "--user-data-dir=#{@profile.directory}"
           end
 
+          if bidi?
+            options['args'] = options['args'].to_a | %w[--enable-unsafe-extension-debugging --remote-debugging-pipe]
+          end
+
           return if (@encoded_extensions + @extensions).empty?
 
           options['extensions'] = @encoded_extensions + @extensions.map { |ext| encode_extension(ext) }

rb/lib/selenium/webdriver/common.rb

@@ -94,6 +94,7 @@
 require 'selenium/webdriver/common/takes_screenshot'
 require 'selenium/webdriver/common/driver'
 require 'selenium/webdriver/common/element'
+require 'selenium/webdriver/common/web_extension'
 require 'selenium/webdriver/common/shadow_root'
 require 'selenium/webdriver/common/websocket_connection'
 require 'selenium/webdriver/common/child_process'

rb/lib/selenium/webdriver/common/driver.rb

@@ -277,6 +277,34 @@ def network
         @network ||= WebDriver::Network.new(bridge)
       end
 
+      #
+      # Installs a browser extension over WebDriver BiDi (+webExtension.install+).
+      #
+      # Firefox sends the extension base64-encoded, so it accepts an unpacked directory, a packed
+      # extension (.xpi/.crx/.zip), or already-encoded base64 bytes, and works with remote (Grid)
+      # sessions. Chromium browsers currently accept only an unpacked directory whose path resolves on
+      # the browser host (local sessions), until chromium-bidi supports base64 (SeleniumHQ/selenium#16541).
+      #
+      # @note Requires a BiDi session (set +web_socket_url+ to true in the browser options).
+      # @param [String] path unpacked extension directory, packed extension file, or base64-encoded bytes
+      # @return [WebExtension] handle for the installed extension
+      #
+
+      def install_web_extension(...)
+        bridge.install_web_extension(...)
+      end
+
+      #
+      # Uninstalls a browser extension installed with {#install_web_extension}.
+      #
+      # @note Requires a BiDi session (set +web_socket_url+ to true in the browser options).
+      # @param [WebExtension] extension handle returned by {#install_web_extension}
+      #
+
+      def uninstall_web_extension(extension)
+        bridge.uninstall_web_extension(extension.id)
+      end
+
       #-------------------------------- sugar  --------------------------------
 
       #

rb/lib/selenium/webdriver/common/driver_extensions/has_addons.rb

@@ -30,6 +30,7 @@ module HasAddons
         #
 
         def install_addon(path, temporary = nil)
+          WebDriver.logger.deprecate('#install_addon', '#install_web_extension', id: :install_addon)
           @bridge.install_addon(path, temporary)
         end
 
@@ -40,6 +41,7 @@ def install_addon(path, temporary = nil)
         #
 
         def uninstall_addon(id)
+          WebDriver.logger.deprecate('#uninstall_addon', '#uninstall_web_extension', id: :uninstall_addon)
           @bridge.uninstall_addon(id)
         end
       end # HasAddons

rb/lib/selenium/webdriver/common/driver_extensions/has_devtools.rb

@@ -25,9 +25,15 @@ module HasDevTools
         # Retrieves connection to DevTools.
         #
         # @return [DevTools]
+        # @raise [Error::WebDriverError] when BiDi is enabled, as CDP shares a transport with it
         #
 
         def devtools(target_type: 'page')
+          if @bridge.bidi?
+            raise Error::WebDriverError,
+                  'CDP (DevTools) is disabled when BiDi is enabled; use the WebDriver BiDi APIs instead'
+          end
+
           @devtools ||= {}
           @devtools[target_type] ||= begin
             require 'selenium/devtools'

rb/lib/selenium/webdriver/common/web_extension.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# 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.
+
+module Selenium
+  module WebDriver
+    #
+    # Handle for a browser extension installed via Driver#install_web_extension.
+    # Wraps the identifier the browser assigned; pass it to Driver#uninstall_web_extension.
+    #
+    class WebExtension
+      #
+      # @return [String] identifier assigned to the extension by the browser
+      #
+
+      attr_reader :id
+
+      #
+      # @api private
+      #
+
+      def initialize(id)
+        @id = id
+      end
+    end # WebExtension
+  end # WebDriver
+end # Selenium

rb/lib/selenium/webdriver/firefox/features.rb

@@ -53,6 +53,21 @@ def uninstall_addon(id)
           execute :uninstall_addon, {}, {id: id}
         end
 
+        def install_web_extension(path, allow_private_browsing: nil, permanent: nil)
+          data = encode_extension(path)
+          return classic_install_web_extension(data, permanent, allow_private_browsing) unless bidi?
+
+          moz = web_extension.moz
+          options = {allow_private_browsing:, permanent:}.compact
+          result = moz.install(extension_data: moz.extension_base64_encoded(value: data), **options)
+          WebDriver::WebExtension.new(result.extension)
+        end
+
+        def uninstall_web_extension(extension_id)
+          bidi? ? web_extension.uninstall(extension: extension_id) : uninstall_addon(extension_id)
+          nil
+        end
+
         def full_screenshot
           execute :full_page_screenshot
         end
@@ -64,6 +79,20 @@ def context=(context)
         def context
           execute :get_context
         end
+
+        private
+
+        def classic_install_web_extension(data, permanent, allow_private_browsing)
+          if allow_private_browsing == false
+            raise Error::WebDriverError,
+                  'allow_private_browsing: false requires a BiDi session; the classic install always grants ' \
+                  'private-browsing access'
+          end
+
+          temporary = !permanent unless permanent.nil?
+          options = {temporary: temporary, allowPrivateBrowsing: allow_private_browsing}.compact
+          WebDriver::WebExtension.new(execute(:install_addon, {}, {addon: data, **options}))
+        end
       end # Bridge
     end # Firefox
   end # WebDriver

rb/lib/selenium/webdriver/remote/bidi_bridge.rb

@@ -45,6 +45,17 @@ def create_session(capabilities)
           end
         end
 
+        def install_web_extension(path)
+          data = web_extension.extension_base64_encoded(value: encode_extension(path))
+          result = web_extension.install(extension_data: data)
+          WebExtension.new(result.extension)
+        end
+
+        def uninstall_web_extension(id)
+          web_extension.uninstall(extension: id)
+          nil
+        end
+
         def get(url)
           browsing_context.navigate(context: window_handle, url: url, wait: readiness_state)
           nil
@@ -91,6 +102,10 @@ def browsing_context
           @browsing_context ||= BiDi::Protocol::BrowsingContext.new(connection)
         end
 
+        def web_extension
+          @web_extension ||= BiDi::Protocol::WebExtension.new(connection)
+        end
+
         def readiness_state
           READINESS_STATE.fetch(capabilities[:page_load_strategy] || 'normal')
         end

rb/lib/selenium/webdriver/remote/bridge.rb

@@ -593,14 +593,18 @@ def click_fedcm_dialog_button
           execute :click_fedcm_dialog_button, {}, {dialogButton: 'ConfirmIdpLoginContinue'}
         end
 
-        def bidi
-          msg = 'BiDi must be enabled by setting #web_socket_url to true in options class'
-          raise(WebDriver::Error::WebDriverError, msg)
+        def bidi(*)
+          raise WebDriver::Error::WebDriverError,
+                'BiDi must be enabled by setting #web_socket_url to true in options class'
         end
+        alias connection bidi
+        alias web_extension bidi
+        alias install_web_extension bidi
+        alias uninstall_web_extension bidi
+        private :web_extension
 
-        def connection
-          msg = 'BiDi must be enabled by setting #web_socket_url to true in options class'
-          raise(WebDriver::Error::WebDriverError, msg)
+        def bidi?
+          !@bidi.nil?
         end
 
         def command_list
@@ -609,6 +613,16 @@ def command_list
 
         private
 
+        def encode_extension(path)
+          if File.directory?(path)
+            Zipper.zip(path)
+          elsif File.file?(path)
+            File.open(path, 'rb') { |file| Base64.strict_encode64(file.read) }
+          else
+            path # already base64-encoded bytes
+          end
+        end
+
         #
         # executes a command on the remote server.
         #