async-webdriver 0.10.0 → 0.12.0

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,20 +1,52 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2025, by Samuel Williams.
+# Copyright, 2023-2026, by Samuel Williams.
 
 require "base64"
 
 module Async
 	module WebDriver
 		module Scope
-			# Helpers for working with printing.
+			# Helpers for printing the current page to PDF.
 			module Printing
-				# Print the current page and return the result as a Base64 encoded string containing a PDF representation of the paginated document.
-				def print(page_ranges: nil, total_pages: nil)
-					reply = session.post("print", {pageRanges: page_ranges, totalPages: total_pages}.compact)
+				# Print the current page as a PDF and return the raw binary data.
+				#
+				# All margin and page measurements are in centimetres. The W3C WebDriver
+				# default page size is US Letter (21.59 × 27.94 cm) with 1 cm margins.
+				#
+				# @parameter orientation [String | Nil] `"portrait"` or `"landscape"`. Default: `"portrait"`.
+				# @parameter scale [Float | Nil] Scaling factor between 0.1 and 2.0. Default: `1.0`.
+				# @parameter background [Boolean | Nil] Whether to print background graphics and colours. Default: `false`.
+				# @parameter page [Hash | Nil] Page dimensions in cm. Keys: `:width`, `:height`.
+				# @parameter margin [Hash | Nil] Page margins in cm. Keys: `:top`, `:bottom`, `:left`, `:right`.
+				# @parameter page_ranges [Array(String) | Nil] Page ranges to print, e.g. `["1-5", "8"]`. Default: all pages.
+				# @parameter shrink_to_fit [Boolean | Nil] Whether to shrink content to fit the page. Default: `true`.
+				# @returns [String] The raw PDF binary data.
+				def print(orientation: nil, scale: nil, background: nil, page: nil, margin: nil, page_ranges: nil, shrink_to_fit: nil)
+					parameters = {
+						orientation: orientation,
+						scale: scale,
+						background: background,
+						page: page,
+						margin: margin,
+						pageRanges: page_ranges,
+						shrinkToFit: shrink_to_fit,
+					}.compact
 					
-					return Base64.decode64(reply["value"])
+					# Synchronise with Chrome's rendering pipeline before issuing the print
+					# command. The underlying CDP call (Page.printToPDF) is synchronous: if
+					# the renderer process has not yet fully initialised its print pipeline
+					# by the time the command arrives, Chrome returns JSON-RPC error -32000
+					# ("Printing failed") with no retry. A JavaScript round-trip forces
+					# ChromeDriver to wait for the renderer to be live (a JS execution
+					# context must exist), which also guarantees the print pipeline is ready.
+					# Without this, fast-loading pages can trigger the race intermittently.
+					session.execute("return document.readyState")
+					
+					reply = session.post("print", parameters)
+					
+					return Base64.decode64(reply)
 				end
 			end
 		end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Async
+	module WebDriver
+		module Scope
+			# Helpers for managing the browser window size and position.
+			module Window
+				# Get the current window rect (position and size).
+				# @returns [Hash] The window rect with keys `"x"`, `"y"`, `"width"`, `"height"`.
+				def window_rect
+					session.get("window/rect")
+				end
+				
+				# Set the window rect (position and/or size).
+				# @parameter x [Integer | Nil] The x position of the window.
+				# @parameter y [Integer | Nil] The y position of the window.
+				# @parameter width [Integer | Nil] The width of the window in CSS pixels.
+				# @parameter height [Integer | Nil] The height of the window in CSS pixels.
+				def set_window_rect(x: nil, y: nil, width: nil, height: nil)
+					session.post("window/rect", {x: x, y: y, width: width, height: height}.compact)
+				end
+				
+				# Resize the browser window to the given dimensions.
+				# @parameter width [Integer] The new width in CSS pixels.
+				# @parameter height [Integer] The new height in CSS pixels.
+				def resize_window(width, height)
+					set_window_rect(width: width, height: height)
+				end
+				
+				# Maximize the browser window.
+				def maximize_window
+					session.post("window/maximize")
+				end
+				
+				# Minimize the browser window.
+				def minimize_window
+					session.post("window/minimize")
+				end
+				
+				# Make the browser window fullscreen.
+				def fullscreen_window
+					session.post("window/fullscreen")
+				end
+			end
+		end
+	end
+end

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"
@@ -13,3 +13,12 @@ require_relative "scope/navigation"
 require_relative "scope/printing"
 require_relative "scope/screen_capture"
 require_relative "scope/timeouts"
+require_relative "scope/window"
+
+module Async
+	module WebDriver
+		# @namespace
+		module Scope
+		end
+	end
+end

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"
@@ -56,6 +56,7 @@ module Async
 				@options = options
 			end
 			
+			# @returns [String] A concise representation of the session.
 			def inspect
 				"\#<#{self.class} id=#{@id.inspect}>"
 			end
@@ -126,6 +127,7 @@ module Async
 			include Scope::Printing
 			include Scope::ScreenCapture
 			include Scope::Timeouts
+			include Scope::Window
 			
 			# Reset the session to a clean state.
 			def reset!

data/lib/async/webdriver/version.rb

@@ -1,10 +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.10.0"
+		VERSION = "0.12.0"
 	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