site_prism 3.7 → 3.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: adf8cf393fc3ad828528159a54048e54c3c396f3743c79b10a75ea313ddd135c
-  data.tar.gz: f2fb2ecb2f8942e3e59228994da32262a65b14a2c49f573468100f1aca799061
+  metadata.gz: c5deda0d9df9e83e2a66663a217cf5c434fd3ed25abae0d14778d99cd5db1c0f
+  data.tar.gz: 6c86aff27c00c5e91b01667f7da1f9ee6e2d33d4f95d18fbb0cfdd9fd44779c5
 SHA512:
-  metadata.gz: aecf017750d915a617052242d8959af91ec1b154e5d394f2fa7df096649cf198052ecdf25cef22476f88682c45d71ff6c49c39262726d7d75ea33d07b751f47b
-  data.tar.gz: e2ed8f07246c08e910fd870ecc9140f813619109b107ae6448d59f98176b84b6f50c58cc8609615e68f5ddd0e09076b3b30f906fe0647994d78ec4df7b2d1941
+  metadata.gz: 254398e151d390326bf085d0746391aedd247d1ed8bf47909d8fb87752b6cedd056ff32c14f324d5b33f4b922734ed01ec2467f64be59a8d97a07cf8aa002eea
+  data.tar.gz: 652781ebe825ed5f943ca0f8480a9b5fbd511e81e6c12d9ce95de7c3239073d4499f4165044c8c58888aeabf0cf2d9bc76e4ca6f2ae6baa6996093117577005a

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

@@ -11,17 +11,28 @@ 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 run on Chrome and Firefox.
 
@@ -1504,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.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'

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,12 @@
 # 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 +17,13 @@ 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
@@ -32,11 +39,6 @@ module SitePrism
       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
-    end
-
     # Prevent users from calling methods with blocks when they shouldn't be.
     #
     # Example (Triggering error):
@@ -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
@@ -170,11 +198,9 @@ module SitePrism
       end
 
       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 +215,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 +242,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 +293,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 +332,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)
@@ -323,20 +345,23 @@ module SitePrism
         klass = Class.new(klass || SitePrism::Section, &block) if block_given?
         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,10 +26,9 @@ 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?.')

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

@@ -66,11 +66,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)
 

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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: site_prism
 version: !ruby/object:Gem::Version
-  version: '3.7'
+  version: 3.7.1
 platform: ruby
 authors:
 - Luke Hill
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-10-15 00:00:00.000000000 Z
+date: 2021-02-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable
@@ -65,14 +65,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: '4.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: pry-byebug
   requirement: !ruby/object:Gem::Requirement
@@ -91,72 +91,72 @@ 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.83.0
+        version: 0.90.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.83.0
+        version: 0.90.0
 - !ruby/object:Gem::Dependency
   name: rubocop-performance
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.5.1
+        version: 1.8.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.5.1
+        version: 1.8.1
 - !ruby/object:Gem::Dependency
   name: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.33.0
+        version: 1.38.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.33.0
+        version: 1.38.0
 - !ruby/object:Gem::Dependency
   name: selenium-webdriver
   requirement: !ruby/object:Gem::Requirement
@@ -197,14 +197,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.1'
+        version: '4.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.1'
+        version: '4.3'
 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:
@@ -236,7 +236,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: []
@@ -253,7 +253,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