site_prism 3.5 → 3.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95c8d9ff0cf7f2b818a8b8cb987ca39f2b512138d572a08533b8466feae6cb63
-  data.tar.gz: 6239a4a2cd9be9233396f2b221328645dcb50a56e531ee0d5b63faa3dbd9bf53
+  metadata.gz: 177884e3ba39ca8a9e1fa0025274c31dd1d765adbba6983f86150feeef4fa301
+  data.tar.gz: 0ecc59ece70808dbb774128d1cf5e7f3fcdaa4d449b27be29f403633b3535c24
 SHA512:
-  metadata.gz: a9a7a79356b8f4c16aad85f923db99a549bba2c78ec23624f245504ce3bbffd7698bad6a572ddbb34cbf9f2406da76bda7ce5d2433d874270112025e5e9d79ea
-  data.tar.gz: 897ae6d1b6a944b52bc5f36ebb81e2796657a276bfa41994fd0a5315031457d404b46408660556644eb262258c8033b72aa5d7400bd79d13f8085993575df826
+  metadata.gz: 5f402e20e4888f02d4c7695289239c1b4dfca44b47e90029699efe4ec050b2d173f78c1e427f1dbd0647c9b8238397f1c34d22697601b5f36689266f942729b7
+  data.tar.gz: 549ac4b1187a96807c34475961999bcfaa6761fceba70cf13bdcedfdce13c86b23aad1fa700bcda122841a057bd258023f26ffc270194a8258d98756b3bf294c

data/LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2011-2019, The SitePrism team
+Copyright (c) 2011-2021, The SitePrism team
 
 All rights reserved.
 

data/README.md

@@ -7,23 +7,34 @@ _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: http://rdoc.info/gems/site_prism/frames
+Find the pretty documentation here: https://rdoc.info/gems/site_prism/frames
 
 Make sure to add your project/company to https://github.com/site-prism/site_prism/wiki/Who-is-using-SitePrism
 
+## Support
+
+Support us with a monthly donation and help us continue our activities by supporting us as a [backer](https://opencollective.com/site-prism#backer)
+
+Become a sponsor and get your logo on our README on Github with a link to your site. [How to Sponsor SitePrism?](https://opencollective.com/site-prism#sponsor)
+
+Free Open Source software can only be maintained with the support of you. If you and/or your company find
+value in SitePrism and would like to contribute financially to its ongoing maintenance and development, 
+then please do so. Visit the OpenCollective links above for more details.
+
 ## Developing / Contributing to SitePrism
 
 We love it when people want to get involved with our Open Source Project.
 
-We have a brief set of setup docs [HERE](https://github.com/site-prism/site_prism/blob/master/HACKING.md)
+We have a brief set of setup docs [HERE](https://github.com/site-prism/site_prism/blob/main/HACKING.md)
 
 ## Supported Rubies / Browsers
 
-SitePrism is built and tested to work on Ruby 2.4 - 2.6. Ruby 2.3 (Now EOL), is supported but not tested against.
-If you are using SitePrism with Ruby 2.3 it is highly advisable to upgrade to a more modern Ruby
-such as 2.6 or 2.7, if for any other reason, to get a noticeable speed boost!
+SitePrism is built and tested to work on Ruby 2.4 - 2.7. Ruby 2.4 (Now EOL), is supported but
+this version will be removed from the Support Matrix in the coming months.
+If you are using SitePrism with Ruby 2.4 it is highly advisable to upgrade to a more modern Ruby
+such as 2.7, if for any other reason, to get a noticeable speed boost!
 
-SitePrism should run on all major browsers. The gem's integration tests are ran on Chrome and Firefox.
+SitePrism should run on all major browsers. The gem's integration tests are run on Chrome and Firefox.
 
 If you find you cannot integrate nicely with SitePrism, please open an
 [issue request](https://github.com/site-prism/site_prism/issues/new)
@@ -298,7 +309,13 @@ expect(@account_page).to be_displayed
 ```
 
 Calling `#displayed?` will return true if the browser's current URL
-matches the page's template and false if it doesn't.
+matches the page's template and false if it doesn't. It will wait for
+`Capybara.default_max_wait_time` seconds or you can pass an explicit
+wait time in seconds as the first argument like this:
+
+```ruby
+@account_page.displayed?(10) # wait up to 10 seconds for display
+```
 
 #### Specifying parameter values for templated URLs
 
@@ -425,8 +442,11 @@ as a string.
 #### Accessing the individual element
 
 The `element` method will add a number of methods to instances of the
-particular Page class. The first method to be added is the name of the
-element. So using the following example:
+particular Page class. The first method added is the name of the
+element. It finds the element using [Capybara::Node::Finders#find](https://www.rubydoc.info/github/teamcapybara/capybara/master/Capybara/Node/Finders#find-instance_method)
+returning a [Capybara::Node::Element](https://www.rubydoc.info/github/teamcapybara/capybara/master/Capybara/Node/Element) or
+raising [Capybara::ElementNotFound](https://www.rubydoc.info/github/teamcapybara/capybara/master/Capybara/ElementNotFound)
+if the element can not be found.
 
 ```ruby
 class Home < SitePrism::Page
@@ -450,7 +470,9 @@ end
 #### Testing for the existence of the element
 
 Another method added to the Page class by the `element` method is the
-`has_<element_name>?` method. Using the same example as above:
+`has_<element_name>?` method.
+This method delegates to [Capybara::Node::Matchers#has_selector?](https://www.rubydoc.info/github/teamcapybara/capybara/master/Capybara/Node/Matchers#has_selector%3F-instance_method).
+Using the same example as above:
 
 ```ruby
 class Home < SitePrism::Page
@@ -480,7 +502,9 @@ end
 
 To test that an element does not exist on the page, it is not possible to just call
 `#not_to have_search_field`. SitePrism supplies the `#has_no_<element>?` method
-that should be used to test for non-existence. Using the above example:
+that should be used 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:
 
 ```ruby
 @home = Home.new
@@ -499,8 +523,9 @@ end
 #### Waiting for an element to become visible
 
 A method that gets added by calling `element` is the
-`wait_until_<element_name>_visible` method. Calling this method will
-cause the test to wait for Capybara's default wait time for the element
+`wait_until_<element_name>_visible` method.
+This method delegates to [Capybara::Node::Matchers#has_selector?](https://www.rubydoc.info/github/teamcapybara/capybara/master/Capybara/Node/Matchers#has_selector%3F-instance_method).
+Calling this method will cause the test to wait for Capybara's default wait time for the element
 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.
 
@@ -513,10 +538,11 @@ of seconds to wait in-line or configuring the default wait time.
 #### Waiting for an element to become invisible
 
 Another method added by calling `element` is the
-`wait_until_<element_name>_invisible` method. Calling this method will
-cause the test to wait for Capybara's default wait time for the element
-to become invisible. You can as with the visibility waiter, customise
-the wait time in the same way.
+`wait_until_<element_name>_invisible` method.
+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).
+Calling this method will cause the test to wait for Capybara's default
+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
@@ -736,6 +762,28 @@ use the bleeding edge version of the logic. Then simply set the following config
 SitePrism.use_all_there_gem = true
 ```
 
+### Getting the list of missing elements
+
+If `#all_there?` returns false and you wish to get the list of missing elements for debugging purposes
+you may want to use `#elements_missing` method. It will return all missing elements from the expected_elements list
+
+If you do not provide a list of `expected_elements` this method will return all elements that are missing on the page;
+from those which are defined.
+
+```ruby
+class Home < SitePrism::Page
+  element :name, '#name'
+  element :address, '#address'
+  element :success_message, 'span.alert-success'
+
+  expected_elements :name, :address
+end
+
+# and... Only `address` is on the page
+
+@test_page.elements_missing #=> [:name]
+```
+
 ## Sections
 
 SitePrism allows you to model sections of a page that appear on multiple
@@ -1467,7 +1515,7 @@ the validations will be performed in the following order:
 **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/master/UPGRADING.md#default-load-validations)
+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
@@ -1688,7 +1736,7 @@ end
 ```
 
 Note that even with implicit waits on you can dynamically modify the wait times
-in any SitePrism method to help work-around special circumstances.  
+in any SitePrism method to help work-around special circumstances.
 
 ```ruby
 # Option 1: using wait key assignment

data/lib/site_prism.rb

@@ -3,15 +3,20 @@
 require 'site_prism/error'
 require 'addressable/template'
 
+# [SitePrism] namespace
+# We autoload our files underneath here to provide a slightly more optimal load solution
 module SitePrism
   autoload :AddressableUrlMatcher, 'site_prism/addressable_url_matcher'
-  autoload :Deprecator, 'site_prism/deprecator'
   autoload :DSL, 'site_prism/dsl'
+  autoload :Deprecator, 'site_prism/deprecator'
   autoload :ElementChecker, 'site_prism/element_checker'
-  autoload :RecursionChecker, 'site_prism/recursion_checker'
+  autoload :Loadable, 'site_prism/loadable'
   autoload :Logger, 'site_prism/logger'
   autoload :Page, 'site_prism/page'
+  autoload :RecursionChecker, 'site_prism/recursion_checker'
+  autoload :RspecMatchers, 'site_prism/rspec_matchers'
   autoload :Section, 'site_prism/section'
+  autoload :Timer, 'site_prism/timer'
   autoload :Waiter, 'site_prism/waiter'
 
   class << self

data/lib/site_prism/addressable_url_matcher.rb

@@ -4,6 +4,10 @@ require 'digest'
 require 'base64'
 
 module SitePrism
+  # [SitePrism::AddressableUrlMatcher]
+  # Used in a couple of places to allow users to ...
+  #   Specify patterns for loading webpages
+  #   Pass in hashable args or query parameters for loading dynamic pages
   class AddressableUrlMatcher
     attr_reader :pattern
 
@@ -43,12 +47,10 @@ module SitePrism
     def all_expected_mappings_match?(expected_mappings, actual_mappings)
       expected_mappings.all? do |key, expected_value|
         actual_value = actual_mappings[key.to_s]
-        if expected_value.is_a?(Numeric)
-          actual_value == expected_value.to_s
-        elsif expected_value.is_a?(Regexp)
-          actual_value.match(expected_value)
-        else
-          expected_value == actual_value
+        case expected_value
+        when Numeric; then actual_value == expected_value.to_s
+        when Regexp;  then actual_value.match(expected_value)
+        else               expected_value == actual_value
         end
       end
     end

data/lib/site_prism/deprecator.rb

@@ -1,8 +1,13 @@
 # frozen_string_literal: true
 
 module SitePrism
+  # [SitePrism::Deprecator]
   class Deprecator
     class << self
+      # @return SitePrism.logger.warn(msg)
+      #
+      # Tells the user that they are using old functionality, which needs removing in the
+      # next major version
       def deprecate(old, new = nil)
         if new
           warn("#{old} is being deprecated and should no longer be used. Use #{new} instead.")
@@ -13,6 +18,14 @@ module SitePrism
         warn("#{old} will be removed in SitePrism v4. You have been warned!")
       end
 
+      # @return SitePrism.logger.debug(msg)
+      #
+      # Tells the user that they are using functionality which is non-optimal
+      #   The functionality should usually provide a reason for it being poor, as well as an
+      #   optional way of upgrading to something different
+      #
+      # NB: As this is bubbled up at debug level, often users will not see this. So it will
+      # never be a candidate for removal directly
       def soft_deprecate(old, reason, new = nil)
         debug("The #{old} method is changing, as is SitePrism, and is now configurable.")
         debug("REASON: #{reason}.")

data/lib/site_prism/dsl.rb

@@ -1,6 +1,13 @@
 # frozen_string_literal: true
 
 module SitePrism
+  # [SitePrism::DSL]
+  #
+  # This is the core Module Namespace for all of the public-facing DSL methods
+  #   such as `element`. The code here is designed to be used through the defining
+  #   of said items, and not to be instantiated directly.
+  #
+  # The whole package here can be thought of as [@api private]
   module DSL
     def self.included(klass)
       klass.extend ClassMethods
@@ -8,9 +15,28 @@ module SitePrism
 
     private
 
-    # The default waiting time set by Capybara's configuration settings.
-    def wait_time
-      Capybara.default_max_wait_time
+    # Call `find` inside context set on page/section
+    def _find(*find_args)
+      kwargs = find_args.pop
+      page.find(*find_args, **kwargs)
+    end
+
+    # Call `all` inside context set on page/section
+    def _all(*find_args)
+      kwargs = find_args.pop
+      page.all(*find_args, **kwargs)
+    end
+
+    # Call `has_selector?` inside context set on page/section
+    def element_exists?(*find_args)
+      kwargs = find_args.pop
+      page.has_selector?(*find_args, **kwargs)
+    end
+
+    # Call `has_no_selector?` inside context set on page/section
+    def element_does_not_exist?(*find_args)
+      kwargs = find_args.pop
+      page.has_no_selector?(*find_args, **kwargs)
     end
 
     # Prevent users from calling methods with blocks when they shouldn't be.
@@ -68,21 +94,29 @@ module SitePrism
     #
     # If the hash is empty, then the hash is omitted from the payload sent
     # to Capybara, and the find / runtime arguments are sent alone.
+    #
+    # NB: If the +wait+ key is present in the options hash, even as false or 0, It will
+    # be set as the user-supplied value (So user error can be the cause for issues).
     def recombine_args(find_args, runtime_args, options)
       options.merge!(find_args.pop) if find_args.last.is_a? Hash
       options.merge!(runtime_args.pop) if runtime_args.last.is_a? Hash
-      options[:wait] = wait_time unless wait_key_present?(options)
-    end
-
-    # Detect if the +wait+ key is present in the options hash.
-    # Note that setting it to to false or 0, still will return true here.
-    def wait_key_present?(options)
-      options.key?(:wait)
+      options[:wait] = Capybara.default_max_wait_time unless options.key?(:wait)
     end
 
+    # SitePrism::DSL::ClassMethods
+    # This exposes all of the DSL definitions users will use when generating
+    # their POM classes.
+    #
+    # Many of these methods will be used in-line to allow users to generate a multitude of
+    # methods and locators for finding elements / sections on a page or section of a page
     module ClassMethods
       attr_reader :expected_items
 
+      # Creates an instance of a SitePrism Element - This will create several methods designed to
+      # Locate the element -> @return [Capybara::Node::Element]
+      # Check the elements presence or non-presence -> @return [Boolean]
+      # Wait for the elements to be present or not -> @return [TrueClass, SitePrism::Error]
+      # Validate certain properties about the element
       def element(name, *find_args)
         SitePrism::Deprecator.deprecate('Passing a block to :element') if block_given?
         build(:element, name, *find_args) do
@@ -94,6 +128,11 @@ module SitePrism
         end
       end
 
+      # Creates a enumerable instance of a SitePrism Element - This will create several methods designed to
+      # Locate the enumerable element -> @return [Capybara::Result]
+      # Check the elements presence or non-presence -> @return [Boolean]
+      # Wait for the elements to be present or not -> @return [TrueClass, SitePrism::Error]
+      # Validate certain properties about the elements
       def elements(name, *find_args)
         SitePrism::Deprecator.deprecate('Passing a block to :elements') if block_given?
         build(:elements, name, *find_args) do
@@ -105,10 +144,18 @@ module SitePrism
         end
       end
 
+      # Sets the `expected_items` iVar on a class. This property is used in conjunction with
+      # `all_there?` to provide a way of granularising the check made to only interrogate a sub-set
+      # of DSL defined items
       def expected_elements(*elements)
         @expected_items = elements
       end
 
+      # Creates an instance of a SitePrism Section - This will create several methods designed to
+      # Locate the section -> @return [SitePrism::Section]
+      # Check the section presence or non-presence -> @return [Boolean]
+      # Wait for the section to be present or not -> @return [TrueClass, SitePrism::Error]
+      # Validate certain properties about the section
       def section(name, *args, &block)
         section_class, find_args = extract_section_options(args, &block)
         build(:section, name, *find_args) do
@@ -120,6 +167,11 @@ module SitePrism
         end
       end
 
+      # Creates an enumerable instance of a SitePrism Section - This will create several methods designed to
+      # Locate the sections -> @return [Array]
+      # Check the sections presence or non-presence -> @return [Boolean]
+      # Wait for the sections to be present or not -> @return [TrueClass, SitePrism::Error]
+      # Validate certain properties about the section
       def sections(name, *args, &block)
         section_class, find_args = extract_section_options(args, &block)
         build(:sections, name, *find_args) do
@@ -145,12 +197,13 @@ module SitePrism
         end
       end
 
+      # 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)
-        if legacy
-          old_mapped_items
-        else
-          new_mapped_items
-        end
+        return old_mapped_items if legacy
+
+        new_mapped_items
       end
 
       private
@@ -165,13 +218,7 @@ module SitePrism
       end
 
       def new_mapped_items
-        @new_mapped_items ||= {
-          element: [],
-          elements: [],
-          section: [],
-          sections: [],
-          iframe: [],
-        }
+        @new_mapped_items ||= { element: [], elements: [], section: [], sections: [], iframe: [] }
       end
 
       def build(type, name, *find_args)
@@ -192,27 +239,15 @@ module SitePrism
       def add_helper_methods(name, *find_args)
         create_existence_checker(name, *find_args)
         create_nonexistence_checker(name, *find_args)
-        create_rspec_existence_matchers(name) 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
 
       def create_helper_method(proposed_method_name, *find_args)
-        if find_args.empty?
-          create_error_method(proposed_method_name)
-        else
-          yield
-        end
-      end
+        return create_error_method(proposed_method_name) if find_args.empty?
 
-      def create_rspec_existence_matchers(element_name)
-        matcher = "has_#{element_name}?"
-        negated_matcher = "has_no_#{element_name}?"
-
-        RSpec::Matchers.define "have_#{element_name}" do |*args|
-          match { |actual| actual.public_send(matcher, *args) }
-          match_when_negated { |actual| actual.public_send(negated_matcher, *args) }
-        end
+        yield
       end
 
       def create_existence_checker(element_name, *find_args)
@@ -261,6 +296,10 @@ module SitePrism
 
       def create_error_method(name)
         SitePrism.logger.error("#{name} has come from an item with no locators.")
+        SitePrism::Deprecator.soft_deprecate(
+          'DSL definition with no find_args',
+          'All DSL elements should have find_args'
+        )
         define_method(name) { raise SitePrism::InvalidElementError }
       end
 
@@ -296,7 +335,7 @@ module SitePrism
       def extract_section_options(args, &block)
         if args.first.is_a?(Class)
           klass = args.shift
-          section_class = klass if klass.ancestors.include?(SitePrism::Section)
+          section_class = klass if klass <= SitePrism::Section
         end
 
         section_class = deduce_section_class(section_class, &block)
@@ -306,23 +345,26 @@ module SitePrism
 
       def deduce_section_class(base_class, &block)
         klass = base_class
-        klass = Class.new(klass || SitePrism::Section, &block) if block_given?
+        klass = Class.new(klass || SitePrism::Section, &block) if block
         return klass if klass
 
-        raise ArgumentError, "You should provide descendant of \
-SitePrism::Section class or/and a block as the second argument."
+        raise ArgumentError, 'You should provide descendant of SitePrism::Section class or/and a block as the second argument.'
       end
 
       def deduce_search_arguments(section_class, args)
         extract_search_arguments(args) ||
           extract_search_arguments(section_class.default_search_arguments) ||
-          raise(ArgumentError, "You should provide search arguments \
-in section creation or set_default_search_arguments within section class")
+          invalidate_search_arguments!
       end
 
       def extract_search_arguments(args)
         args if args && !args.empty?
       end
+
+      def invalidate_search_arguments!
+        SitePrism.logger.error('Could not deduce search_arguments')
+        raise(ArgumentError, 'search arguments are needed in `section` definition or alternatively use `set_default_search_arguments`')
+      end
     end
   end
 end

data/lib/site_prism/element_checker.rb

@@ -1,6 +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
@@ -21,20 +26,29 @@ 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)
-      if recursion == :none
-        elements_to_check.all? { |name| there?(name) }
-      elsif recursion == :one
-        all_there_with_recursion
+      case recursion
+      when :none; then elements_to_check.all? { |name| there?(name) }
+      when :one;  then all_there_with_recursion
       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
     end
 
+    # Returns each element that is currently present inside the scope being tested
+    #
+    # @return [Array]
     def elements_present
       _mapped_items.select { |name| there?(name) }
     end
 
+    # Returns each element that is not currently present inside the scope being tested
+    #
+    # @return [Array]
+    def elements_missing
+      elements_to_check.reject { |name| there?(name) }
+    end
+
     private
 
     def all_there_with_recursion

data/lib/site_prism/error.rb

@@ -25,14 +25,6 @@ module SitePrism
   # Formerly known as `NoSelectorForElement`
   class InvalidElementError < SitePrismError; end
 
-  # A tool like Timecop is being used to "freeze time" by overriding Time.now
-  # and similar methods. In this case, our waiter functions won't work, because
-  # Time.now does not change.
-  # If you encounter this issue, check that you are not doing Timecop.freeze without
-  # an accompanying Timecop.return.
-  # Also check out Timecop.safe_mode https://github.com/travisjeffery/timecop#timecopsafe_mode
-  class FrozenInTimeError < SitePrismError; end
-
   # The condition that was being evaluated inside the block did not evaluate
   # to true within the time limit
   # Formerly known as `TimeoutException`

data/lib/site_prism/loadable.rb

@@ -1,6 +1,13 @@
 # frozen_string_literal: true
 
 module SitePrism
+  # [SitePrism::Loadable]
+  #
+  # SitePrism Loadable's are defined as checks or waiters which "must" pass before
+  # the rest of the loading logic can be performed on a class or section.
+  #
+  # Loadable's are primarily used with the `#load` method which will auto-execute them all
+  # in their defined order. But they can be used dynamically wherever desired.
   module Loadable
     module ClassMethods
       # The list of load_validations.

data/lib/site_prism/page.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'site_prism/loadable'
-
 module SitePrism
   class Page
     include Capybara::DSL
@@ -12,25 +10,36 @@ module SitePrism
     class << self
       attr_reader :url
 
+      # Sets and returns the specific url that will be loaded for a page object
+      #
+      # @return [String]
       def set_url(page_url)
         @url = page_url.to_s
       end
 
+      # Sets and returns the specific url matcher that will be used to validate the page is loaded
+      #
+      # @return [Regexp]
       def set_url_matcher(page_url_matcher)
         @url_matcher = page_url_matcher
       end
 
+      # The specific url matcher that is used to validate the page is loaded.
+      # When one hasn't been previously set, use the url that was set as a direct Regexp exact matcher
+      #
+      # @return [Regexp]
       def url_matcher
         @url_matcher ||= url
       end
     end
 
+    # Where a Capybara HTML fragment has been directly injected into `#load` as a block return this loaded fragment
+    # Where a page has been directly navigated to through traditional means (i.e. Selenium), return an instance of the
+    # current Capybara session (With all applicable methods)
+    #
+    # @return [Capybara::Node::Simple || Capybara::Session]
     def page
-      if defined?(@page)
-        @page
-      else
-        Capybara.current_session
-      end
+      (defined?(@page) && @page) || Capybara.current_session
     end
 
     # Loads the page.
@@ -72,24 +81,19 @@ module SitePrism
       raise SitePrism::NoUrlMatcherForPageError unless url_matcher
 
       expected_mappings = args.last.is_a?(::Hash) ? args.pop : {}
-      seconds = args&.first || wait_time
+      seconds = args&.first || Capybara.default_max_wait_time
       Waiter.wait_until_true(seconds) { url_matches?(expected_mappings) }
     end
 
-    def url_matches(seconds = wait_time)
+    def url_matches(seconds = Capybara.default_max_wait_time)
       return unless displayed?(seconds)
+      return regexp_backed_matches if url_matcher.is_a?(Regexp)
 
-      if url_matcher.is_a?(Regexp)
-        regexp_backed_matches
-      else
-        template_backed_matches
-      end
+      template_backed_matches
     end
 
     def url(expansion = {})
-      return nil if self.class.url.nil?
-
-      Addressable::Template.new(self.class.url).expand(expansion).to_s
+      self.class.url && Addressable::Template.new(self.class.url).expand(expansion).to_s
     end
 
     def url_matcher
@@ -102,26 +106,6 @@ module SitePrism
 
     private
 
-    def _find(*find_args)
-      kwargs = find_args.pop
-      page.find(*find_args, **kwargs)
-    end
-
-    def _all(*find_args)
-      kwargs = find_args.pop
-      page.all(*find_args, **kwargs)
-    end
-
-    def element_exists?(*find_args)
-      kwargs = find_args.pop
-      page.has_selector?(*find_args, **kwargs)
-    end
-
-    def element_does_not_exist?(*find_args)
-      kwargs = find_args.pop
-      page.has_no_selector?(*find_args, **kwargs)
-    end
-
     def regexp_backed_matches
       url_matcher.match(page.current_url)
     end
@@ -165,7 +149,7 @@ module SitePrism
       visit expanded_url
       if with_validations
         when_loaded(&block)
-      elsif block_given?
+      elsif block
         yield self
       end
     end

data/lib/site_prism/recursion_checker.rb

@@ -3,6 +3,7 @@
 module SitePrism
   class RecursionChecker
     attr_reader :instance
+
     private :instance
 
     def initialize(instance)
@@ -28,7 +29,7 @@ module SitePrism
         expected(mapped_items, :elements),
         expected(mapped_items, :section),
         expected(mapped_items, :sections),
-        expected(mapped_items, :iframe),
+        expected(mapped_items, :iframe)
       ]
     end
 

data/lib/site_prism/rspec_matchers.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module SitePrism
+  class RspecMatchers
+    attr_reader :element_name
+
+    def initialize(element_name)
+      @element_name = element_name
+    end
+
+    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)
+    end
+
+    private
+
+    def create_rspec_existence_matchers(matcher, object_method, negated_object_method, warning)
+      RSpec::Matchers.define(matcher) do |*args|
+        match { |actual| actual.public_send(object_method, *args) }
+        match_when_negated do |actual|
+          return actual.public_send(negated_object_method, *args) if actual.respond_to?(negated_object_method)
+
+          SitePrism.logger.debug(warning)
+          !actual.public_send(object_method, *args)
+        end
+      end
+    end
+
+    def matcher
+      "have_#{element_name}"
+    end
+
+    def object_method
+      "has_#{element_name}?"
+    end
+
+    def negated_object_method
+      "has_no_#{element_name}?"
+    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. "\
+        'Falling back to the default RSpec matcher.'
+    end
+  end
+end

data/lib/site_prism/section.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 
-require 'site_prism/loadable'
-
 module SitePrism
   class Section
-    include Capybara::DSL
     include ElementChecker
     include Loadable
     include DSL
@@ -12,48 +9,67 @@ module SitePrism
 
     attr_reader :root_element, :parent
 
-    def self.set_default_search_arguments(*args)
-      @default_search_arguments = args
-    end
+    class << self
+      def set_default_search_arguments(*args)
+        @default_search_arguments = args
+      end
+
+      def default_search_arguments
+        return @default_search_arguments if @default_search_arguments
+
+        superclass.respond_to?(:default_search_arguments) && superclass.default_search_arguments
+      end
 
-    def self.default_search_arguments
-      @default_search_arguments ||
-        (
-          superclass.respond_to?(:default_search_arguments) &&
-          superclass.default_search_arguments
-        ) ||
-        nil
+      private
+
+      def root_element_methods
+        ::Capybara::Session::NODE_METHODS + %i[native visible?]
+      end
+
+      def session_methods
+        ::Capybara::Session::DSL_METHODS - root_element_methods
+      end
     end
 
     def initialize(parent, root_element, &block)
       @parent = parent
       @root_element = root_element
-      within(&block) if block_given?
+      within(&block) if block
     end
 
-    def within
-      Capybara.within(@root_element) { yield(self) }
+    # Send all root_element methods through `#root_element`
+    # NB: This requires a method called `#to_capybara_node` being created and
+    # then set to this value (Capybara agnostic API)
+    root_element_methods.each do |method|
+      def_delegators :root_element, method
     end
 
-    # Capybara::DSL module "delegates" Capybara methods to the "page" method
-    # as such we need to overload this method so that the correct scoping
-    # occurs and calls within a section (For example section.find(element))
-    # correctly scope to look within the section only
-    def page
-      return root_element if root_element
+    # Send all methods that previously acted on the `#page` method that existed previously
+    # through to the same location - But directly as `Capybara.current_session`
+    session_methods.each do |method|
+      def_delegators :capybara_session, method
+    end
 
-      SitePrism.logger.warn('Root Element not found; Falling back to `super`')
-      super
+    # This scopes our calls inside Section correctly to the `Capybara::Node::Element`
+    def to_capybara_node
+      root_element
     end
 
-    def visible?
-      page.visible?
+    # This allows us to return anything thats passed in as a block to the section at
+    # creation time, so that an anonymous section or such-like will have the extra methods
+    def within
+      Capybara.within(root_element) { yield(self) }
     end
 
-    def_delegators :capybara_session,
-                   :execute_script,
-                   :evaluate_script,
-                   :within_frame
+    # 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::Deprecator.deprecate('Using page inside section')
+      return root_element if root_element
+
+      SitePrism.logger.warn('Root Element not found; Falling back to Capybara.current_session')
+      capybara_session
+    end
 
     def capybara_session
       Capybara.current_session
@@ -64,31 +80,5 @@ module SitePrism
       candidate = candidate.parent until candidate.is_a?(SitePrism::Page)
       candidate
     end
-
-    def native
-      root_element.native
-    end
-
-    private
-
-    def _find(*find_args)
-      kwargs = find_args.pop
-      page.find(*find_args, **kwargs)
-    end
-
-    def _all(*find_args)
-      kwargs = find_args.pop
-      page.all(*find_args, **kwargs)
-    end
-
-    def element_exists?(*find_args)
-      kwargs = find_args.pop
-      page.has_selector?(*find_args, **kwargs)
-    end
-
-    def element_does_not_exist?(*find_args)
-      kwargs = find_args.pop
-      page.has_no_selector?(*find_args, **kwargs)
-    end
   end
 end

data/lib/site_prism/timer.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module SitePrism
+  # [SitePrism::Timer]
+  #
+  # Used to count asynchronously towards an overall desired duration or condition (Block)
+  class Timer
+    attr_reader :wait_time
+
+    # Return &block
+    #
+    # Count towards a specified time (Supplied)
+    def self.run(wait_time, &block)
+      new(wait_time).run(&block)
+    end
+
+    def initialize(wait_time)
+      @wait_time = wait_time
+      @done = false
+    end
+
+    # Return Boolean
+    #
+    # Whether the timer has completed
+    def done?
+      @done == true
+    end
+
+    # Return &block
+    #
+    # Start the Timer and re-evaluate the block repeatedly
+    def run
+      start
+      yield self
+    ensure
+      stop
+    end
+
+    # Return [Boolean, Nil]
+    #
+    # Start the Timer in a separate process
+    def start
+      stop
+      return if wait_time.zero?
+
+      @done = false
+      @thread = Thread.start do
+        sleep wait_time
+        @done = true
+      end
+    end
+
+    # Return True
+    #
+    # Forcibly stop the timer, and kill any threads created by it
+    def stop
+      if @thread
+        @thread.kill
+        @thread.join
+        @thread = nil
+      end
+      @done = true
+    end
+  end
+end

data/lib/site_prism/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SitePrism
-  VERSION = '3.5'
+  VERSION = '3.7.2'
 end

data/lib/site_prism/waiter.rb

@@ -1,34 +1,22 @@
 # frozen_string_literal: true
 
 module SitePrism
+  # [SitePrism::Waiter]
   class Waiter
-    class << self
-      def wait_until_true(wait_time = Capybara.default_max_wait_time)
-        start_time = Time.now
-
+    # @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
+    def self.wait_until_true(wait_time = Capybara.default_max_wait_time)
+      Timer.run(wait_time) do |timer|
         loop do
           return true if yield
-          break if Time.now - start_time > wait_time
+          break if timer.done?
 
           sleep(0.05)
-
-          check_for_time_stopped!(start_time)
         end
-
         raise SitePrism::TimeoutError, "Timed out after #{wait_time}s."
       end
-
-      private
-
-      def check_for_time_stopped!(start_time)
-        return unless start_time == Time.now
-
-        raise(
-          SitePrism::FrozenInTimeError,
-          'Time appears to be frozen. For more info, see ' \
-          'https://github.com/site-prism/site_prism/blob/master/lib/site_prism/error.rb'
-        )
-      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: site_prism
 version: !ruby/object:Gem::Version
-  version: '3.5'
+  version: 3.7.2
 platform: ruby
 authors:
 - Luke Hill
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-06-04 00:00:00.000000000 Z
+date: 2021-08-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable
@@ -29,16 +29,16 @@ dependencies:
   name: capybara
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "<="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.29'
+        version: '3.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "<="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.29'
+        version: '3.8'
 - !ruby/object:Gem::Dependency
   name: site_prism-all_there
   requirement: !ruby/object:Gem::Requirement
@@ -63,16 +63,22 @@ dependencies:
   name: cucumber
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.2'
 - !ruby/object:Gem::Dependency
   name: pry-byebug
   requirement: !ruby/object:Gem::Requirement
@@ -91,114 +97,120 @@ dependencies:
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.3'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.3'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.8'
+        version: '3.9'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.8'
+        version: '3.9'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.75.0
+        version: 0.93.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.75.0
+        version: 0.93.0
 - !ruby/object:Gem::Dependency
   name: rubocop-performance
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.5.1
+        version: 1.10.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.5.1
+        version: 1.10.1
 - !ruby/object:Gem::Dependency
   name: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.33.0
+        version: 1.44.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.33.0
+        version: 1.44.0
 - !ruby/object:Gem::Dependency
   name: selenium-webdriver
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '3.7'
+        version: '3.11'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '3.7'
+        version: '3.11'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.1'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.17'
+        version: '0.18'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.17'
+        version: '0.18'
 - !ruby/object:Gem::Dependency
   name: webdrivers
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '4.5'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '4.5'
 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:
@@ -220,7 +232,9 @@ files:
 - lib/site_prism/logger.rb
 - lib/site_prism/page.rb
 - lib/site_prism/recursion_checker.rb
+- lib/site_prism/rspec_matchers.rb
 - lib/site_prism/section.rb
+- lib/site_prism/timer.rb
 - lib/site_prism/version.rb
 - lib/site_prism/waiter.rb
 homepage: https://github.com/site-prism/site_prism
@@ -228,7 +242,7 @@ licenses:
 - BSD-3-Clause
 metadata:
   bug_tracker_uri: https://github.com/site-prism/site_prism/issues
-  changelog_uri: https://github.com/site-prism/site_prism/blob/master/CHANGELOG.md
+  changelog_uri: https://github.com/site-prism/site_prism/blob/main/CHANGELOG.md
   source_code_uri: https://github.com/site-prism/site_prism
 post_install_message: 
 rdoc_options: []
@@ -238,14 +252,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.3'
+      version: '2.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.6
+rubygems_version: 3.0.8
 signing_key: 
 specification_version: 4
 summary: A Page Object Model DSL for Capybara