capybara 2.7.0 → 3.35.3

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

@@ -1,16 +1,29 @@
 # frozen_string_literal: true
+
 Capybara::SpecHelper.spec '#find_button' do
   before do
     @session.visit('/form')
   end
 
-  it "should find any button" do
-    expect(@session.find_button('med')[:id]).to eq("mediocre")
-    expect(@session.find_button('crap321').value).to eq("crappy")
+  it 'should find any button' do
+    expect(@session.find_button('med')[:id]).to eq('mediocre')
+    expect(@session.find_button('crap321').value).to eq('crappy')
   end
 
-  it "casts to string" do
-    expect(@session.find_button(:'med')[:id]).to eq("mediocre")
+  context 'aria_label attribute with Capybara.enable_aria_label' do
+    it 'should find when true' do
+      Capybara.enable_aria_label = true
+      expect(@session.find_button('Mediocre Button')[:id]).to eq('mediocre')
+    end
+
+    it 'should not find when false' do
+      Capybara.enable_aria_label = false
+      expect { @session.find_button('Mediocre Button') }.to raise_error(Capybara::ElementNotFound)
+    end
+  end
+
+  it 'casts to string' do
+    expect(@session.find_button(:med)[:id]).to eq('mediocre')
   end
 
   it "should raise error if the button doesn't exist" do
@@ -19,37 +32,43 @@ Capybara::SpecHelper.spec '#find_button' do
     end.to raise_error(Capybara::ElementNotFound)
   end
 
-  context "with :exact option" do
-    it "should accept partial matches when false" do
-      expect(@session.find_button('What an Awesome', :exact => false)[:value]).to eq("awesome")
+  context 'with :exact option' do
+    it 'should accept partial matches when false' do
+      expect(@session.find_button('What an Awesome', exact: false).value).to eq('awesome')
     end
 
-    it "should not accept partial matches when true" do
+    it 'should not accept partial matches when true' do
       expect do
-        @session.find_button('What an Awesome', :exact => true)
+        @session.find_button('What an Awesome', exact: true)
       end.to raise_error(Capybara::ElementNotFound)
     end
   end
 
-  context "with :disabled option" do
-    it "should find disabled buttons when true" do
-      expect(@session.find_button('Disabled button', :disabled => true).value).to eq("Disabled button")
+  context 'with :disabled option' do
+    it 'should find disabled buttons when true' do
+      expect(@session.find_button('Disabled button', disabled: true).value).to eq('Disabled button')
     end
 
-    it "should not find disabled buttons when false" do
+    it 'should not find disabled buttons when false' do
       expect do
-        @session.find_button('Disabled button', :disabled => false)
+        @session.find_button('Disabled button', disabled: false)
       end.to raise_error(Capybara::ElementNotFound)
     end
 
-    it "should default to not finding disabled buttons" do
+    it 'should default to not finding disabled buttons' do
       expect do
         @session.find_button('Disabled button')
       end.to raise_error(Capybara::ElementNotFound)
     end
 
-    it "should find disabled buttons when :all" do
-      expect(@session.find_button('Disabled button', :disabled => :all).value).to eq("Disabled button")
+    it 'should find disabled buttons when :all' do
+      expect(@session.find_button('Disabled button', disabled: :all).value).to eq('Disabled button')
+    end
+  end
+
+  context 'without locator' do
+    it 'should use options' do
+      expect(@session.find_button(disabled: true).value).to eq('Disabled button')
     end
   end
 end

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

@@ -1,31 +1,32 @@
 # frozen_string_literal: true
+
 Capybara::SpecHelper.spec '#find_by_id' do
   before do
     @session.visit('/with_html')
   end
 
-  it "should find any element by id" do
+  it 'should find any element by id' do
     expect(@session.find_by_id('red').tag_name).to eq('a')
   end
 
-  it "casts to string" do
-    expect(@session.find_by_id(:'red').tag_name).to eq('a')
+  it 'casts to string' do
+    expect(@session.find_by_id(:red).tag_name).to eq('a')
   end
 
-  it "should raise error if no element with id is found" do
+  it 'should raise error if no element with id is found' do
     expect do
       @session.find_by_id('nothing_with_this_id')
     end.to raise_error(Capybara::ElementNotFound)
   end
 
-  context "with :visible option" do
-    it "finds invisible elements when `false`" do
-      expect(@session.find_by_id("hidden_via_ancestor", :visible => false).text(:all)).to match(/with hidden ancestor/)
+  context 'with :visible option' do
+    it 'finds invisible elements when `false`' do
+      expect(@session.find_by_id('hidden_via_ancestor', visible: false).text(:all)).to match(/with hidden ancestor/)
     end
 
-    it "finds invisible elements when `false`" do
+    it "doesn't find invisible elements when `true`" do
       expect do
-        @session.find_by_id("hidden_via_ancestor", :visible => true)
+        @session.find_by_id('hidden_via_ancestor', visible: true)
       end.to raise_error(Capybara::ElementNotFound)
     end
   end

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

@@ -1,17 +1,35 @@
 # frozen_string_literal: true
+
 Capybara::SpecHelper.spec '#find_field' do
   before do
     @session.visit('/form')
   end
 
-  it "should find any field" do
+  it 'should find any field' do
+    Capybara.test_id = 'data-test-id'
     expect(@session.find_field('Dog').value).to eq('dog')
-    expect(@session.find_field('form_description').text).to eq('Descriptive text goes here')
+    expect(@session.find_field('form_description').value).to eq('Descriptive text goes here')
     expect(@session.find_field('Region')[:name]).to eq('form[region]')
+    expect(@session.find_field('With Asterisk*')).to be_truthy
+    expect(@session.find_field('my_test_id')).to be_truthy
+  end
+
+  context 'aria_label attribute with Capybara.enable_aria_label' do
+    it 'should find when true' do
+      Capybara.enable_aria_label = true
+      expect(@session.find_field('Unlabelled Input')[:name]).to eq('form[which_form]')
+      # expect(@session.find_field('Emergency Number')[:id]).to eq('html5_tel')
+    end
+
+    it 'should not find when false' do
+      Capybara.enable_aria_label = false
+      expect { @session.find_field('Unlabelled Input') }.to raise_error(Capybara::ElementNotFound)
+      # expect { @session.find_field('Emergency Number') }.to raise_error(Capybara::ElementNotFound)
+    end
   end
 
-  it "casts to string" do
-    expect(@session.find_field(:'Dog').value).to eq('dog')
+  it 'casts to string' do
+    expect(@session.find_field(:Dog).value).to eq('dog')
   end
 
   it "should raise error if the field doesn't exist" do
@@ -20,71 +38,76 @@ Capybara::SpecHelper.spec '#find_field' do
     end.to raise_error(Capybara::ElementNotFound)
   end
 
-  it "should warn if filter option is invalid" do
-    expect_any_instance_of(Kernel).to receive(:warn).
-      with('Invalid value nil passed to filter disabled - defaulting to false')
-    @session.find_field('Dog', disabled: nil)
-  end
-
-  it "should be aliased as 'field_labeled' for webrat compatibility" do
-    expect(@session.field_labeled('Dog').value).to eq('dog')
+  it 'should raise error if filter option is invalid' do
     expect do
-      @session.field_labeled('Does not exist')
-    end.to raise_error(Capybara::ElementNotFound)
+      @session.find_field('Dog', disabled: nil)
+    end.to raise_error ArgumentError, 'Invalid value nil passed to NodeFilter disabled'
   end
 
-  context "with :exact option" do
-    it "should accept partial matches when false" do
-      expect(@session.find_field("Explanation", :exact => false)[:name]).to eq("form[name_explanation]")
+  context 'with :exact option' do
+    it 'should accept partial matches when false' do
+      expect(@session.find_field('Explanation', exact: false)[:name]).to eq('form[name_explanation]')
     end
 
-    it "should not accept partial matches when true" do
+    it 'should not accept partial matches when true' do
       expect do
-        @session.find_field("Explanation", :exact => true)
+        @session.find_field('Explanation', exact: true)
       end.to raise_error(Capybara::ElementNotFound)
     end
   end
 
-  context "with :disabled option" do
-    it "should find disabled fields when true" do
-      expect(@session.find_field("Disabled Checkbox", :disabled => true)[:name]).to eq("form[disabled_checkbox]")
+  context 'with :disabled option' do
+    it 'should find disabled fields when true' do
+      expect(@session.find_field('Disabled Checkbox', disabled: true)[:name]).to eq('form[disabled_checkbox]')
+      expect(@session.find_field('form_disabled_fieldset_child', disabled: true)[:name]).to eq('form[disabled_fieldset_child]')
+      expect(@session.find_field('form_disabled_fieldset_descendant', disabled: true)[:name]).to eq('form[disabled_fieldset_descendant]')
     end
 
-    it "should not find disabled fields when false" do
+    it 'should not find disabled fields when false' do
       expect do
-        @session.find_field("Disabled Checkbox", :disabled => false)
+        @session.find_field('Disabled Checkbox', disabled: false)
       end.to raise_error(Capybara::ElementNotFound)
     end
 
-    it "should not find disabled fields by default" do
+    it 'should not find disabled fields by default' do
       expect do
-        @session.find_field("Disabled Checkbox")
+        @session.find_field('Disabled Checkbox')
       end.to raise_error(Capybara::ElementNotFound)
     end
 
-    it "should find disabled fields when :all" do
-      expect(@session.find_field("Disabled Checkbox", :disabled => :all)[:name]).to eq("form[disabled_checkbox]")
+    it 'should find disabled fields when :all' do
+      expect(@session.find_field('Disabled Checkbox', disabled: :all)[:name]).to eq('form[disabled_checkbox]')
     end
 
-    it "should find enabled fields when :all" do
-      expect(@session.find_field('Dog', :disabled => :all).value).to eq('dog')
+    it 'should find enabled fields when :all' do
+      expect(@session.find_field('Dog', disabled: :all).value).to eq('dog')
     end
   end
 
-
   context 'with :readonly option' do
-    it "should find readonly fields when true" do
+    it 'should find readonly fields when true' do
       expect(@session.find_field('form[readonly_test]', readonly: true)[:id]).to eq 'readonly'
     end
 
-    it "should not find readonly fields when false" do
+    it 'should not find readonly fields when false' do
       expect(@session.find_field('form[readonly_test]', readonly: false)[:id]).to eq 'not_readonly'
     end
 
-    it "should ignore readonly by default" do
+    it 'should ignore readonly by default' do
       expect do
         @session.find_field('form[readonly_test]')
       end.to raise_error(Capybara::Ambiguous, /found 2 elements/)
     end
   end
+
+  context 'with no locator' do
+    it 'should use options to find the field' do
+      expect(@session.find_field(type: 'checkbox', with: 'dog')['id']).to eq 'form_pets_dog'
+    end
+  end
+
+  it 'should accept an optional filter block' do
+    # this would be better done with the :with option but this is just a test
+    expect(@session.find_field('form[pets][]') { |node| node.value == 'dog' }[:id]).to eq 'form_pets_dog'
+  end
 end

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

@@ -1,16 +1,29 @@
 # frozen_string_literal: true
+
 Capybara::SpecHelper.spec '#find_link' do
   before do
     @session.visit('/with_html')
   end
 
-  it "should find any field" do
-    expect(@session.find_link('foo').text).to eq("ullamco")
-    expect(@session.find_link('labore')[:href]).to match %r(/with_simple_html$)
+  it 'should find any link' do
+    expect(@session.find_link('foo').text).to eq('ullamco')
+    expect(@session.find_link('labore')[:href]).to match %r{/with_simple_html$}
   end
 
-  it "casts to string" do
-    expect(@session.find_link(:'foo').text).to eq("ullamco")
+  context 'aria_label attribute with Capybara.enable_aria_label' do
+    it 'should find when true' do
+      Capybara.enable_aria_label = true
+      expect(@session.find_link('Go to simple')[:href]).to match %r{/with_simple_html$}
+    end
+
+    it 'should not find when false' do
+      Capybara.enable_aria_label = false
+      expect { @session.find_link('Go to simple') }.to raise_error(Capybara::ElementNotFound)
+    end
+  end
+
+  it 'casts to string' do
+    expect(@session.find_link(:foo).text).to eq('ullamco')
   end
 
   it "should raise error if the field doesn't exist" do
@@ -19,15 +32,39 @@ Capybara::SpecHelper.spec '#find_link' do
     end.to raise_error(Capybara::ElementNotFound)
   end
 
-  context "with :exact option" do
-    it "should accept partial matches when false" do
-      expect(@session.find_link('abo', :exact => false).text).to eq("labore")
+  context 'with :exact option' do
+    it 'should accept partial matches when false' do
+      expect(@session.find_link('abo', exact: false).text).to eq('labore')
     end
 
-    it "should not accept partial matches when true" do
+    it 'should not accept partial matches when true' do
       expect do
-        @session.find_link('abo', :exact => true)
+        @session.find_link('abo', exact: true)
       end.to raise_error(Capybara::ElementNotFound)
     end
   end
+
+  context 'without locator' do
+    it 'should use options' do
+      expect(@session.find_link(href: '#anchor').text).to eq 'Normal Anchor'
+    end
+  end
+
+  context 'download filter' do
+    it 'finds a download link' do
+      expect(@session.find_link('Download Me', download: true).text).to eq 'Download Me'
+    end
+
+    it "doesn't find a download link if download is false" do
+      expect { @session.find_link('Download Me', download: false) }.to raise_error Capybara::ElementNotFound
+    end
+
+    it 'finds a renaming download link' do
+      expect(@session.find_link(download: 'other.csv').text).to eq 'Download Other'
+    end
+
+    it 'raises if passed an invalid value' do
+      expect { @session.find_link(download: 37) }.to raise_error ArgumentError
+    end
+  end
 end

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

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 Capybara::SpecHelper.spec '#find' do
   before do
     @session.visit('/with_html')
@@ -8,66 +9,67 @@ Capybara::SpecHelper.spec '#find' do
     Capybara::Selector.remove(:monkey)
   end
 
-  it "should find the first element using the given locator" 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')
+  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')
   end
 
-  it "should raise an error if there are multiple matches" do
+  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
+    Capybara.default_max_wait_time = 2
     @session.visit('/with_js')
     @session.click_link('Click me')
-    expect(@session.find(:css, "a#has-been-clicked").text).to include('Has been clicked')
+    expect(@session.find(:css, 'a#has-been-clicked').text).to include('Has been clicked')
   end
 
-  context "with :text option" do
+  context 'with :text option' do
     it "casts text's argument to string" do
-      expect(@session.find(:css, '.number', text: 42)).to have_content("42")
+      expect(@session.find(:css, '.number', text: 42)).to have_content('42')
     end
   end
 
-  context "with :wait option", :requires => [:js] do
-    it "should not wait for asynchronous load when `false` given" 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
 
-    it "should not find element if it appears after given wait duration" do
+    it 'should not find element if it appears after given wait duration' 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
+    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: 3.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
+      it 'will time out even if time is frozen' do
         @session.visit('/with_js')
         now = Time.now
         allow(Time).to receive(:now).and_return(now)
         expect { @session.find('//isnotthere') }.to raise_error(Capybara::ElementNotFound)
       end
     else
-      it "raises an error suggesting that Capybara is stuck in time" do
+      it 'raises an error suggesting that Capybara is stuck in time' do
         @session.visit('/with_js')
         now = Time.now
         allow(Time).to receive(:now).and_return(now)
@@ -76,26 +78,42 @@ Capybara::SpecHelper.spec '#find' do
     end
   end
 
-  context "with css selectors" do
-    it "should find the first element using the given locator" 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
+    it 'should support pseudo selectors' do
       expect(@session.find(:css, 'input:disabled').value).to eq('This is disabled')
     end
+
+    it 'should support escaping characters' do
+      expect(@session.find(:css, '#\31 escape\.me').text).to eq('needs escaping')
+      expect(@session.find(:css, '.\32 escape').text).to eq('needs escaping')
+    end
+
+    it 'should not warn about locator' do
+      expect { @session.find(:css, '#not_on_page') }.to raise_error Capybara::ElementNotFound do |e|
+        expect(e.message).not_to match(/you may be passing a CSS selector or XPath expression/)
+      end
+    end
   end
 
-  context "with xpath selectors" do
-    it "should find the first element using the given locator" 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
+
+    it 'should warn if passed a non-valid locator type' do
+      expect { @session.find(:xpath, 123) }.to raise_error(Exception) # The exact error is not yet well defined
+        .and output(/must respond to to_xpath or be an instance of String/).to_stderr
     end
   end
 
-  context "with custom selector" do
-    it "should use the custom selector" do
+  context 'with custom selector' do
+    it 'should use the custom selector' do
       Capybara.add_selector(:beatle) do
         xpath { |name| ".//*[@id='#{name}']" }
       end
@@ -104,11 +122,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')
@@ -117,269 +135,397 @@ Capybara::SpecHelper.spec '#find' do
     end
   end
 
-  context "with custom selector with custom filter" do
+  context 'with custom selector with custom filter' do
     before do
       Capybara.add_selector(:beatle) do
         xpath { |name| ".//li[contains(@class, 'beatle')][contains(text(), '#{name}')]" }
-        filter(:type) { |node, type| node[:class].split(/\s+/).include?(type) }
+        node_filter(:type) { |node, type| node[:class].split(/\s+/).include?(type) }
+        node_filter(:fail) { |_node, _val| raise Capybara::ElementNotFound, 'fail' }
       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')
+    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')
     end
 
-    it "ignores filter when it is not given" do
+    it 'ignores filter when it is not given' do
       expect(@session.find(:beatle, 'Paul').text).to eq('Paul')
       expect(@session.find(:beatle, 'John').text).to eq('John')
     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
+
+    it 'should not raise an ElementNotFound error from in a filter' do
+      expect { @session.find(:beatle, 'John', fail: 'something') }.to raise_error(Capybara::ElementNotFound, /beatle "John"/)
     end
   end
 
-  context "with custom selector with custom filter and default" do
+  context 'with custom selector with custom filter and default' 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) }
+        node_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')
+    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')
     end
 
-    it "should use default value when filter is not given" do
+    it 'should use default value when filter is not given' do
       expect(@session.find(:beatle, 'Paul').text).to eq('Paul')
       expect { @session.find(:beatle, 'John') }.to raise_error(Capybara::ElementNotFound)
     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 css as default selector" do
+  context 'with alternate filter set' do
+    before do
+      Capybara::Selector::FilterSet.add(:value) do
+        node_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
+
+  context 'with css as default selector' do
     before { Capybara.default_selector = :css }
-    it "should find the first element using the given locator" do
+
+    after { Capybara.default_selector = :xpath }
+
+    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
 
-  it "should raise ElementNotFound with a useful default message if nothing was found" 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 xpath "//div[@id=\\"nosuchthing\\"]"')
   end
 
-  it "should accept an XPath instance" do
+  it 'should accept an XPath instance' do
     @session.visit('/form')
-    @xpath = XPath::HTML.fillable_field('First Name')
+    @xpath = Capybara::Selector.new(:fillable_field, config: {}, format: :xpath).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")
+  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 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")
+    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')
     end
 
-    it "defaults to `Capybara.exact`" do
+    it 'defaults to `Capybara.exact`' do
       Capybara.exact = true
       expect do
-        @session.find(:xpath, XPath.descendant(:input)[XPath.attr(:id).is("est_fiel")])
+        @session.find(:xpath, XPath.descendant(:input)[XPath.attr(:id).is('est_fiel')])
       end.to raise_error(Capybara::ElementNotFound)
       Capybara.exact = false
-      @session.find(:xpath, XPath.descendant(:input)[XPath.attr(:id).is("est_fiel")])
+      @session.find(:xpath, XPath.descendant(:input)[XPath.attr(:id).is('est_fiel')])
+    end
+
+    it 'warns when the option has no effect' do
+      expect { @session.find(:css, '#test_field', exact: true) }.to \
+        output(/^The :exact option only has an effect on queries using the XPath#is method. Using it with the query "#test_field" has no effect/).to_stderr
     end
   end
 
-  context "with :match option" do
-    context "when set to `one`" do
-      it "raises an error when multiple matches exist" do
+  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
+
+      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")
+
+      it 'returns the element if there is only one' do
+        expect(@session.find(:css, '.singular', match: :one).text).to eq('singular')
       end
-      it "raises an error if there is no match" do
+
+      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")
+    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')
       end
-      it "raises an error if there is no match" do
+
+      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
 
-    context "when set to `smart`" do
-      context "and `exact` set to `false`" do
-        it "raises an error when there are multiple exact matches" do
+    context 'when set to `smart`' 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)
-          expect(result.text).to eq("almost singular")
+
+        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)
+          expect(result.text).to eq('almost singular')
         end
-        it "raises an error when there are multiple inexact matches" do
+
+        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)
-          expect(result.text).to eq("almost singular but not quite")
+
+        it 'finds a single inexact match' do
+          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
+
+        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
 
-      context "with `exact` set to `true`" do
-        it "raises an error when there are multiple exact matches" 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)
-          expect(result.text).to eq("almost singular")
+
+        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)
+          expect(result.text).to eq('almost singular')
         end
-        it "raises an error when there are multiple inexact matches" do
+
+        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
+
+        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
+
+        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
     end
 
-    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)
-          expect(result.text).to eq("multiple one")
+    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)
+          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)
-          expect(result.text).to eq("almost singular")
+
+        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)
+          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)
-          expect(result.text).to eq("almost singular but not quite")
+
+        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)
+          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)
-          expect(result.text).to eq("almost singular but not quite")
+
+        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)
+          expect(result.text).to eq('almost singular but not quite')
         end
-        it "raises an error if there is no match" do
+
+        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)
-          expect(result.text).to eq("multiple one")
+      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)
+          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)
-          expect(result.text).to eq("almost singular")
+
+        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)
+          expect(result.text).to eq('almost singular')
         end
-        it "raises an error if there are multiple inexact matches" do
+
+        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
+
+        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
+
+        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
     end
 
-    it "defaults to `Capybara.match`" do
+    it 'defaults to `Capybara.match`' do
       Capybara.match = :one
       expect do
-        @session.find(:css, ".multiple")
+        @session.find(:css, '.multiple')
       end.to raise_error(Capybara::Ambiguous)
       Capybara.match = :first
-      expect(@session.find(:css, ".multiple").text).to eq("multiple one")
+      expect(@session.find(:css, '.multiple').text).to eq('multiple one')
     end
 
-    it "raises an error when unknown option given" 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
 
-  context "within a scope" do
+  it 'supports a custom filter block' do
+    expect(@session.find(:css, 'input', &:disabled?)[:name]).to eq('disabled_text')
+  end
+
+  context 'with spatial filters', requires: [:spatial] do
+    before do
+      @session.visit('/spatial')
+    end
+
+    let :center do
+      @session.find(:css, 'div.center')
+    end
+
+    it 'should find an element above another element' do
+      expect(@session.find(:css, 'div:not(.corner)', above: center).text).to eq('2')
+    end
+
+    it 'should find an element below another element' do
+      expect(@session.find(:css, 'div:not(.corner):not(.footer)', below: center).text).to eq('8')
+    end
+
+    it 'should find an element left of another element' do
+      expect(@session.find(:css, 'div:not(.corner)', left_of: center).text).to eq('4')
+    end
+
+    it 'should find an element right of another element' do
+      expect(@session.find(:css, 'div:not(.corner)', right_of: center).text).to eq('6')
+    end
+
+    it 'should combine spatial filters' do
+      expect(@session.find(:css, 'div', left_of: center, above: center).text).to eq('1')
+      expect(@session.find(:css, 'div', right_of: center, below: center).text).to eq('9')
+    end
+
+    it 'should find an element "near" another element' do
+      expect(@session.find(:css, 'div.distance', near: center).text).to eq('2')
+    end
+  end
+
+  context 'within a scope' do
     before do
       @session.visit('/with_scope')
     end
 
-    it "should find the an element using the given locator" do
+    it 'should find the an element using the given locator' do
       @session.within(:xpath, "//div[@id='for_bar']") do
         expect(@session.find('.//li[1]').text).to match(/With Simple HTML/)
       end
     end
 
-    it "should support pseudo selectors" do
+    it 'should support pseudo selectors' do
       @session.within(:xpath, "//div[@id='for_bar']") do
         expect(@session.find(:css, 'input:disabled').value).to eq('James')
       end
     end
   end
+
+  it 'should raise if selector type is unknown' do
+    expect do
+      @session.find(:unknown, '//h1')
+    end.to raise_error(ArgumentError)
+  end
+
+  context 'with Capybara.test_id' do
+    it 'should not match on it when nil' do
+      Capybara.test_id = nil
+      expect(@session).not_to have_field('test_id')
+    end
+
+    it 'should work with the attribute set to `data-test-id` attribute' do
+      Capybara.test_id = 'data-test-id'
+      expect(@session.find(:field, 'test_id')[:id]).to eq 'test_field'
+    end
+
+    it 'should use a different attribute if set' do
+      Capybara.test_id = 'data-other-test-id'
+      expect(@session.find(:field, 'test_id')[:id]).to eq 'normal'
+    end
+
+    it 'should find a link with the test_id' do
+      Capybara.test_id = 'data-test-id'
+      expect(@session.find(:link, 'test-foo')[:id]).to eq 'foo'
+    end
+  end
 end