async-webdriver 0.9.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d44f03f80dc5674a12fabaeb89138fb2edc8d4aa240644a554d12edd9b70686
-  data.tar.gz: '07129f8f6173caebca9e23629018ceec2299c5093e5eea9bec252ad4641f0b1f'
+  metadata.gz: 5aad63b2a9668b73cce1b22358cd050e3b126b7c4fde2bc9d998338eacdc6377
+  data.tar.gz: 73b0d6e9eb31c7ef19cdaa12307c00ba3ff09efb895f9d274f7e46cee552c785
 SHA512:
-  metadata.gz: 729f7b01d41bae86173a3b0c26b7741ebae3ba3254da57c4d1583eb50c4564d1b1eace54bcf54b0f1c993f761e960d4ddaeda4389bb26dfe2255fcafb0885f9a
-  data.tar.gz: bb089d62cdf93ddf7db5799e1d64f7f97c7819b8272694d0c657bf1a3f990bd5f247677d38b631111df99576f290b14507de3f3cc9f4ce8150050b0be7357b3a
+  metadata.gz: ed9a55e1ad513fe7ae9a9143b97e348dce6c1d9eccc759397ab5c5005439398131085ab5f847e8560e3bd26232bd4486991b4f514e56b6272df2f2406510e422
+  data.tar.gz: 876dd5764f7582f43f7ffe749f4a5c7aeb032d82abc920d64694804dc39500f23f04c998566fe0d48d4d3cdce1d56e6128a63eeeb3665e33f2f90d9b22ce7422

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/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.1"
+		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.1
+  version: 0.10.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