From 813d4d104b1b49efd2378bcfd1a661728ac1b710 Mon Sep 17 00:00:00 2001
From: Sean Doyle <sean.p.doyle24@gmail.com>
Date: Mon, 22 Feb 2021 19:00:47 -0500
Subject: [PATCH] Promote nest_selection to public API as within

Declare `#within` as part of the public interface. Implement it as a
thin wrapper around `Assertions::SelectorAssertions#nest_selection`.

```ruby
within css_select('.hello') do
  assert_dom 'p', 'Hello!'
end

within document_root_element.at('.hello') do
  assert_dom 'p', 'Hello!'
end
```
---
 README.md                                     | 10 ++++++
 .../testing/assertions/selector_assertions.rb | 19 +++++++++++
 test/selector_assertions_test.rb              | 33 +++++++++++++++++++
 3 files changed, 62 insertions(+)

diff --git a/README.md b/README.md
index 8aacea1..fd605d4 100644
--- a/README.md
+++ b/README.md
@@ -49,6 +49,16 @@ assert_dom_encoded '#out-of-your-element'
 
 # assert elements within an html email exists
 assert_dom_email '#you-got-mail'
+
+# explicitly modifies the document_root_element for the supplied Nodeset and block
+within css_select('.hello') do
+  assert_dom 'p', 'Hello!'
+end
+
+# explicitly modifies the document_root_element for the supplied node and block
+within document_root_element.at('.hello') do
+  assert_dom 'p', 'Hello!'
+end
 ```
 
 The documentation in [selector_assertions.rb](https://github.com/rails/rails-dom-testing/blob/master/lib/rails/dom/testing/assertions/selector_assertions.rb) goes into a lot more detail of how selector assertions can be used.
diff --git a/lib/rails/dom/testing/assertions/selector_assertions.rb b/lib/rails/dom/testing/assertions/selector_assertions.rb
index a6171e5..ada560f 100644
--- a/lib/rails/dom/testing/assertions/selector_assertions.rb
+++ b/lib/rails/dom/testing/assertions/selector_assertions.rb
@@ -263,6 +263,25 @@ def assert_dom_email(&block)
         end
         alias_method :assert_select_email, :assert_dom_email
 
+
+        # Changes the depth of the document_root_element for the operations
+        # nested within the provided block. Accepts a singular Nokogiri node or
+        # an Nokogiri NodeSet as its argument.
+        #
+        #  within document_root_element.at_css("main") do
+        #    assert_dom "h1", "Hello, World"
+        #  end
+        #
+        #  within css_select("article") do
+        #    items = assert_dom "ol>li"
+        #    items.each do
+        #       # Work with items here...
+        #    end
+        #  end
+        def within(selection, &block)
+          nest_selection nodeset(selection), &block
+        end
+
         private
           include CountDescribable
 
diff --git a/test/selector_assertions_test.rb b/test/selector_assertions_test.rb
index cd1b9f6..04012bd 100644
--- a/test/selector_assertions_test.rb
+++ b/test/selector_assertions_test.rb
@@ -312,6 +312,39 @@ def test_body_class_can_be_tested_with_html
     assert_select '.foo'
   end
 
+
+  #
+  # Test within
+  #
+
+  def test_assert_dom_nested_in_within_with_node
+    render_html %Q{<aside>other</aside><div id="1"><span>foo</span></div><div id="2"><span>bar</span></div>}
+    within document_root_element.at_css("div") do
+      assert_dom "div", text: "foo", count: 1
+      assert_dom "span", text: "foo", count: 1
+      assert_dom "div", text: "bar", count: 0
+      assert_dom "span", text: "bar", count: 0
+      assert_dom "aside", text: "other", count: 0
+    end
+    assert_dom "div", text: "foo", count: 1
+    assert_dom "div", text: "bar", count: 1
+    assert_dom "aside", text: "other", count: 1
+  end
+
+  def test_assert_dom_nested_in_within_with_nodeset
+    render_html %Q{<aside>other</aside><div id="1"><span>foo</span></div><div id="2"><span>bar</span></div>}
+    within css_select("div") do
+      assert_dom "div", text: "foo", count: 1
+      assert_dom "span", text: "foo", count: 1
+      assert_dom "div", text: "bar", count: 1
+      assert_dom "span", text: "bar", count: 1
+      assert_dom "aside", text: "other", count: 0
+    end
+    assert_dom "div", text: "foo", count: 1
+    assert_dom "div", text: "bar", count: 1
+    assert_dom "aside", text: "other", count: 1
+  end
+
   protected
     def render_html(html)
       fake_render(:html, html)