Add details about handling redirects.

Author: ioquatix

guides/navigation-timing/readme.md

@@ -25,13 +25,33 @@ If any navigation operation is triggered during steps 1-4, it **interrupts** thi
 - 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.click_button("Login")        # Triggers form submission.
 session.navigate_to("/dashboard")    # May interrupt login process!
 ```
 
@@ -40,10 +60,19 @@ session.navigate_to("/dashboard")    # May interrupt login process!
 ```ruby
 # ❌ PROBLEMATIC: May interrupt form submission
 session.fill_in("email", "[email protected]")
-session.click_button("Subscribe")    # Triggers form submission
+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.
@@ -67,8 +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
 ```
@@ -79,20 +107,20 @@ 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. In some cases, the element isn't present before the navigation starts, which can cause hangs. However, sometimes it may work by chance, if the navigation completes before the find element call is invoked. It also appears to depend on which browser is being used, and perhaps even which version of that browser.
+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")
+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. Fail to find element on initial page, or
-# 2. Hang if the navigation is still in progress.
-# 3. Succeed by chance if navigation has completed sufficiently.
+# 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 form submission:
+# Assuming the previous operation did not hang, this navigation may interrupt the redirect:
 session.navigate_to("/next-page")
 ```
 

test/async/webdriver/scope/navigation.rb

@@ -80,10 +80,11 @@
 
 		session.click_button("Submit")
 
-		# Use wait_for_navigation to properly wait for the form submission to complete:
+		# Use wait_for_navigation to properly wait for the form submission to complete and the redirect to occur:
 		session.wait_for_navigation do |current_url|
 			current_url.end_with?("/success")
 		end
+		# If you remove the redirect, the above wait_for_navigation is not needed.
 
 		# This alone is insufficient, the above wait_for_navigation ensures the page is loaded:
 		session.find_element_by_xpath("//h1[text()='Form Submitted Successfully']")