Add all method, make find return a single element

lib/capybara/dsl.rb

@@ -50,7 +50,7 @@ module Capybara
     :visit, :body, :click_link, :click_button, :fill_in, :choose, :has_xpath?, :has_css?,
     :check, :uncheck, :attach_file, :select, :has_content?, :within, :within_fieldset,
     :within_table, :save_and_open_page, :find, :find_field, :find_link, :find_button,
-    :field_labeled
+    :field_labeled, :all
   ]
   SESSION_METHODS.each do |method|
     class_eval <<-RUBY, __FILE__, __LINE__+1

lib/capybara/session.rb

@@ -93,7 +93,7 @@ module Capybara
     end
 
     def has_xpath?(path, options={})
-      results = find(path)
+      results = all(path)
       if options[:text]
         results = filter_by_text(results, options[:text])
       end
@@ -111,7 +111,7 @@ module Capybara
     def within(kind, scope=nil)
       kind, scope = Capybara.default_selector, kind unless scope
       scope = css_to_xpath(scope) if kind == :css
-      raise Capybara::ElementNotFound, "scope '#{scope}' not found on page" if find(scope).empty?
+      raise Capybara::ElementNotFound, "scope '#{scope}' not found on page" unless find(scope)
       scopes.push(scope)
       yield
       scopes.pop
@@ -134,11 +134,15 @@ module Capybara
       Capybara::SaveAndOpenPage.save_and_open_page(body)
     end
 
-    def find(locator)
+    def all(locator)
       locator = current_scope.to_s + locator
       driver.find(locator)
     end
     
+    def find(locator)
+      all(locator).first
+    end
+
     def find_field(locator, *kinds)
       kinds = FIELDS_PATHS.keys if kinds.empty?
       find_field_by_id(locator, *kinds) || find_field_by_label(locator, *kinds)
@@ -146,12 +150,12 @@ module Capybara
     alias_method :field_labeled, :find_field
 
     def find_link(locator)
-      find("//a[@id='#{locator}' or contains(.,'#{locator}') or @title='#{locator}']").first
+      find("//a[@id='#{locator}' or contains(.,'#{locator}') or @title='#{locator}']")
     end
 
     def find_button(locator)
-      button = find("//input[@type='submit' or @type='image'][@id='#{locator}' or @value='#{locator}']").first
+      button = find("//input[@type='submit' or @type='image'][@id='#{locator}' or @value='#{locator}']")
-      button || find("//button[@id='#{locator}' or @value='#{locator}' or contains(.,'#{locator}')]").first
+      button || find("//button[@id='#{locator}' or @value='#{locator}' or contains(.,'#{locator}')]")
     end
 
   private
@@ -181,12 +185,12 @@ module Capybara
 
     def find_field_by_id(locator, *kinds)
       field_locator = kinds.map { |kind| FIELDS_PATHS[kind].call(locator) }.join("|")
-      element = find(field_locator).first
+      element = find(field_locator)
       return element
     end
 
     def find_field_by_label(locator, *kinds)
-      label = find("//label[text()='#{locator}']").first || find("//label[contains(.,'#{locator}')]").first
+      label = find("//label[text()='#{locator}']") || find("//label[contains(.,'#{locator}')]")
       if label
         element = find_field_by_id(label[:for], *kinds)
         return element if element

spec/session_spec.rb

@@ -597,19 +597,19 @@ shared_examples_for "session" do
     end
   end
 
-  describe '#find' do
+  describe '#all' do
     before do
       @session.visit('/with_html')
     end
 
-    it "should find any element using the given locator" do
+    it "should find all elements using the given locator" do
-      @session.find('//p').should have(3).elements
+      @session.all('//p').should have(3).elements
-      @session.find('//h1').first.text.should == 'This is a test'
+      @session.all('//h1').first.text.should == 'This is a test'
-      @session.find("//input[@id='test_field']").first[:value].should == 'monkey'
+      @session.all("//input[@id='test_field']").first[:value].should == 'monkey'
     end
     
     it "should return an empty array when nothing was found" do
-      @session.find('//div').should be_empty
+      @session.all('//div').should be_empty
     end
     
     context "within a scope" do
@@ -619,7 +619,34 @@ shared_examples_for "session" do
 
       it "should find any element using the given locator" do
         @session.within(:xpath, "//div[@id='for_bar']") do
-          @session.find('//li').should have(2).elements
+          @session.all('//li').should have(2).elements
+        end        
+      end
+    end
+  end
+
+  describe '#find' do
+    before do
+      @session.visit('/with_html')
+    end
+
+    it "should find the first element using the given locator" do
+      @session.find('//h1').text.should == 'This is a test'
+      @session.find("//input[@id='test_field']")[:value].should == 'monkey'
+    end
+    
+    it "should return nil when nothing was found" do
+      @session.find('//div').should be_nil
+    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.find('//li').text.should =~ /With Simple HTML/
         end        
       end
     end