Add Installer::Chrome for automatic Chrome for Testing installation

bake/async/webdriver/chrome.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+# Install Chrome for Testing and its matching ChromeDriver.
+#
+# Downloads the requested version from the Chrome for Testing infrastructure
+# and caches it in `~/.cache/async-webdriver.rb/` (XDG `$XDG_CACHE_HOME`).
+# Subsequent calls with the same version are a no-op.
+#
+# @parameter version [String] The version to install: a channel (`stable`, `beta`, `dev`, `canary`),
+#   a major version (e.g. `148`), or an exact version (e.g. `148.0.7778.56`). Default: `stable`.
+def install(version: "stable")
+	require "async/webdriver/installer/chrome"
+
+	installation = Async::WebDriver::Installer::Chrome.install(version)
+
+	Console.info(self, "Chrome for Testing is ready.",
+		version: installation.version,
+		platform: installation.platform,
+		browser_path: installation.browser_path,
+		driver_path: installation.driver_path,
+	)
+
+	return installation
+end

lib/async/webdriver/bridge/chrome.rb

@@ -21,13 +21,13 @@ module Bridge
 			# ```
 			class Chrome < Generic
 				# @returns [String] The path to the `chromedriver` executable.
-				def path
-					@options.fetch(:path, "chromedriver")
+				def driver_path
+					@options.fetch(:driver_path, "chromedriver")
 				end
 
 				# @returns [String] The version of the `chromedriver` executable.
 				def version
-					::IO.popen([self.path, "--version"]) do |io|
+					::IO.popen([self.driver_path, "--version"]) do |io|
 						return io.read
 					end
 				rescue Errno::ENOENT
@@ -46,7 +46,7 @@ def initialize(**options)
 					# @returns [Array(String)] The arguments to pass to the `chromedriver` executable.
 					def arguments(**options)
 						[
-							options.fetch(:path, "chromedriver"),
+							options.fetch(:driver_path, "chromedriver"),
 							"--port=#{self.port}",
 						].compact
 					end
@@ -69,21 +69,51 @@ def close
 					end
 				end
 
-				# Start the driver.
+				# Start the driver, forwarding the bridge's own options to the driver process
+				# so that a custom `:driver_path` reaches the chromedriver executable.
 				def start(**options)
-					Driver.new(**options).tap(&:start)
+					Driver.new(**@options, **options).tap(&:start)
+				end
+
+				# Ensure the given version of Chrome for Testing is installed and return a
+				# fully configured {Chrome} bridge pointing at it.
+				#
+				# Delegates to {Async::WebDriver::Installer::Chrome.install} for version
+				# resolution and download, then wraps the result in a configured bridge.
+				#
+				# @parameter version [Symbol | String] `:stable`, `:beta`, `:dev`, `:canary`,
+				#   a major version string like `"148"`, or an exact version like `"148.0.7778.56"`.
+				# @parameter cache_path [String] Root of the cache directory.
+				#   Default: `~/.cache/async-webdriver.rb` (XDG-compliant).
+				# @parameter options [Hash] Additional options forwarded to {.new} (e.g. `headless: false`).
+				# @returns [Chrome] A configured bridge.
+				def self.for(version = :stable, cache_path: Installer.cache_path("chrome"), **options)
+					require_relative "../installer/chrome"
+					installation = Installer::Chrome.find(version, cache_path: cache_path) || Installer::Chrome.install(version, cache_path: cache_path)
+					new(driver_path: installation.driver_path, browser_path: installation.browser_path, **options)
+				end
+
+				# The path to the Chrome browser executable. If `nil`, ChromeDriver uses its own discovery.
+				# @returns [String | Nil]
+				def browser_path
+					@options[:browser_path]
 				end
 
 				# The default capabilities for the Chrome browser which need to be provided when requesting a new session.
 				# @parameter headless [Boolean] Whether to run the browser in headless mode.
+				# @parameter browser_path [String | Nil] Path to the Chrome browser executable. Overrides ChromeDriver's default discovery, useful for pointing at a specific Chrome for Testing installation.
 				# @returns [Hash] The default capabilities for the Chrome browser.
-				def default_capabilities(headless: self.headless?)
+				def default_capabilities(headless: self.headless?, browser_path: self.browser_path)
+					chrome_options = {
+						args: [headless ? "--headless=new" : nil].compact,
+					}
+
+					chrome_options[:binary] = browser_path if browser_path
+
 					{
 						alwaysMatch: {
 							browserName: "chrome",
-							"goog:chromeOptions": {
-								args: [headless ? "--headless=new" : nil].compact,
-							},
+							"goog:chromeOptions": chrome_options,
 							webSocketUrl: true,
 						},
 					}

lib/async/webdriver/bridge/firefox.rb

@@ -20,13 +20,13 @@ module Bridge
 			# end
 			class Firefox < Generic
 				# @returns [String] The path to the `geckodriver` executable.
-				def path
-					@options.fetch(:path, "geckodriver")
+				def driver_path
+					@options.fetch(:driver_path, "geckodriver")
 				end
 
 				# @returns [String] The version of the `geckodriver` executable.
 				def version
-					::IO.popen([self.path, "--version"]) do |io|
+					::IO.popen([self.driver_path, "--version"]) do |io|
 						return io.read
 					end
 				rescue Errno::ENOENT
@@ -47,10 +47,10 @@ def concurrency
 						1
 					end
 
-					# @returns [Array(String)] The arguments to pass to the `chromedriver` executable.
+					# @returns [Array(String)] The arguments to pass to the `geckodriver` executable.
 					def arguments(**options)
 						[
-							options.fetch(:path, "geckodriver"),
+							options.fetch(:driver_path, "geckodriver"),
 							"--port", self.port.to_s,
 						].compact
 					end
@@ -75,7 +75,7 @@ def close
 
 				# Start the driver.
 				def start(**options)
-					Driver.new(**options).tap(&:start)
+					Driver.new(**@options, **options).tap(&:start)
 				end
 
 				# The default capabilities for the Firefox browser which need to be provided when requesting a new session.

lib/async/webdriver/bridge/safari.rb

@@ -21,13 +21,13 @@ module Bridge
 			# ```
 			class Safari < Generic
 				# @returns [String] The path to the `safaridriver` executable.
-				def path
-					@options.fetch(:path, "safaridriver")
+				def driver_path
+					@options.fetch(:driver_path, "safaridriver")
 				end
 
 				# @returns [String] The version of the `safaridriver` executable.
 				def version
-					::IO.popen([self.path, "--version"]) do |io|
+					::IO.popen([self.driver_path, "--version"]) do |io|
 						return io.read
 					end
 				rescue Errno::ENOENT
@@ -46,7 +46,7 @@ def initialize(**options)
 					# @returns [Array(String)] The arguments to pass to the `safaridriver` executable.
 					def arguments(**options)
 						[
-							options.fetch(:path, "safaridriver"),
+							options.fetch(:driver_path, "safaridriver"),
 							"--port=#{self.port}",
 						].compact
 					end
@@ -71,7 +71,7 @@ def close
 
 				# Start the driver.
 				def start(**options)
-					Driver.new(**options).tap(&:start)
+					Driver.new(**@options, **options).tap(&:start)
 				end
 
 				# The default capabilities for the Safari browser which need to be provided when requesting a new session.

lib/async/webdriver/installer.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "installer/chrome"
+
+module Async
+	module WebDriver
+		# Browser installation and management for automated testing.
+		#
+		# Each browser has its own sub-module with browser-specific platform detection,
+		# version resolution, and download logic:
+		#
+		# - {Installer::Chrome} — Chrome for Testing, via the Chrome for Testing JSON API.
+		module Installer
+			# Resolve the cache path for the given sub-directory.
+			#
+			# Follows the XDG Base Directory Specification, using `$XDG_CACHE_HOME`
+			# (default: `~/.cache`) as the root, with `async-webdriver.rb` as the
+			# application directory.
+			#
+			# @parameter subdirectory [String | Nil] Optional sub-directory, e.g. `"chrome"`.
+			# @parameter env [Hash] Environment to read `XDG_CACHE_HOME` from. Default: `ENV`.
+			# @returns [String] Absolute path.
+			def self.cache_path(subdirectory = nil, env = ENV)
+				path = File.expand_path("async-webdriver.rb", env.fetch("XDG_CACHE_HOME", "~/.cache"))
+
+				if subdirectory
+					path = File.join(path, subdirectory)
+				end
+
+				return path
+			end
+		end
+	end
+end

lib/async/webdriver/installer/chrome.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "chrome/platform"
+require_relative "chrome/releases"
+require_relative "chrome/installation"
+
+module Async
+	module WebDriver
+		module Installer
+			# Installer for Chrome for Testing, the purpose-built Chrome variant
+			# designed for automated testing.
+			#
+			# Versions can be specified as:
+			# - A channel symbol: `:stable`, `:beta`, `:dev`, `:canary`
+			# - A major version string: `"148"` (resolves to the latest patch)
+			# - An exact version string: `"148.0.7778.56"`
+			#
+			# Installations are cached in `~/.cache/async-webdriver.rb/` by default
+			# (respects `$XDG_CACHE_HOME`).
+			#
+			# ## Example
+			#
+			# ``` ruby
+			# installation = Async::WebDriver::Installer::Chrome.install(:stable)
+			# bridge = Async::WebDriver::Bridge::Chrome.new(
+			#   driver_path:  installation.driver_path,
+			#   browser_path: installation.browser_path,
+			# )
+			# ```
+			#
+			# Or via the convenience shorthand on the bridge:
+			#
+			# ``` ruby
+			# bridge = Async::WebDriver::Bridge::Chrome.for(:stable)
+			# ```
+			module Chrome
+				# Default cache directory, following the XDG Base Directory Specification.
+
+
+				# Ensure the given version is installed and return an {Installation}.
+				#
+				# Checks the local cache first; downloads from the Chrome for Testing
+				# infrastructure only when the version is not already present.
+				#
+				# @parameter version [Symbol | String] Version specifier.
+				# @parameter cache_path [String] Root of the cache directory.
+				# @returns [Installation]
+				def self.install(version = :stable, cache_path: Installer.cache_path("chrome"))
+					Installation.install(version, cache_path: cache_path)
+				end
+
+				# Find an already-installed version or channel without hitting the network.
+				#
+				# @parameter version [Symbol | String] Channel or exact version string.
+				# @parameter cache_path [String] Root of the cache directory.
+				# @returns [Installation | Nil]
+				def self.find(version, cache_path: Installer.cache_path("chrome"))
+					Installation.find(version, Platform.current, cache_path: cache_path)
+				end
+			end
+		end
+	end
+end