capybara 2.5.0 → 2.18.0

data/lib/capybara/spec/session/find_spec.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 Capybara::SpecHelper.spec '#find' do
   before do
     @session.visit('/with_html')
@@ -9,19 +10,19 @@ Capybara::SpecHelper.spec '#find' do
 
   it "should find the first element using the given locator" do
     expect(@session.find('//h1').text).to eq('This is a test')
-    expect(@session.find("//input[@id='test_field']")[:value]).to eq('monkey')
+    expect(@session.find("//input[@id='test_field']").value).to eq('monkey')
   end
 
   it "should find the first element using the given locator and options" do
-    expect(@session.find('//a', :text => 'Redirect')[:id]).to eq('red')
-    expect(@session.find(:css, 'a', :text => 'A link came first')[:title]).to eq('twas a fine link')
+    expect(@session.find('//a', text: 'Redirect')[:id]).to eq('red')
+    expect(@session.find(:css, 'a', text: 'A link came first')[:title]).to eq('twas a fine link')
   end
 
   it "should raise an error if there are multiple matches" do
     expect { @session.find('//a') }.to raise_error(Capybara::Ambiguous)
   end
 
-  it "should wait for asynchronous load", :requires => [:js] do
+  it "should wait for asynchronous load", requires: [:js] do
     @session.visit('/with_js')
     @session.click_link('Click me')
     expect(@session.find(:css, "a#has-been-clicked").text).to include('Has been clicked')
@@ -33,12 +34,12 @@ Capybara::SpecHelper.spec '#find' do
     end
   end
 
-  context "with :wait option", :requires => [:js] do
+  context "with :wait option", requires: [:js] do
     it "should not wait for asynchronous load when `false` given" do
       @session.visit('/with_js')
       @session.click_link('Click me')
       expect do
-        @session.find(:css, "a#has-been-clicked", :wait => false)
+        @session.find(:css, "a#has-been-clicked", wait: false)
       end.to raise_error(Capybara::ElementNotFound)
     end
 
@@ -46,18 +47,18 @@ Capybara::SpecHelper.spec '#find' do
       @session.visit('/with_js')
       @session.click_link('Slowly')
       expect do
-        @session.find(:css, "a#slow-clicked", :wait => 0.2)
+        @session.find(:css, "a#slow-clicked", wait: 0.2)
       end.to raise_error(Capybara::ElementNotFound)
     end
 
     it "should find element if it appears before given wait duration" do
       @session.visit('/with_js')
       @session.click_link('Click me')
-      expect(@session.find(:css, "a#has-been-clicked", :wait => 0.9).text).to include('Has been clicked')
+      expect(@session.find(:css, "a#has-been-clicked", wait: 2.0).text).to include('Has been clicked')
     end
   end
 
-  context "with frozen time", :requires => [:js] do
+  context "with frozen time", requires: [:js] do
     if defined?(Process::CLOCK_MONOTONIC)
       it "will time out even if time is frozen" do
         @session.visit('/with_js')
@@ -78,7 +79,7 @@ Capybara::SpecHelper.spec '#find' do
   context "with css selectors" do
     it "should find the first element using the given locator" do
       expect(@session.find(:css, 'h1').text).to eq('This is a test')
-      expect(@session.find(:css, "input[id='test_field']")[:value]).to eq('monkey')
+      expect(@session.find(:css, "input[id='test_field']").value).to eq('monkey')
     end
 
     it "should support pseudo selectors" do
@@ -89,7 +90,7 @@ Capybara::SpecHelper.spec '#find' do
   context "with xpath selectors" do
     it "should find the first element using the given locator" do
       expect(@session.find(:xpath, '//h1').text).to eq('This is a test')
-      expect(@session.find(:xpath, "//input[@id='test_field']")[:value]).to eq('monkey')
+      expect(@session.find(:xpath, "//input[@id='test_field']").value).to eq('monkey')
     end
   end
 
@@ -103,11 +104,11 @@ Capybara::SpecHelper.spec '#find' do
     end
   end
 
-  context "with custom selector with :for option" do
-    it "should use the selector when it matches the :for option" do
+  context "with custom selector with custom `match` block" do
+    it "should use the custom selector when locator matches the block" do
       Capybara.add_selector(:beatle) do
         xpath { |num| ".//*[contains(@class, 'beatle')][#{num}]" }
-        match { |value| value.is_a?(Fixnum) }
+        match { |value| value.is_a?(Integer) }
       end
       expect(@session.find(:beatle, '2').text).to eq('Paul')
       expect(@session.find(1).text).to eq('John')
@@ -125,8 +126,8 @@ Capybara::SpecHelper.spec '#find' do
     end
 
     it "should find elements that match the filter" do
-      expect(@session.find(:beatle, 'Paul', :type => 'drummer').text).to eq('Paul')
-      expect(@session.find(:beatle, 'Ringo', :type => 'drummer').text).to eq('Ringo')
+      expect(@session.find(:beatle, 'Paul', type: 'drummer').text).to eq('Paul')
+      expect(@session.find(:beatle, 'Ringo', type: 'drummer').text).to eq('Ringo')
     end
 
     it "ignores filter when it is not given" do
@@ -135,8 +136,8 @@ Capybara::SpecHelper.spec '#find' do
     end
 
     it "should not find elements that don't match the filter" do
-      expect { @session.find(:beatle, 'John', :type => 'drummer') }.to raise_error(Capybara::ElementNotFound)
-      expect { @session.find(:beatle, 'George', :type => 'drummer') }.to raise_error(Capybara::ElementNotFound)
+      expect { @session.find(:beatle, 'John', type: 'drummer') }.to raise_error(Capybara::ElementNotFound)
+      expect { @session.find(:beatle, 'George', type: 'drummer') }.to raise_error(Capybara::ElementNotFound)
     end
   end
 
@@ -144,13 +145,13 @@ Capybara::SpecHelper.spec '#find' do
     before do
       Capybara.add_selector(:beatle) do
         xpath { |name| ".//li[contains(@class, 'beatle')][contains(text(), '#{name}')]" }
-        filter(:type, :default => "drummer") { |node, type| node[:class].split(/\s+/).include?(type) }
+        filter(:type, default: "drummer") { |node, type| node[:class].split(/\s+/).include?(type) }
       end
     end
 
     it "should find elements that match the filter" do
-      expect(@session.find(:beatle, 'Paul', :type => 'drummer').text).to eq('Paul')
-      expect(@session.find(:beatle, 'Ringo', :type => 'drummer').text).to eq('Ringo')
+      expect(@session.find(:beatle, 'Paul', type: 'drummer').text).to eq('Paul')
+      expect(@session.find(:beatle, 'Ringo', type: 'drummer').text).to eq('Ringo')
     end
 
     it "should use default value when filter is not given" do
@@ -159,8 +160,36 @@ Capybara::SpecHelper.spec '#find' do
     end
 
     it "should not find elements that don't match the filter" do
-      expect { @session.find(:beatle, 'John', :type => 'drummer') }.to raise_error(Capybara::ElementNotFound)
-      expect { @session.find(:beatle, 'George', :type => 'drummer') }.to raise_error(Capybara::ElementNotFound)
+      expect { @session.find(:beatle, 'John', type: 'drummer') }.to raise_error(Capybara::ElementNotFound)
+      expect { @session.find(:beatle, 'George', type: 'drummer') }.to raise_error(Capybara::ElementNotFound)
+    end
+  end
+
+  context "with alternate filter set" do
+    before do
+      Capybara::Selector::FilterSet.add(:value) do
+        filter(:with) { |node, with| node.value == with.to_s }
+      end
+
+      Capybara.add_selector(:id_with_field_filters) do
+        xpath { |id| XPath.descendant[XPath.attr(:id) == id.to_s] }
+        filter_set(:field)
+      end
+    end
+
+    it "should allow use of filters from custom filter set" do
+      expect(@session.find(:id, 'test_field', filter_set: :value, with: 'monkey').value).to eq('monkey')
+      expect{ @session.find(:id, 'test_field', filter_set: :value, with: 'not_monkey') }.to raise_error(Capybara::ElementNotFound)
+    end
+
+    it "should allow use of filter set from a different selector" do
+      expect(@session.find(:id, 'test_field', filter_set: :field, with: 'monkey').value).to eq('monkey')
+      expect{ @session.find(:id, 'test_field', filter_set: :field, with: 'not_monkey') }.to raise_error(Capybara::ElementNotFound)
+    end
+
+    it "should allow importing of filter set into selector" do
+      expect(@session.find(:id_with_field_filters, 'test_field', with: 'monkey').value).to eq('monkey')
+      expect{ @session.find(:id_with_field_filters, 'test_field', with: 'not_monkey') }.to raise_error(Capybara::ElementNotFound)
     end
   end
 
@@ -168,7 +197,7 @@ Capybara::SpecHelper.spec '#find' do
     before { Capybara.default_selector = :css }
     it "should find the first element using the given locator" do
       expect(@session.find('h1').text).to eq('This is a test')
-      expect(@session.find("input[id='test_field']")[:value]).to eq('monkey')
+      expect(@session.find("input[id='test_field']").value).to eq('monkey')
     end
     after { Capybara.default_selector = :xpath }
   end
@@ -176,26 +205,27 @@ Capybara::SpecHelper.spec '#find' do
   it "should raise ElementNotFound with a useful default message if nothing was found" do
     expect do
       @session.find(:xpath, '//div[@id="nosuchthing"]').to be_nil
-    end.to raise_error(Capybara::ElementNotFound, "Unable to find xpath \"//div[@id=\\\"nosuchthing\\\"]\"")
+    end.to raise_error(Capybara::ElementNotFound, "Unable to find visible xpath \"//div[@id=\\\"nosuchthing\\\"]\"")
   end
 
   it "should accept an XPath instance" do
     @session.visit('/form')
-    @xpath = XPath::HTML.fillable_field('First Name')
+    @xpath = Capybara::Selector.all[:fillable_field].call('First Name')
+    expect(@xpath).to be_a(::XPath::Union)
     expect(@session.find(@xpath).value).to eq('John')
   end
 
   context "with :exact option" do
     it "matches exactly when true" do
-      expect(@session.find(:xpath, XPath.descendant(:input)[XPath.attr(:id).is("test_field")], :exact => true).value).to eq("monkey")
+      expect(@session.find(:xpath, XPath.descendant(:input)[XPath.attr(:id).is("test_field")], exact:  true).value).to eq("monkey")
       expect do
-        @session.find(:xpath, XPath.descendant(:input)[XPath.attr(:id).is("est_fiel")], :exact => true)
+        @session.find(:xpath, XPath.descendant(:input)[XPath.attr(:id).is("est_fiel")], exact:  true)
       end.to raise_error(Capybara::ElementNotFound)
     end
 
     it "matches loosely when false" do
-      expect(@session.find(:xpath, XPath.descendant(:input)[XPath.attr(:id).is("test_field")], :exact => false).value).to eq("monkey")
-      expect(@session.find(:xpath, XPath.descendant(:input)[XPath.attr(:id).is("est_fiel")], :exact => false).value).to eq("monkey")
+      expect(@session.find(:xpath, XPath.descendant(:input)[XPath.attr(:id).is("test_field")], exact:  false).value).to eq("monkey")
+      expect(@session.find(:xpath, XPath.descendant(:input)[XPath.attr(:id).is("est_fiel")], exact:  false).value).to eq("monkey")
     end
 
     it "defaults to `Capybara.exact`" do
@@ -206,37 +236,43 @@ Capybara::SpecHelper.spec '#find' do
       Capybara.exact = false
       @session.find(:xpath, XPath.descendant(:input)[XPath.attr(:id).is("est_fiel")])
     end
+
+    it "warns when the option has no effect" do
+      expect_any_instance_of(Kernel).to receive(:warn).
+        with('The :exact option only has an effect on queries using the XPath#is method. Using it with the query "#test_field" has no effect.')
+      @session.find(:css, '#test_field', exact: true)
+    end
   end
 
   context "with :match option" do
     context "when set to `one`" do
       it "raises an error when multiple matches exist" do
         expect do
-          @session.find(:css, ".multiple", :match => :one)
+          @session.find(:css, ".multiple", match: :one)
         end.to raise_error(Capybara::Ambiguous)
       end
       it "raises an error even if there the match is exact and the others are inexact" do
         expect do
-          @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("almost_singular")], :exact => false, :match => :one)
+          @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("almost_singular")], exact:  false, match: :one)
         end.to raise_error(Capybara::Ambiguous)
       end
       it "returns the element if there is only one" do
-        expect(@session.find(:css, ".singular", :match => :one).text).to eq("singular")
+        expect(@session.find(:css, ".singular", match: :one).text).to eq("singular")
       end
       it "raises an error if there is no match" do
         expect do
-          @session.find(:css, ".does-not-exist", :match => :one)
+          @session.find(:css, ".does-not-exist", match: :one)
         end.to raise_error(Capybara::ElementNotFound)
       end
     end
 
     context "when set to `first`" do
       it "returns the first matched element" do
-        expect(@session.find(:css, ".multiple", :match => :first).text).to eq("multiple one")
+        expect(@session.find(:css, ".multiple", match: :first).text).to eq("multiple one")
       end
       it "raises an error if there is no match" do
         expect do
-          @session.find(:css, ".does-not-exist", :match => :first)
+          @session.find(:css, ".does-not-exist", match: :first)
         end.to raise_error(Capybara::ElementNotFound)
       end
     end
@@ -245,25 +281,25 @@ Capybara::SpecHelper.spec '#find' do
       context "and `exact` set to `false`" do
         it "raises an error when there are multiple exact matches" do
           expect do
-            @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("multiple")], :match => :smart, :exact => false)
+            @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("multiple")], match: :smart, exact:  false)
           end.to raise_error(Capybara::Ambiguous)
         end
         it "finds a single exact match when there also are inexact matches" do
-          result = @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("almost_singular")], :match => :smart, :exact => false)
+          result = @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("almost_singular")], match: :smart, exact:  false)
           expect(result.text).to eq("almost singular")
         end
         it "raises an error when there are multiple inexact matches" do
           expect do
-            @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("almost_singul")], :match => :smart, :exact => false)
+            @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("almost_singul")], match: :smart, exact:  false)
           end.to raise_error(Capybara::Ambiguous)
         end
         it "finds a single inexact match" do
-          result = @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("almost_singular but")], :match => :smart, :exact => false)
+          result = @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("almost_singular but")], match: :smart, exact:  false)
           expect(result.text).to eq("almost singular but not quite")
         end
         it "raises an error if there is no match" do
           expect do
-            @session.find(:css, ".does-not-exist", :match => :smart, :exact => false)
+            @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("does-not-exist")], match: :smart, exact:  false)
           end.to raise_error(Capybara::ElementNotFound)
         end
       end
@@ -271,26 +307,26 @@ Capybara::SpecHelper.spec '#find' do
       context "with `exact` set to `true`" do
         it "raises an error when there are multiple exact matches" do
           expect do
-            @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("multiple")], :match => :smart, :exact => true)
+            @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("multiple")], match: :smart, exact:  true)
           end.to raise_error(Capybara::Ambiguous)
         end
         it "finds a single exact match when there also are inexact matches" do
-          result = @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("almost_singular")], :match => :smart, :exact => true)
+          result = @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("almost_singular")], match: :smart, exact:  true)
           expect(result.text).to eq("almost singular")
         end
         it "raises an error when there are multiple inexact matches" do
           expect do
-            @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("almost_singul")], :match => :smart, :exact => true)
+            @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("almost_singul")], match: :smart, exact:  true)
           end.to raise_error(Capybara::ElementNotFound)
         end
         it "raises an error when there is a single inexact matches" do
           expect do
-            result = @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("almost_singular but")], :match => :smart, :exact => true)
+            @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("almost_singular but")], match: :smart, exact:  true)
           end.to raise_error(Capybara::ElementNotFound)
         end
         it "raises an error if there is no match" do
           expect do
-            @session.find(:css, ".does-not-exist", :match => :smart, :exact => true)
+            @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("does-not-exist")], match: :smart, exact:  true)
           end.to raise_error(Capybara::ElementNotFound)
         end
       end
@@ -299,50 +335,50 @@ Capybara::SpecHelper.spec '#find' do
     context "when set to `prefer_exact`" do
       context "and `exact` set to `false`" do
         it "picks the first one when there are multiple exact matches" do
-          result = @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("multiple")], :match => :prefer_exact, :exact => false)
+          result = @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("multiple")], match: :prefer_exact, exact:  false)
           expect(result.text).to eq("multiple one")
         end
         it "finds a single exact match when there also are inexact matches" do
-          result = @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("almost_singular")], :match => :prefer_exact, :exact => false)
+          result = @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("almost_singular")], match: :prefer_exact, exact:  false)
           expect(result.text).to eq("almost singular")
         end
         it "picks the first one when there are multiple inexact matches" do
-          result = @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("almost_singul")], :match => :prefer_exact, :exact => false)
+          result = @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("almost_singul")], match: :prefer_exact, exact:  false)
           expect(result.text).to eq("almost singular but not quite")
         end
         it "finds a single inexact match" do
-          result = @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("almost_singular but")], :match => :prefer_exact, :exact => false)
+          result = @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("almost_singular but")], match: :prefer_exact, exact:  false)
           expect(result.text).to eq("almost singular but not quite")
         end
         it "raises an error if there is no match" do
           expect do
-            @session.find(:css, ".does-not-exist", :match => :prefer_exact, :exact => false)
+            @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("does-not-exist")], match: :prefer_exact, exact:  false)
           end.to raise_error(Capybara::ElementNotFound)
         end
       end
 
       context "with `exact` set to `true`" do
         it "picks the first one when there are multiple exact matches" do
-          result = @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("multiple")], :match => :prefer_exact, :exact => true)
+          result = @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("multiple")], match: :prefer_exact, exact:  true)
           expect(result.text).to eq("multiple one")
         end
         it "finds a single exact match when there also are inexact matches" do
-          result = @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("almost_singular")], :match => :prefer_exact, :exact => true)
+          result = @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("almost_singular")], match: :prefer_exact, exact:  true)
           expect(result.text).to eq("almost singular")
         end
         it "raises an error if there are multiple inexact matches" do
           expect do
-            @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("almost_singul")], :match => :prefer_exact, :exact => true)
+            @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("almost_singul")], match: :prefer_exact, exact:  true)
           end.to raise_error(Capybara::ElementNotFound)
         end
         it "raises an error if there is a single inexact match" do
           expect do
-            @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("almost_singular but")], :match => :prefer_exact, :exact => true)
+            @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("almost_singular but")], match: :prefer_exact, exact:  true)
           end.to raise_error(Capybara::ElementNotFound)
         end
         it "raises an error if there is no match" do
           expect do
-            @session.find(:css, ".does-not-exist", :match => :prefer_exact, :exact => true)
+            @session.find(:xpath, XPath.descendant[XPath.attr(:class).is("does-not-exist")], match: :prefer_exact, exact:  true)
           end.to raise_error(Capybara::ElementNotFound)
         end
       end
@@ -359,11 +395,15 @@ Capybara::SpecHelper.spec '#find' do
 
     it "raises an error when unknown option given" do
       expect do
-        @session.find(:css, ".singular", :match => :schmoo)
+        @session.find(:css, ".singular", match: :schmoo)
       end.to raise_error(ArgumentError)
     end
   end
 
+  it "supports a custom filter block" do
+    expect(@session.find(:css, 'input'){|node| node.disabled? }[:name]).to eq('disabled_text')
+  end
+
   context "within a scope" do
     before do
       @session.visit('/with_scope')
@@ -381,4 +421,10 @@ Capybara::SpecHelper.spec '#find' do
       end
     end
   end
+
+  it "should raise if selector type is unknown" do
+    expect do
+      @session.find(:unknown, '//h1')
+    end.to raise_error(ArgumentError)
+  end
 end

data/lib/capybara/spec/session/first_spec.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 Capybara::SpecHelper.spec '#first' do
   before do
     @session.visit('/with_html')
@@ -5,7 +6,7 @@ Capybara::SpecHelper.spec '#first' do
 
   it "should find the first element using the given locator" do
     expect(@session.first('//h1').text).to eq('This is a test')
-    expect(@session.first("//input[@id='test_field']")[:value]).to eq('monkey')
+    expect(@session.first("//input[@id='test_field']").value).to eq('monkey')
   end
 
   it "should return nil when nothing was found" do
@@ -14,21 +15,27 @@ Capybara::SpecHelper.spec '#first' do
 
   it "should accept an XPath instance" do
     @session.visit('/form')
-    @xpath = XPath::HTML.fillable_field('First Name')
+    @xpath = Capybara::Selector.all[:fillable_field].call('First Name')
+    expect(@xpath).to be_a(::XPath::Union)
     expect(@session.first(@xpath).value).to eq('John')
   end
 
+  it "should warn when unused parameters are passed" do
+    expect_any_instance_of(Kernel).to receive(:warn).with(/Unused parameters passed.*unused text/)
+    @session.first(:css, '.header h2', 'unused text')
+  end
+
   context "with css selectors" do
     it "should find the first element using the given selector" do
       expect(@session.first(:css, 'h1').text).to eq('This is a test')
-      expect(@session.first(:css, "input[id='test_field']")[:value]).to eq('monkey')
+      expect(@session.first(:css, "input[id='test_field']").value).to eq('monkey')
     end
   end
 
   context "with xpath selectors" do
     it "should find the first element using the given locator" do
       expect(@session.first(:xpath, '//h1').text).to eq('This is a test')
-      expect(@session.first(:xpath, "//input[@id='test_field']")[:value]).to eq('monkey')
+      expect(@session.first(:xpath, "//input[@id='test_field']").value).to eq('monkey')
     end
   end
 
@@ -36,33 +43,38 @@ Capybara::SpecHelper.spec '#first' do
     before { Capybara.default_selector = :css }
     it "should find the first element using the given locator" do
       expect(@session.first('h1').text).to eq('This is a test')
-      expect(@session.first("input[id='test_field']")[:value]).to eq('monkey')
+      expect(@session.first("input[id='test_field']").value).to eq('monkey')
     end
   end
 
   context "with visible filter" do
     it "should only find visible nodes when true" do
-      expect(@session.first(:css, "a#invisible", :visible => true)).to be_nil
+      expect(@session.first(:css, "a#invisible", visible: true)).to be_nil
     end
 
     it "should find nodes regardless of whether they are invisible when false" do
-      expect(@session.first(:css, "a#invisible", :visible => false)).not_to be_nil
-      expect(@session.first(:css, "a#visible", :visible => false)).not_to be_nil
+      expect(@session.first(:css, "a#invisible", visible: false)).not_to be_nil
+      expect(@session.first(:css, "a#invisible", visible: false, text: 'hidden link')).not_to be_nil
+      expect(@session.first(:css, "a#visible", visible: false)).not_to be_nil
     end
 
     it "should find nodes regardless of whether they are invisible when :all" do
-      expect(@session.first(:css, "a#invisible", :visible => :all)).not_to be_nil
-      expect(@session.first(:css, "a#visible", :visible => :all)).not_to be_nil
+      expect(@session.first(:css, "a#invisible", visible: :all)).not_to be_nil
+      expect(@session.first(:css, "a#invisible", visible: :all, text: 'hidden link')).not_to be_nil
+      expect(@session.first(:css, "a#visible", visible: :all)).not_to be_nil
     end
 
     it "should find only hidden nodes when :hidden" do
-      expect(@session.first(:css, "a#invisible", :visible => :hidden)).not_to be_nil
-      expect(@session.first(:css, "a#visible", :visible => :hidden)).to be_nil
+      expect(@session.first(:css, "a#invisible", visible: :hidden)).not_to be_nil
+      expect(@session.first(:css, "a#invisible", visible: :hidden, text: 'hidden link')).not_to be_nil
+      expect(@session.first(:css, "a#invisible", visible: :hidden, text: 'not hidden link')).to be_nil
+      expect(@session.first(:css, "a#visible", visible: :hidden)).to be_nil
     end
 
     it "should find only visible nodes when :visible" do
-      expect(@session.first(:css, "a#invisible", :visible => :visible)).to be_nil
-      expect(@session.first(:css, "a#visible", :visible => :visible)).not_to be_nil
+      expect(@session.first(:css, "a#invisible", visible: :visible)).to be_nil
+      expect(@session.first(:css, "a#invisible", visible: :visible, text: 'hidden link')).to be_nil
+      expect(@session.first(:css, "a#visible", visible: :visible)).not_to be_nil
     end
 
     it "should default to Capybara.ignore_hidden_elements" do
@@ -99,14 +111,18 @@ Capybara::SpecHelper.spec '#first' do
 
     it "should wait for at least one match if true" do
       Capybara.wait_on_first_by_default = true
-      @session.click_link('clickable')
-      expect(@session.first(:css, 'a#has-been-clicked')).not_to be_nil
+      Capybara.using_wait_time(3) do
+        @session.click_link('clickable')
+        expect(@session.first(:css, 'a#has-been-clicked')).not_to be_nil
+      end
     end
 
     it "should return nil after waiting if no match" do
       Capybara.wait_on_first_by_default = true
-      @session.click_link('clickable')
-      expect(@session.first(:css, 'a#not-a-real-link')).to be_nil
+      Capybara.using_wait_time(3) do
+        @session.click_link('clickable')
+        expect(@session.first(:css, 'a#not-a-real-link')).to be_nil
+      end
     end
   end
 end

data/lib/capybara/spec/session/frame/switch_to_frame_spec.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+Capybara::SpecHelper.spec '#switch_to_frame', requires: [:frames] do
+  before(:each) do
+    @session.visit('/within_frames')
+  end
+
+  after(:each) do
+    # Ensure we clean up after the frame changes
+    @session.switch_to_frame(:top)
+  end
+
+  it "should find the div in frameOne" do
+    frame = @session.find(:frame, "frameOne")
+    @session.switch_to_frame(frame)
+    expect(@session.find("//*[@id='divInFrameOne']").text).to eql 'This is the text of divInFrameOne'
+  end
+
+  it "should find the div in FrameTwo" do
+    frame = @session.find(:frame, "frameTwo")
+    @session.switch_to_frame(frame)
+    expect(@session.find("//*[@id='divInFrameTwo']").text).to eql 'This is the text of divInFrameTwo'
+  end
+
+  it "should return to the parent frame when told to" do
+    frame = @session.find(:frame, "frameOne")
+    @session.switch_to_frame(frame)
+    @session.switch_to_frame(:parent)
+    expect(@session.find("//*[@id='divInMainWindow']").text).to eql 'This is the text for divInMainWindow'
+  end
+
+  it "should be able to switch to nested frames" do
+    frame = @session.find(:frame, "parentFrame")
+    @session.switch_to_frame frame
+    frame = @session.find(:frame, "childFrame")
+    @session.switch_to_frame frame
+    frame = @session.find(:frame, "grandchildFrame1")
+    @session.switch_to_frame frame
+    expect(@session).to have_selector(:css, '#divInFrameOne', text: 'This is the text of divInFrameOne')
+  end
+
+  it "should reset scope when changing frames" do
+    frame = @session.find(:frame, 'parentFrame')
+    @session.within(:css, '#divInMainWindow') do
+      @session.switch_to_frame(frame)
+      expect(@session.has_selector?(:css, "iframe#childFrame")).to be true
+      @session.switch_to_frame(:parent)
+    end
+  end
+
+  it "works if the frame is closed", requires: [:frames, :js] do
+    frame = @session.find(:frame, 'parentFrame')
+    @session.switch_to_frame frame
+    frame = @session.find(:frame, 'childFrame')
+    @session.switch_to_frame frame
+
+    @session.click_link 'Close Window'
+    @session.switch_to_frame :parent # Go back to parentFrame
+    expect(@session).to have_selector(:css, 'body#parentBody')
+    expect(@session).not_to have_selector(:css, '#childFrame')
+    @session.switch_to_frame :parent # Go back to top
+  end
+
+  it "can return to the top frame", requires: [:frames] do
+    frame = @session.find(:frame, "parentFrame")
+    @session.switch_to_frame frame
+    frame = @session.find(:frame, "childFrame")
+    @session.switch_to_frame frame
+    @session.switch_to_frame :top
+    expect(@session.find("//*[@id='divInMainWindow']").text).to eql 'This is the text for divInMainWindow'
+  end
+
+  it "should raise error if switching to parent unmatched inside `within` as it's nonsense" do
+    expect do
+      frame = @session.find(:frame, 'parentFrame')
+      @session.switch_to_frame(frame)
+      @session.within(:css, '#parentBody') do
+        @session.switch_to_frame(:parent)
+      end
+    end.to raise_error(Capybara::ScopeError, "`switch_to_frame(:parent)` cannot be called from inside a descendant frame's `within` block.")
+  end
+
+  it "should raise error if switching to top inside a `within` in a frame as it's nonsense" do
+    frame = @session.find(:frame, 'parentFrame')
+    @session.switch_to_frame(frame)
+    @session.within(:css, '#parentBody') do
+      expect do
+        @session.switch_to_frame(:top)
+      end.to raise_error(Capybara::ScopeError, "`switch_to_frame(:top)` cannot be called from inside a descendant frame's `within` block.")
+    end
+  end
+
+  it "should raise error if switching to top inside a nested `within` in a frame as it's nonsense" do
+    frame = @session.find(:frame, 'parentFrame')
+    @session.switch_to_frame(frame)
+    @session.within(:css, '#parentBody') do
+      @session.switch_to_frame(@session.find(:frame, "childFrame"))
+      expect do
+        @session.switch_to_frame(:top)
+      end.to raise_error(Capybara::ScopeError, "`switch_to_frame(:top)` cannot be called from inside a descendant frame's `within` block.")
+      @session.switch_to_frame(:parent)
+    end
+  end
+end