site_prism 3.6 → 3.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ec5104247e3512bd7ebf0a48c579cc92041ef21b9c130531ef0cb4ff5a52f88
-  data.tar.gz: a44ff822766bb37ff023048349037c0467ae47333d4b421bc53d8a59cb2af087
+  metadata.gz: 77096cbc91dc0e53b17b8f1af09415d52be9f2859333874869af7a4b07f3e488
+  data.tar.gz: 3562488e2a5122a6e71a43f3f042c6c18c6b97d89ee4bee8cf39efdbbd7963e3
 SHA512:
-  metadata.gz: 1a6991ecd0110bb53533fb848c40753a13067aed17913f2dd261a5d0b4c8c1747f9f54d1be83d954856037e6cbd24abd665d498b74ff0ad835ab1bea1e0a084a
-  data.tar.gz: bcfe1f63bcaf2b20c64241c03b1c9c718628609fa0bdaa67c01a78b02964b809135aa815e6b0073d4272235226eda5ad802b8b6852d8b118d0806d96e09e2068
+  metadata.gz: 5a97080c7a80c18b4fee6e4673957a16fe9a97a98d87b2cf4d4add2ce76500b326008684626757c16a090bc8a82a3363bd85d49b2b266815bcec49897f82b394
+  data.tar.gz: 22b3dc450956bbfbc05e0950815395c3cc4f44b9c5c8d28553cf784b8f95872f604ba177dab2a1b75c88f386f4a86544ee2fc46f70e1cf0c771b5a0bf0123cc3

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

@@ -1,29 +1,40 @@
 # SitePrism
 [![Gem Version](https://badge.fury.io/rb/site_prism.svg)](https://badge.fury.io/rb/site_prism)
-[![Build Status](https://travis-ci.com/site-prism/site_prism.png)](https://travis-ci.com/site-prism/site_prism)
+[![Build Status](https://github.com/site-prism/site_prism/actions/workflows/ci.yml/badge.svg)](https://github.com/site-prism/site_prism/actions/workflows/ci.yml)
 
 _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
@@ -1489,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

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
@@ -126,7 +128,7 @@ module SitePrism
     end
 
     # If a slug begins with non-alpha characters, it may denote the start of
-    # a new component (e.g. query or fragment). We emit thie prefix as part of
+    # a new component (e.g. query or fragment). We emit this prefix as part of
     # the substituted slug so that Addressable's URI parser can see it as such.
     def slug_prefix(slug)
       prefix = slug.match(/\A{([^A-Za-z]+)/)

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,33 +15,28 @@ module SitePrism
 
     private
 
-    # Call `find` inside context set on page/section
+    # Call `find` inside `to_capybara_node` context (Either Capybara::Session or Capybara::Node::Element)
     def _find(*find_args)
       kwargs = find_args.pop
-      page.find(*find_args, **kwargs)
+      to_capybara_node.find(*find_args, **kwargs)
     end
 
-    # Call `all` inside context set on page/section
+    # Call `all` inside `to_capybara_node` context (Either Capybara::Session or Capybara::Node::Element)
     def _all(*find_args)
       kwargs = find_args.pop
-      page.all(*find_args, **kwargs)
+      to_capybara_node.all(*find_args, **kwargs)
     end
 
-    # Call `has_selector?` inside context set on page/section
+    # Call `has_selector?` inside `to_capybara_node` context (Either Capybara::Session or Capybara::Node::Element)
     def element_exists?(*find_args)
       kwargs = find_args.pop
-      page.has_selector?(*find_args, **kwargs)
+      to_capybara_node.has_selector?(*find_args, **kwargs)
     end
 
-    # Call `has_no_selector?` inside context set on page/section
+    # 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
-      page.has_no_selector?(*find_args, **kwargs)
-    end
-
-    # The default waiting time set by Capybara's configuration settings.
-    def wait_time
-      Capybara.default_max_wait_time
+      to_capybara_node.has_no_selector?(*find_args, **kwargs)
     end
 
     # Prevent users from calling methods with blocks when they shouldn't be.
@@ -92,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
@@ -118,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
@@ -129,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
@@ -144,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
@@ -169,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
@@ -189,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)
@@ -222,11 +245,9 @@ module SitePrism
       end
 
       def create_helper_method(proposed_method_name, *find_args)
-        if find_args.empty?
-          create_error_method(proposed_method_name)
-        else
-          yield
-        end
+        return create_error_method(proposed_method_name) if find_args.empty?
+
+        yield
       end
 
       def create_existence_checker(element_name, *find_args)
@@ -275,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
 
@@ -310,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)
@@ -320,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,25 @@ 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

data/lib/site_prism/loadable.rb

@@ -1,46 +1,14 @@
 # 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.
-      # They will be executed in the order they are defined.
-      #
-      # @return [Array]
-      def load_validations
-        if superclass.respond_to?(:load_validations)
-          superclass.load_validations + _load_validations
-        else
-          _load_validations
-        end
-      end
-
-      # Appends a load validation block to the page class.
-      #
-      # When `loaded?` is called, these blocks are instance_eval'd
-      # against the current page instance.
-      # This allows users to wait for specific events to occur on
-      # the page or certain elements to be loaded before performing
-      # any actions on the page.
-      #
-      # @param block [&block] A block which returns true if the page
-      # loaded successfully, or false if it did not.
-      # This block can contain up to 2 elements in an array
-      # The first is the physical validation test to be truthily evaluated.
-      #
-      # If this does not pass, then the 2nd item (if defined), is output
-      # as an error message to the +FailedLoadValidationError+ that is thrown
-      def load_validation(&block)
-        _load_validations << block
-      end
-
-      private
-
-      def _load_validations
-        @_load_validations ||= []
-      end
-    end
-
     def self.included(base)
       base.extend(ClassMethods)
     end
@@ -99,5 +67,51 @@ module SitePrism
         passed
       end
     end
+
+    # [SitePrism::Loadable::ClassMethods]
+    # This exposes all of the DSL definitions users will use when generating "loadables"
+    #
+    # A "Loadable" is a definition whereby the page object once loaded must pass a boolean check
+    # These loadables are typically provided using the method `load_validation`
+    module ClassMethods
+      # The list of load_validations.
+      # They will be executed in the order they are defined.
+      #
+      # @return [Array]
+      def load_validations
+        if superclass.respond_to?(:load_validations)
+          superclass.load_validations + _load_validations
+        else
+          _load_validations
+        end
+      end
+
+      # Appends a load validation block to the page class.
+      #
+      # When `loaded?` is called, these blocks are instance_eval'd
+      # against the current page instance.
+      # This allows users to wait for specific events to occur on
+      # the page or certain elements to be loaded before performing
+      # any actions on the page.
+      #
+      # @param block [&block] A block which returns true if the page
+      # loaded successfully, or false if it did not.
+      # This block can contain up to 2 elements in an array
+      # The first is the physical validation test to be truthily evaluated.
+      #
+      # If this does not pass, then the 2nd item (if defined), is output
+      # as an error message to the +FailedLoadValidationError+ that is thrown
+      #
+      # @return [Proc]
+      def load_validation(&block)
+        _load_validations << block
+      end
+
+      private
+
+      def _load_validations
+        @_load_validations ||= []
+      end
+    end
   end
 end

data/lib/site_prism/page.rb

@@ -10,23 +10,43 @@ 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
       (defined?(@page) && @page) || Capybara.current_session
     end
 
+    # This scopes our calls inside Page correctly to the `Capybara::Session`
+    def to_capybara_node
+      page
+    end
+
     # Loads the page.
     # @param expansion_or_html
     # @param block [&block] An optional block to run once the page is loaded.
@@ -66,11 +86,11 @@ 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)
 
@@ -134,7 +154,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)

data/lib/site_prism/rspec_matchers.rb

@@ -19,9 +19,7 @@ module SitePrism
       RSpec::Matchers.define(matcher) do |*args|
         match { |actual| actual.public_send(object_method, *args) }
         match_when_negated do |actual|
-          if actual.respond_to?(negated_object_method)
-            return actual.public_send(negated_object_method, *args)
-          end
+          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)

data/lib/site_prism/section.rb

@@ -2,7 +2,6 @@
 
 module SitePrism
   class Section
-    include Capybara::DSL
     include ElementChecker
     include Loadable
     include DSL
@@ -10,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
+
+      private
 
-    def self.default_search_arguments
-      @default_search_arguments ||
-        (
-          superclass.respond_to?(:default_search_arguments) &&
-          superclass.default_search_arguments
-        ) ||
-        nil
+      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
@@ -62,9 +80,5 @@ module SitePrism
       candidate = candidate.parent until candidate.is_a?(SitePrism::Page)
       candidate
     end
-
-    def native
-      root_element.native
-    end
   end
 end

data/lib/site_prism/timer.rb

@@ -1,9 +1,15 @@
 # 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
@@ -13,10 +19,16 @@ module SitePrism
       @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
@@ -24,6 +36,9 @@ module SitePrism
       stop
     end
 
+    # Return [Boolean, Nil]
+    #
+    # Start the Timer in a separate process
     def start
       stop
       return if wait_time.zero?
@@ -35,6 +50,9 @@ module SitePrism
       end
     end
 
+    # Return True
+    #
+    # Forcibly stop the timer, and kill any threads created by it
     def stop
       if @thread
         @thread.kill

data/lib/site_prism/version.rb

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

data/lib/site_prism/waiter.rb

@@ -1,18 +1,19 @@
 # frozen_string_literal: true
 
 module SitePrism
+  # [SitePrism::Waiter]
   class Waiter
-    def self.sleep_duration
-      0.05
-    end
-
+    # @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 timer.done?
 
-          sleep(sleep_duration)
+          sleep(0.05)
         end
         raise SitePrism::TimeoutError, "Timed out after #{wait_time}s."
       end

data/lib/site_prism.rb

@@ -3,6 +3,8 @@
 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 :DSL, 'site_prism/dsl'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: site_prism
 version: !ruby/object:Gem::Version
-  version: '3.6'
+  version: 3.7.3
 platform: ruby
 authors:
 - Luke Hill
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-08-17 00:00:00.000000000 Z
+date: 2021-09-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable
@@ -17,34 +17,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.5'
+        version: '2.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.5'
+        version: '2.6'
 - !ruby/object:Gem::Dependency
   name: capybara
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '3.8'
-    - - "<="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.29'
+        version: '3.15'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '3.8'
-    - - "<="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.29'
+        version: '3.15'
 - !ruby/object:Gem::Dependency
   name: site_prism-all_there
   requirement: !ruby/object:Gem::Requirement
@@ -69,16 +63,22 @@ dependencies:
   name: cucumber
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">"
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: '4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">"
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: '4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
 - !ruby/object:Gem::Dependency
   name: pry-byebug
   requirement: !ruby/object:Gem::Requirement
@@ -93,83 +93,69 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '12.3'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '12.3'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.8'
+        version: '3.10'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.8'
+        version: '3.10'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.81.0
+        version: 1.11.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.81.0
+        version: 1.11.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: 2.2.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.33.0
+        version: 2.2.0
 - !ruby/object:Gem::Dependency
   name: selenium-webdriver
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '3.9'
+        version: '3.13'
     - - "<"
       - !ruby/object:Gem::Version
         version: '4.1'
@@ -179,7 +165,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '3.9'
+        version: '3.13'
     - - "<"
       - !ruby/object:Gem::Version
         version: '4.1'
@@ -189,28 +175,28 @@ dependencies:
     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.1'
+        version: '4.6'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.1'
+        version: '4.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:
@@ -242,7 +228,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: []
@@ -259,7 +245,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !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