feat: Add Frame#frame_element method (#524)

Faciliates easier retrieval of the `iframe` element that embeds the
`window` (represented as a `Frame` object by Ferrum).

Author: myabc

lib/ferrum/frame/dom.rb

@@ -95,6 +95,22 @@ def body
         evaluate("document.documentElement?.outerHTML") || ""
       end
 
+      #
+      # Returns the element in which the window is embedded.
+      #
+      # @return [Node, nil]
+      #   The element in which the window is embedded.
+      #
+      # @example
+      #   browser.go_to("https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe")
+      #   frame = browser.frames.last
+      #   frame.frame_element # => [Node]
+      #   frame.parent.parent.parent.frame_element # => nil
+      #
+      def frame_element
+        evaluate("window.frameElement")
+      end
+
       #
       # Finds nodes by using a XPath selector.
       #

spec/frame_spec.rb

@@ -205,6 +205,43 @@
     expect(page.doctype).to be_nil
   end
 
+  context "#frame_element" do
+    it "gets the frame element" do
+      page.go_to("/frames")
+
+      frame_element = page.at_xpath("//iframe")
+      frame = frame_element.frame
+      expect(frame.frame_element).to eq(frame_element)
+      expect(frame.frame_element.frame_id).to eq frame.id
+      expect(frame.frame_element.attribute(:src)).to end_with("/slow")
+    end
+
+    it "returns nil if main frame" do
+      page.go_to("/frames")
+
+      parent_frame = page.at_xpath("//iframe").frame.parent
+      expect(parent_frame).to be_main
+      expect(parent_frame.frame_element).to be_nil
+    end
+
+    it "supports nested frames" do
+      page.go_to("/frames")
+      page.execute <<-JS
+        document.body.innerHTML += "<iframe src='/nested_frame_test' name='outer_frame' style='padding:200px'>"
+      JS
+      page.network.wait_for_idle
+
+      outer_frame_element = page.at_xpath("//iframe[@name='outer_frame']")
+      outer_frame = outer_frame_element.frame
+
+      inner_frame_element = outer_frame.at_xpath("//iframe")
+      inner_frame = inner_frame_element.frame
+
+      expect(outer_frame.frame_element).to eq(outer_frame_element)
+      expect(inner_frame.frame_element).to eq(inner_frame_element)
+    end
+  end
+
   context "#xpath" do
     it "returns given nodes" do
       page.go_to("/with_js")