async-webdriver 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe93050116a6c87ff0cdb48231966242d1c99e2bab1b773f455ff2d0fdda5a87
-  data.tar.gz: 25977c570eb1235fadf1eee31a2e42c1fc97f98b7ccd9759aea46959b6fd82ed
+  metadata.gz: 5aad63b2a9668b73cce1b22358cd050e3b126b7c4fde2bc9d998338eacdc6377
+  data.tar.gz: 73b0d6e9eb31c7ef19cdaa12307c00ba3ff09efb895f9d274f7e46cee552c785
 SHA512:
-  metadata.gz: 5a433e7bd71265ef9e65097cdac2d19b966ac3c7ddabf2cbe02b64ffc17367fcfb9218aac5cfcd230ed481c819b0bed34ed91c8238e445cc426c6b219a64e5f8
-  data.tar.gz: 8e762c8be4bf92aab638d38c047d8644a29a9e856256717eb6153ff6b8e1efc563f36fe6267ad6a8a2bf0a9a4c1521de1387249f00fab74da6987287609dbd16
+  metadata.gz: ed9a55e1ad513fe7ae9a9143b97e348dce6c1d9eccc759397ab5c5005439398131085ab5f847e8560e3bd26232bd4486991b4f514e56b6272df2f2406510e422
+  data.tar.gz: 876dd5764f7582f43f7ffe749f4a5c7aeb032d82abc920d64694804dc39500f23f04c998566fe0d48d4d3cdce1d56e6128a63eeeb3665e33f2f90d9b22ce7422

data/context/debugging.md

@@ -0,0 +1,252 @@
+# Debugging
+
+This guide explains how to debug WebDriver issues by capturing HTML source and screenshots when tests fail.
+
+## Overview
+
+When WebDriver tests fail, it's often helpful to capture the current state of the page to understand what went wrong. The most useful debugging artifacts are:
+
+- **HTML Source**: Shows the current DOM structure, helpful for understanding why element selectors might be failing
+- **Screenshots**: Provides a visual representation of what the browser is actually showing
+
+## Core Concepts
+
+`async-webdriver` provides built-in methods for capturing debugging information:
+
+- {ruby Async::WebDriver::Session#document_source} returns the HTML source of the current page.
+- {ruby Async::WebDriver::Session#screenshot} captures a screenshot of the entire page.
+- {ruby Async::WebDriver::Element#screenshot} captures a screenshot of a specific element.
+
+## Basic Debugging
+
+### Capturing HTML Source
+
+To save the current page HTML to a file:
+
+```ruby
+require "async/webdriver"
+
+Async::WebDriver::Bridge::Pool.open do |pool|
+	pool.session do |session|
+		session.visit("https://example.com")
+		
+		# Save HTML source for debugging
+		html = session.document_source
+		File.write("debug.html", html)
+		
+		puts "HTML saved to debug.html"
+	end
+end
+```
+
+### Capturing Screenshots
+
+To save a screenshot of the current page:
+
+```ruby
+require "async/webdriver"
+
+Async::WebDriver::Bridge::Pool.open do |pool|
+	pool.session do |session|
+		session.visit("https://example.com")
+		
+		# Take a screenshot (returns PNG binary data)
+		screenshot_data = session.screenshot
+		File.binwrite("debug.png", screenshot_data)
+		
+		puts "Screenshot saved to debug.png"
+	end
+end
+```
+
+### Element Screenshots
+
+To capture a screenshot of a specific element:
+
+```ruby
+require "async/webdriver"
+
+Async::WebDriver::Bridge::Pool.open do |pool|
+	pool.session do |session|
+		session.visit("https://example.com")
+		
+		# Find an element and screenshot it
+		element = session.find_element_by_tag_name("body")
+		element_screenshot = element.screenshot
+		File.binwrite("element-debug.png", element_screenshot)
+		
+		puts "Element screenshot saved to element-debug.png"
+	end
+end
+```
+
+## Debugging Failed Element Searches
+
+A common debugging scenario is when `find_element` fails. Here's how to capture debugging information:
+
+```ruby
+require "async/webdriver"
+
+def debug_element_search(session, locator_type, locator_value)
+	begin
+		# Use the correct locator format for async-webdriver
+		locator = {using: locator_type, value: locator_value}
+		element = session.find_element(locator)
+		puts "✅ Element found: #{locator_type}=#{locator_value}"
+		return element
+	rescue Async::WebDriver::NoSuchElementError => e
+		puts "❌ Element not found: #{locator_type}=#{locator_value}"
+		
+		# Capture debugging information
+		timestamp = Time.now.strftime("%Y%m%d-%H%M%S")
+		
+		# Save HTML source
+		html = session.document_source
+		html_file = "debug-#{timestamp}.html"
+		File.write(html_file, html)
+		puts "📄 HTML saved to #{html_file}"
+		
+		# Save screenshot
+		screenshot_data = session.screenshot
+		screenshot_file = "debug-#{timestamp}.png"
+		File.binwrite(screenshot_file, screenshot_data)
+		puts "📸 Screenshot saved to #{screenshot_file}"
+		
+		# Re-raise the original error
+		raise e
+	end
+end
+
+# Usage example
+Async::WebDriver::Bridge::Pool.open do |pool|
+	pool.session do |session|
+		session.visit("https://example.com")
+		
+		# This will save debug files if the element isn't found
+		button = debug_element_search(session, "id", "submit-button")
+	end
+end
+```
+
+## Advanced Debugging Techniques
+
+### Configuring Timeouts for Debugging
+
+WebDriver uses different timeout settings that affect how long operations wait:
+
+```ruby
+require "async/webdriver"
+
+Async::WebDriver::Bridge::Pool.open do |pool|
+	pool.session do |session|
+		# Configure timeouts for debugging (values in milliseconds)
+		session.implicit_wait_timeout = 10_000  # 10 seconds for element finding
+		session.page_load_timeout = 30_000      # 30 seconds for page loads
+		session.script_timeout = 5_000          # 5 seconds for JavaScript execution
+		
+		puts "Current timeouts: #{session.timeouts}"
+		
+		# Now element finding will wait up to 10 seconds
+		session.visit("https://example.com")
+		element = session.find_element(:id, "dynamic-content")  # Will wait up to 10s
+	end
+end
+```
+
+### Wait and Debug Pattern
+
+Sometimes elements appear after a delay. Here's how to debug timing issues:
+
+```ruby
+require "async/webdriver"
+
+def wait_and_debug(session, locator_type, locator_value, timeout: 10000)
+	# Set implicit wait timeout (in milliseconds)
+	original_timeout = session.implicit_wait_timeout
+	session.implicit_wait_timeout = timeout
+	
+	start_time = Time.now
+	
+	begin
+		# Try to find the element (will use implicit wait timeout)
+		locator = {using: locator_type, value: locator_value}
+		session.find_element(locator)
+	rescue Async::WebDriver::NoSuchElementError => error
+		elapsed = Time.now - start_time
+		puts "⏰ Timeout after #{elapsed.round(2)}s waiting for #{locator_type}=#{locator_value}"
+		
+		# Capture final state
+		timestamp = Time.now.strftime("%Y%m%d-%H%M%S")
+		
+		html = session.document_source
+		File.write("timeout-debug-#{timestamp}.html", html)
+		
+		screenshot_data = session.screenshot
+		File.binwrite("timeout-debug-#{timestamp}.png", screenshot_data)
+		
+		puts "📄 Final HTML saved to timeout-debug-#{timestamp}.html"
+		puts "📸 Final screenshot saved to timeout-debug-#{timestamp}.png"
+		
+		raise
+	ensure
+		# Restore original timeout
+		session.implicit_wait_timeout = original_timeout
+	end
+end
+```
+
+### Multi-Step Debugging
+
+For complex test scenarios, capture state at multiple points:
+
+```ruby
+require "async/webdriver"
+
+class DebugHelper
+	def initialize(test_name)
+		@test_name = test_name
+		@step = 0
+	end
+	
+	def capture_state(session, description)
+		@step += 1
+		timestamp = Time.now.strftime("%Y%m%d-%H%M%S")
+		prefix = "#{@test_name}-step#{@step}-#{timestamp}"
+		
+		# Save HTML
+		html = session.document_source
+		html_file = "#{prefix}-#{description}.html"
+		File.write(html_file, html)
+		
+		# Save screenshot
+		screenshot_data = session.screenshot
+		screenshot_file = "#{prefix}-#{description}.png"
+		File.binwrite(screenshot_file, screenshot_data)
+		
+		puts "🔍 Step #{@step}: #{description}"
+		puts "   📄 #{html_file}"
+		puts "   📸 #{screenshot_file}"
+	end
+end
+
+# Usage example
+debug = DebugHelper.new("login-test")
+
+Async::WebDriver::Bridge::Pool.open do |pool|
+	pool.session do |session|
+		debug.capture_state(session, "initial-page")
+		
+		session.visit("https://example.com/login")
+		debug.capture_state(session, "login-page-loaded")
+		
+		session.find_element_by_id("username").send_keys("user@example.com")
+		debug.capture_state(session, "username-entered")
+		
+		session.find_element_by_id("password").send_keys("password")
+		debug.capture_state(session, "password-entered")
+		
+		session.find_element_by_id("submit").click
+		debug.capture_state(session, "form-submitted")
+	end
+end
+```

data/context/getting-started.md

@@ -0,0 +1,90 @@
+# Getting Started
+
+This guide explains how to use `async-webdriver` for controlling a browser.
+
+## Installation
+
+Add the gem to your project:
+
+~~~ bash
+$ bundle add async-webdriver
+~~~
+
+## Core Concepts
+
+`async-webdriver` is a Ruby implementation of the [WebDriver](https://www.w3.org/TR/webdriver/) protocol. It allows you to control a browser from Ruby code. It is built on top of [async](https://github.com/socketry/async) and [async-http](https://github.com/socketry/async-http). It has several core concepts:
+
+- A {ruby Async::WebDriver::Bridge} can be used to start a web driver process, e.g. `chromedriver`, `geckodriver`, etc. It can be used in isolation, or not at all.
+- A {ruby Async::WebDriver::Client} is used to connect to a running web driver and can be used to create new sessions.
+- A {ruby Async::WebDriver::Session} represents a single browser session. It is used to control a browser window and navigate to different pages.
+- A {ruby Async::WebDriver::Element} represents a single element on a page. It can be used to interact with the element, e.g. click, type, etc.
+
+## Basic Usage
+
+The following example shows how to use `async-webdriver` to open a browser, navigate to a page, and click a button:
+
+~~~ ruby
+require 'async/webdriver'
+
+Async do
+	bridge = Async::WebDriver::Bridge::Chrome.new(headless: false)
+	
+	driver = bridge.start
+	client = Async::WebDriver::Client.open(driver.endpoint)
+	
+	session = client.session(bridge.default_capabilities)
+	# Set the implicit wait timeout to 10 seconds since we are dealing with the real internet (which can be slow):
+	session.implicit_wait_timeout = 10_000
+	
+	session.visit('https://google.com')
+	
+	session.fill_in('q', 'async-webdriver')
+	session.click_button("I'm Feeling Lucky")
+	
+	puts session.document_title
+ensure
+	session&.close
+	client&.close
+	driver&.close
+end
+~~~
+
+### Using a Pool to Manage Sessions
+
+If you are running multiple tests in parallel, you may want to use a session pool to manage the sessions. This can be done as follows:
+
+~~~ ruby
+require 'async/webdriver'
+
+Async do
+	bridge = Async::WebDriver::Bridge::Pool.new(Async::WebDriver::Bridge::Chrome.new(headless: false))
+	
+	session = bridge.session
+	# Set the implicit wait timeout to 10 seconds since we are dealing with the real internet (which can be slow):
+	session.implicit_wait_timeout = 10_000
+	
+	session.visit('https://google.com')
+	
+	session.fill_in('q', 'async-webdriver')
+	session.click_button("I'm Feeling Lucky")
+	
+	puts session.document_title
+ensure
+	session&.close
+	bridge&.close
+end
+~~~
+
+The sessions will be cached and reused if possible.
+
+## Integration vs Unit Testing
+
+`async-webdriver` is designed for integration testing. It is not designed for unit testing (e.g. wrapping a tool like `rack-test` as `capybara` can do). It is designed for testing your application in a real browser and web server. It is designed for testing your application in the same way that a real user would use it. Unfortunately, this style of integration testing is significantly slower than unit testing, but it is also significantly more representative of how your application will behave in production. There are other tools, e.g. [rack-test](https://github.com/rack/rack-test) which provide significantly faster unit testing, but they do not test how your application will behave in an actual web browser. A comprehensive test suite should include both unit tests and integration tests.
+
+### Headless Mode
+
+During testing, often you will want to see the real browser window to determine if the test is working correctly. By default, for performance reasons, `async-webdriver` will run the browser in headless mode. This means that the browser will not be visible on the screen. If you want to see the browser window, you can disable headless mode by setting the `headless` option to `false`:
+
+~~~ shell
+$ ASYNC_WEBDRIVER_BRIDGE_HEADLESS=false ./webdriver-script.rb
+~~~

data/context/github-actions-integration.md

@@ -0,0 +1,68 @@
+# GitHub Actions Integrations
+
+This guide explains how to use `async-webdriver` with GitHub Actions.
+
+We recommend using the [browser-actions](https://github.com/browser-actions) for setting up `chromedriver` and `geckodriver`. They are pre-configured to work with `async-webdriver` and are easy to use.
+
+## Pipeline Configuration
+
+The following example shows how to setup both `chromedriver` and `geckodriver` in a single pipeline:
+
+~~~ yaml
+name: Test
+
+on: [push, pull_request]
+
+permissions:
+  contents: read
+
+env:
+  CONSOLE_OUTPUT: XTerm
+
+jobs:
+  test:
+    name: ${{matrix.ruby}} on ${{matrix.os}}
+    runs-on: ${{matrix.os}}-latest
+    continue-on-error: ${{matrix.experimental}}
+    
+    strategy:
+      matrix:
+        os:
+          - ubuntu
+          - macos
+        
+        ruby:
+          - "3.0"
+          - "3.1"
+          - "3.2"
+        
+        experimental: [false]
+        
+        include:
+          - os: ubuntu
+            ruby: truffleruby
+            experimental: true
+          - os: ubuntu
+            ruby: jruby
+            experimental: true
+          - os: ubuntu
+            ruby: head
+            experimental: true
+    
+    steps:
+    - uses: actions/checkout@v3
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{matrix.ruby}}
+        bundler-cache: true
+    
+    - uses: browser-actions/setup-chrome@v1
+    - uses: browser-actions/setup-firefox@v1
+    - uses: browser-actions/setup-geckodriver@latest
+      with:
+        token: ${{secrets.GITHUB_TOKEN}}
+    
+    - name: Run tests
+      timeout-minutes: 10
+      run: bundle exec bake test
+~~~

data/context/index.yaml

@@ -0,0 +1,28 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: A native library implementing the W3C WebDriver client specification.
+metadata:
+  documentation_uri: https://socketry.github.io/async-webdriver/
+  funding_uri: https://github.com/sponsors/ioquatix
+  source_code_uri: https://github.com/socketry/async-webdriver.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to use `async-webdriver` for controlling a
+    browser.
+- path: debugging.md
+  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.
+- path: sus-integration.md
+  title: Sus Integration
+  description: This guide will show you how to integrate `async-webdriver` with the
+    sus test framework.

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/context/sus-integration.md

@@ -0,0 +1,51 @@
+# Sus Integration
+
+This guide will show you how to integrate `async-webdriver` with the sus test framework.
+
+## Usage
+
+Sus has out of the box support for `async-webdriver`. You can use it like this:
+
+```shell
+$ bundle add sus-fixtures-async-http sus-fixtures-async-webdriver protocol-rack
+$ bundle update
+```
+
+Then write your integration test:
+
+```ruby
+# test/my_integration_test.rb
+
+require "sus/fixtures/async/http/server_context"
+require "sus/fixtures/async/webdriver/session_context"
+
+require "protocol/rack/adapter"
+require "rack/builder"
+
+describe "my website" do
+	include Sus::Fixtures::Async::HTTP::ServerContext
+	include Sus::Fixtures::Async::WebDriver::SessionContext
+	
+	def middleware
+		Protocol::Rack::Adapter.new(app)
+	end
+	
+	def app
+		Rack::Builder.load_file(File.expand_path("../config.ru", __dir__))
+	end
+	
+	it "has a title" do
+		navigate_to("/")
+		
+		expect(session.document_title).to be == "Example"
+	end
+	
+	it "has a paragraph" do
+		navigate_to("/")
+		
+		expect(session).to have_element(tag_name: "p")
+	end
+end
+```
+
+For more information, refer to the [sus-fixtures-async-webdriver](https://github.com/socketry/sus-fixtures-async-webdriver) documentation.

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

@@ -5,6 +5,6 @@
 
 module Async
 	module WebDriver
-		VERSION = "0.9.0"
+		VERSION = "0.10.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,10 @@ 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.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`).

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## 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.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -112,6 +112,12 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- context/debugging.md
+- 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
 - lib/async/webdriver/bridge/chrome.rb