page_magic 1.2.7 → 2.0.0

data/lib/page_magic/element/selector/methods.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module PageMagic
+  class Element
+    class Selector
+      # module SelectorMethods - adds method for getting and setting an element selector
+      module Methods
+        # Gets/Sets a selector
+        # @param [Hash<Symbol,String>] selector method for locating the browser element. E.g. text: 'the text'
+        def selector(selector = nil)
+          return @selector unless selector
+
+          @selector = selector
+        end
+      end
+    end
+  end
+end

data/lib/page_magic/element/selector/model.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module PageMagic
+  class Element
+    class Selector
+      # class model - represents the parameters for capybara finder methods
+      class Model
+        attr_reader :args, :options
+
+        def initialize(args, options = {})
+          @args = args
+          @options = options
+        end
+
+        def ==(other)
+          other.args == args && other.options == options
+        end
+      end
+    end
+  end
+end

data/lib/page_magic/element_context.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module PageMagic
   # class ElementContext - resolves which element definition to use when accessing the browser.
   class ElementContext
@@ -7,9 +9,9 @@ module PageMagic
       @page_element = page_element
     end
 
-    # acts as proxy to element defintions defined on @page_element
-    # @return [Object] result of callng method on page_element
-    # @return [Element] animated page element containing located browser element
+    # acts as proxy to element definitions defined on @page_element
+    # @return [Object] result of calling method on page_element
+    # @return [Element] page element containing located browser element
     # @return [Array<Element>] array of elements if more that one result was found the browser
     def method_missing(method, *args, &block)
       return page_element.send(method, *args, &block) if page_element.methods.include?(method)
@@ -18,27 +20,11 @@ module PageMagic
 
       super unless builder
 
-      prefecteched_element = builder.element
-      return builder.build(prefecteched_element) if prefecteched_element
-
-      find(builder)
+      builder.build(page_element.browser_element)
     end
 
-    def respond_to?(*args)
+    def respond_to_missing?(*args)
       page_element.respond_to?(*args) || super
     end
-
-    private
-
-    def find(builder)
-      query = builder.build_query
-      result = query.execute(page_element.browser_element)
-
-      if query.multiple_results?
-        result.collect { |e| builder.build(e) }
-      else
-        builder.build(result)
-      end
-    end
   end
 end

data/lib/page_magic/element_definition_builder.rb

@@ -1,41 +1,37 @@
+# frozen_string_literal: true
+
 module PageMagic
   # Builder for creating ElementDefinitions
   class ElementDefinitionBuilder
-    INVALID_SELECTOR_MSG = 'Pass a locator/define one on the class'.freeze
-    attr_reader :definition_class, :options, :selector, :type, :element, :query_builder
-
-    def initialize(definition_class:, selector:, type:, options: {}, element: nil)
-      unless element
-        selector ||= definition_class.selector
-        raise UndefinedSelectorException, INVALID_SELECTOR_MSG if selector.nil? || selector.empty?
-      end
-
+    def initialize(definition_class:, selector:, query_class: PageMagic::Element::Query::SingleResult, element: nil)
       @definition_class = definition_class
-      @selector = selector
-      @type = type
-      @query_builder = Element::QueryBuilder.find(type)
-
-      @options = { multiple_results: false }.merge(options)
-      @element = element
-    end
 
-    # @return [Capybara::Query] query to find this element in the browser
-    def build_query
-      multiple_results = options.delete(:multiple_results)
-      query_builder.build(selector, options, multiple_results: multiple_results)
+      @query = if element
+                 PageMagic::Element::Query::PrefetchedResult.new(element)
+               else
+                 query_class.new(*selector.args, options: selector.options)
+               end
     end
 
     # Create new instance of the ElementDefinition modeled by this builder
     # @param [Object] browser_element capybara browser element corresponding to the element modelled by this builder
-    # @return [Element] element definition
+    # @return [Capybara::Node::Element]
+    # @return [Array<Capybara::Node::Element>]
     def build(browser_element)
-      definition_class.new(browser_element)
+      query.execute(browser_element) do |result|
+        definition_class.new(result)
+      end
     end
 
     def ==(other)
       return false unless other.is_a?(ElementDefinitionBuilder)
-      this = [options, selector, type, element, definition_class]
-      this == [other.options, other.selector, other.type, other.element, other.definition_class]
+
+      this = [query, definition_class]
+      this == [other.send(:query), other.send(:definition_class)]
     end
+
+    private
+
+    attr_reader :query, :definition_class
   end
 end

data/lib/page_magic/elements.rb

@@ -1,125 +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'.freeze
-
-    TYPES = [:text_field, :button, :link, :checkbox, :select_list, :radio, :textarea].collect do |type|
-      [type, :"#{type}s"]
-    end.flatten.freeze
+    INVALID_METHOD_NAME_MSG = 'a method already exists with this method name'
 
     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)
+    #  @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
 
-      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
-        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
 
-    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