Fix typo and explain sleep usage in tests

lib/capybara/spec/session/click_link_spec.rb

@@ -211,7 +211,7 @@ Capybara::SpecHelper.spec '#click_link' do
     download_file = File.join(Capybara.save_path, 'download.csv')
     expect(File).not_to exist(download_file)
     @session.click_link('Download Me')
-    sleep 2
+    sleep 2 # allow time for file to download
     expect(File).to exist(download_file)
     FileUtils.rm_rf download_file
   end

lib/capybara/spec/session/html_spec.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+# Note: This file uses `sleep` to sync up parts of the tests. This is only implemented like this
+# because of the methods being tested. In tests using Capybara this type of behavior should be implemented
+# using Capybara provided assertions with builtin waiting behavior.
+
 Capybara::SpecHelper.spec '#html' do
   it 'should return the unmodified page body' do
     @session.visit('/')
@@ -8,6 +12,7 @@ Capybara::SpecHelper.spec '#html' do
 
   it 'should return the current state of the page', requires: [:js] do
     @session.visit('/with_js')
+    sleep 1
     expect(@session.html).to include('I changed it')
     expect(@session.html).not_to include('This is text')
   end
@@ -21,6 +26,7 @@ Capybara::SpecHelper.spec '#source' do
 
   it 'should return the current state of the page', requires: [:js] do
     @session.visit('/with_js')
+    sleep 1
     expect(@session.source).to include('I changed it')
     expect(@session.source).not_to include('This is text')
   end
@@ -34,6 +40,7 @@ Capybara::SpecHelper.spec '#body' do
 
   it 'should return the current state of the page', requires: [:js] do
     @session.visit('/with_js')
+    sleep 1
     expect(@session.body).to include('I changed it')
     expect(@session.body).not_to include('This is text')
   end

lib/capybara/spec/session/node_spec.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+# Note: This file uses `sleep` to sync up parts of the tests. This is only implemented like this
+# because of the methods being tested. In tests using Capybara this type of behavior should be implemented
+# using Capybara provided assertions with builtin waiting behavior.
+
 Capybara::SpecHelper.spec 'node' do
   before do
     @session.visit('/with_html')
@@ -478,7 +482,7 @@ Capybara::SpecHelper.spec 'node' do
       expect(@session.find(:css, '#address1_city').value).to eq 'Oceanside'
     end
 
-    it 'should hold modifers at top level' do
+    it 'should hold modifiers at top level' do
       @session.visit('/form')
       @session.find(:css, '#address1_city').send_keys('ocean', :shift, 'side')
       expect(@session.find(:css, '#address1_city').value).to eq 'oceanSIDE'

lib/capybara/spec/session/refresh_spec.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+# Note: This file uses `sleep` to sync up parts of the tests. This is only implemented like this
+# because of the methods being tested. In tests using Capybara this type of behavior should be implemented
+# using Capybara provided assertions with builtin waiting behavior.
+
 Capybara::SpecHelper.spec '#refresh' do
   it 'reload the page' do
     @session.visit('/form')

lib/capybara/spec/session/window/switch_to_window_spec.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+# Note: This file uses `sleep` to sync up parts of the tests. This is only implemented like this
+# because of the methods being tested. In tests using Capybara this type of behavior should be implemented
+# using Capybara provided assertions with builtin waiting behavior.
+
 Capybara::SpecHelper.spec '#switch_to_window', requires: [:windows] do
   before do
     @window = @session.current_window

lib/capybara/spec/session/window/window_opened_by_spec.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+# Note: This file uses `sleep` to sync up parts of the tests. This is only implemented like this
+# because of the methods being tested. In tests using Capybara this type of behavior should be implemented
+# using Capybara provided assertions with builtin waiting behavior.
+
 Capybara::SpecHelper.spec '#window_opened_by', requires: [:windows] do
   before do
     @window = @session.current_window

lib/capybara/spec/session/window/window_spec.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+# Note: This file uses `sleep` to sync up parts of the tests. This is only implemented like this
+# because of the methods being tested. In tests using Capybara this type of behavior should be implemented
+# using Capybara provided assertions with builtin waiting behavior.
+
 Capybara::SpecHelper.spec Capybara::Window, requires: [:windows] do
   before do
     @window = @session.current_window

lib/capybara/spec/session/window/windows_spec.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+# Note: This file uses `sleep` to sync up parts of the tests. This is only implemented like this
+# because of the methods being tested. In tests using Capybara this type of behavior should be implemented
+# using Capybara provided assertions with builtin waiting behavior.
+
 Capybara::SpecHelper.spec '#windows', requires: [:windows] do
   before do
     @window = @session.current_window