Merge pull request #928 from abotalov/master

Document actual within_frame support

lib/capybara/driver/base.rb

@@ -35,7 +35,7 @@ class Capybara::Driver::Base
     raise Capybara::NotSupportedByDriverError
   end
 
-  def within_frame(frame_id)
+  def within_frame(frame_handle)
     raise Capybara::NotSupportedByDriverError
   end
 

lib/capybara/selenium/driver.rb

@@ -74,9 +74,21 @@ class Capybara::Selenium::Driver < Capybara::Driver::Base
     end
   end
 
-  def within_frame(frame_id)
+  ##
+  #
+  # Webdriver supports frame name, id, index(zero-based) or {Capybara::Element} to find iframe
+  #
+  # @overload within_frame(index)
+  #   @param [Integer] index                 index of a frame
+  # @overload within_frame(name_or_id)
+  #   @param [String] name_or_id             name or id of a frame
+  # @overload within_frame(element)
+  #   @param [Capybara::Node::Base] a_node   frame element
+  #
+  def within_frame(frame_handle)
+    frame_handle = frame_handle.native if frame_handle.is_a?(Capybara::Node::Base)
     old_window = browser.window_handle
-    browser.switch_to.frame(frame_id)
+    browser.switch_to.frame(frame_handle)
     yield
   ensure
     browser.switch_to.window old_window

lib/capybara/session.rb

@@ -243,13 +243,16 @@ module Capybara
 
     ##
     #
-    # Execute the given block within the given iframe given the id of that iframe. Only works on
-    # some drivers (e.g. Selenium)
+    # Execute the given block within the given iframe using given frame name or index.
+    # May be supported by not all drivers. Drivers that support it, may provide additional options.
     #
-    # @param [String] frame_id   Id of the frame
+    # @overload within_frame(index)
+    #   @param [Integer] index         index of a frame
+    # @overload within_frame(name)
+    #   @param [String] name           name of a frame
     #
-    def within_frame(frame_id)
-      driver.within_frame(frame_id) do
+    def within_frame(frame_handle)
+      driver.within_frame(frame_handle) do
         yield
       end
     end

lib/capybara/spec/session/within_frame_spec.rb

@@ -28,4 +28,10 @@ Capybara::SpecHelper.spec '#within_frame', :requires => [:frames] do
   it "should return the result of executing the block" do
     @session.within_frame("frameOne") { "return value" }.should eql "return value"
   end
+  it "should find the div given Element" do
+    element = @session.find(:id, 'frameOne')
+    @session.within_frame element do
+      @session.find("//*[@id='divInFrameOne']").text.should eql 'This is the text of divInFrameOne'
+    end
+  end  
 end