async-webdriver 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5aad63b2a9668b73cce1b22358cd050e3b126b7c4fde2bc9d998338eacdc6377
-  data.tar.gz: 73b0d6e9eb31c7ef19cdaa12307c00ba3ff09efb895f9d274f7e46cee552c785
+  metadata.gz: 06203afae057f1ba3f11ac14dccfd38dde2698a1d56d5ecbae3961b8317c2f98
+  data.tar.gz: 07e491fb4ceec6a760eb0ff2e3f301b8f082edb410dafcf885278aa311c34138
 SHA512:
-  metadata.gz: ed9a55e1ad513fe7ae9a9143b97e348dce6c1d9eccc759397ab5c5005439398131085ab5f847e8560e3bd26232bd4486991b4f514e56b6272df2f2406510e422
-  data.tar.gz: 876dd5764f7582f43f7ffe749f4a5c7aeb032d82abc920d64694804dc39500f23f04c998566fe0d48d4d3cdce1d56e6128a63eeeb3665e33f2f90d9b22ce7422
+  metadata.gz: 65e7bafd0d7f1656af4739a55ab37efbb7471d99726cdd38b689e5d4d24f0f3ee9d290cd717ac4c2c39e819953029360b8b6a59b3ed3a7d60bc9610425b068c0
+  data.tar.gz: a0baab577a90d809486da2ff3ae12956b07ee11e39131534de2f36e0179ecde07da66f09baffb1e7ed070320ad1520fae4025f1df0b675a4260023af3f84a004

data/context/navigation-timing.md

@@ -84,7 +84,7 @@ The most reliable approach is to use `wait_for_navigation` to wait for the URL o
 ```ruby
 # ✅ RELIABLE: Wait for URL change
 session.click_button("Submit")
-session.wait_for_navigation {|url| url.end_with?("/success")}
+session.wait_for_navigation{|url| url.end_with?("/success")}
 session.navigate_to("/next-page") # Now safe
 ```
 
@@ -96,7 +96,7 @@ For critical operations like authentication, wait for server-side effects to com
 # ✅ RELIABLE: Wait for authentication cookie
 session.click_button("Login")
 session.wait_for_navigation do |url, ready_state|
-  ready_state == "complete" && session.cookies.any?{|cookie| cookie['name'] == 'auth_token'}
+	ready_state == "complete" && session.cookies.any?{|cookie| cookie["name"] == "auth_token"}
 end
 session.navigate_to("/dashboard") # Now safe
 ```

data/lib/async/webdriver/bridge/chrome.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,20 +20,24 @@ module Async
 			# end
 			# ```
 			class Chrome < Generic
-				def path
-					@options.fetch(:path, "chromedriver")
+				# @returns [String] The path to the `chromedriver` executable.
+				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
 					return nil
 				end
 				
+				# A locally managed `chromedriver` process.
 				class Driver < Bridge::Driver
+					# Initialize a managed Chrome driver process.
+					# @parameter options [Hash] Driver configuration options.
 					def initialize(**options)
 						super(**options)
 						@process_group = nil
@@ -42,17 +46,19 @@ 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
 					
+					# Start the managed Chrome driver process and wait for readiness.
 					def start
 						@process_group = ProcessGroup.spawn(*arguments(**@options))
 						
 						super
 					end
 					
+					# Stop the managed Chrome driver process.
 					def close
 						if @process_group
 							@process_group.close
@@ -63,21 +69,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" : nil].compact,
-							},
+							"goog:chromeOptions": chrome_options,
 							webSocketUrl: true,
 						},
 					}

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

@@ -1,19 +1,22 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023, by Samuel Williams.
+# Copyright, 2023-2026, by Samuel Williams.
 
 module Async
 	module WebDriver
 		module Bridge
 			# Represents an instance of a locally running driver (usually with a process group).
 			class Driver
+				# Initialize a driver wrapper.
+				# @parameter options [Hash] Driver configuration options.
 				def initialize(**options)
 					@options = options
 					@count = 0
 					@closed = false
 				end
 				
+				# @returns [Integer] The number of concurrent sessions the driver can sustain.
 				def concurrency
 					@options.fetch(:concurrency, 128)
 				end
@@ -23,18 +26,22 @@ module Async
 				# @attribute [Hash] The status of the driver after a connection has been established.
 				attr :status
 				
+				# @returns [Boolean] Whether the driver can still be used.
 				def viable?
 					!@closed
 				end
 				
+				# @returns [Boolean] Whether the driver has been closed.
 				def closed?
 					@closed
 				end
 				
+				# Mark the driver as closed.
 				def close
 					@closed = true
 				end
 				
+				# @returns [Boolean] Whether the driver may be returned to a pool.
 				def reusable?
 					@options.fetch(:reusable, !@closed)
 				end
@@ -50,14 +57,17 @@ module Async
 					end
 				end
 				
+				# @returns [Integer] The port the driver listens on.
 				def port
 					@port ||= @options.fetch(:port, self.ephemeral_port)
 				end
 				
+				# @returns [Async::HTTP::Endpoint] The HTTP endpoint exposed by the driver.
 				def endpoint
 					Async::HTTP::Endpoint.parse("http://localhost", port: self.port)
 				end
 				
+				# @returns [Client] A client connected to the driver endpoint.
 				def client
 					Client.open(self.endpoint)
 				end

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"
@@ -19,43 +19,50 @@ module Async
 			# 	bridge&.close
 			# end
 			class Firefox < Generic
-				def path
-					@options.fetch(:path, "geckodriver")
+				# @returns [String] The path to the `geckodriver` executable.
+				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
 					return nil
 				end
 				
+				# A locally managed `geckodriver` process.
 				class Driver < Bridge::Driver
+					# Initialize a managed Firefox driver process.
+					# @parameter options [Hash] Driver configuration options.
 					def initialize(**options)
 						super(**options)
 						@process_group = nil
 					end
 					
+					# @returns [Integer] Firefox drivers support one session at a time.
 					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
 					
+					# Start the managed Firefox driver process and wait for readiness.
 					def start
 						@process_group = ProcessGroup.spawn(*arguments(**@options))
 						
 						super
 					end
 					
+					# Stop the managed Firefox driver process.
 					def close
 						if @process_group
 							@process_group.close
@@ -68,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"
@@ -12,6 +12,8 @@ module Async
 		module Bridge
 			# Generic W3C WebDriver implementation.
 			class Generic
+				# Initialize a generic bridge wrapper.
+				# @parameter options [Hash] Bridge configuration options.
 				def initialize(**options)
 					@options = options
 				end
@@ -26,6 +28,7 @@ module Async
 					version != nil
 				end
 				
+				# @returns [Boolean] Whether headless mode is enabled by default.
 				def headless?
 					@options.fetch(:headless, true)
 				end

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"
@@ -24,14 +24,22 @@ module Async
 			# end
 			# ```
 			class Pool
+				# Controls pooled drivers and cached sessions.
 				class BridgeController
+					# Initialize the bridge controller.
+					# @parameter bridge [Bridge] The bridge used to create drivers.
+					# @parameter capabilities [Hash] Capabilities used for new sessions.
 					def initialize(bridge, capabilities: bridge.default_capabilities)
 						@bridge = bridge
 						@capabilities = capabilities
 						@pool = Async::Pool::Controller.new(self)
 					end
 					
+					# Caches sessions created from a single driver instance.
 					class SessionCache
+						# Initialize a session cache for one driver instance.
+						# @parameter driver [Driver] The driver backing cached sessions.
+						# @parameter capabilities [Hash] Capabilities for newly created sessions.
 						def initialize(driver, capabilities)
 							@driver = driver
 							@capabilities = capabilities
@@ -40,14 +48,17 @@ module Async
 							@sessions = []
 						end
 						
+						# @returns [Boolean] Whether the underlying driver remains usable.
 						def viable?
 							@driver&.viable?
 						end
 						
+						# @returns [Boolean] Whether cached sessions may be reused.
 						def reusable?
 							@driver&.reusable?
 						end
 						
+						# Close the cached sessions, driver, and HTTP client.
 						def close
 							if @driver
 								@driver.close
@@ -64,10 +75,13 @@ module Async
 							end
 						end
 						
+						# @returns [Integer] The number of concurrently usable sessions.
 						def concurrency
 							@driver.concurrency
 						end
 						
+						# Acquire a cached or newly created session payload.
+						# @returns [Hash] A WebDriver session payload.
 						def acquire
 							if @sessions.empty?
 								session = @client.post("session", {capabilities: @capabilities})
@@ -85,6 +99,8 @@ module Async
 							end
 						end
 						
+						# Return a session payload to the cache.
+						# @parameter session [Hash] The session payload to cache.
 						def release(session)
 							@sessions.push(session)
 						end
@@ -95,12 +111,16 @@ module Async
 						SessionCache.new(@bridge.start, @capabilities)
 					end
 					
+					# Acquire a session payload from the pool.
+					# @returns [Hash] The acquired session payload.
 					def acquire
 						session_cache = @pool.acquire
 						
 						return session_cache.acquire
 					end
 					
+					# Return a session payload to the pool.
+					# @parameter session [Hash] The session payload to release.
 					def release(session)
 						session_cache = session[:cache]
 						
@@ -109,6 +129,8 @@ module Async
 						@pool.release(session_cache)
 					end
 					
+					# Retire a session payload and its cache from the pool.
+					# @parameter session [Hash] The session payload to retire.
 					def retire(session)
 						session_cache = session[:cache]
 						
@@ -117,6 +139,7 @@ module Async
 						@pool.retire(session_cache)
 					end
 					
+					# Close the underlying driver pool.
 					def close
 						if @pool
 							@pool.close
@@ -136,15 +159,19 @@ module Async
 					@controller.close
 				end
 				
+				# A pooled session wrapper that returns sessions to the cache on close.
 				class CachedWrapper < Session
+					# @returns [Pool] The pool responsible for reusing this session.
 					def pool
 						@options[:pool]
 					end
 					
+					# @returns [Hash] The raw session payload returned by the bridge.
 					def payload
 						@options[:payload]
 					end
 					
+					# Return the session to the pool when possible.
 					def close
 						unless self.pool.reuse(self)
 							super
@@ -167,6 +194,9 @@ module Async
 					end
 				end
 				
+				# Reset and return a session to the pool.
+				# @parameter session [CachedWrapper] The session to reuse.
+				# @returns [Boolean] Always returns `true` once the session is released.
 				def reuse(session)
 					session.reset!
 					

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"
 
@@ -75,13 +75,18 @@ module Async
 				end
 			end
 			
+			# A driver wrapper that closes an associated process handle.
 			class ProcessDriver < Driver
+				# Initialize a process-backed driver.
+				# @parameter endpoint [Object] Driver options or endpoint information.
+				# @parameter process [ProcessGroup] The managed process group.
 				def initialize(endpoint, process)
 					super(endpoint)
 					
 					@process = process
 				end
 				
+				# Close the driver and its process group.
 				def close
 					super
 					

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"
@@ -20,20 +20,24 @@ module Async
 			# end
 			# ```
 			class Safari < Generic
-				def path
-					@options.fetch(:path, "safaridriver")
+				# @returns [String] The path to the `safaridriver` executable.
+				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
 					return nil
 				end
 				
+				# A locally managed `safaridriver` process.
 				class Driver < Bridge::Driver
+					# Initialize a managed Safari driver process.
+					# @parameter options [Hash] Driver configuration options.
 					def initialize(**options)
 						super(**options)
 						@process_group = nil
@@ -42,17 +46,19 @@ 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
 					
+					# Start the managed Safari driver process and wait for readiness.
 					def start
 						@process_group = ProcessGroup.spawn(*arguments(**@options))
 						
 						super
 					end
 					
+					# Stop the managed Safari driver process.
 					def close
 						if @process_group
 							@process_group.close
@@ -65,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"
@@ -21,6 +21,9 @@ module Async
 				Bridge::Safari,
 			]
 			
+			# Iterate over supported bridge implementations.
+			# @yields {|bridge| ...} Each supported bridge class.
+			# 	@parameter bridge [Class] A supported bridge implementation.
 			def self.each(&block)
 				return enum_for(:each) unless block_given?
 				
@@ -45,6 +48,7 @@ module Async
 			# ```
 			ASYNC_WEBDRIVER_BRIDGE_HEADLESS = "ASYNC_WEBDRIVER_BRIDGE_HEADLESS"
 			
+			# Raised when no supported bridge implementation is available.
 			class UnsupportedError < Error
 			end
 			

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"
 
@@ -20,6 +20,8 @@ module Async
 			class Attributes
 				include Enumerable
 				
+				# Initialize the attribute wrapper for an element.
+				# @parameter element [Element] The element whose attributes will be accessed.
 				def initialize(element)
 					@element = element
 					@keys = nil

data/lib/async/webdriver/error.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2025, by Samuel Williams.
+# Copyright, 2023-2026, by Samuel Williams.
 
 require_relative "version"
 
 module Async
 	module WebDriver
+		# The base class for WebDriver protocol errors.
 		class Error < StandardError
 		end