Define the return type for actions where not otherwise defined as the…

… element being interacted with

lib/capybara/node/actions.rb

@@ -18,6 +18,8 @@ module Actions
       #
       #   @param [String] locator      Text, id or value of link or button
       #
+      # @return [Capybara::Node::Element]  The element clicked
+      #
       def click_link_or_button(locator=nil, options={})
         locator, options = nil, locator if locator.is_a? Hash
         find(:link_or_button, locator, options).click
@@ -35,6 +37,7 @@ def click_link_or_button(locator=nil, options={})
       #   @param [String] locator         text, id, title or nested image's alt attribute
       #   @param options                  See {Capybara::Node::Finders#find_link}
       #
+      # @return [Capybara::Node::Element]  The element clicked
       def click_link(locator=nil, options={})
         locator, options = nil, locator if locator.is_a? Hash
         find(:link, locator, options).click
@@ -52,6 +55,7 @@ def click_link(locator=nil, options={})
       # @overload click_button([locator], options)
       #   @param [String] locator      Which button to find
       #   @param options     See {Capybara::Node::Finders#find_button}
+      # @return [Capybara::Node::Element]  The element clicked
       def click_button(locator=nil, options={})
         locator, options = nil, locator if locator.is_a? Hash
         find(:button, locator, options).click
@@ -77,6 +81,7 @@ def click_button(locator=nil, options={})
       #   @option options [String] :placeholder    Match fields that match the placeholder attribute
       #   @option options [String, Array<String>] :class    Match links that match the class(es) provided
       #
+      # @return [Capybara::Node::Element]  The element filled_in
       def fill_in(locator, options={})
         locator, options = nil, locator if locator.is_a? Hash
         raise "Must pass a hash containing 'with'" if not options.is_a?(Hash) or not options.has_key?(:with)
@@ -104,6 +109,8 @@ def fill_in(locator, options={})
       #   @option options [String, Array<String>] :class    Match links that match the class(es) provided
       #   @macro waiting_behavior
       #   @macro label_click
+      #
+      # @return [Capybara::Node::Element]  The element chosen or the label clicked
       def choose(locator, options={})
         locator, options = nil, locator if locator.is_a? Hash
         allow_label_click = options.delete(:allow_label_click) { Capybara.automatic_label_click }
@@ -141,6 +148,7 @@ def choose(locator, options={})
       #   @macro label_click
       #   @macro waiting_behavior
       #
+      # @return [Capybara::Node::Element]  The element checked or the label clicked
       def check(locator, options={})
         locator, options = nil, locator if locator.is_a? Hash
         allow_label_click = options.delete(:allow_label_click) { Capybara.automatic_label_click }
@@ -178,6 +186,7 @@ def check(locator, options={})
       #   @macro label_click
       #   @macro waiting_behavior
       #
+      # @return [Capybara::Node::Element]  The element unchecked or the label clicked
       def uncheck(locator, options={})
         locator, options = nil, locator if locator.is_a? Hash
         allow_label_click = options.delete(:allow_label_click) { Capybara.automatic_label_click }
@@ -213,6 +222,7 @@ def uncheck(locator, options={})
       # @param [String] value                   Which option to select
       # @option options [String] :from  The id, name or label of the select box
       #
+      # @return [Capybara::Node::Element]  The option element selected
       def select(value, options={})
         if options.has_key?(:from)
           from = options.delete(:from)
@@ -235,6 +245,7 @@ def select(value, options={})
       # @param [String] value                   Which option to unselect
       # @param [Hash{:from => String}] options  The id, name or label of the select box
       #
+      # @return [Capybara::Node::Element]  The option element unselected
       def unselect(value, options={})
         if options.has_key?(:from)
           from = options.delete(:from)
@@ -263,6 +274,7 @@ def unselect(value, options={})
       # @option options [String] name           Match fields that match the name attribute
       # @option options [String, Array<String>] :class    Match links that match the class(es) provided
       #
+      # @return [Capybara::Node::Element]  The file field element
       def attach_file(locator, path, options={})
         locator, path, options = nil, locator, path if path.is_a? Hash
         Array(path).each do |p|

lib/capybara/node/document.rb

@@ -24,6 +24,10 @@ def text(type=nil)
         find(:xpath, '/html').text(type)
       end
 
+      ##
+      #
+      # @return [String]    The title of the document
+      #
       def title
         session.driver.title
       end

lib/capybara/node/element.rb

@@ -92,6 +92,7 @@ def value
       # @param [String] value    The new value
       # @param [Hash{}] options  Driver specific options for how to set the value
       #
+      # @return [Capybara::Node::Element]  The element
       def set(value, options={})
         options ||= {}
 
@@ -108,47 +109,58 @@ def set(value, options={})
             base.set(value)
           end
         end
+        return self
       end
 
       ##
       #
       # Select this node if is an option element inside a select tag
       #
+      # @return [Capybara::Node::Element]  The element
       def select_option
         warn "Attempt to select disabled option: #{value || text}" if disabled?
         synchronize { base.select_option }
+        return self
       end
 
       ##
       #
       # Unselect this node if is an option element inside a multiple select tag
       #
+      # @return [Capybara::Node::Element]  The element
       def unselect_option
         synchronize { base.unselect_option }
+        return self
       end
 
       ##
       #
       # Click the Element
       #
+      # @return [Capybara::Node::Element]  The element
       def click
         synchronize { base.click }
+        return self
       end
 
       ##
       #
       # Right Click the Element
       #
+      # @return [Capybara::Node::Element]  The element
       def right_click
         synchronize { base.right_click }
+        return self
       end
 
       ##
       #
       # Double Click the Element
       #
+      # @return [Capybara::Node::Element]  The element
       def double_click
         synchronize { base.double_click }
+        return self
       end
 
       ##
@@ -221,16 +233,20 @@ def double_click
       # :meta
       # :command      - alias of :meta
       #
+      # @return [Capybara::Node::Element]  The element
       def send_keys(*args)
         synchronize { base.send_keys(*args) }
+        return self
       end
 
       ##
       #
       # Hover on the Element
       #
+      # @return [Capybara::Node::Element]  The element
       def hover
         synchronize { base.hover }
+        return self
       end
 
       ##
@@ -319,8 +335,10 @@ def path
       #
       # @param [String] event       The name of the event to trigger
       #
+      # @return [Capybara::Node::Element]  The element
       def trigger(event)
         synchronize { base.trigger(event) }
+        return self
       end
 
       ##
@@ -333,8 +351,10 @@ def trigger(event)
       #
       # @param [Capybara::Node::Element] node     The element to drag to
       #
+      # @return [Capybara::Node::Element]  The element
       def drag_to(node)
         synchronize { base.drag_to(node.base) }
+        return self
       end
 
       def reload

lib/capybara/node/simple.rb

@@ -148,6 +148,9 @@ def allow_reload!
         # no op
       end
 
+      ##
+      #
+      # @return [String]     The title of the document
       def title
         if native.respond_to? :title
           native.title

lib/capybara/spec/session/choose_spec.rb

@@ -86,4 +86,9 @@
       end
     end
   end
+
+  it "should return the chosen radio button" do
+    el = @session.find(:radio_button, 'gender_male')
+    expect(@session.choose("gender_male")).to eq el
+  end
 end

lib/capybara/spec/session/click_link_or_button_spec.rb

@@ -108,6 +108,11 @@
         @session.click_link_or_button('Disabled button', disabled: false)
       end.to raise_error(Capybara::ElementNotFound)
     end
+  end
 
+  it "should return the element clicked" do
+    @session.visit('/with_html')
+    link = @session.find(:link, 'labore')
+    expect(@session.click_link_or_button('labore')).to eq link
   end
 end

lib/capybara/spec/session/click_link_spec.rb

@@ -186,4 +186,9 @@
       expect(@session).to have_content('Another World')
     end
   end
+
+  it "should return element clicked", twtw: true do
+    el = @session.find(:link, 'Normal Anchor')
+    expect(@session.click_link('Normal Anchor')).to eq el
+  end
 end

lib/capybara/spec/session/fill_in_spec.rb

@@ -181,4 +181,9 @@
       end.to raise_error(Capybara::ElementNotFound)
     end
   end
+
+  it "should return the element filled in" do
+    el = @session.find(:fillable_field, 'form_first_name')
+    expect(@session.fill_in('form_first_name', with: 'Harry')).to eq el
+  end
 end