site_prism 3.7.3 → 4.0

data/lib/site_prism/dsl.rb

@@ -11,65 +11,39 @@ module SitePrism
   module DSL
     def self.included(klass)
       klass.extend ClassMethods
+      klass.extend DSLValidator
     end
 
     private
 
-    # Call `find` inside `to_capybara_node` context (Either Capybara::Session or Capybara::Node::Element)
+    def raise_if_runtime_block_supplied(object, name, has_block, type)
+      return unless has_block
+
+      SitePrism.logger.debug("Type passed in: #{type}")
+      SitePrism.logger.error("#{object.class}##{name} cannot accept runtime blocks")
+      raise SitePrism::UnsupportedBlockError
+    end
+
     def _find(*find_args)
       kwargs = find_args.pop
       to_capybara_node.find(*find_args, **kwargs)
     end
 
-    # Call `all` inside `to_capybara_node` context (Either Capybara::Session or Capybara::Node::Element)
     def _all(*find_args)
       kwargs = find_args.pop
       to_capybara_node.all(*find_args, **kwargs)
     end
 
-    # Call `has_selector?` inside `to_capybara_node` context (Either Capybara::Session or Capybara::Node::Element)
     def element_exists?(*find_args)
       kwargs = find_args.pop
       to_capybara_node.has_selector?(*find_args, **kwargs)
     end
 
-    # Call `has_no_selector?` inside `to_capybara_node` context (Either Capybara::Session or Capybara::Node::Element)
     def element_does_not_exist?(*find_args)
       kwargs = find_args.pop
       to_capybara_node.has_no_selector?(*find_args, **kwargs)
     end
 
-    # Prevent users from calling methods with blocks when they shouldn't be.
-    #
-    # Example (Triggering error):
-    #
-    #       class MyPage
-    #         element :sample, '.css-locator' do
-    #           puts "This won't be output"
-    #         end
-    #       end
-    #
-    # At runtime this will generate a `SitePrism::UnsupportedBlockError`
-    #
-    # The only DSL keywords that can use blocks are :section and :iframe
-    def raise_if_block(obj, name, has_block, type)
-      return unless has_block
-
-      SitePrism.logger.debug("Type passed in: #{type}")
-      SitePrism.logger.warn('section / iFrame can only accept blocks.')
-      SitePrism.logger.error("#{obj.class}##{name} does not accept blocks")
-
-      raise SitePrism::UnsupportedBlockError
-    end
-
-    # Warn users from naming the elements starting with no_
-    def warn_if_dsl_collision(obj, name)
-      return unless name.to_s.start_with?('no_')
-
-      SitePrism.logger.warn("#{obj.class}##{name} should not start with no_")
-      SitePrism::Deprecator.deprecate('Using no_ prefix in DSL definition')
-    end
-
     # Sanitize method called before calling any SitePrism DSL method or
     # meta-programmed method. This ensures that the Capybara query is correct.
     #
@@ -112,17 +86,23 @@ module SitePrism
     module ClassMethods
       attr_reader :expected_items
 
+      # 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 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?
+        raise_if_build_time_block_supplied(self, name, block_given?, :element)
         build(:element, name, *find_args) do
-          define_method(name) do |*runtime_args, &element_block|
-            warn_if_dsl_collision(self, name)
-            raise_if_block(self, name, !element_block.nil?, :element)
+          define_method(name) do |*runtime_args, &runtime_block|
+            raise_if_runtime_block_supplied(self, name, runtime_block, :element)
             _find(*merge_args(find_args, runtime_args))
           end
         end
@@ -134,23 +114,15 @@ module SitePrism
       # Wait for the elements to be present or not -> @return [TrueClass, SitePrism::Error]
       # Validate certain properties about the elements
       def elements(name, *find_args)
-        SitePrism::Deprecator.deprecate('Passing a block to :elements') if block_given?
+        raise_if_build_time_block_supplied(self, name, block_given?, :elements)
         build(:elements, name, *find_args) do
-          define_method(name) do |*runtime_args, &element_block|
-            warn_if_dsl_collision(self, name)
-            raise_if_block(self, name, !element_block.nil?, :elements)
+          define_method(name) do |*runtime_args, &runtime_block|
+            raise_if_runtime_block_supplied(self, name, runtime_block, :elements)
             _all(*merge_args(find_args, runtime_args))
           end
         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]
@@ -160,7 +132,6 @@ module SitePrism
         section_class, find_args = extract_section_options(args, &block)
         build(:section, name, *find_args) do
           define_method(name) do |*runtime_args, &runtime_block|
-            warn_if_dsl_collision(self, name)
             section_element = _find(*merge_args(find_args, runtime_args))
             section_class.new(self, section_element, &runtime_block)
           end
@@ -175,8 +146,8 @@ module SitePrism
       def sections(name, *args, &block)
         section_class, find_args = extract_section_options(args, &block)
         build(:sections, name, *find_args) do
-          define_method(name) do |*runtime_args, &element_block|
-            raise_if_block(self, name, !element_block.nil?, :sections)
+          define_method(name) do |*runtime_args, &runtime_block|
+            raise_if_runtime_block_supplied(self, name, runtime_block, :sections)
             _all(*merge_args(find_args, runtime_args)).map do |element|
               section_class.new(self, element)
             end
@@ -185,7 +156,7 @@ module SitePrism
       end
 
       def iframe(name, klass, *args)
-        SitePrism.logger.debug('Block passed into iFrame construct at build time') if block_given?
+        raise_if_build_time_block_supplied(self, name, block_given?, :elements)
         element_find_args = deduce_iframe_element_find_args(args)
         scope_find_args = deduce_iframe_scope_find_args(args)
         build(:iframe, name, *element_find_args) do
@@ -200,46 +171,30 @@ module SitePrism
       # Return a list of all mapped items on a SitePrism class instance (Page or Section)
       # If legacy is set to true (Default) -> @return [Array]
       # If legacy is set to false (New behaviour) -> @return [Hash]
-      def mapped_items(legacy: true)
-        return old_mapped_items if legacy
+      def mapped_items(legacy: false)
+        return legacy_mapped_items if legacy
 
-        new_mapped_items
+        @mapped_items ||= { element: [], elements: [], section: [], sections: [], iframe: [] }
       end
 
       private
 
-      def old_mapped_items
-        SitePrism::Deprecator.soft_deprecate(
-          '.mapped_items on a class',
-          'To allow easier recursion through the items in conjunction with #all_there?',
-          '.mapped_items(legacy: false)'
-        )
-        @old_mapped_items ||= []
-      end
-
-      def new_mapped_items
-        @new_mapped_items ||= { element: [], elements: [], section: [], sections: [], iframe: [] }
-      end
-
       def build(type, name, *find_args)
+        raise InvalidDSLNameError if ENV.fetch('SITEPRISM_DSL_VALIDATION_ENABLED', nil) && invalid?(name)
+
         if find_args.empty?
           create_error_method(name)
         else
           map_item(type, name)
           yield
         end
-        add_helper_methods(name, *find_args)
+        add_helper_methods(name, type, *find_args)
       end
 
-      def map_item(type, name)
-        old_mapped_items << { type => name }
-        new_mapped_items[type] << name.to_sym
-      end
-
-      def add_helper_methods(name, *find_args)
+      def add_helper_methods(name, _type, *find_args)
         create_existence_checker(name, *find_args)
         create_nonexistence_checker(name, *find_args)
-        SitePrism::RspecMatchers.new(name)._create_rspec_existence_matchers if defined?(RSpec)
+        SitePrism::RSpecMatchers.new(name)._create_rspec_existence_matchers if defined?(RSpec)
         create_visibility_waiter(name, *find_args)
         create_invisibility_waiter(name, *find_args)
       end
@@ -295,14 +250,35 @@ module SitePrism
       end
 
       def create_error_method(name)
-        SitePrism.logger.error("#{name} has come from an item with no locators.")
-        SitePrism::Deprecator.soft_deprecate(
+        SitePrism::Deprecator.deprecate(
           'DSL definition with no find_args',
-          'All DSL elements should have find_args'
+          'DSL definition with at least 1 find_arg'
         )
+        SitePrism.logger.error("#{name} has come from an item with no locators.")
         define_method(name) { raise SitePrism::InvalidElementError }
       end
 
+      def raise_if_build_time_block_supplied(parent_object, name, has_block, type)
+        return unless has_block
+
+        SitePrism.logger.debug("Type passed in: #{type}")
+        SitePrism.logger.error("#{name} has been defined as a '#{type}' item in #{parent_object}. It does not accept build-time blocks.")
+        raise SitePrism::UnsupportedBlockError
+      end
+
+      def legacy_mapped_items
+        SitePrism::Deprecator.deprecate(
+          '.mapped_items structure (internally), on a class',
+          'Thew new .mapped_items structure'
+        )
+        @legacy_mapped_items ||= []
+      end
+
+      def map_item(type, name)
+        mapped_items(legacy: true) << { type => name }
+        mapped_items[type] << name.to_sym
+      end
+
       def deduce_iframe_scope_find_args(args)
         warn_on_invalid_selector_input(args)
         case args[0]

data/lib/site_prism/dsl_validator.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module SitePrism
+  # [SitePrism::DSLValidator]
+  #
+  # This is the new validator module which will check all DSL items against a whitelist
+  # for any entries which are prohibited
+  module DSLValidator
+    def invalid?(name)
+      prefix_invalid?(name) ||
+        suffix_invalid?(name) ||
+        characters_invalid?(name) ||
+        blacklisted?(name)
+    end
+
+    private
+
+    def prefix_invalid?(name)
+      prefix_blacklist.any? { |prefix| name.start_with?(prefix) }.tap { |result| log_failure(name, 'prefix') unless result }
+    end
+
+    def suffix_invalid?(name)
+      suffix_blacklist.any? { |prefix| name.end_with?(prefix) }.tap { |result| log_failure(name, 'suffix') unless result }
+    end
+
+    def characters_invalid?(name)
+      !name.match?(regex_permission).tap { |result| log_failure(name, 'character(s)') unless result }
+    end
+
+    def blacklisted?(name)
+      blacklisted_names.include?(name).tap { |result| log_failure(name, 'name (blacklisted entry)') unless result }
+    end
+
+    def regex_permission
+      /^[a-z]\w+$/
+    end
+
+    def prefix_blacklist
+      %w[
+        no_
+        _
+      ]
+    end
+
+    def suffix_blacklist
+      %w[
+        _
+        ?
+      ]
+    end
+
+    def blacklisted_names
+      %w[
+        attributes
+        html
+        no
+        title
+      ]
+    end
+
+    def log_failure(name, type)
+      SitePrism.logger.error("DSL item: #{name} has an invalid #{type}")
+      SitePrism.logger.debug(debug_error(type))
+    end
+
+    def debug_error(type)
+      case type
+      when 'prefix';       then "Invalid Prefixes: #{prefix_blacklist.join(', ')}."
+      when 'suffix';       then "Invalid Suffixes: #{suffix_blacklist.join(', ')}"
+      when 'character(s)'; then "Invalid DSL Names: #{blacklisted_names.join(', ')}"
+      else                      "DSL Charset REGEX: #{regex_permission.inspect}"
+      end
+    end
+  end
+end

data/lib/site_prism/element_checker.rb

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

data/lib/site_prism/error.rb

@@ -8,50 +8,46 @@ module SitePrism
   class PageLoadError < SitePrismError; end
 
   # A page calls #load with no URL set
-  # Formerly known as `NoUrlForPage`
   class NoUrlForPageError < PageLoadError; end
 
   # A page calls #displayed? with no URL matcher set
-  # Formerly known as `NoUrlMatcherForPage`
   class NoUrlMatcherForPageError < PageLoadError; end
 
   # The URL matcher was not recognised as a Regex or String and as such
   # it couldn't be parsed by Addressable. It also could be caused by
   # the usage of templated port numbers - which aren't supported
-  # Formerly known as `InvalidUrlMatcher`
   class InvalidUrlMatcherError < PageLoadError; end
 
   # A SitePrism defined DSL item was defined without a selector
-  # Formerly known as `NoSelectorForElement`
   class InvalidElementError < SitePrismError; end
 
   # The condition that was being evaluated inside the block did not evaluate
   # to true within the time limit
-  # Formerly known as `TimeoutException`
   class TimeoutError < SitePrismError; end
 
   # The wait_until_*_visible meta-programmed method didn't evaluate to true
   # within the prescribed time limit
-  # Formerly known as `TimeOutWaitingForElementVisibility`
   class ElementVisibilityTimeoutError < TimeoutError; end
 
   # The wait_until_*_invisible meta-programmed method didn't evaluate to true
   # within the prescribed time limit
-  # Formerly known as `TimeOutWaitingForElementInvisibility`
   class ElementInvisibilityTimeoutError < TimeoutError; end
 
   # Generic Block validation family of errors inherit from this error
   class BlockError < SitePrismError; end
 
   # A Block was passed to the method, which it cannot interpret
-  # Formerly known as `UnsupportedBlock`
   class UnsupportedBlockError < BlockError; end
 
   # A Block was required, but not supplied
-  # Formerly known as `BlockMissingError`
   class MissingBlockError < BlockError; end
 
   # A page was loaded then failed one of the validations defined by the user
-  # Formerly known as `NotLoadedError`
   class FailedLoadValidationError < PageLoadError; end
+
+  # Generic Attribute validation family of errors inherit from this error
+  class AttributeValidationError < SitePrismError; end
+
+  # DSL items are not permitted to start with certain prefixes
+  class InvalidDSLNameError < AttributeValidationError; end
 end

data/lib/site_prism/loadable.rb

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

data/lib/site_prism/page.rb

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

data/lib/site_prism/rspec_matchers.rb

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

data/lib/site_prism/section.rb

@@ -1,6 +1,15 @@
 # frozen_string_literal: true
 
 module SitePrism
+  # [SitePrism::Section]
+  #
+  # SitePrism Sections are the mid level construct of the POM framework
+  #
+  # Instances of this class represent a a part of a web page that can either sit inside a SitePrism::Page
+  # or sit inside another N sections, which then eventually will sit inside a page
+  #
+  # All method calls made whilst on a page are scoped using `#to_capybara_node` which will be represented by
+  # the current `#root_element`. This is the locator for the section itself and is a mandatory argument
   class Section
     include ElementChecker
     include Loadable
@@ -55,22 +64,14 @@ module SitePrism
       root_element
     end
 
-    # This allows us to return anything thats passed in as a block to the section at
+    # This allows us to return anything that's passed in as a block to the section at
     # creation time, so that an anonymous section or such-like will have the extra methods
+    #
+    # This can also be used manually at runtime to allow people to abbreviate their calls
     def within
       Capybara.within(root_element) { yield(self) }
     end
 
-    # This was the old API-style of delegating through the Capybara.page call and over-loading
-    # the method so we always went through our correct `root_element`
-    def page
-      SitePrism::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
     end

data/lib/site_prism/timer.rb

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