From f2fe859f409984f7ff393281e8181c8bdffc4df7 Mon Sep 17 00:00:00 2001
From: Andrey Botalov <botalov.andrey@gmail.com>
Date: Tue, 8 Jan 2013 11:40:12 +0300
Subject: [PATCH] Document actual within_frame support

---
 lib/capybara/driver/base.rb                    |  2 +-
 lib/capybara/selenium/driver.rb                | 16 ++++++++++++++--
 lib/capybara/session.rb                        | 13 ++++++++-----
 lib/capybara/spec/session/within_frame_spec.rb |  6 ++++++
 4 files changed, 29 insertions(+), 8 deletions(-)

diff --git a/lib/capybara/driver/base.rb b/lib/capybara/driver/base.rb
index ff129eed..7424e17a 100644
--- a/lib/capybara/driver/base.rb
+++ b/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
 
diff --git a/lib/capybara/selenium/driver.rb b/lib/capybara/selenium/driver.rb
index 9c7a834c..840c2b16 100644
--- a/lib/capybara/selenium/driver.rb
+++ b/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
diff --git a/lib/capybara/session.rb b/lib/capybara/session.rb
index f7c89b9c..e48d6eef 100644
--- a/lib/capybara/session.rb
+++ b/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
diff --git a/lib/capybara/spec/session/within_frame_spec.rb b/lib/capybara/spec/session/within_frame_spec.rb
index 9f10a5cb..e3266d71 100644
--- a/lib/capybara/spec/session/within_frame_spec.rb
+++ b/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