remove allow_nil option from Session#first

lib/capybara/node/finders.rb

@@ -277,22 +277,20 @@ module Capybara
       ##
       #
       # Find the first element on the page matching the given selector
-      # and options.  Will raise an error if no matching element is found
-      # unless the `allow_nil` option is true.
+      # and options. By default `first` will wait up to `Capybara.default_max_wait_time`
+      # seconds for matching elements to appear and then raise an error if no matching
+      # element is found
       #
       # @overload first([kind], locator, options)
       #   @param [:css, :xpath] kind                 The type of selector
       #   @param [String] locator                    The selector
       #   @param [Hash] options                      Additional options; see {#all}
       # @return [Capybara::Node::Element]            The found element or nil
-      # @raise  [Capybara::ElementNotFound]          If the element can't be found before time expires and `allow_nil` is not true
+      # @raise  [Capybara::ElementNotFound]          If the element can't be found before time expires
       #
-      def first(*args, allow_nil: false, **options, &optional_filter_block)
+      def first(*args, **options, &optional_filter_block)
         options = {minimum: 1}.merge(options)
         all(*args, **options, &optional_filter_block).first
-      rescue Capybara::ElementNotFound
-        raise unless allow_nil
-        nil
       end
 
       private

lib/capybara/selector.rb

@@ -159,7 +159,7 @@ Capybara.add_selector(:link) do
     when Regexp
       node[:href].match href
     else
-      node.first(:xpath, XPath.self[XPath.attr(:href).equals(href.to_s)], allow_nil: true, wait: false)
+      node.first(:xpath, XPath.self[XPath.attr(:href).equals(href.to_s)], minimum: 0)
     end
   end
 

lib/capybara/spec/session/first_spec.rb

@@ -123,7 +123,11 @@ Capybara::SpecHelper.spec '#first' do
 
     it "should not wait if minimum: 0" do
       @session.click_link('clickable')
-      expect(@session.first(:css, 'a#has-been-clicked', minimum: 0)).to be_nil
+      Capybara.using_wait_time(3) do
+        start_time = Time.now
+        expect(@session.first(:css, 'a#has-been-clicked', minimum: 0)).to be_nil
+        expect(Time.now-start_time).to be < 3
+      end
     end
 
     it "should wait for at least one match by default" do
@@ -133,11 +137,13 @@ Capybara::SpecHelper.spec '#first' do
       end
     end
 
-    it "should return nil after waiting if no match and allow_nil is true" do
+    it "should raise an error after waiting if no match" do
       @session.click_link('clickable')
-      start_time = Time.now
       Capybara.using_wait_time(3) do
-        expect(@session.first(:css, 'a#not-a-real-link', allow_nil: true)).to be_nil
+        start_time = Time.now
+        expect {
+          @session.first(:css, 'a#not-a-real-link')
+        }.to raise_error Capybara::ElementNotFound
         expect(Time.now-start_time).to be > 3
       end
     end