Deprecate Element#parent in favor of Element#query_scope

History.md

@@ -12,6 +12,7 @@ Release date: Unreleased
 * Capybara::Selector::FilterSet allows for sharing filter definitions between selectors [Thomas Walpole]
 * Remove need to pass nil locator in most node actions when locator is not needed [Thomas Walpole]
 * New frames API for drivers - Issue #1365 [Thomas Walpole]
+* Deprecated Element#parent in favor of Element#query_scope to better indicate what it is [Thomas Walpole]
 
 #Version 2.7.1
 Release date: 2016-05-01

lib/capybara/node/base.rb

@@ -23,7 +23,7 @@ module Capybara
     #     session.has_css?('#foobar')               # from Capybara::Node::Matchers
     #
     class Base
-      attr_reader :session, :base, :parent
+      attr_reader :session, :base, :query_scope
 
       include Capybara::Node::Finders
       include Capybara::Node::Actions
@@ -108,6 +108,12 @@ module Capybara
         base.find_xpath(xpath)
       end
 
+      # @deprecated Use query_scope instead
+      def parent
+        warn "DEPRECATED: #parent is deprecated in favor of #query_scope - Note: #parent was not the elements parent in the document so it's most likely not what you wanted anyway"
+        query_scope
+      end
+
     protected
 
       def catch_error?(error, errors = nil)

lib/capybara/node/element.rb

@@ -23,9 +23,9 @@ module Capybara
     #
     class Element < Base
 
-      def initialize(session, base, parent, query)
+      def initialize(session, base, query_scope, query)
         super(session, base)
-        @parent = parent
+        @query_scope = query_scope
         @query = query
       end
 
@@ -340,7 +340,7 @@ module Capybara
       def reload
         if @allow_reload
           begin
-            reloaded = parent.reload.first(@query.name, @query.locator, @query.options)
+            reloaded = query_scope.reload.first(@query.name, @query.locator, @query.options)
             @base = reloaded.base if reloaded
           rescue => e
             raise e unless catch_error?(e)

lib/capybara/node/matchers.rb

@@ -179,7 +179,7 @@ module Capybara
       def assert_matches_selector(*args)
         query = Capybara::Queries::MatchQuery.new(*args)
         synchronize(query.wait) do
-          result = query.resolve_for(self.parent)
+          result = query.resolve_for(self.query_scope)
           unless result.include? self
             raise Capybara::ExpectationNotMet, "Item does not match the provided selector"
           end
@@ -190,7 +190,7 @@ module Capybara
       def assert_not_matches_selector(*args)
         query = Capybara::Queries::MatchQuery.new(*args)
         synchronize(query.wait) do
-          result = query.resolve_for(self.parent)
+          result = query.resolve_for(self.query_scope)
           if result.include? self
             raise Capybara::ExpectationNotMet, 'Item matched the provided selector'
           end

lib/capybara/spec/session/node_spec.rb

@@ -19,11 +19,19 @@ Capybara::SpecHelper.spec "node" do
     expect(@session.find(:css, '#second')).to have_no_css('h1')
   end
 
+  describe "#query_scope" do
+    it "should have a reference to the element the query was evaluated on if there is one" do
+      @node = @session.find(:css, '#first')
+      expect(@node.query_scope).to eq(@node.session.document)
+      expect(@node.find(:css, '#foo').query_scope).to eq(@node)
+    end
+  end
+
   describe "#parent" do
-    it "should have a reference to its parent if there is one" do
+    it "should be deprecated" do
+      expect_any_instance_of(Kernel).to receive(:warn).with(/^DEPRECATED:/)
       @node = @session.find(:css, '#first')
       expect(@node.parent).to eq(@node.session.document)
-      expect(@node.find(:css, '#foo').parent).to eq(@node)
     end
   end
 
@@ -408,7 +416,7 @@ Capybara::SpecHelper.spec "node" do
       end
     end
   end
-  
+
   context "when #synchronize raises server errors" do
     it "sets an explanatory exception as the cause of server exceptions", :requires => [:server, :js] do
       skip "This version of ruby doesn't support exception causes" unless Exception.instance_methods.include? :cause
@@ -416,7 +424,7 @@ Capybara::SpecHelper.spec "node" do
       expect do
         @session.find(:css, 'span')
       end.to raise_error(TestApp::TestAppError) do |e|
-        expect(e.cause).to be_a Capybara::CapybaraError 
+        expect(e.cause).to be_a Capybara::CapybaraError
         expect(e.cause.message).to match /Your application server raised an error/
       end
     end