site_prism 4.0.beta → 4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ebb39462fdc078aff996d358cfadeb4feddbb443cb0655340efa51f4d4af80d
-  data.tar.gz: 2913da09df5462bcf924d3598d8d9f6f4e996c65951acb31694d0dea67990b4d
+  metadata.gz: a42324a6a59bf20f2c35c519c130d94e314c5170b47ddf1c9f1d3faae98238d7
+  data.tar.gz: d17845d3b0131de25848bf85b86a7c696ef1160bdc4cf759bd43958d56742d00
 SHA512:
-  metadata.gz: '080072c82a3df37666dd079600cd75db84be14b2f73e2f06227bdf48e45f8ff2783a64d122c05e12c8eda54462491a6c0f3d3e935b48fad54278dcf4eab0d841'
-  data.tar.gz: 79157445566537187b9578113b3a3100aa13dbf4cbb615f9e8563dc6d1264177eaab62d9caa2fa79f152118aa1c919a5607477492fa33b1d2b23c6f2bf162b49
+  metadata.gz: 7e09efb630b6f8270c7c8bb23c9db92bcccaa09e54c0a7e9ef1a6f2a645f47d821bf912141588ccec1bb3c6aea73f181ff6c8e5b771116f84936d10f95e714ab
+  data.tar.gz: d1dee7191ea9c01a8cc03e0726ae55ec1de91fe1d9bbb0f6db73e0c6b8af261d598b59d4d1be54e0589e481613b40e574f0d406ac1242d6a2e4cd46a9480c08c

data/README.md

@@ -7,7 +7,7 @@ _A Page Object Model DSL for Capybara_
 SitePrism gives you a simple, clean and semantic DSL for describing your site using the Page Object Model pattern,
 for use with Capybara in automated acceptance testing.
 
-Find the pretty documentation here: https://rdoc.info/gems/site_prism/frames
+Find the pretty documentation here: https://www.rubydoc.info/github/site-prism/site_prism
 
 Make sure to add your project/company to https://github.com/site-prism/site_prism/wiki/Who-is-using-SitePrism
 
@@ -81,34 +81,34 @@ end
 
 # now for some tests
 
-When(/^I navigate to the google home page$/) do
+When('I navigate to the google home page') do
   @home = Home.new
   @home.load
 end
 
-Then(/^the home page should contain the menu and the search form$/) do
-  @home.wait_until_menu_visible # menu loads after a second or 2, give it time to arrive
+Then('the home page should contain the menu and the search form') do
+  @home.wait_until_menu_visible(wait: 5)
   expect(@home).to have_menu
   expect(@home).to have_search_field
   expect(@home).to have_search_button
 end
 
-When(/^I search for Sausages$/) do
-  @home.search_field.set 'Sausages'
+When('I search for Sausages') do
+  @home.search_field.send_keys('Sausages')
   @home.search_button.click
 end
 
-Then(/^the search results page is displayed$/) do
+Then('the search results page is displayed') do
   @results_page = SearchResults.new
   expect(@results_page).to be_displayed
 end
 
-Then(/^the search results page contains 10 individual search results$/) do
-  @results_page.wait_until_search_results_visible
+Then('the search results page contains 10 individual search results') do
+  @results_page.wait_until_search_results_visible(wait: 5)
   expect(@results_page).to have_search_results(count: 10)
 end
 
-Then(/^the search results contain a link to the wikipedia sausages page$/) do
+Then('the search results contain a link to the wikipedia sausages page') do
   expect(@results_page.search_result_links).to include('http://en.wikipedia.org/wiki/Sausage')
 end
 ```
@@ -134,7 +134,6 @@ require 'capybara'
 require 'capybara/cucumber'
 require 'selenium-webdriver'
 require 'site_prism'
-require 'site_prism/all_there' # Optional but needed to perform more complex matching
 ```
 
 The driver creation is identical to how you would normally create a Capybara driver,
@@ -143,7 +142,7 @@ a sample Selenium one could look something like this...
 ```ruby
 Capybara.register_driver :site_prism do |app|
   browser = ENV.fetch('browser', 'firefox').to_sym
-  Capybara::Selenium::Driver.new(app, browser: browser, desired_capabilities: capabilities)
+  Capybara::Selenium::Driver.new(app, browser: browser, options: options)
 end
 
 # Then tell Capybara to use the Driver you've just defined as its default driver
@@ -161,7 +160,6 @@ require 'capybara'
 require 'capybara/rspec'
 require 'selenium-webdriver'
 require 'site_prism'
-require 'site_prism/all_there' # Optional but needed to perform more complex matching
 ```
 
 And again, as above, a sample driver is no different to a normal driver instantiation in Capybara.
@@ -175,7 +173,7 @@ to then use instances of those classes in your tests.
 
 If a class represents a page then each element of the page is
 represented by a method that, when called, returns a reference to that
-element that can then be acted upon (clicked, set text value), or
+element that can then be acted upon (clicked, type in some text), or
 queried (is it enabled? / visible?).
 
 SitePrism is based around this concept, but goes further as you'll see
@@ -218,7 +216,7 @@ class Home < SitePrism::Page
 end
 ```
 
-Note that setting a URL is optional - you only need to set a url if you want to be able to
+Note that setting a URL is **optional** - you only need to set a url if you want to be able to
 navigate directly to that page. It makes sense to set the URL for a page model of a
 home page or a login page, but probably not a search results page.
 
@@ -245,8 +243,7 @@ See https://github.com/sporkmonger/addressable for more details on parameterized
 
 ### Navigating to the Page
 
-Once the URL has been set (using `set_url`), you can navigate directly
-to the page using `#load`:
+Once the URL has been set (using `set_url`), you can navigate directly to the page using `#load`:
 
 ```ruby
 @home_page = Home.new
@@ -282,8 +279,6 @@ end
 This will tell whichever capybara driver you have configured to
 navigate to the URL set against that page's class.
 
-See https://github.com/sporkmonger/addressable for more details on parameterized URLs.
-
 ### Verifying that a particular page is displayed
 
 Automated tests often need to verify that a particular page is
@@ -319,8 +314,7 @@ wait time in seconds as the first argument like this:
 #### Specifying parameter values for templated URLs
 
 Sometimes you want to verify not just that the current URL matches the
-template, but that you're looking at a specific page matching that
-template.
+template, but that you're looking at a specific page matching that template.
 
 Given the previous example, if you wanted to ensure that the browser had loaded
 account number 22, you could assert the following:
@@ -347,7 +341,7 @@ when comparing your page's URL template to the current_url:
 @account_page.load(id: 22, query: { token: 'ca2786616a4285bc', color: 'irrelevant' })
 
 expect(@account_page).to be_displayed(id: 22)
-expect(@account_page.url_matches['query']['token']).to eq('ca2786616a4285bc')
+expect(@account_page.url_matches.dig('query', 'token')).to eq('ca2786616a4285bc')
 ```
 
 #### Falling back to basic regexp matchers
@@ -367,7 +361,7 @@ end
 SitePrism's `#displayed?` predicate method allows for semantic code in your tests:
 
 ```ruby
-Then(/^the account page is displayed$/) do
+Then('the account page is displayed') do
   expect(@account_page).to be_displayed
   expect(@some_other_page).not_to be_displayed
 end
@@ -375,8 +369,7 @@ end
 
 ### Getting the Current Page's URL
 
-SitePrism allows you to get the current page's URL. Here's how it's
-done:
+SitePrism allows you to get the current page's URL. Here's how it's done:
 
 ```ruby
 class Account < SitePrism::Page
@@ -462,8 +455,8 @@ end
 @home.load
 
 @home.search_field #=> will return the capybara element found using the selector
-@home.search_field.set 'the search string' #=> `search_field` returns a capybara element, so use the capybara API to deal with it
-@home.search_field.text #=> standard method on a capybara element; returns a string
+@home.search_field.send_keys('the search string')
+@home.search_field['value'] #=> standard method on a capybara element (field); returns the string value
 ```
 
 #### Testing for the existence of the element
@@ -492,16 +485,16 @@ end
 ...which makes for nice test code:
 
 ```ruby
-Then(/^the search field exists$/) do
+Then('the search field exists') do
   expect(@home).to have_search_field
 end
 ```
 
 #### Testing that an element does not exist
 
-To test that an element does not exist on the page, it is not possible to just call
+To test that an element does not exist on the page, you should not call
 `#not_to have_search_field`. SitePrism supplies the `#has_no_<element>?` method
-that should be used to test for non-existence.
+that should be used instead to test for non-existence.
 This method delegates to [Capybara::Node::Matchers#has_no_selector?](https://www.rubydoc.info/github/teamcapybara/capybara/master/Capybara/Node/Matchers#has_no_selector%3F-instance_method)
 Using the above example:
 
@@ -514,7 +507,7 @@ Using the above example:
 ...which makes for nice test code:
 
 ```ruby
-Then(/^the search field exists$/)do
+Then('the search field exists')do
   expect(@home).to have_no_search_field #NB: NOT => expect(@home).not_to have_search_field
 end
 ```
@@ -529,7 +522,7 @@ to become visible. You can customise the wait time by supplying a number
 of seconds to wait in-line or configuring the default wait time.
 
 ```ruby
-@home.wait_until_search_field_visible
+@home.wait_until_search_field_visible # using the default wait time set
 # or...
 @home.wait_until_search_field_visible(wait: 10)
 ```
@@ -544,7 +537,7 @@ wait time for the element to become invisible. You can as with the visibility
 waiter, customise the wait time in the same way.
 
 ```ruby
-@home.wait_until_search_field_invisible
+@home.wait_until_search_field_invisible # using the default wait time set
 # or...
 @home.wait_until_search_field_invisible(wait: 10)
 ```
@@ -663,7 +656,7 @@ Then the following method is available:
 This in turn allows the following nice test code
 
 ```ruby
-Then(/^there should be some names listed on the page$/) do
+Then('there should be some names listed on the page') do
   expect(@friends_page).to have_names #=> This only passes if there is at least one `name`
 end
 ```
@@ -704,16 +697,16 @@ are present in the browser and `false` if they're not all there.
 
 # and...
 
-Then(/^the friends page contains all the expected elements$/) do
+Then('the friends page contains all the expected elements') do
   expect(@friends_page).to be_all_there
 end
 ```
 
 You may wish to have elements declared in a page object class that are not
 always guaranteed to be present (success or error messages, etc.).
-If you'd still like to test such a page with `all_there?` you can declare
-`expected_elements` on your page object class that narrows the elements
-included in `all_there?` check to those that definitely should be present.
+If you'd still like to test such a page with `#all_there?` you can declare
+`.expected_elements` on your page class that narrows the elements
+included in `#all_there?` check to those that definitely should be present.
 
 ```ruby
 class TestPage < SitePrism::Page
@@ -748,9 +741,9 @@ for this at the moment are `:none` and `:one`
 Passing `:none` (default), will not change the functionality. However passing in `:one` will cause
 `site_prism` to recurse through all `section` / `sections` items defined in your present scope.
 
-Work alongside developing this functionality further is being continued in the
+Work to develop this is contained in the
 [site_prism-all_there](http://www.github.com/site-prism/site_prism-all_there) repo. So head on over
-there if you're interested in how this feature will work going forwards
+there if you're interested in this area more
 
 ### Getting the list of missing elements
 
@@ -830,15 +823,14 @@ class People < SitePrism::Section
 end
 
 class Home < SitePrism::Page
-  # section people_with_block will have `headline` and
-  # `footer` elements in it
+  # section people_with_block will have `headline` and `footer` elements in it
   section :people_with_block, People do
     element :headline, 'h2'
   end
 end
 ```
 
-The 3rd argument (Locators), can be omitted if you are re-using the same
+The 3rd argument (Locator), can be omitted if you are re-using the same
 locator for all references to the section Class. In order to do this,
 simply tell SitePrism that you want to use default search arguments.
 
@@ -874,7 +866,7 @@ end
 # the page and section in action
 
 @home = Home.new
-@home.menu #=> <MenuSection...>
+@home.menu #=> <Menu...>
 ```
 
 When the `menu` method is called against `@home`, an instance of `Menu`
@@ -949,7 +941,7 @@ end
 This then leads to some pretty test code ...
 
 ```ruby
-Then(/^the home page menu contains a link to the various search functions$/) do
+Then('the home page menu contains a link to the various search functions') do
   expect(@home.menu).to have_search
   expect(@home.menu.search['href']).to include('google.com')
   expect(@home.menu).to have_images
@@ -964,7 +956,7 @@ similar to Capybara's `within` method and allows for shorter test code
 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
+Then('the home page menu contains a link to the various search functions') do
   @home.menu.within do |menu|
     expect(menu).to have_search
     expect(menu.search['href']).to include('google.com')
@@ -974,10 +966,12 @@ Then(/^the home page menu contains a link to the various search functions$/) do
 end
 ```
 
-Note that on an individual section 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.
+Note that on an individual section 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
+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
@@ -1129,26 +1123,22 @@ class Home < SitePrism::Page
   section :login_and_registration, LoginRegistrationForm, 'div.login-registration'
 end
 
-# how to login (fatuous, but demonstrates the point):
+# Then you could log in like so ...
 
-Then(/^I sign in$/) do
+Then('I sign in') do
   @home = Home.new
   @home.load
-  expect(@home).to have_login_and_registration
-  expect(@home.login_and_registration).to have_username
-  @home.login_and_registration.login.username.set 'bob'
-  @home.login_and_registration.login.password.set 'p4ssw0rd'
+  @home.login_and_registration.login.username.send_keys('bob')
+  @home.login_and_registration.login.password.send_keys('p4ssw0rd')
   @home.login_and_registration.login.sign_in.click
 end
 
-# how to sign up:
+# And you could sign up like so ...
 
-When(/^I enter my name into the home page's registration form$/) do
+When('I sign up') do
   @home = Home.new
   @home.load
-  expect(@home.login_and_registration).to have_first_name
-  expect(@home.login_and_registration).to have_last_name
-  @home.login_and_registration.first_name.set 'Bob'
+  @home.login_and_registration.first_name.send_keys('Bob')
   # ...
 end
 ```
@@ -1188,7 +1178,7 @@ can be called in a page or a section.
 
 The only difference between `section` and `sections` is that whereas the
 first returns an instance of the supplied section class, the second
-returns an array containing as many instances of the section class as
+returns a `Capybara::Result` containing as many instances of the section class as
 there are capybara elements found by the supplied css selector. This is
 better explained in the following example ...
 
@@ -1220,7 +1210,7 @@ end
 This allows for pretty tests ...
 
 ```ruby
-Then(/^there are lots of search_results$/) do
+Then('there are lots of search_results') do
   expect(@results_page.search_results.size).to eq(10)
 
   @home.search_results.each do |result|
@@ -1235,12 +1225,14 @@ The css selector that is passed as the 3rd argument to the
 elements. Each capybara element found using the css selector is used to
 create a new instance of `SearchResults` and becomes its root
 element. So if the css selector finds 3 `li` elements, calling
-`search_results` will return an array containing 3 instances of
+`search_results` will return a `Capybara::Result` 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:
+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|
@@ -1304,7 +1296,7 @@ Here's how to test for the existence of the section:
 This allows for some pretty tests ...
 
 ```ruby
-Then(/^there are search results on the page$/) do
+Then('there are search results on the page') do
   expect(@home).to have_search_results
 end
 ```
@@ -1443,8 +1435,8 @@ The error message is ignored unless the boolean value is evaluated as falsey.
 
 ```ruby
 class SomePage < SitePrism::Page
-  element :foo_element, '.foo'
-  load_validation { [has_foo_element?, 'did not have foo element!'] }
+  element :foo, '.foo'
+  load_validation { [has_foo?, 'did not have foo element!'] }
 end
 ```
 
@@ -1490,8 +1482,8 @@ class FooPage < BasePage
   section :form, '#form'
   element :some_other_element, '.myelement'
 
-  load_validation { [has_form?, 'form did not appear'] }
-  load_validation { [has_some_other_element?, 'some other element did not appear'] }
+  load_validation { [has_form?(wait: 5), 'form did not appear'] }
+  load_validation { [has_some_other_element?(wait: 5), 'some other element did not appear'] }
 end
 ```
 
@@ -1502,12 +1494,6 @@ the validations will be performed in the following order:
 2. The `FooPage` validation will wait for the `form` element to be present.
 3. The `FooPage` validation will wait for the `some_other_element` element to be present.
 
-**NB:** `SitePrism::Page` **used to** include a default load validation on
-`page.displayed?` however for v3 this has been removed. It is therefore
-necessary to re-define this if you want to retain the behaviour
-from site_prism v2. See [UPGRADING.md](https://github.com/site-prism/site_prism/blob/main/UPGRADING.md#default-load-validations)
-for more info on this.
-
 ## Using Capybara Query Options
 
 When querying an element, section or a collection of elements or sections,
@@ -1535,7 +1521,7 @@ fail if the page has not finished loading the section(s):
 ```ruby
 @home = Home.new
 # ...
-expect(@home.search_results.size).to == 25 # This may fail!
+expect(@home.search_results.size).to eq(25) # This may fail!
 ```
 
 The above query can be rewritten to utilize the Capybara `:count` option
@@ -1546,16 +1532,16 @@ the page within the timeout:
 
 ```ruby
 @home = Home.new
-@home.has_search_results?(count: 25)
+@home.has_search_results?(count: 25) # will wait default wait time
 # OR
-@home.search_results(count: 25)
+@home.search_results(count: 25, wait: 5) # will wait 5 seconds
 ```
 
 Now we can write pretty, non-failing tests without hard coding these options
 into our page and section classes:
 
 ```ruby
-Then(/^there are search results on the page$/) do
+Then('there are search results on the page') do
   expect(@results_page).to have_search_results(count: 25)
 end
 ```
@@ -1586,7 +1572,7 @@ The following element methods allow Capybara options to be passed as arguments t
 ## Test views with Page objects
 
 It's possible to use the same page objects of integration tests for view tests, too,
-just pass the rendered HTML to the ```load``` method:
+just pass the rendered HTML to the `load` method:
 
 ```ruby
 require 'spec_helper'
@@ -1688,14 +1674,14 @@ class Home < SitePrism::Page
 end
 
 # cucumber step that performs login
-When(/^I log in$/) do
+When('I log in') do
   @home = Home.new
   @home.load
 
   @home.login_frame do |frame|
     #`frame` is an instance of the `LoginFrame` class
-    frame.username.set 'admin'
-    frame.password.set 'p4ssword'
+    frame.username.send_keys('admin')
+    frame.password.send_keys('p4ssword')
   end
 end
 ```
@@ -1738,14 +1724,6 @@ Capybara.using_wait_time(20) do
 end
 ```
 
-## Using SitePrism with VCR
-
-There's a SitePrism plugin called `site_prism.vcr` that lets you use
-SitePrism with the VCR gem. Check it out [HERE](https://github.com/dnesteryuk/site_prism.vcr)
-
-Note that as of 2016 this plugin doesn't appear to have been under active development. Also it is
-still pinned to the `2.x` series of site_prism so use it of your own accord.
-
 # Epilogue
 
 So, we've seen how to use SitePrism to put together page objects made up
@@ -1756,7 +1734,7 @@ all over the place. Here's an example of this common problem:
 ```ruby
 @home = Home.new # <-- noise
 @home.load
-@home.search_field.set 'Sausages'
+@home.search_field.send_keys('Sausages')
 @home.search_field.search_button.click
 @results_page = SearchResults.new # <-- noise
 expect(@results_page).to have_search_result_items
@@ -1766,7 +1744,7 @@ The annoyance (and, later, maintenance nightmare) is having to create
 `@home` and `@results_page`. It would be better to not have to create
 instances of pages all over your tests.
 
-The way I've dealt with this problem is to create a class containing
+One way you can deal with this problem is to create a class containing
 methods that return instances of the pages. Eg:
 
 ```ruby
@@ -1803,17 +1781,17 @@ end
 # and here's how to use it
 
 #first line of the test...
-Given(/^I start on the home page$/) do
+Given('I start on the home page') do
   @app = App.new
   @app.home.load
 end
 
-When(/^I search for Sausages$/) do
+When('I search for Sausages') do
   @app.home.search_field.set 'Sausages'
   @app.home.search_button.click
 end
 
-Then(/^I am on the results page$/) do
+Then('I am on the results page') do
   expect(@app.results_page).to be_displayed
 end
 
@@ -1823,8 +1801,8 @@ end
 The only thing that needs instantiating is the `App` class - from then on
 pages don't need to be initialized, they are now returned by methods on `@app`.
 
-It is possible to further optimise this, by using Cucumber/RSpec hooks, amongst
-other things. However the investigation and optimisation of this (and other
+It is possible to further optimise this, by using Cucumber/RSpec hooks, memoization as well
+as many other things. However the investigation and optimisation of this (and other
 aspects of SitePrism), is left as an exercise to the Reader.
 
 Happy testing from all of the SitePrism team!

data/lib/site_prism/deprecator.rb

@@ -15,7 +15,7 @@ module SitePrism
           warn("#{old} is being deprecated and should no longer be used.")
         end
 
-        warn("#{old} will be removed in SitePrism v4. You have been warned!")
+        warn("#{old} will be removed in SitePrism v5. You have been warned!")
       end
 
       # @return SitePrism.logger.debug(msg)

data/lib/site_prism/dsl.rb

@@ -16,7 +16,7 @@ module SitePrism
 
     private
 
-    def raise_if_block(object, name, has_block, type)
+    def raise_if_runtime_block_supplied(object, name, has_block, type)
       return unless has_block
 
       SitePrism.logger.debug("Type passed in: #{type}")
@@ -24,25 +24,21 @@ module SitePrism
       raise SitePrism::UnsupportedBlockError
     end
 
-    # Call `find` inside `to_capybara_node` context (Either Capybara::Session or Capybara::Node::Element)
     def _find(*find_args)
       kwargs = find_args.pop
       to_capybara_node.find(*find_args, **kwargs)
     end
 
-    # Call `all` inside `to_capybara_node` context (Either Capybara::Session or Capybara::Node::Element)
     def _all(*find_args)
       kwargs = find_args.pop
       to_capybara_node.all(*find_args, **kwargs)
     end
 
-    # Call `has_selector?` inside `to_capybara_node` context (Either Capybara::Session or Capybara::Node::Element)
     def element_exists?(*find_args)
       kwargs = find_args.pop
       to_capybara_node.has_selector?(*find_args, **kwargs)
     end
 
-    # Call `has_no_selector?` inside `to_capybara_node` context (Either Capybara::Session or Capybara::Node::Element)
     def element_does_not_exist?(*find_args)
       kwargs = find_args.pop
       to_capybara_node.has_no_selector?(*find_args, **kwargs)
@@ -103,10 +99,10 @@ module SitePrism
       # Wait for the elements to be present or not -> @return [TrueClass, SitePrism::Error]
       # Validate certain properties about the element
       def element(name, *find_args)
-        raise_if_block(self, name, block_given?, :element)
+        raise_if_build_time_block_supplied(self, name, block_given?, :element)
         build(:element, name, *find_args) do
           define_method(name) do |*runtime_args, &runtime_block|
-            raise_if_block(self, name, runtime_block, :element)
+            raise_if_runtime_block_supplied(self, name, runtime_block, :element)
             _find(*merge_args(find_args, runtime_args))
           end
         end
@@ -118,10 +114,10 @@ module SitePrism
       # Wait for the elements to be present or not -> @return [TrueClass, SitePrism::Error]
       # Validate certain properties about the elements
       def elements(name, *find_args)
-        raise_if_block(self, name, block_given?, :elements)
+        raise_if_build_time_block_supplied(self, name, block_given?, :elements)
         build(:elements, name, *find_args) do
           define_method(name) do |*runtime_args, &runtime_block|
-            raise_if_block(self, name, runtime_block, :elements)
+            raise_if_runtime_block_supplied(self, name, runtime_block, :elements)
             _all(*merge_args(find_args, runtime_args))
           end
         end
@@ -151,7 +147,7 @@ module SitePrism
         section_class, find_args = extract_section_options(args, &block)
         build(:sections, name, *find_args) do
           define_method(name) do |*runtime_args, &runtime_block|
-            raise_if_block(self, name, runtime_block, :sections)
+            raise_if_runtime_block_supplied(self, name, runtime_block, :sections)
             _all(*merge_args(find_args, runtime_args)).map do |element|
               section_class.new(self, element)
             end
@@ -160,7 +156,7 @@ module SitePrism
       end
 
       def iframe(name, klass, *args)
-        SitePrism.logger.debug('Block passed into iFrame construct at build time') if block_given?
+        raise_if_build_time_block_supplied(self, name, block_given?, :elements)
         element_find_args = deduce_iframe_element_find_args(args)
         scope_find_args = deduce_iframe_scope_find_args(args)
         build(:iframe, name, *element_find_args) do
@@ -175,10 +171,10 @@ module SitePrism
       # Return a list of all mapped items on a SitePrism class instance (Page or Section)
       # If legacy is set to true (Default) -> @return [Array]
       # If legacy is set to false (New behaviour) -> @return [Hash]
-      def mapped_items(legacy: true)
-        return old_mapped_items if legacy
+      def mapped_items(legacy: false)
+        return legacy_mapped_items if legacy
 
-        new_mapped_items
+        @mapped_items ||= { element: [], elements: [], section: [], sections: [], iframe: [] }
       end
 
       private
@@ -192,13 +188,13 @@ module SitePrism
           map_item(type, name)
           yield
         end
-        add_helper_methods(name, *find_args)
+        add_helper_methods(name, type, *find_args)
       end
 
-      def add_helper_methods(name, *find_args)
+      def add_helper_methods(name, _type, *find_args)
         create_existence_checker(name, *find_args)
         create_nonexistence_checker(name, *find_args)
-        SitePrism::RspecMatchers.new(name)._create_rspec_existence_matchers if defined?(RSpec)
+        SitePrism::RSpecMatchers.new(name)._create_rspec_existence_matchers if defined?(RSpec)
         create_visibility_waiter(name, *find_args)
         create_invisibility_waiter(name, *find_args)
       end
@@ -254,15 +250,15 @@ module SitePrism
       end
 
       def create_error_method(name)
-        SitePrism.logger.error("#{name} has come from an item with no locators.")
-        SitePrism::Deprecator.soft_deprecate(
+        SitePrism::Deprecator.deprecate(
           'DSL definition with no find_args',
-          'All DSL elements should have find_args'
+          'DSL definition with at least 1 find_arg'
         )
+        SitePrism.logger.error("#{name} has come from an item with no locators.")
         define_method(name) { raise SitePrism::InvalidElementError }
       end
 
-      def raise_if_block(parent_object, name, has_block, type)
+      def raise_if_build_time_block_supplied(parent_object, name, has_block, type)
         return unless has_block
 
         SitePrism.logger.debug("Type passed in: #{type}")
@@ -270,22 +266,17 @@ module SitePrism
         raise SitePrism::UnsupportedBlockError
       end
 
-      def old_mapped_items
-        SitePrism::Deprecator.soft_deprecate(
-          '.mapped_items on a class',
-          'To allow easier recursion through the items in conjunction with #all_there?',
-          '.mapped_items(legacy: false)'
+      def legacy_mapped_items
+        SitePrism::Deprecator.deprecate(
+          '.mapped_items structure (internally), on a class',
+          'Thew new .mapped_items structure'
         )
-        @old_mapped_items ||= []
-      end
-
-      def new_mapped_items
-        @new_mapped_items ||= { element: [], elements: [], section: [], sections: [], iframe: [] }
+        @legacy_mapped_items ||= []
       end
 
       def map_item(type, name)
-        old_mapped_items << { type => name }
-        new_mapped_items[type] << name.to_sym
+        mapped_items(legacy: true) << { type => name }
+        mapped_items[type] << name.to_sym
       end
 
       def deduce_iframe_scope_find_args(args)

data/lib/site_prism/element_checker.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
 module SitePrism
+  #
   # [SitePrism::ElementChecker]
   #
   # This allows users to run `#all_there?` checks on an instance.
   #
-  # NB: This functionality is being removed in v4 in favour of the all_there gem
   module ElementChecker
     # Runnable in the scope of any SitePrism::Page or Section.
     # Returns +true+ when "every item" that is being checked is
@@ -26,13 +26,7 @@ module SitePrism
     # Override: 'one' => Perform one recursive dive into all section/sections
     # items and call #all_there? on all of those items too.
     def all_there?(recursion: :none)
-      case recursion
-      when :none; then elements_to_check.all? { |name| there?(name) }
-      when :one;  then SitePrism::AllThere::RecursionChecker.new(self).all_there?
-      else
-        SitePrism.logger.debug("Input value '#{recursion}'. Valid values are :none or :one.")
-        SitePrism.logger.error('Invalid recursion setting, Will not run #all_there?.')
-      end
+      SitePrism::AllThere::RecursionChecker.new(self).all_there?(recursion: recursion)
     end
 
     # Returns each element that is currently present inside the scope being tested
@@ -51,8 +45,6 @@ module SitePrism
 
     private
 
-    # If the page or section has expected_items set, return expected_items that are mapped
-    # otherwise just return the list of all mapped_items
     def elements_to_check
       if _expected_items
         SitePrism.logger.debug('Expected Items has been set.')
@@ -63,7 +55,7 @@ module SitePrism
     end
 
     def _mapped_items
-      self.class.mapped_items(legacy: false).values.flatten.uniq
+      self.class.mapped_items.values.flatten.uniq
     end
 
     def _expected_items

data/lib/site_prism/loadable.rb

@@ -43,10 +43,11 @@ module SitePrism
 
     # Check if the page is loaded.
     #
-    # On failure, if an error was reported by a failing validation,
-    # it will be available via the `load_error` accessor.
+    # On failure, if an error was reported by a failing validation, it will be available via the `load_error` accessor
     #
-    # @return [Boolean] True if the page loaded successfully; otherwise false.
+    # It will return true if the page has been loaded successfully; otherwise it returns false
+    #
+    # @return [Boolean]
     def loaded?
       self.load_error = nil
 
@@ -57,8 +58,6 @@ module SitePrism
 
     private
 
-    # If any load validations from page subclasses returns false,
-    # immediately return false.
     def load_validations_pass?
       self.class.load_validations.all? do |validation|
         passed, message = instance_eval(&validation)

data/lib/site_prism/page.rb

@@ -9,7 +9,7 @@ module SitePrism
   # through clicking buttons or filling in fields, or verbosely loaded by using the `#load` method
   #
   # All method calls made whilst on a page are scoped using `#to_capybara_node` which defaults to the
-  # current Capybara session
+  # current Capybara session or the `@page` that has been loaded in-line
   class Page
     include Capybara::DSL
     include ElementChecker
@@ -48,12 +48,15 @@ module SitePrism
     #
     # @return [Capybara::Node::Simple || Capybara::Session]
     def page
+      SitePrism::Deprecator.deprecate('Calling #page on a SitePrism::Page instance')
       (defined?(@page) && @page) || Capybara.current_session
     end
 
     # This scopes our calls inside Page correctly to the `Capybara::Session`
+    #
+    # @return [Capybara::Node::Simple || Capybara::Session]
     def to_capybara_node
-      page
+      (defined?(@page) && @page) || Capybara.current_session
     end
 
     # Loads the page.
@@ -85,12 +88,21 @@ module SitePrism
       return_yield || true
     end
 
+    # Returns true if the page is displayed within the requisite time
+    # Returns false if the page is not displayed within the requisite time
+    #
+    # @return [Boolean]
     def displayed?(*args)
       wait_until_displayed(*args)
     rescue SitePrism::TimeoutError
       false
     end
 
+    # Wait until the page is displayed according to input arguments
+    # If no url_matcher is provided we don't know how to determine if the page is displayed. So we return an error
+    # Then we wait until the url matches the expected mappings
+    #
+    # @return [Boolean]
     def wait_until_displayed(*args)
       raise SitePrism::NoUrlMatcherForPageError unless url_matcher
 
@@ -99,6 +111,13 @@ module SitePrism
       Waiter.wait_until_true(seconds) { url_matches?(expected_mappings) }
     end
 
+    # Return the matching information of a page
+    #
+    # Return nil if the page is not displayed correctly
+    # Return the regex matches if we have provided a regexp style url_matcher
+    # Otherwise fall back to an addressable-style template of matches
+    #
+    # @return [Nil || MatchData || Hash]
     def url_matches(seconds = Capybara.default_max_wait_time)
       return unless displayed?(seconds)
       return regexp_backed_matches if url_matcher.is_a?(Regexp)
@@ -106,14 +125,24 @@ module SitePrism
       template_backed_matches
     end
 
+    # Returns the templated url from the set_url property defined during the page definition
+    # Returns `nil` if there was not a property set (i.e. the page should not be directly loaded)
+    #
+    # @return [NilClass || String]
     def url(expansion = {})
       self.class.url && Addressable::Template.new(self.class.url).expand(expansion).to_s
     end
 
+    # Returns the url_matcher property defined during the page definition
+    #
+    # @return [Regexp]
     def url_matcher
       self.class.url_matcher
     end
 
+    # Returns true if the page is secure, otherwise returns false
+    #
+    # @return [Boolean]
     def secure?
       page.current_url.start_with?('https')
     end

data/lib/site_prism/rspec_matchers.rb

@@ -4,13 +4,16 @@ module SitePrism
   #
   # @api private
   #
-  class RspecMatchers
+  class RSpecMatchers
     attr_reader :element_name
 
     def initialize(element_name)
       @element_name = element_name
     end
 
+    # Create the positive and negative rspec matchers that will use the SitePrism boolean methods
+    #
+    # @return [Symbol]
     def _create_rspec_existence_matchers
       SitePrism.logger.debug('Including all relevant matcher names / warnings in RSpec scope.')
       create_rspec_existence_matchers(matcher, object_method, negated_object_method, warning)
@@ -43,8 +46,8 @@ module SitePrism
     end
 
     def warning
-      "The RSpec matcher '#{matcher}' was added by SitePrism, but the object under test "\
-        "does not respond to '#{negated_object_method}' and is probably not a SitePrism object. "\
+      "The RSpec matcher '#{matcher}' was added by SitePrism, but the object under test " \
+        "does not respond to '#{negated_object_method}' and is probably not a SitePrism object. " \
         'Falling back to the default RSpec matcher.'
     end
   end

data/lib/site_prism/section.rb

@@ -72,13 +72,6 @@ module SitePrism
       Capybara.within(root_element) { yield(self) }
     end
 
-    # This was the old API-style of delegating through the Capybara.page call and over-loading
-    # the method so we always went through our correct `root_element`
-    def page
-      SitePrism.logger.fatal('This is not supposed to be used. All delegation now happens automatically!')
-      raise SitePrism::SitePrismError
-    end
-
     def capybara_session
       Capybara.current_session
     end

data/lib/site_prism/timer.rb

@@ -7,9 +7,9 @@ module SitePrism
   class Timer
     attr_reader :wait_time
 
-    # Return &block
-    #
     # Count towards a specified time (Supplied)
+    #
+    # @return [Proc]
     def self.run(wait_time, &block)
       new(wait_time).run(&block)
     end
@@ -19,16 +19,16 @@ module SitePrism
       @done = false
     end
 
-    # Return Boolean
-    #
     # Whether the timer has completed
+    #
+    # @return [Boolean]
     def done?
       @done == true
     end
 
-    # Return &block
-    #
     # Start the Timer and re-evaluate the block repeatedly
+    #
+    # @return [Proc]
     def run
       start
       yield self
@@ -36,9 +36,9 @@ module SitePrism
       stop
     end
 
-    # Return [Boolean, Nil]
-    #
     # Start the Timer in a separate process
+    #
+    # Return [True]
     def start
       stop
       return if wait_time.zero?
@@ -50,9 +50,9 @@ module SitePrism
       end
     end
 
-    # Return True
-    #
     # Forcibly stop the timer, and kill any threads created by it
+    #
+    # Return [True]
     def stop
       if @thread
         @thread.kill

data/lib/site_prism/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SitePrism
-  VERSION = '4.0.beta'
+  VERSION = '4.0'
 end

data/lib/site_prism/waiter.rb

@@ -3,10 +3,10 @@
 module SitePrism
   # [SitePrism::Waiter]
   class Waiter
-    # @return Boolean
-    #
     # A looper that will wait until the passed in block evaluates to true
     # Alternatively it will time out once the wait_time is exceeded
+    #
+    # @return [Boolean]
     def self.wait_until_true(wait_time = Capybara.default_max_wait_time, sleep_duration = 0.05)
       Timer.run(wait_time) do |timer|
         loop do

data/lib/site_prism.rb

@@ -16,7 +16,7 @@ module SitePrism
   autoload :Loadable, 'site_prism/loadable'
   autoload :Logger, 'site_prism/logger'
   autoload :Page, 'site_prism/page'
-  autoload :RspecMatchers, 'site_prism/rspec_matchers'
+  autoload :RSpecMatchers, 'site_prism/rspec_matchers'
   autoload :Section, 'site_prism/section'
   autoload :Timer, 'site_prism/timer'
   autoload :Waiter, 'site_prism/waiter'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: site_prism
 version: !ruby/object:Gem::Version
-  version: 4.0.beta
+  version: '4.0'
 platform: ruby
 authors:
 - Luke Hill
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-11-28 00:00:00.000000000 Z
+date: 2023-04-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable
@@ -17,48 +17,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.6'
+        version: '2.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.6'
+        version: '2.8'
 - !ruby/object:Gem::Dependency
   name: capybara
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.15'
+        version: '3.27'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.15'
+        version: '3.27'
 - !ruby/object:Gem::Dependency
   name: site_prism-all_there
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">"
-      - !ruby/object:Gem::Version
-        version: '1'
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '2'
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">"
-      - !ruby/object:Gem::Version
-        version: '1'
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '2'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: cucumber
   requirement: !ruby/object:Gem::Requirement
@@ -85,104 +79,104 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.10'
+        version: '3.12'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.10'
+        version: '3.12'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.28.0
+        version: 1.49.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.28.0
+        version: 1.49.0
 - !ruby/object:Gem::Dependency
   name: rubocop-performance
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.13.0
+        version: 1.16.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.13.0
+        version: 1.16.0
 - !ruby/object:Gem::Dependency
   name: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.7.0
+        version: 2.19.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.7.0
+        version: 2.19.0
 - !ruby/object:Gem::Dependency
   name: selenium-webdriver
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '3.13'
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '5'
+        version: '4.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '3.13'
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '5'
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.18'
+        version: '0.21'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.18'
+        version: '0.21'
 - !ruby/object:Gem::Dependency
   name: webdrivers
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">"
       - !ruby/object:Gem::Version
         version: '4.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">"
       - !ruby/object:Gem::Version
         version: '4.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
 description: SitePrism gives you a simple, clean and semantic DSL for describing your
   site. SitePrism implements the Page Object Model pattern on top of Capybara.
 email:
@@ -224,12 +218,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '2.6'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubygems_version: 3.0.3.1
 signing_key: