async-webdriver 0.9.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d44f03f80dc5674a12fabaeb89138fb2edc8d4aa240644a554d12edd9b70686
-  data.tar.gz: '07129f8f6173caebca9e23629018ceec2299c5093e5eea9bec252ad4641f0b1f'
+  metadata.gz: 9a70af1593c116227ab4863c4e209bb4002faf9bdfe18e7183b0656811b83066
+  data.tar.gz: 64ca1a5125e4a8289f2d55b6a6fe8b6e8579ae1b0b9ffd139bcc407d22a4702a
 SHA512:
-  metadata.gz: 729f7b01d41bae86173a3b0c26b7741ebae3ba3254da57c4d1583eb50c4564d1b1eace54bcf54b0f1c993f761e960d4ddaeda4389bb26dfe2255fcafb0885f9a
-  data.tar.gz: bb089d62cdf93ddf7db5799e1d64f7f97c7819b8272694d0c657bf1a3f990bd5f247677d38b631111df99576f290b14507de3f3cc9f4ce8150050b0be7357b3a
+  metadata.gz: e9770cacf231cf999256001afb4e53a6c8d2dbbe5ea34f9d67974651ba8c2d04ff7ce0984aa083dfe15895d63ec7c2265de7d6d919e9571a4e7cd11a8f65cc6a
+  data.tar.gz: f775e069001ebbf3a52a4d909e8734242c039410c218142c44cd1973921af1f6490098debd3be854dbd214e017908e277d4a6a5f6c1585393254cacce3992d97

data/context/index.yaml

@@ -15,6 +15,10 @@ files:
   title: Debugging
   description: This guide explains how to debug WebDriver issues by capturing HTML
     source and screenshots when tests fail.
+- path: navigation-timing.md
+  title: Navigation Timing
+  description: This guide explains how to avoid race conditions when triggering navigation
+    operations while browser navigation is already in progress.
 - path: github-actions-integration.md
   title: GitHub Actions Integrations
   description: This guide explains how to use `async-webdriver` with GitHub Actions.

data/context/navigation-timing.md

@@ -0,0 +1,157 @@
+# Navigation Timing
+
+This guide explains how to avoid race conditions when triggering navigation operations while browser navigation is already in progress.
+
+## The Problem
+
+When you trigger navigation in a browser (form submission, link clicks), the browser starts a complex process that takes time. If you call `navigate_to` while this process is still running, it will interrupt the ongoing navigation, potentially causing:
+
+- Server-side effects (like setting session cookies) to not complete.
+- The intended navigation to never finish.
+- Your test to end up in an unexpected state.
+
+## Understanding the Race Condition
+
+When you trigger navigation (form submission, link clicks), the browser starts a process:
+
+1. **Submit Request**: Form data is sent to the server.
+2. **Server Processing**: Server handles the request (authentication, validation, etc.).
+3. **Response**: Server sends back response (redirect, new page, etc.).
+4. **Browser Navigation**: Browser processes the response and updates the page.
+5. **Page Load**: New page loads and `document.readyState` becomes "complete".
+
+If any navigation operation is triggered during steps 1-4, it **interrupts** this process:
+- Server-side effects (like setting session cookies) may not complete.
+- The intended navigation never finishes.
+- Your test ends up in an unexpected state.
+
+## The Redirect Race Condition
+
+A particularly common variant of this race condition occurs with **HTTP redirects** (302, 301, etc.). When a form submission or other action triggers a redirect:
+
+1. **Form Submission**: Browser sends POST request to `/submit`.
+2. **Server Response**: Server returns `302 Found` with `Location: /success` header.
+3. **Redirect Processing**: Browser receives the 302 response (usually with empty body).
+4. **Follow Redirect**: Browser automatically navigates to `/success`.
+5. **Final Page Load**: Success page loads with actual content.
+
+The race condition occurs because element-based waits can execute during step 3, when the browser has received the 302 response but hasn't yet loaded the target page:
+
+```ruby
+session.click_button("Submit")               # Triggers POST -> 302 redirect
+session.find_element(xpath: "//h1")          # May execute on empty 302 page!
+session.navigate_to("/other-page")           # Interrupts redirect to /success
+```
+
+This explains why redirect-based workflows (login forms, contact forms, checkout processes) are particularly susceptible to race conditions.
+
+## Problematic Code Examples
+
+### Example 1: Login Form Race Condition
+
+```ruby
+# ❌ PROBLEMATIC: May interrupt login before authentication completes
+session.click_button("Login")        # Triggers form submission.
+session.navigate_to("/dashboard")    # May interrupt login process!
+```
+
+### Example 2: Form Submission Race Condition
+
+```ruby
+# ❌ PROBLEMATIC: May interrupt form submission
+session.fill_in("email", "user@example.com")
+session.click_button("Subscribe")    # Triggers form submission.
+session.navigate_to("/thank-you")    # May interrupt subscription action on server!
+```
+
+### Example 3: Redirect Race Condition
+
+```ruby
+# ❌ PROBLEMATIC: May interrupt redirect before it completes
+session.click_button("Submit")       # POST -> 302 redirect.
+session.find_element(xpath: "//h1")  # May find element on 302 page and fail.
+session.navigate_to("/dashboard")    # Interrupts redirect to success page.
+```
+
+## Detection and Mitigation Strategies
+
+⚠️ **Important**: Element-based waits (`find_element`) are **insufficient** for preventing race conditions because navigation can be interrupted before target elements ever appear on the page.
+
+### Reliable Strategy: Use `wait_for_navigation`
+
+The most reliable approach is to use `wait_for_navigation` to wait for the URL or page state to change:
+
+```ruby
+# ✅ RELIABLE: Wait for URL change
+session.click_button("Submit")
+session.wait_for_navigation{|url| url.end_with?("/success")}
+session.navigate_to("/next-page") # Now safe
+```
+
+### Alternative: Wait for Server-Side Effects
+
+For critical operations like authentication, wait for server-side effects to complete:
+
+```ruby
+# ✅ 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"}
+end
+session.navigate_to("/dashboard") # Now safe
+```
+
+### Unreliable Approaches (Common But Insufficient)
+
+These approaches are commonly used but **may still allow race conditions**:
+
+#### Element-based Waits
+
+Unfortunately, waiting for specific elements to appear does not always work when navigation operations are in progress. This is especially problematic with redirects, where element waits can execute on the intermediate redirect response (which typically has no content) rather than the final destination page.
+
+```ruby
+# ❌ UNRELIABLE: Navigation can be interrupted before element appears
+session.click_button("Submit")               # Triggers POST -> 302 redirect
+
+# In principle, wait for the form submission to complete:
+session.find_element(xpath: "//h1[text()='Success']")
+# However, in reality it may:
+# 1. Execute on the 302 redirect page (empty content) and fail immediately
+# 2. Hang if the redirect navigation is still in progress
+# 3. Succeed by chance if the redirect has completed sufficiently
+
+# Assuming the previous operation did not hang, this navigation may interrupt the redirect:
+session.navigate_to("/next-page")
+```
+
+#### Generic Page Waits
+
+```ruby
+# ❌ UNRELIABLE: Doesn't ensure the intended navigation completed
+session.click_button("Submit")
+
+# This can find the wrong element on the initial page before the form submission causes a page navigation operation:
+session.find_element(xpath: "//html")
+
+# This navigation may interrupt the form submission:
+session.navigate_to("/next-page")
+```
+
+These approaches fail because `navigate_to` can interrupt the ongoing navigation before the target page (and its elements) ever loads.
+
+## Best Practices Summary
+
+1. **Always wait** after triggering navigation before calling `navigate_to` again.
+2. **Use `wait_for_navigation`** with URL or state conditions for reliable synchronization.
+3. **Test for race conditions** in your test suite with deliberate delays.
+4. **Avoid element-based waits** for navigation synchronization (they're unreliable).
+5. **Consider server-side effects** when designing wait conditions.
+6. **Prefer URL-based waits** over element-based waits for navigation timing.
+
+## Common Pitfalls
+
+- **Don't assume** `click_button` waits for navigation to complete.
+- **Don't rely on** element-based waits (`find_element`) to prevent race conditions.
+- **Don't use** arbitrary `sleep` calls instead of proper synchronization.
+- **Don't ignore** server-side effects like cookie setting or session management.
+- **Don't chain** multiple navigation operations without URL-based synchronization.

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/navigation.rb

@@ -4,11 +4,14 @@
 # Copyright, 2023-2025, by Samuel Williams.
 
 require "uri"
+require "async/clock"
 
 module Async
 	module WebDriver
 		module Scope
 			# Helpers for navigating the browser.
+			#
+			# ⚠️ **Important**: Navigation operations (and events that trigger navigation) may result in race conditions if not properly synchronized. Consult the "Navigation Timing" Guide in the documentation for more details.
 			module Navigation
 				# Navigate to the given URL.
 				# @parameter url [String] The URL to navigate to.
@@ -44,6 +47,36 @@ module Async
 				def refresh
 					session.post("refresh")
 				end
+				
+				# Wait for navigation to complete with custom conditions.
+				#
+				# This method helps avoid race conditions by polling the browser state until your specified conditions are met.
+				#
+				# @parameter timeout [Float] Maximum time to wait in seconds (default: 10.0).
+				# @yields {|current_url| ...} Yields the current URL to the block, when the ready state is "complete".
+				# @yields {|current_url, ready_state| ...} Yields both the current URL and ready state to the block, allowing more complex conditions.
+				def wait_for_navigation(timeout: 10.0, &block)
+					clock = Clock.start
+					duration = [timeout / 100.0, 0.005].max
+					
+					while true
+						current_url = session.current_url
+						ready_state = session.execute("return document.readyState;")
+						
+						if block.arity > 1
+							break if yield(current_url, ready_state)
+						else
+							break if ready_state == "complete" && yield(current_url)
+						end
+						
+						if clock.total > timeout
+							raise TimeoutError, "Timed out waiting for navigation to complete (current_url: #{current_url}, ready_state: #{ready_state})"
+						end
+						
+						Console.debug(self, "Waiting for navigation...", ready_state: ready_state, location: current_url, elapsed: clock.total)
+						sleep(duration)
+					end
+				end
 			end
 		end
 	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.9.1"
+		VERSION = "0.11.0"
 	end
 end

data/readme.md

@@ -18,6 +18,8 @@ Please see the [project documentation](https://socketry.github.io/async-webdrive
 
   - [Debugging](https://socketry.github.io/async-webdriver/guides/debugging/index) - This guide explains how to debug WebDriver issues by capturing HTML source and screenshots when tests fail.
 
+  - [Navigation Timing](https://socketry.github.io/async-webdriver/guides/navigation-timing/index) - This guide explains how to avoid race conditions when triggering navigation operations while browser navigation is already in progress.
+
   - [GitHub Actions Integrations](https://socketry.github.io/async-webdriver/guides/github-actions-integration/index) - This guide explains how to use `async-webdriver` with GitHub Actions.
 
   - [Sus Integration](https://socketry.github.io/async-webdriver/guides/sus-integration/index) - This guide will show you how to integrate `async-webdriver` with the sus test framework.
@@ -26,6 +28,15 @@ 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.
+
 ### v0.9.0
 
   - Fix `Scope#screenshot` to use the correct HTTP method (`GET` instead of `POST`).
@@ -49,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,14 @@
 # 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.
+
 ## v0.9.0
 
   - Fix `Scope#screenshot` to use the correct HTTP method (`GET` instead of `POST`).

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-webdriver
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.11.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -116,6 +116,7 @@ files:
 - context/getting-started.md
 - context/github-actions-integration.md
 - context/index.yaml
+- context/navigation-timing.md
 - context/sus-integration.md
 - lib/async/webdriver.rb
 - lib/async/webdriver/bridge.rb
@@ -142,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
@@ -162,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: []