Add support for node_wrappers implementing `to_capybara_node`

lib/capybara/minitest.rb

@@ -262,6 +262,8 @@ module Capybara
         case args.first
         when Capybara::Session, Capybara::Node::Base, Capybara::Node::Simple
           [args.shift, args]
+        when -> (arg) { arg.respond_to?(:to_capybara_node) }
+          [args.shift.to_capybara_node, args]
         else
           [page, args]
         end

lib/capybara/node/base.rb

@@ -111,6 +111,10 @@ module Capybara
         session.config
       end
 
+      def to_capybara_node
+        self
+      end
+
     protected
 
       def catch_error?(error, errors = nil)

lib/capybara/rspec/matchers.rb

@@ -11,7 +11,8 @@ module Capybara
       attr_reader :failure_message, :failure_message_when_negated
 
       def wrap(actual)
-        @context_el = if actual.respond_to?("has_selector?")
+        actual = actual.to_capybara_node if actual.respond_to?(:to_capybara_node)
+        @context_el = if actual.respond_to?(:has_selector?)
           actual
         else
           Capybara.string(actual.to_s)

lib/capybara/session.rb

@@ -335,7 +335,7 @@ module Capybara
     # @raise  [Capybara::ElementNotFound]      If the scope can't be found before time expires
     #
     def within(*args)
-      new_scope = args.first.is_a?(Capybara::Node::Base) ? args.first : find(*args)
+      new_scope = args.first.respond_to?(:to_capybara_node) ? args.first.to_capybara_node : find(*args)
       begin
         scopes.push(new_scope)
         yield

lib/capybara/spec/session/node_wrapper_spec.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+Capybara::SpecHelper.spec "#to_capybara_node", :focus_ do
+  before do
+    @session.visit('/with_html')
+  end
+
+  class NodeWrapper
+    def initialize(element); @element = element end
+    def to_capybara_node(); @element end
+  end
+
+  it "should support have_xxx expectations" do
+    para = NodeWrapper.new(@session.find(:css, '#first'))
+    expect(para).to have_link("ullamco")
+  end
+
+  it "should support within" do
+    para = NodeWrapper.new(@session.find(:css, '#first'))
+    expect(@session).to have_css('#second')
+    @session.within(para) do
+      expect(@session).to have_link('ullamco')
+      expect(@session).not_to have_css('#second')
+    end
+  end
+
+  it "should generate correct errors" do
+    para = NodeWrapper.new(@session.find(:css, '#first'))
+    expect {
+      expect(para).to have_text("Header Class Test One")
+    }.to raise_error /^expected to find text "Header Class Test One" in "Lore/
+    expect {
+      expect(para).to have_css('#second')
+    }.to raise_error /^expected to find visible css "#second" within #<Capybara::Node::Element/
+  end
+end