page_magic 2.0.0.alpha1 → 2.0.0

data/lib/page_magic/elements.rb

@@ -1,162 +1,122 @@
 # frozen_string_literal: true
 
 require 'active_support/inflector'
-require 'page_magic/element_definition_builder'
+require_relative 'element_definition_builder'
+require_relative 'elements/inheritance_hooks'
+require_relative 'elements/config'
+require_relative 'elements/types'
+
 module PageMagic
   # module Elements - contains methods that add element definitions to the objects it is mixed in to
   module Elements
-    # hooks for objects that inherit classes that include the Elements module
-    module InheritanceHooks
-      # Copies parent element definitions on to subclass
-      # @param [Class] clazz - inheritting class
-      def inherited(clazz)
-        clazz.element_definitions.merge!(element_definitions)
-      end
-    end
-
     INVALID_METHOD_NAME_MSG = 'a method already exists with this method name'
 
-    # css
-    # datalist_input
-    # datalist_option
-    # field
-    # fieldset
-    # file_field
-    # fillable_field
-    # frame
-    # link_or_button
-    # option
-    # radio_button
-    # select
-    # table
-    # table_row
-    # xpath
-    #
-
-    TYPES = %i[field
-    fieldset
-    file_field
-    fillable_field
-    frame
-    link_or_button
-    option
-    radio_button
-    select
-    table
-    table_row
-    text_field
-    button
-    link
-    checkbox
-    select_list
-    radio
-    textarea
-    label].collect{ |type| [type, :"#{type}s"]}.flatten.freeze
-
     class << self
       def extended(clazz)
         clazz.extend(InheritanceHooks)
       end
+
+      private
+
+      def define_element_methods(types)
+        types.each { |type| alias_method type, :element }
+      end
+
+      def define_pluralised_element_methods(types)
+        types.each { |type| alias_method type.to_s.pluralize, :elements }
+      end
     end
 
-    # Creates an element defintion.
-    # Element defintions contain specifications for locating them and other sub elements.
-    # if a block is specified then it will be executed against the element defintion.
+    # Creates an Element definition
     # This method is aliased to each of the names specified in {TYPES TYPES}
+    # Element definitions contain specifications for locating them and other sub elements.
+    # @yield if a block is specified then it will be executed against the element definition.
     # @example
     #   element :widget, id: 'widget' do
     #     link :next, text: 'next'
     #   end
     # @overload element(name, selector, &block)
     #  @param [Symbol] name the name of the element.
-    #  @param [Hash] selector a key value pair defining the method for locating this element
+    #  @param [Hash<Symbol,String>] selector a key value pair defining the method for locating this element
     #  @option selector [String] :text text contained within the element
     #  @option selector [String] :css css selector
     #  @option selector [String] :id the id of the element
     #  @option selector [String] :name the value of the name attribute belonging to the element
     #  @option selector [String] :label value of the label tied to the require field
+    #  @param optional [Hash<Symbol,String>] capybara_options
     # @overload element(element_class, &block)
     #  @param [ElementClass] element_class a custom class of element that inherits {Element}.
     #   the name of the element is derived from the class name. the Class name coverted to snakecase.
     #   The selector must be defined on the class itself.
+    #  @param optional [Hash<Symbol,String>] capybara_options
     # @overload element(name, element_class, &block)
     #  @param [Symbol] name the name of the element.
     #  @param [ElementClass] element_class a custom class of element that inherits {Element}.
     #   The selector must be defined on the class itself.
+    #  @param optional [Hash<Symbol,String>] capybara_options
     # @overload element(name, element_class, selector, &block)
     #  @param [Symbol] name the name of the element.
     #  @param [ElementClass] element_class a custom class of element that inherits {Element}.
-    #  @param [Hash] selector a key value pair defining the method for locating this element. See above for details
-    def element(*args, &block)
-      block ||= proc {}
-      options = compute_options(args.dup, __callee__)
-
-      section_class = options.delete(:section_class)
-
-      add_element_definition(options.delete(:name)) do |parent_element, *e_args|
-        definition_class = Class.new(section_class) do
-          parent_element(parent_element)
-          class_exec(*e_args, &block)
-        end
+    #  @param optional [Hash<Symbol,String>] capybara_options
+    def element(*args, **capybara_options, &block)
+      define_element(*args,
+                     type: __callee__,
+                     query_class: PageMagic::Element::Query::SingleResult,
+                     **capybara_options,
+                     &block)
+    end
 
-        ElementDefinitionBuilder.new(**options.merge(definition_class: definition_class))
-      end
+    # see docs for {Elements#element}
+    def elements(*args, **capybara_options, &block)
+      define_element(*args,
+                     type: __callee__.to_s.singularize.to_sym,
+                     query_class: PageMagic::Element::Query::MultipleResults,
+                     **capybara_options,
+                     &block)
     end
 
-    alias elements element
-    TYPES.each { |type| alias_method type, :element }
+    define_element_methods(TYPES)
+    define_pluralised_element_methods(TYPES)
 
-    # @return [Hash] element definition names mapped to blocks that can be used to create unique instances of
-    #  and {Element} definitions
+    # @return [Hash<Symbol,ElementDefinitionBuilder>] element definition names mapped to
+    # blocks that can be used to create unique instances of {Element} definitions
     def element_definitions
       @element_definitions ||= {}
     end
 
     private
 
-    def compute_options(args, type)
-      section_class = remove_argument(args, Class) || Element
-
-      { name: compute_name(args, section_class),
-        type: type,
-        selector: compute_selector(args, section_class),
-        options: compute_argument(args, Hash),
-        element: args.delete_at(0),
-        section_class: section_class }.tap do |hash|
-        hash[:options][:multiple_results] = type.to_s.end_with?('s')
-      end
-    end
-
-    def add_element_definition(name, &block)
-      raise InvalidElementNameException, 'duplicate page element defined' if element_definitions[name]
-
-      methods = respond_to?(:instance_methods) ? instance_methods : methods()
-      raise InvalidElementNameException, INVALID_METHOD_NAME_MSG if methods.find { |method| method == name }
-
-      element_definitions[name] = block
-    end
+    def define_element(*args, type:, query_class:, **capybara_options, &block)
+      block ||= proc {}
+      args << capybara_options unless capybara_options.empty?
+      config = validate!(args, type)
 
-    def compute_name(args, section_class)
-      name = remove_argument(args, Symbol)
-      name || section_class.name.demodulize.underscore.to_sym unless section_class.is_a?(Element)
-    end
+      element_definitions[config.name] = proc do |parent_element, *e_args|
+        config.definition_class = Class.new(config.element_class) do
+          parent_element(parent_element)
+          class_exec(*e_args, &block)
+        end
 
-    def compute_selector(args, section_class)
-      selector = remove_argument(args, Hash)
-      selector || section_class.selector if section_class.respond_to?(:selector)
+        ElementDefinitionBuilder.new(query_class: query_class, **config.element_options)
+      end
     end
 
     def method_added(method)
+      super
       raise InvalidMethodNameException, 'method name matches element name' if element_definitions[method]
     end
 
-    def compute_argument(args, clazz)
-      remove_argument(args, clazz) || clazz.new
+    def validate!(args, type)
+      config = Config.build(args, type).validate!
+      validate_element_name(config.name)
+      config
     end
 
-    def remove_argument(args, clazz)
-      argument = args.find { |arg| arg.is_a?(clazz) }
-      args.delete(argument)
+    def validate_element_name(name)
+      raise InvalidElementNameException, 'duplicate page element defined' if element_definitions[name]
+
+      methods = respond_to?(:instance_methods) ? instance_methods : methods()
+      raise InvalidElementNameException, INVALID_METHOD_NAME_MSG if methods.find { |method| method == name }
     end
   end
 end

data/lib/page_magic/elements/config.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module PageMagic
+  module Elements
+    CONFIG_STRUCT = Struct.new(:name,
+                               :definition_class,
+                               :type,
+                               :selector,
+                               :options,
+                               :element,
+                               :element_class,
+                               keyword_init: true)
+
+    # class Config - use to validate input to {PageMagic::Elements#elment}
+    class Config < CONFIG_STRUCT
+      INVALID_SELECTOR_MSG = 'Pass a locator/define one on the class'
+      INVALID_ELEMENT_CLASS_MSG = 'Element class must be of type `PageMagic::Element`'
+      TYPE_REQUIRED_MESSAGE = 'element type required'
+
+      class << self
+        # Create `Config` used to build instances `PageMagic::Element` see `Page::Elements#element` for details
+        # @param [Args<Object>] args arguments passed to `Page::Elements#element`
+        # @return [Config]
+        def build(args, type)
+          element_class = remove_argument(args, Class) || Element
+          new(
+            name: compute_name(args, element_class),
+            type: type_for(type),
+            selector: compute_selector(args, element_class),
+            options: compute_argument(args, Hash),
+            element: args.delete_at(0),
+            element_class: element_class
+          )
+        end
+
+        private
+
+        def compute_name(args, element_class)
+          name = remove_argument(args, Symbol)
+          name || element_class.name.demodulize.underscore.to_sym unless element_class.is_a?(Element)
+        end
+
+        def compute_selector(args, element_class)
+          selector = remove_argument(args, Hash)
+          selector || element_class.selector if element_class.respond_to?(:selector)
+        end
+
+        def compute_argument(args, clazz)
+          remove_argument(args, clazz) || clazz.new
+        end
+
+        def remove_argument(args, clazz)
+          argument = args.find { |arg| arg.is_a?(clazz) }
+          args.delete(argument)
+        end
+
+        def type_for(type)
+          field?(type) ? :field : type
+        end
+
+        def field?(type)
+          %i[ text_field checkbox select_list radio textarea field file_field fillable_field
+              radio_button select].include?(type)
+        end
+      end
+
+      # Options for the building of `PageMagic::Element` via `PageMagic::ElementDefinitionBuilder#new`
+      # @return [Hash<Symbol,Object>]
+      def element_options
+        to_h.except(:element_class, :name, :type, :options).update(selector: selector)
+      end
+
+      # Selector built using supplied configuration
+      # @return [PageMagic::Element::Selector::Model]
+      def selector
+        selector = self[:selector]
+        Element::Selector.find(selector.keys.first).build(type, selector.values.first, options: options)
+      end
+
+      # Validate supplied configuration
+      # @raise [PageMagic::InvalidConfigurationException]
+      # @return [PageMagic::Elements::Config]
+      def validate!
+        raise PageMagic::InvalidConfigurationException, INVALID_SELECTOR_MSG unless element || valid_selector?
+        raise PageMagic::InvalidConfigurationException, 'element type required' unless type
+        raise PageMagic::InvalidConfigurationException, INVALID_ELEMENT_CLASS_MSG unless valid_element_class?
+
+        self
+      end
+
+      private
+
+      def valid_selector?
+        selector = self[:selector]
+        selector.is_a?(Hash) && !selector.empty?
+      end
+
+      def valid_element_class?
+        element_class && (element_class == PageMagic::Element || element_class < PageMagic::Element)
+      end
+    end
+  end
+end

data/lib/page_magic/elements/inheritance_hooks.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module PageMagic
+  module Elements
+    # hooks for objects that inherit classes that include the Elements module
+    module InheritanceHooks
+      # Copies parent element definitions on to subclass
+      # @param [Class] clazz - inheriting class
+      def inherited(clazz)
+        super
+        clazz.element_definitions.merge!(element_definitions)
+      end
+    end
+  end
+end

data/lib/page_magic/elements/types.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module PageMagic
+  module Elements
+    TYPES = %i[field
+               fieldset
+               file_field
+               fillable_field
+               frame
+               link_or_button
+               option
+               radio_button
+               select
+               table
+               table_row
+               text_field
+               button
+               link
+               checkbox
+               select_list
+               radio
+               textarea
+               label].freeze
+  end
+end

data/lib/page_magic/exceptions.rb

@@ -36,4 +36,7 @@ module PageMagic
 
   class NotSupportedException < RuntimeError
   end
+
+  class InvalidConfigurationException < StandardError
+  end
 end

data/lib/page_magic/instance_methods.rb

@@ -19,7 +19,7 @@ module PageMagic
       @browser_element = browser
     end
 
-    # @return [Array] class level defined element definitions
+    # @return [Array<ElementDefinitionBuilder>] class level defined element definitions
     def element_definitions
       self.class.element_definitions
     end
@@ -37,7 +37,7 @@ module PageMagic
       element_context.send(method, *args)
     end
 
-    def respond_to?(*args)
+    def respond_to_missing?(*args)
       contains_element?(args.first) || super
     end
 

data/lib/page_magic/mapping.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative '../active_support/core_ext/object/to_query'
+require_relative 'comparator'
+
+
+module PageMagic
+  # models mapping used to relate pages to uris
+  class Mapping
+    attr_reader :path, :parameters, :fragment
+
+    # @param [Object] path String or Regular expression to match with
+    # @param [Hash] parameters mapping of parameter name to literal or regex to match with
+    # @param [Object] fragment String or Regular expression to match with
+    # @raise [MatcherInvalidException] if at least one component is not specified
+    def initialize(path = nil, parameters: {}, fragment: nil)
+      raise MatcherInvalidException unless path || parameters || fragment
+
+      @path = Comparator.for(path)
+      @parameters = Comparator.for(parameters)
+      @fragment = Comparator.for(fragment)
+    end
+
+    # @return [Boolean] true if no component contains a Regexp
+    def can_compute_uri?
+      !fragment.fuzzy? && !path.fuzzy? && !parameters.fuzzy?
+    end
+
+    # @return [String] uri represented by this mapping
+    def compute_uri
+      path.to_s.dup.tap do |uri|
+        uri << "?#{parameters.comparator.to_query}" unless parameters.empty?
+        uri << "##{fragment}" if fragment.present?
+      end
+    end
+
+    # @return [Fixnum] hash for instance
+    def hash
+      [path, parameters, fragment].hash
+    end
+
+    # @param [String] uri
+    # @return [Boolean] returns true if the uri is matched against this matcher
+    def match?(uri)
+      uri = URI(uri)
+      path.match?(uri.path) && parameters.match?(parameters_hash(uri.query)) && fragment.match?(uri.fragment)
+    end
+
+    # compare this matcher against another
+    # @param [Mapping] other
+    # @return [Fixnum] -1 = smaller, 0 = equal to, 1 = greater than
+    def <=>(other)
+      path_comparison = path <=> other.path
+      return path_comparison unless path_comparison.zero?
+
+      parameter_comparison = parameters <=> other.parameters
+      return parameter_comparison unless parameter_comparison.zero?
+
+      fragment <=> other.fragment
+    end
+
+    # check equality
+    # @param [Mapping] other
+    # @return [Boolean]
+    def ==(other)
+      return false unless other.is_a?(Mapping)
+
+      path == other.path && parameters == other.parameters && fragment == other.fragment
+    end
+
+    alias eql? ==
+
+    private
+
+    def parameters_hash(string)
+      CGI.parse(string.to_s.downcase).collect { |key, value| [key.downcase, value.first] }.to_h
+    end
+  end
+end