add label selector

lib/capybara/selector.rb

@@ -354,6 +354,27 @@ Capybara.add_selector(:file_field) do
   end
 end
 
+Capybara.add_selector(:label) do
+  label "label"
+  xpath do |locator|
+    xpath = XPath.descendant(:label)
+    xpath = xpath[XPath.string.n.is(locator.to_s) | XPath.attr(:id).equals(locator.to_s)] unless locator.nil?
+    xpath
+  end
+
+  filter(:for) do |node, field_or_value|
+    if field_or_value.is_a? Capybara::Node::Element
+      if field_or_value[:id] && (field_or_value[:id] == node[:for])
+        true
+      else
+        field_or_value.find_xpath('./ancestor::label[1]').include? node
+      end
+    else
+      node[:for] == field_or_value.to_s
+    end
+  end
+end
+
 Capybara.add_selector(:table) do
   xpath do |locator|
     xpath = XPath.descendant(:table)

lib/capybara/spec/session/selectors_spec.rb

@@ -0,0 +1,35 @@
+Capybara::SpecHelper.spec Capybara::Selector do
+  before do
+    @session.visit('/form')
+  end
+
+  describe ":label selector" do
+    it "finds a label by text" do
+      expect(@session.find(:label, 'Customer Name').text).to eq 'Customer Name'
+    end
+
+    it "finds a label by for attribute string" do
+      expect(@session.find(:label, for: 'form_other_title')['for']).to eq 'form_other_title'
+    end
+
+    it "finds a label from nested input using :for filter" do
+      input = @session.find(:id, 'nested_label')
+      expect(@session.find(:label, for: input).text).to eq 'Nested Label'
+    end
+
+    it "finds the label for an non-nested element when using :for filter" do
+      select = @session.find(:id, 'form_other_title')
+      expect(@session.find(:label, for: select)['for']).to eq 'form_other_title'
+    end
+
+    context "with exact option" do
+      it "matches substrings" do
+        expect(@session.find(:label, 'Customer Na', exact: false).text).to eq 'Customer Name'
+      end
+
+      it "doesn't match substrings" do
+        expect { @session.find(:label, 'Customer Na', exact: true) }.to raise_error(Capybara::ElementNotFound)
+      end
+    end
+  end
+end

lib/capybara/spec/views/form.erb

@@ -333,6 +333,11 @@ New line after and before textarea tag
 
 <input type="text" name="form[outside_input]" value="outside_input" form="form1"/>
 
+<label>
+  Nested Label
+  <input type="text" name="nested_label" id="nested_label"/>
+</label>
+
 <form id="form1" action="/form" method="post">
   <input type="text" name="form[which_form]" value="form1" id="form_which_form"/>
   <input type="text" name="form[for_form2]" value="for_form2" form="form2"/>