Document using #within
MODIFY
README.md
README.md
@@ -921,14 +921,13 @@ end
##### Accessing section elements using a block
-A Section can be scoped so it is only accessible inside a block. This is
+You can execute a block within the context of a Section. This is
similar to Capybara's `within` method and allows for shorter test code
-particularly with nested sections. Some of this test code can be
-made a little prettier by simply passing a block in.
+particularly with nested sections. Test code that might have to repeat the block name can be shortened up this way.
```ruby
Then(/^the home page menu contains a link to the various search functions$/) do
- @home.menu do |menu|
+ @home.menu.within do |menu|
expect(menu).to have_search
expect(menu.search['href']).to include('google.com')
expect(menu).to have_images
@@ -937,6 +936,16 @@ Then(/^the home page menu contains a link to the various search functions$/) do
end
```
+Note that on individual sections it's possible to pass a block directly to the section without using `within`. Because the block is executed only during Section initialization this won't work when accessing a single Section from an array of Sections. For that reason we recommend using `within` which works in either case.
+
+```ruby
+Then(/^the home page menu contains a link to the various search functions$/) do
+ @home.menu do |menu| # possible, but prefer: `@home.menu.within`
+ expect(menu).to have_search
+ end
+end
+```
+
#### Getting a section's parent
It is possible to ask a section for its parent (page, or section if this
@@ -1191,6 +1200,26 @@ element. So if the css selector finds 3 `li` elements, calling
`search_results` will return an array containing 3 instances of
`SearchResults`, each with one of the `li` elements as it's root element.
+##### Accessing Within a Collection of Sections
+
+When using an iterator such as `each` to pass a block through to a collection of sections it is possible to skip using `within`. However some caution is warranted when accessing the Sections directly from an array, as the block can only be executed when the section is being initialized. The following does not work:
+
+```rb
+ @home.search_results.first do |result|
+ # This block is silently ignored.
+ expect(result).to have_title
+ end
+```
+Instead use `within` to access the inner-context of the Section.
+
+```rb
+ @home.search_results.first.within do |result|
+ # This block is run within the context of the Section.
+ expect(result).to have_title
+ end
+```
+
+
#### Anonymous Section Collections
You can define collections of anonymous sections the same way you would

Document using #within