async-webdriver 0.11.0 → 0.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a70af1593c116227ab4863c4e209bb4002faf9bdfe18e7183b0656811b83066
-  data.tar.gz: 64ca1a5125e4a8289f2d55b6a6fe8b6e8579ae1b0b9ffd139bcc407d22a4702a
+  metadata.gz: 243addf7d5e3f7a978552847d2ae011d34399050668c0c2fc7b6573cacc9fa7e
+  data.tar.gz: 296591c00edb0071b417a0bf70dc42ef3caed330d4155b15b81da7a2c6ae5282
 SHA512:
-  metadata.gz: e9770cacf231cf999256001afb4e53a6c8d2dbbe5ea34f9d67974651ba8c2d04ff7ce0984aa083dfe15895d63ec7c2265de7d6d919e9571a4e7cd11a8f65cc6a
-  data.tar.gz: f775e069001ebbf3a52a4d909e8734242c039410c218142c44cd1973921af1f6490098debd3be854dbd214e017908e277d4a6a5f6c1585393254cacce3992d97
+  metadata.gz: 9337ecc0e8a306a5f2b4ddabaffd2cc76f03ba1cd3132cb76ef22cfca413bf63f5dd318efb1c93b864250c8238b5726551c8e9d3e20f5b78b9655f59de7912f5
+  data.tar.gz: f367473a2e748c86b3dbbfcfbe3286c09e0e9c70b8e3a44e0fa504ec9dec48f3f3446b08cdc83386dc0cc898f09a7e67122e941b52e24e5008624331ce5be8c3

data/lib/async/webdriver/bridge/chrome.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2025, by Samuel Williams.
+# Copyright, 2023-2026, by Samuel Williams.
 
 require_relative "generic"
 require_relative "process_group"
+require_relative "../installer"
 
 module Async
 	module WebDriver
@@ -21,13 +22,13 @@ module Async
 			# ```
 			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 +47,7 @@ module Async
 					# @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 +70,51 @@ module Async
 					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,
 						},
 					}

data/lib/async/webdriver/bridge/driver.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023, by Samuel Williams.
+# Copyright, 2023-2026, by Samuel Williams.
 
 module Async
 	module WebDriver

data/lib/async/webdriver/bridge/firefox.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2025, by Samuel Williams.
+# Copyright, 2023-2026, by Samuel Williams.
 
 require_relative "generic"
 require_relative "process_group"
@@ -20,13 +20,13 @@ module Async
 			# 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 @@ module Async
 						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 @@ module Async
 				
 				# 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.

data/lib/async/webdriver/bridge/generic.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2025, by Samuel Williams.
+# Copyright, 2023-2026, by Samuel Williams.
 
 require "socket"
 require "async/http/endpoint"

data/lib/async/webdriver/bridge/pool.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2025, by Samuel Williams.
+# Copyright, 2023-2026, by Samuel Williams.
 
 require "async/actor"
 require "async/pool"

data/lib/async/webdriver/bridge/process_group.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2025, by Samuel Williams.
+# Copyright, 2023-2026, by Samuel Williams.
 
 require_relative "driver"
 

data/lib/async/webdriver/bridge/safari.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024-2025, by Samuel Williams.
+# Copyright, 2024-2026, by Samuel Williams.
 
 require_relative "generic"
 require_relative "process_group"
@@ -21,13 +21,13 @@ module Async
 			# ```
 			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 @@ module Async
 					# @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 @@ module Async
 				
 				# 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.

data/lib/async/webdriver/bridge.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2025, by Samuel Williams.
+# Copyright, 2023-2026, by Samuel Williams.
 
 require_relative "bridge/chrome"
 require_relative "bridge/firefox"

data/lib/async/webdriver/element.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2025, by Samuel Williams.
+# Copyright, 2023-2026, by Samuel Williams.
 
 require_relative "request_helper"
 

data/lib/async/webdriver/error.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2025, by Samuel Williams.
+# Copyright, 2023-2026, by Samuel Williams.
 
 require_relative "version"
 

data/lib/async/webdriver/installer/chrome/installation.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "fileutils"
+require "tempfile"
+require_relative "platform"
+require_relative "releases"
+
+module Async
+	module WebDriver
+		module Installer
+			module Chrome
+				# Represents a Chrome for Testing installation on disk, and provides class-level
+				# methods for resolving, locating, and downloading installations.
+				#
+				# Installations are stored under the cache_path directory, organised as:
+				#
+				# 	{cache_path}/{platform}/{version}/
+				# 	  chrome/       ← extracted chrome zip contents
+				# 	  chromedriver/ ← extracted chromedriver zip contents
+				#
+				# Channel names (e.g. `stable`) are stored as symlinks pointing at the
+				# specific version directory, so that {find} can resolve them without
+				# hitting the network. {install} always re-checks the API and updates
+				# the symlink if the channel has moved on to a newer version.
+				class Installation
+					# Look up an existing installation, or download and install a fresh one.
+					#
+					# For channel specifiers (`:stable`, `:beta`, etc.), always hits the
+					# Chrome for Testing API to resolve the current version, downloads if
+					# needed, and updates the channel symlink. For exact versions, checks
+					# the local cache only.
+					#
+					# @parameter version [Symbol | String] Channel or version specifier.
+					# @parameter cache_path [String] Root of the cache directory.
+					# @returns [Installation]
+					def self.install(version, cache_path:)
+						platform = Platform.current
+						release = Releases.resolve(version, platform)
+						
+						unless installation = find(release[:version], platform, cache_path: cache_path)
+							Console.info(self, "Installing Chrome for Testing #{release[:version]}...", platform: platform)
+							
+							dir = installation_dir(release[:version], platform, cache_path: cache_path)
+							FileUtils.mkdir_p(dir)
+							
+							begin
+								download_and_extract(release[:chrome_url], File.join(dir, "chrome"))
+								download_and_extract(release[:chromedriver_url], File.join(dir, "chromedriver"))
+								
+								installation = find(release[:version], platform, cache_path: cache_path) or
+									raise "Installation failed: binaries not found after extraction"
+								
+								Console.info(self, "Installed Chrome for Testing #{release[:version]}.", platform: platform)
+							rescue
+								FileUtils.rm_rf(dir)
+								raise
+							end
+						end
+						
+						# Update the channel symlink so subsequent find(:stable) calls
+						# resolve locally without a network request.
+						if channel = channel_name(version)
+							update_channel_symlink(channel, release[:version], platform, cache_path: cache_path)
+						end
+						
+						return installation
+					end
+					
+					# Find an already-installed version or channel, without hitting the network.
+					#
+					# For channel names (`:stable`, `"stable"`, etc.), resolves the local
+					# symlink. For exact versions, checks the installation directory directly.
+					#
+					# @parameter version [Symbol | String] Channel or exact version string.
+					# @parameter platform [String] Platform string, e.g. `"mac-arm64"`.
+					# @parameter cache_path [String] Root of the cache directory.
+					# @returns [Installation | Nil]
+					def self.find(version, platform, cache_path:)
+						if channel = channel_name(version)
+							find_channel(channel, platform, cache_path: cache_path)
+						else
+							find_version(version, platform, cache_path: cache_path)
+						end
+					end
+					
+					# @parameter browser_path [String] Absolute path to the Chrome browser executable.
+					# @parameter driver_path [String] Absolute path to the chromedriver executable.
+					# @parameter version [String] Exact version string.
+					# @parameter platform [String] Platform string.
+					def initialize(browser_path:, driver_path:, version:, platform:)
+						@browser_path = browser_path
+						@driver_path = driver_path
+						@version = version
+						@platform = platform
+					end
+					
+					# @attribute [String] Absolute path to the Chrome browser executable.
+					attr :browser_path
+					
+					# @attribute [String] Absolute path to the chromedriver executable.
+					attr :driver_path
+					
+					# @attribute [String] Exact installed version, e.g. `"148.0.7778.56"`.
+					attr :version
+					
+					# @attribute [String] Platform, e.g. `"mac-arm64"`.
+					attr :platform
+					
+					private_class_method def self.channel_name(version)
+						Releases::CHANNELS.key(version.to_s.capitalize) && version.to_s.downcase
+					end
+					
+					private_class_method def self.find_channel(channel, platform, cache_path:)
+						symlink = channel_symlink(channel, platform, cache_path: cache_path)
+						return nil unless File.symlink?(symlink)
+						
+						# Derive the version from the symlink target name.
+						version = File.basename(File.readlink(symlink))
+						find_version(version, platform, cache_path: cache_path)
+					end
+					
+					private_class_method def self.find_version(version, platform, cache_path:)
+						dir = installation_dir(version, platform, cache_path: cache_path)
+						
+						browser_path = File.join(dir, "chrome", Platform.chrome_binary(platform))
+						driver_path = File.join(dir, "chromedriver", Platform.chromedriver_binary(platform))
+						
+						return nil unless File.exist?(browser_path) && File.exist?(driver_path)
+						
+						new(
+							browser_path: browser_path,
+							driver_path: driver_path,
+							version: version,
+							platform: platform,
+						)
+					end
+					
+					private_class_method def self.update_channel_symlink(channel, version, platform, cache_path:)
+						symlink = channel_symlink(channel, platform, cache_path: cache_path)
+						target = installation_dir(version, platform, cache_path: cache_path)
+						
+						# Remove stale symlink if it points elsewhere.
+						if File.symlink?(symlink) && File.readlink(symlink) != target
+							File.unlink(symlink)
+						end
+						
+						File.symlink(target, symlink) unless File.symlink?(symlink)
+					end
+					
+					private_class_method def self.channel_symlink(channel, platform, cache_path:)
+						File.join(cache_path, platform, channel.to_s)
+					end
+					
+					private_class_method def self.installation_dir(version, platform, cache_path:)
+						File.join(cache_path, platform, version)
+					end
+					
+					private_class_method def self.download_and_extract(url, dest)
+						require "async/http/internet"
+						
+						Tempfile.create(["async-webdriver-", ".zip"]) do |tmp|
+							tmp.binmode
+							
+							Sync do
+								internet = Async::HTTP::Internet.new
+								begin
+									Console.debug(self, "Downloading...", url: url)
+									response = internet.get(url)
+									tmp.write(response.read)
+									tmp.flush
+								ensure
+									internet.close
+								end
+							end
+							
+							FileUtils.mkdir_p(dest)
+							system("unzip", "-q", "-o", tmp.path, "-d", dest) or
+								raise "Failed to extract #{url}"
+							
+							# Remove macOS quarantine attributes added to files downloaded via code.
+							if RUBY_PLATFORM.include?("darwin")
+								system("xattr", "-r", "-d", "com.apple.quarantine", dest)
+							end
+						end
+					end
+				end
+			end
+		end
+	end
+end

data/lib/async/webdriver/installer/chrome/platform.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Async
+	module WebDriver
+		module Installer
+			module Chrome
+				# Platform detection for Chrome for Testing downloads.
+				#
+				# Maps Ruby's `RUBY_PLATFORM` to the platform strings used by the
+				# Chrome for Testing JSON API and zip file naming conventions.
+				module Platform
+					# Ordered list of (pattern, platform) pairs. First match wins.
+					PLATFORM_MAP = [
+						[/arm.*darwin|darwin.*arm|aarch64.*darwin|darwin.*aarch64/, "mac-arm64"],
+						[/darwin/, "mac-x64"],
+						[/aarch64.*linux|linux.*aarch64/, "linux-arm64"],
+						[/linux/, "linux64"],
+						[/x64.*mingw|mingw.*x64/, "win64"],
+						[/mingw/, "win32"],
+					].freeze
+					
+					# Detect the current platform.
+					# @returns [String] e.g. `"mac-arm64"`, `"linux64"`.
+					# @raises [RuntimeError] If the platform is not recognised.
+					def self.current
+						PLATFORM_MAP.each do |pattern, platform|
+							return platform if RUBY_PLATFORM.match?(pattern)
+						end
+						raise "Unsupported platform: #{RUBY_PLATFORM}"
+					end
+					
+					# Relative path to the Chrome binary inside the extracted chrome zip.
+					# @parameter platform [String]
+					# @returns [String]
+					def self.chrome_binary(platform)
+						case platform
+						when "mac-arm64"
+							"chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing"
+						when "mac-x64"
+							"chrome-mac-x64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing"
+						when "linux64"
+							"chrome-linux64/chrome"
+						when "linux-arm64"
+							"chrome-linux-arm64/chrome"
+						when "win64"
+							"chrome-win64/chrome.exe"
+						when "win32"
+							"chrome-win32/chrome.exe"
+						else
+							raise "Unknown platform: #{platform}"
+						end
+					end
+					
+					# Relative path to the chromedriver binary inside the extracted chromedriver zip.
+					# @parameter platform [String]
+					# @returns [String]
+					def self.chromedriver_binary(platform)
+						case platform
+						when "mac-arm64"
+							"chromedriver-mac-arm64/chromedriver"
+						when "mac-x64"
+							"chromedriver-mac-x64/chromedriver"
+						when "linux64"
+							"chromedriver-linux64/chromedriver"
+						when "linux-arm64"
+							"chromedriver-linux-arm64/chromedriver"
+						when "win64"
+							"chromedriver-win64/chromedriver.exe"
+						when "win32"
+							"chromedriver-win32/chromedriver.exe"
+						else
+							raise "Unknown platform: #{platform}"
+						end
+					end
+				end
+			end
+		end
+	end
+end

data/lib/async/webdriver/installer/chrome/releases.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "json"
+
+module Async
+	module WebDriver
+		module Installer
+			module Chrome
+				# Resolves Chrome for Testing version specifiers and download URLs using the
+				# public Chrome for Testing JSON API.
+				module Releases
+					# Returns the latest known-good version for each release channel.
+					CHANNELS_URL = "https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions-with-downloads.json"
+					
+					# Returns every known-good version with its download URLs.
+					VERSIONS_URL = "https://googlechromelabs.github.io/chrome-for-testing/known-good-versions-with-downloads.json"
+					
+					# Maps symbolic channel names to the API's title-case keys.
+					CHANNELS = {
+						stable: "Stable",
+						beta:   "Beta",
+						dev:    "Dev",
+						canary: "Canary",
+					}.freeze
+					
+					# Resolve a version specifier and platform to a version string and download URLs.
+					#
+					# @parameter version [Symbol | String] `:stable`, `:beta`, `:dev`, `:canary`,
+					#   a major version string like `"148"`, or an exact version like `"148.0.7778.56"`.
+					# @parameter platform [String] A Chrome for Testing platform string, e.g. `"mac-arm64"`.
+					# @returns [Hash] `{ version:, chrome_url:, chromedriver_url: }`
+					def self.resolve(version, platform)
+						case version
+						when Symbol                    then resolve_channel(version, platform)
+						when /\A(stable|beta|dev|canary)\z/ then resolve_channel(version.to_sym, platform)
+						when /\A\d+\z/                 then resolve_major(version, platform)
+						else                                resolve_exact(version, platform)
+						end
+					end
+					
+					private
+					
+					def self.fetch_json(url)
+						require "async/http/internet"
+						
+						Sync do
+							internet = Async::HTTP::Internet.new
+							begin
+								response = internet.get(url)
+								JSON.parse(response.read)
+							ensure
+								internet.close
+							end
+						end
+					end
+					
+					def self.resolve_channel(channel, platform)
+						key = CHANNELS.fetch(channel) do
+							raise ArgumentError, "Unknown channel #{channel.inspect}. Expected one of: #{CHANNELS.keys.inspect}"
+						end
+						
+						data = fetch_json(CHANNELS_URL)
+						entry = data.dig("channels", key) or raise "Channel #{key} not found in API response"
+						
+						extract(entry, platform)
+					end
+					
+					def self.resolve_major(major, platform)
+						data = fetch_json(VERSIONS_URL)
+						
+						entry = data["versions"]
+							.select{|v| v["version"].start_with?("#{major}.")}
+							.max_by{|v| Gem::Version.new(v["version"])}
+						
+						raise "No version found for major version #{major}" unless entry
+						
+						extract(entry, platform)
+					end
+					
+					def self.resolve_exact(version, platform)
+						data = fetch_json(VERSIONS_URL)
+						
+						entry = data["versions"].find{|v| v["version"] == version}
+						raise "Version #{version} not found" unless entry
+						
+						extract(entry, platform)
+					end
+					
+					def self.extract(entry, platform)
+						version   = entry["version"]
+						downloads = entry["downloads"]
+						
+						chrome_url = downloads["chrome"]
+							&.find{|d| d["platform"] == platform}
+							&.dig("url")
+						
+						chromedriver_url = downloads["chromedriver"]
+							&.find{|d| d["platform"] == platform}
+							&.dig("url")
+						
+						raise "No Chrome download for platform #{platform} in version #{version}" unless chrome_url
+						raise "No ChromeDriver download for platform #{platform} in version #{version}" unless chromedriver_url
+						
+						{version: version, chrome_url: chrome_url, chromedriver_url: chromedriver_url}
+					end
+				end
+			end
+		end
+	end
+end

data/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

data/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

data/lib/async/webdriver/scope/printing.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2025, by Samuel Williams.
+# Copyright, 2023-2026, by Samuel Williams.
 
 require "base64"
 

data/lib/async/webdriver/scope/window.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2025, by Samuel Williams.
+# Copyright, 2026, by Samuel Williams.
 
 module Async
 	module WebDriver

data/lib/async/webdriver/scope.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2025, by Samuel Williams.
+# Copyright, 2023-2026, by Samuel Williams.
 
 require_relative "scope/alerts"
 require_relative "scope/cookies"

data/lib/async/webdriver/session.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2025, by Samuel Williams.
+# Copyright, 2023-2026, by Samuel Williams.
 
 require_relative "request_helper"
 require_relative "element"

data/lib/async/webdriver/version.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2025, by Samuel Williams.
+# Copyright, 2023-2026, by Samuel Williams.
 
 # @namespace
 module Async
 	# @namespace
 	module WebDriver
-		VERSION = "0.11.0"
+		VERSION = "0.12.1"
 	end
 end

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2023-2025, by Samuel Williams.  
+Copyright, 2023-2026, by Samuel Williams.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/readme.md

@@ -28,6 +28,14 @@ Please see the [project documentation](https://socketry.github.io/async-webdrive
 
 Please see the [project releases](https://socketry.github.io/async-webdriver/releases/index) for all releases.
 
+### v0.12.0
+
+  - Add `Async::WebDriver::Installer::Chrome` for automatic Chrome for Testing installation and management. `Installer::Chrome.install(version)` resolves the version via the Chrome for Testing JSON API, caches binaries in `~/.local/state/async-webdriver/` (XDG `$XDG_STATE_HOME`), and returns an `Installation` with paths to both the Chrome and ChromeDriver binaries.
+  - Add `Bridge::Chrome.for(version)` as a convenience shorthand: installs the requested version if needed, then returns a fully configured `Chrome` bridge. Versions can be a channel symbol (`:stable`, `:beta`, `:dev`, `:canary`), a major version string (`"148"`), or an exact version string (`"148.0.7778.56"`).
+  - Add `bake async:webdriver:chrome:install` task for installing Chrome for Testing from the command line, e.g. in CI setup steps.
+  - Fix `Bridge::Chrome#start`, `Bridge::Firefox#start`, and `Bridge::Safari#start` not forwarding the bridge's own options (including `:driver_path`) to the driver process.
+  - Rename `path:` to `driver_path:` on `Bridge::Chrome`, `Bridge::Firefox`, and `Bridge::Safari` for consistency. Add `browser_path:` to `Bridge::Chrome` (mapped to `goog:chromeOptions.binary`) in place of the former `binary:` option, consistent with `Installer::Chrome::Installation#browser_path` and `#driver_path`.
+
 ### v0.11.0
 
   - Add `Scope::Window` with `#window_rect`, `#resize_window`, `#set_window_rect`, `#maximize_window`, `#minimize_window`, and `#fullscreen_window`.

data/releases.md

@@ -1,5 +1,13 @@
 # Releases
 
+## v0.12.0
+
+  - Add `Async::WebDriver::Installer::Chrome` for automatic Chrome for Testing installation and management. `Installer::Chrome.install(version)` resolves the version via the Chrome for Testing JSON API, caches binaries in `~/.local/state/async-webdriver/` (XDG `$XDG_STATE_HOME`), and returns an `Installation` with paths to both the Chrome and ChromeDriver binaries.
+  - Add `Bridge::Chrome.for(version)` as a convenience shorthand: installs the requested version if needed, then returns a fully configured `Chrome` bridge. Versions can be a channel symbol (`:stable`, `:beta`, `:dev`, `:canary`), a major version string (`"148"`), or an exact version string (`"148.0.7778.56"`).
+  - Add `bake async:webdriver:chrome:install` task for installing Chrome for Testing from the command line, e.g. in CI setup steps.
+  - Fix `Bridge::Chrome#start`, `Bridge::Firefox#start`, and `Bridge::Safari#start` not forwarding the bridge's own options (including `:driver_path`) to the driver process.
+  - Rename `path:` to `driver_path:` on `Bridge::Chrome`, `Bridge::Firefox`, and `Bridge::Safari` for consistency. Add `browser_path:` to `Bridge::Chrome` (mapped to `goog:chromeOptions.binary`) in place of the former `binary:` option, consistent with `Installer::Chrome::Installation#browser_path` and `#driver_path`.
+
 ## v0.11.0
 
   - Add `Scope::Window` with `#window_rect`, `#resize_window`, `#set_window_rect`, `#maximize_window`, `#minimize_window`, and `#fullscreen_window`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-webdriver
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.1
 platform: ruby
 authors:
 - Samuel Williams
@@ -130,6 +130,11 @@ files:
 - lib/async/webdriver/client.rb
 - lib/async/webdriver/element.rb
 - lib/async/webdriver/error.rb
+- lib/async/webdriver/installer.rb
+- lib/async/webdriver/installer/chrome.rb
+- lib/async/webdriver/installer/chrome/installation.rb
+- lib/async/webdriver/installer/chrome/platform.rb
+- lib/async/webdriver/installer/chrome/releases.rb
 - lib/async/webdriver/locator.rb
 - lib/async/webdriver/request_helper.rb
 - lib/async/webdriver/scope.rb