site_prism 4.0.3 → 5.0.beta

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31d906cda08dd376f6e81fe3ed760b954cf172d2037dcee25d91c01b3b8ace24
-  data.tar.gz: aefc0ed612cf57548101505e46c92845ef9fa2f7482b23e5d6b38cc7c37cf9f7
+  metadata.gz: 919e215261486aca371a708b7b06826e54941a29cf1580ebca68e2dea4cfbc0a
+  data.tar.gz: ecd938940c5546287ffbbf182aece2d6aacf96b454738f33a73b114c09803f19
 SHA512:
-  metadata.gz: 9eda5c088201fe6055d67d92cdd3a5f08a90ffe9ccbd2788ac1b4da6e6a0dff32e000c59819e113b4091fc33d2c38d875c9b3d36bd4d2dc549d42d4e1f071ac3
-  data.tar.gz: 5f926bac135af87939fc52ce5d110dd806ed7e3708bad8b885670a71e75065057d58de506547389ac11f2216ffcc043031262c4eeb5d11697ff38f114d1685f9
+  metadata.gz: ebb6eb3adbe1cb9663160d4347a5c3189c333937b4cb49649bf998a397cd634be4d4b557d5dc6ad5e5415d7eee8f297a8b05e8b894d19fe98cb3a9ff7a602657
+  data.tar.gz: e63ee2fd016759f69c943de5ea7e477151c1333af5c25aef8a10834426db5e14fa1790accf5069726c405ae9ec33dd2a96d9877ad75cfb558b85b284e4e1875d

data/lib/site_prism/dsl/builder.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module SitePrism
+  module DSL
+    # [SitePrism::DSL::Builder]
+    #
+    # @api private
+    #
+    # The Building logic - Initially coming from `.build`
+    #   This will take a request to build from a DSL invocation such as `element` and generate a series of
+    #   helper methods and waiters. It will also generate the correct classes for `SitePrism::Section` objects
+    #
+    #   Whilst doing all of this, it will also build up a "map" of objects in memory which can be used for
+    #   future interrogation. There are 2 ways of this being stored currently (Default as a hash, Legacy as an array)
+    #
+    module Builder
+      # Return a list of all mapped items on a SitePrism class instance (Page or Section)
+      # If legacy is set to false (Default) -> @return [Hash]
+      # If legacy is set to true (Old behaviour) -> @return [Array]
+      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', 'true') == 'true' && 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 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 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_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_helper_method(proposed_method_name, *find_args)
+        return create_error_method(proposed_method_name) if find_args.empty?
+
+        yield
+      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 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/dsl/locators.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module SitePrism
+  module DSL
+    # [SitePrism::DSL::Locators]
+    #
+    # The locator logic for scoping all items - for use in locators, boolean tests and waiters
+    #
+    # @api private
+    #
+    module Locators
+      private
+
+      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
+    end
+  end
+end

data/lib/site_prism/dsl/methods.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module SitePrism
+  module DSL
+    # [SitePrism::DSL::Methods]
+    #
+    # The meta-programmed methods for using SitePrism during runtime. This public DSL contains all the methods
+    # you will use on `SitePrism::Page` or `SitePrism::Section` classes
+    #
+    module Methods
+      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
+
+      private
+
+      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 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 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 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
+    end
+  end
+end

data/lib/site_prism/dsl/validator.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module SitePrism
+  module DSL
+    # [SitePrism::DSL::Validators]
+    #
+    # 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
+      def invalid?(name)
+        prefix_invalid?(name) ||
+          suffix_invalid?(name) ||
+          characters_invalid?(name) ||
+          blacklisted?(name)
+      end
+
+      private
+
+      def prefix_invalid?(name)
+        return unless prefix_blacklist.any? { |prefix| name.start_with?(prefix) }
+
+        log_failure(name, 'prefix')
+      end
+
+      def suffix_invalid?(name)
+        return unless suffix_blacklist.any? { |prefix| name.end_with?(prefix) }
+
+        log_failure(name, 'suffix')
+      end
+
+      def characters_invalid?(name)
+        return if name.match?(regex_permission)
+
+        log_failure(name, 'character(s)')
+      end
+
+      def blacklisted?(name)
+        return 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)
+        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
+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/error.rb

@@ -48,6 +48,6 @@ 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
 end

data/lib/site_prism/page.rb

@@ -42,18 +42,6 @@ module SitePrism
       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]
@@ -183,7 +171,7 @@ module SitePrism
 
     def load_html_string(string)
       @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 +183,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.beta'
 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'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: site_prism
 version: !ruby/object:Gem::Version
-  version: 4.0.3
+  version: 5.0.beta
 platform: ruby
 authors:
 - Luke Hill
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-07-07 00:00:00.000000000 Z
+date: 2023-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable
@@ -18,6 +18,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.8'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.8.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -25,54 +28,77 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.8'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.8.1
 - !ruby/object:Gem::Dependency
   name: capybara
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.27'
+        version: '3.31'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.27'
+        version: '3.31'
 - !ruby/object:Gem::Dependency
   name: site_prism-all_there
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: automation_helpers
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: cucumber
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">"
       - !ruby/object:Gem::Version
-        version: '6'
+        version: '7'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '9'
+        version: '10'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">"
       - !ruby/object:Gem::Version
-        version: '6'
+        version: '7'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '9'
+        version: '10'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -93,56 +119,56 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.49.0
+        version: 1.53.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.49.0
+        version: 1.53.0
 - !ruby/object:Gem::Dependency
   name: rubocop-performance
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.17.1
+        version: 1.19.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.17.1
+        version: 1.19.0
 - !ruby/object:Gem::Dependency
   name: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.20.0
+        version: 2.23.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.20.0
+        version: 2.23.2
 - !ruby/object:Gem::Dependency
   name: selenium-webdriver
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '4.7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '4.7'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -157,20 +183,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.21'
-- !ruby/object:Gem::Dependency
-  name: webdrivers
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.0'
 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:
@@ -186,7 +198,10 @@ files:
 - lib/site_prism/addressable_url_matcher.rb
 - lib/site_prism/deprecator.rb
 - lib/site_prism/dsl.rb
-- lib/site_prism/dsl_validator.rb
+- lib/site_prism/dsl/builder.rb
+- lib/site_prism/dsl/locators.rb
+- lib/site_prism/dsl/methods.rb
+- lib/site_prism/dsl/validator.rb
 - lib/site_prism/element_checker.rb
 - lib/site_prism/error.rb
 - lib/site_prism/loadable.rb
@@ -212,14 +227,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.6'
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
-rubygems_version: 3.4.13
+rubygems_version: 3.2.3
 signing_key: 
 specification_version: 4
 summary: A Page Object Model DSL for Capybara

data/lib/site_prism/dsl_validator.rb

@@ -1,75 +0,0 @@
-# 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