async-webdriver 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5aad63b2a9668b73cce1b22358cd050e3b126b7c4fde2bc9d998338eacdc6377
-  data.tar.gz: 73b0d6e9eb31c7ef19cdaa12307c00ba3ff09efb895f9d274f7e46cee552c785
+  metadata.gz: 9a70af1593c116227ab4863c4e209bb4002faf9bdfe18e7183b0656811b83066
+  data.tar.gz: 64ca1a5125e4a8289f2d55b6a6fe8b6e8579ae1b0b9ffd139bcc407d22a4702a
 SHA512:
-  metadata.gz: ed9a55e1ad513fe7ae9a9143b97e348dce6c1d9eccc759397ab5c5005439398131085ab5f847e8560e3bd26232bd4486991b4f514e56b6272df2f2406510e422
-  data.tar.gz: 876dd5764f7582f43f7ffe749f4a5c7aeb032d82abc920d64694804dc39500f23f04c998566fe0d48d4d3cdce1d56e6128a63eeeb3665e33f2f90d9b22ce7422
+  metadata.gz: e9770cacf231cf999256001afb4e53a6c8d2dbbe5ea34f9d67974651ba8c2d04ff7ce0984aa083dfe15895d63ec7c2265de7d6d919e9571a4e7cd11a8f65cc6a
+  data.tar.gz: f775e069001ebbf3a52a4d909e8734242c039410c218142c44cd1973921af1f6490098debd3be854dbd214e017908e277d4a6a5f6c1585393254cacce3992d97

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

@@ -20,6 +20,7 @@ module Async
 			# end
 			# ```
 			class Chrome < Generic
+				# @returns [String] The path to the `chromedriver` executable.
 				def path
 					@options.fetch(:path, "chromedriver")
 				end
@@ -33,7 +34,10 @@ module Async
 					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
@@ -47,12 +51,14 @@ module Async
 						].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
@@ -76,7 +82,7 @@ module Async
 						alwaysMatch: {
 							browserName: "chrome",
 							"goog:chromeOptions": {
-								args: [headless ? "--headless" : nil].compact,
+								args: [headless ? "--headless=new" : nil].compact,
 							},
 							webSocketUrl: true,
 						},

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

@@ -8,12 +8,15 @@ module Async
 		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

@@ -19,6 +19,7 @@ module Async
 			# 	bridge&.close
 			# end
 			class Firefox < Generic
+				# @returns [String] The path to the `geckodriver` executable.
 				def path
 					@options.fetch(:path, "geckodriver")
 				end
@@ -32,12 +33,16 @@ module Async
 					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
@@ -50,12 +55,14 @@ module Async
 						].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

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

@@ -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

@@ -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

@@ -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

@@ -20,6 +20,7 @@ module Async
 			# end
 			# ```
 			class Safari < Generic
+				# @returns [String] The path to the `safaridriver` executable.
 				def path
 					@options.fetch(:path, "safaridriver")
 				end
@@ -33,7 +34,10 @@ module Async
 					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
@@ -47,12 +51,14 @@ module Async
 						].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

data/lib/async/webdriver/bridge.rb

@@ -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

@@ -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

@@ -7,6 +7,7 @@ require_relative "version"
 
 module Async
 	module WebDriver
+		# The base class for WebDriver protocol errors.
 		class Error < StandardError
 		end
 		

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

@@ -8,13 +8,45 @@ 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, 2023-2025, 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

@@ -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

@@ -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

@@ -3,8 +3,10 @@
 # Released under the MIT License.
 # Copyright, 2023-2025, by Samuel Williams.
 
+# @namespace
 module Async
+	# @namespace
 	module WebDriver
-		VERSION = "0.10.0"
+		VERSION = "0.11.0"
 	end
 end

data/readme.md

@@ -28,6 +28,11 @@ 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.11.0
+
+  - Add `Scope::Window` with `#window_rect`, `#resize_window`, `#set_window_rect`, `#maximize_window`, `#minimize_window`, and `#fullscreen_window`.
+  - Expand `Scope::Printing#print` with full W3C WebDriver parameters: `orientation`, `scale`, `background`, `page`, `margin`, `page_ranges`, and `shrink_to_fit`.
+
 ### v0.10.0
 
   - Introduce `Scope#wait_for_navigation` to properly wait for page navigations to complete.
@@ -55,6 +60,22 @@ We welcome contributions to this project.
 4.  Push to the branch (`git push origin my-new-feature`).
 5.  Create new Pull Request.
 
+### Running Tests
+
+To run the test suite:
+
+``` shell
+bundle exec sus
+```
+
+### Making Releases
+
+To make a new release:
+
+``` shell
+bundle exec bake gem:release:patch # or minor or major
+```
+
 ### Developer Certificate of Origin
 
 In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.

data/releases.md

@@ -1,5 +1,10 @@
 # Releases
 
+## v0.11.0
+
+  - Add `Scope::Window` with `#window_rect`, `#resize_window`, `#set_window_rect`, `#maximize_window`, `#minimize_window`, and `#fullscreen_window`.
+  - Expand `Scope::Printing#print` with full W3C WebDriver parameters: `orientation`, `scale`, `background`, `page`, `margin`, `page_ranges`, and `shrink_to_fit`.
+
 ## v0.10.0
 
   - Introduce `Scope#wait_for_navigation` to properly wait for page navigations to complete.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-webdriver
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -143,6 +143,7 @@ files:
 - lib/async/webdriver/scope/printing.rb
 - lib/async/webdriver/scope/screen_capture.rb
 - lib/async/webdriver/scope/timeouts.rb
+- lib/async/webdriver/scope/window.rb
 - lib/async/webdriver/session.rb
 - lib/async/webdriver/version.rb
 - lib/async/webdriver/xpath.rb
@@ -163,14 +164,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.6
 specification_version: 4
 summary: A native library implementing the W3C WebDriver client specification.
 test_files: []