site_prism 4.0.3 → 5.0

data/lib/site_prism/dsl/validator.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module SitePrism
+  module DSL
+    # [SitePrism::DSL::Validator]
+    #
+    # This is the new validator module which will check all DSL items against a whitelist
+    # for any entries which break specific rules
+    #
+    # @api private
+    #
+    module Validator
+      attr_accessor :dsl_name_error
+
+      def name_invalid?(name)
+        prefix_invalid?(name) ||
+          suffix_invalid?(name) ||
+          characters_invalid?(name) ||
+          blacklisted?(name)
+      end
+
+      private
+
+      def prefix_invalid?(name)
+        return false unless prefix_blacklist.any? { |prefix| name.start_with?(prefix) }
+
+        log_failure(name, 'prefix')
+      end
+
+      def suffix_invalid?(name)
+        return false unless suffix_blacklist.any? { |prefix| name.end_with?(prefix) }
+
+        log_failure(name, 'suffix')
+      end
+
+      def characters_invalid?(name)
+        return false if name.match?(regex_permission)
+
+        log_failure(name, 'character(s)')
+      end
+
+      def blacklisted?(name)
+        return false unless blacklisted_names.include?(name)
+
+        log_failure(name, 'name (blacklisted entry)')
+      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
+          element
+          elements
+          section
+          sections
+          iframe
+        ]
+      end
+
+      def log_failure(name, type)
+        self.dsl_name_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
+end

data/lib/site_prism/dsl.rb

@@ -1,17 +1,25 @@
 # frozen_string_literal: true
 
+require 'site_prism/dsl/builder'
+require 'site_prism/dsl/methods'
+require 'site_prism/dsl/locators'
+require 'site_prism/dsl/validator'
+
 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.
+  # This is the core internal workings of SitePrism. It consists of four moving parts - plus some generic methods included here
+  #   Builder -> The way in which the .build method generates lots of instance-methods on a SitePrism::Page or SitePrism::Section instance
+  #   Methods -> The public DSL metaprogram methods, such as `element` or `section`
+  #   Locators -> Our locator scoping logic within capybara. By and large leaning on `#to_capybara_node`
+  #   Validators -> EXPERIMENTAL: A new module that ensures names of all DSL items conform to certain rules
   #
-  # The whole package here can be thought of as [@api private]
   module DSL
     def self.included(klass)
-      klass.extend ClassMethods
-      klass.extend DSLValidator
+      klass.extend Builder
+      klass.extend Methods
+      klass.include Locators
+      klass.extend Validator
     end
 
     private
@@ -23,326 +31,5 @@ module SitePrism
       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
-
-    def _all(*find_args)
-      kwargs = find_args.pop
-      to_capybara_node.all(*find_args, **kwargs)
-    end
-
-    def element_exists?(*find_args)
-      kwargs = find_args.pop
-      to_capybara_node.has_selector?(*find_args, **kwargs)
-    end
-
-    def element_does_not_exist?(*find_args)
-      kwargs = find_args.pop
-      to_capybara_node.has_no_selector?(*find_args, **kwargs)
-    end
-
-    # Sanitize method called before calling any SitePrism DSL method or
-    # meta-programmed method. This ensures that the Capybara query is correct.
-    #
-    # Accepts any combination of arguments sent at DSL definition or runtime
-    # and combines them in such a way that Capybara can operate with them.
-    def merge_args(find_args, runtime_args, visibility_args = {})
-      find_args = find_args.dup
-      runtime_args = runtime_args.dup
-      options = visibility_args.dup
-      SitePrism.logger.debug("Initial args: #{find_args}, #{runtime_args}.")
-
-      recombine_args(find_args, runtime_args, options)
-
-      return [*find_args, *runtime_args, {}] if options.empty?
-
-      [*find_args, *runtime_args, options]
-    end
-
-    # Options re-combiner. This takes the original inputs and combines
-    # them such that there is only one hash passed as a final argument
-    # to Capybara.
-    #
-    # 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] = 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
-
-      # 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)
-        raise_if_build_time_block_supplied(self, name, block_given?, :element)
-        build(:element, name, *find_args) do
-          define_method(name) do |*runtime_args, &runtime_block|
-            raise_if_runtime_block_supplied(self, name, runtime_block, :element)
-            _find(*merge_args(find_args, runtime_args))
-          end
-        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)
-        raise_if_build_time_block_supplied(self, name, block_given?, :elements)
-        build(:elements, name, *find_args) do
-          define_method(name) do |*runtime_args, &runtime_block|
-            raise_if_runtime_block_supplied(self, name, runtime_block, :elements)
-            _all(*merge_args(find_args, runtime_args))
-          end
-        end
-      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
-          define_method(name) do |*runtime_args, &runtime_block|
-            section_element = _find(*merge_args(find_args, runtime_args))
-            section_class.new(self, section_element, &runtime_block)
-          end
-        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
-          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
-          end
-        end
-      end
-
-      def iframe(name, klass, *args)
-        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
-          define_method(name) do |&block|
-            raise MissingBlockError unless block
-
-            within_frame(*scope_find_args) { block.call(klass.new) }
-          end
-        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: false)
-        return legacy_mapped_items if legacy
-
-        @mapped_items ||= { element: [], elements: [], section: [], sections: [], iframe: [] }
-      end
-
-      private
-
-      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, type, *find_args)
-      end
-
-      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)
-        create_visibility_waiter(name, *find_args)
-        create_invisibility_waiter(name, *find_args)
-      end
-
-      def create_helper_method(proposed_method_name, *find_args)
-        return create_error_method(proposed_method_name) if find_args.empty?
-
-        yield
-      end
-
-      def create_existence_checker(element_name, *find_args)
-        method_name = "has_#{element_name}?"
-        create_helper_method(method_name, *find_args) do
-          define_method(method_name) do |*runtime_args|
-            args = merge_args(find_args, runtime_args)
-            element_exists?(*args)
-          end
-        end
-      end
-
-      def create_nonexistence_checker(element_name, *find_args)
-        method_name = "has_no_#{element_name}?"
-        create_helper_method(method_name, *find_args) do
-          define_method(method_name) do |*runtime_args|
-            args = merge_args(find_args, runtime_args)
-            element_does_not_exist?(*args)
-          end
-        end
-      end
-
-      def create_visibility_waiter(element_name, *find_args)
-        method_name = "wait_until_#{element_name}_visible"
-        create_helper_method(method_name, *find_args) do
-          define_method(method_name) do |*runtime_args|
-            args = merge_args(find_args, runtime_args, visible: true)
-            return true if element_exists?(*args)
-
-            raise SitePrism::ElementVisibilityTimeoutError
-          end
-        end
-      end
-
-      def create_invisibility_waiter(element_name, *find_args)
-        method_name = "wait_until_#{element_name}_invisible"
-        create_helper_method(method_name, *find_args) do
-          define_method(method_name) do |*runtime_args|
-            args = merge_args(find_args, runtime_args, visible: true)
-            return true if element_does_not_exist?(*args)
-
-            raise SitePrism::ElementInvisibilityTimeoutError
-          end
-        end
-      end
-
-      def create_error_method(name)
-        SitePrism::Deprecator.deprecate(
-          'DSL definition with no 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
-        @legacy_mapped_items ||= begin
-          SitePrism::Deprecator.deprecate(
-            '.mapped_items structure (internally), on a class',
-            'the new .mapped_items structure'
-          )
-          []
-        end
-      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]
-        when Integer then [args[0]]
-        when String  then [:css, args[0]]
-        else args
-        end
-      end
-
-      def deduce_iframe_element_find_args(args)
-        warn_on_invalid_selector_input(args)
-        case args[0]
-        when Integer then "iframe:nth-of-type(#{args[0] + 1})"
-        when String  then [:css, args[0]]
-        else args
-        end
-      end
-
-      def warn_on_invalid_selector_input(args)
-        return unless looks_like_xpath?(args[0])
-
-        SitePrism.logger.warn('The arguments passed in look like xpath. Check your locators.')
-        SitePrism.logger.debug("Default locator strategy: #{Capybara.default_selector}")
-      end
-
-      def looks_like_xpath?(arg)
-        arg.is_a?(String) && arg.start_with?('/', './')
-      end
-
-      def extract_section_options(args, &block)
-        if args.first.is_a?(Class)
-          klass = args.shift
-          section_class = klass if klass <= SitePrism::Section
-        end
-
-        section_class = deduce_section_class(section_class, &block)
-        arguments = deduce_search_arguments(section_class, args)
-        [section_class, arguments]
-      end
-
-      def deduce_section_class(base_class, &block)
-        klass = base_class
-        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.'
-      end
-
-      def deduce_search_arguments(section_class, args)
-        extract_search_arguments(args) ||
-          extract_search_arguments(section_class.default_search_arguments) ||
-          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

@@ -13,7 +13,7 @@ module SitePrism
     # for how the definition of "every item" is derived.
     #
     # Example
-    # @my_page.class.mapped_items
+    # `@my_page.class.mapped_items`
     #  {
     #    element => [:button_one, :button_two],
     #    elements => [:button_collection_one, :button_collection_two],
@@ -21,7 +21,7 @@ module SitePrism
     #    sections => [:search_result],
     #    iframe => []
     #  }
-    # @my_page.all_there?
+    # `@my_page.all_there?`
     # => true - If the items above are all present
     #
     # Note that #elements_to_check will check the hash of mapped_items

data/lib/site_prism/error.rb

@@ -48,6 +48,9 @@ module SitePrism
   # Generic Attribute validation family of errors inherit from this error
   class AttributeValidationError < SitePrismError; end
 
-  # DSL items are not permitted to start with certain prefixes
+  # DSL items are not permitted to be named in certain ways
   class InvalidDSLNameError < AttributeValidationError; end
+
+  # The version of the target gem is unsupported, so using that feature is not possible
+  class UnsupportedGemVersionError < SitePrismError; end
 end

data/lib/site_prism/loadable.rb

@@ -13,10 +13,8 @@ module SitePrism
       base.extend(ClassMethods)
     end
 
-    # In certain circumstances, we cache that the page has already
-    # been confirmed to be loaded so that actions which
-    # call `loaded?` a second time do not need to perform
-    # the load_validation queries against the page a second time.
+    # In certain circumstances, we cache that the page or section has already been "loaded" so that actions which
+    # call `loaded?` a second time do not need to perform the load_validation queries against the page a second time.
     attr_accessor :loaded, :load_error
 
     # Executes the given block after the page is loaded.
@@ -27,8 +25,7 @@ module SitePrism
       # inside another when_loaded block.
       previously_loaded = loaded
 
-      # Within the block, check (and cache) loaded?, to see whether the
-      # page has indeed loaded according to the rules defined by the user.
+      # Within the block, check (and cache) loaded?, to see whether the page has indeed loaded according to the rules defined by the user.
       self.loaded = loaded?
 
       # If the page hasn't loaded. Then crash and return the error message.
@@ -68,13 +65,12 @@ module SitePrism
     end
 
     # [SitePrism::Loadable::ClassMethods]
-    # This exposes all of the DSL definitions users will use when generating "loadables"
+    # 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`
+    # A "Loadable" is a definition whereby the page/section 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.
+      # The list of load_validations. They are executed in the order they are defined.
       #
       # @return [Array]
       def load_validations
@@ -85,21 +81,15 @@ module SitePrism
         end
       end
 
-      # Appends a load validation block to the page class.
+      # Appends a load validation block to the page/section 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.
+      # 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.
+      # @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
+      # If this does not pass, then the 2nd item (if defined), is output as an error message on the +FailedLoadValidationError+
       #
       # @return [Proc]
       def load_validation(&block)

data/lib/site_prism/logger.rb

@@ -10,7 +10,7 @@ module SitePrism
     def create(output = $stdout)
       logger = ::Logger.new(output)
       logger.progname = 'SitePrism'
-      logger.level = :UNKNOWN
+      logger.level = :WARN
       logger.formatter = proc do |severity, time, progname, msg|
         "#{time.strftime('%F %T')} - #{severity} - #{progname} - #{msg}\n"
       end

data/lib/site_prism/page.rb

@@ -36,24 +36,12 @@ module SitePrism
       # 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]
+      # @return [Regexp || String]
       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
-      @_page ||= begin
-        SitePrism::Deprecator.deprecate('Calling #page on a SitePrism::Page instance')
-        to_capybara_node
-      end
-    end
-
     # This scopes our calls inside Page correctly to the `Capybara::Session`
     #
     # @return [Capybara::Node::Simple || Capybara::Session]
@@ -182,8 +170,9 @@ module SitePrism
     end
 
     def load_html_string(string)
+      SitePrism::Deprecator.deprecate('Using an input fragment (Loading partials using html strings).')
       @page = Capybara.string(string)
-      yield self if block_given?
+      yield to_capybara_node if block_given?
     end
 
     def load_html_website(html, &block)
@@ -195,7 +184,7 @@ module SitePrism
       if with_validations
         when_loaded(&block)
       elsif block
-        yield self
+        yield to_capybara_node
       end
     end
   end

data/lib/site_prism/version.rb

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

data/lib/site_prism.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require 'site_prism/error'
 require 'site_prism/all_there'
 
 require 'addressable/template'
@@ -8,10 +7,10 @@ require 'capybara/dsl'
 require 'forwardable'
 
 require 'site_prism/addressable_url_matcher'
-require 'site_prism/dsl'
-require 'site_prism/dsl_validator'
 require 'site_prism/deprecator'
+require 'site_prism/dsl'
 require 'site_prism/element_checker'
+require 'site_prism/error'
 require 'site_prism/loadable'
 require 'site_prism/logger'
 require 'site_prism/page'
@@ -23,6 +22,11 @@ require 'site_prism/waiter'
 # [SitePrism]
 module SitePrism
   class << self
+    # SitePrism will enforce strict validation on all generated DSL items i.e. `element`
+    # The validations are found inside the SitePrism::DSL::Validator module
+    # NB: To ensure no unwanted validation issues, this must be disabled BEFORE any page / section code is autoloaded
+    attr_accessor :dsl_validation_disabled
+
     def configure
       yield self
     end