Specs for #first

lib/capybara/session.rb

@@ -27,7 +27,7 @@ module Capybara
   #
   class Session
     DSL_METHODS = [
-      :all, :attach_file, :body, :check, :choose, :click_link_or_button, :click_button, :click_link, :current_url, :drag, :evaluate_script,
+      :all, :first, :attach_file, :body, :check, :choose, :click_link_or_button, :click_button, :click_link, :current_url, :drag, :evaluate_script,
       :field_labeled, :fill_in, :find, :find_button, :find_by_id, :find_field, :find_link, :has_content?, :has_css?,
       :has_no_content?, :has_no_css?, :has_no_xpath?, :has_xpath?, :locate, :save_and_open_page, :select, :source, :uncheck,
       :visit, :wait_until, :within, :within_fieldset, :within_table, :within_frame, :within_window, :has_link?, :has_no_link?, :has_button?,

lib/capybara/spec/session.rb

@@ -42,6 +42,7 @@ shared_examples_for "session" do
   end
 
   it_should_behave_like "all"
+  it_should_behave_like "first"
   it_should_behave_like "attach_file"
   it_should_behave_like "check"
   it_should_behave_like "choose"

lib/capybara/spec/session/first_spec.rb

@@ -0,0 +1,72 @@
+shared_examples_for "first" do
+  describe '#first' do
+    before do
+      @session.visit('/with_html')
+    end
+
+    it "should find the first element using the given locator" do
+      @session.first('//h1').text.should == 'This is a test'
+      @session.first("//input[@id='test_field']")[:value].should == 'monkey'
+    end
+
+    it "should return nil when nothing was found" do
+      @session.first('//div[@id="nosuchthing"]').should be_nil
+    end
+
+    it "should accept an XPath instance" do
+      @session.visit('/form')
+      @xpath = XPath::HTML.fillable_field('Name')
+      @session.first(@xpath).value.should == 'John Smith'
+    end
+
+    context "with css selectors" do
+      it "should find the first element using the given selector" do
+        @session.first(:css, 'h1').text.should == 'This is a test'
+        @session.first(:css, "input[id='test_field']")[:value].should == 'monkey'
+      end
+    end
+
+    context "with xpath selectors" do
+      it "should find the first element using the given locator" do
+        @session.first(:xpath, '//h1').text.should == 'This is a test'
+        @session.first(:xpath, "//input[@id='test_field']")[:value].should == 'monkey'
+      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
+        @session.first('h1').text.should == 'This is a test'
+        @session.first("input[id='test_field']")[:value].should == 'monkey'
+      end
+      after { Capybara.default_selector = :xpath }
+    end
+
+    context "with visible filter" do
+      after { Capybara.ignore_hidden_elements = false }
+      it "should only find visible nodes" do
+        @session.first(:css, "a.visibility").should_not be_visible
+        @session.first(:css, "a.visibility", :visible => true).should be_visible
+        Capybara.ignore_hidden_elements = true
+        @session.first(:css, "a.visibility").should be_visible
+      end
+
+      it "should only find invisible nodes" do
+        Capybara.ignore_hidden_elements = true
+        @session.first(:css, "a.visibility", :visible => false).should_not be_visible
+      end
+    end
+
+    context "within a scope" do
+      before do
+        @session.visit('/with_scope')
+      end
+
+      it "should find the first element using the given locator" do
+        @session.within(:xpath, "//div[@id='for_bar']") do
+          @session.first('.//form').should_not be_nil
+        end
+      end
+    end
+  end
+end

lib/capybara/spec/views/with_html.erb

@@ -55,6 +55,14 @@
   <a href="/with_simple_html" title="awesome title" class="simple">hidden link</a>
 </div>
 
+<div style="display: none;">
+  <a class="visibility">hidden link</a>
+</div>
+
+<div>
+  <a class="visibility">visible link</a>
+</div>
+
 <ul>
   <li id="john_monkey">Monkey John</li>
   <li id="paul_monkey">Monkey Paul</li>