page_magic 2.0.0.alpha1 → 2.0.0

data/lib/page_magic/element.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
 require 'forwardable'
-require 'page_magic/element/selector_methods'
-require 'page_magic/element/locators'
-require 'page_magic/element/selector'
-require 'page_magic/element/query_builder'
+require_relative 'element/not_found'
+require_relative 'element/selector/methods'
+require_relative 'element/locators'
+require_relative 'element/selector'
+require_relative 'element/query'
 module PageMagic
   # class Element - represents an element in a html page.
   class Element
@@ -16,9 +17,9 @@ module PageMagic
     include WaitMethods
     include SessionMethods
     include Watchers
-    include SelectorMethods
+    include Selector::Methods
     extend Forwardable
-    extend SelectorMethods
+    extend Selector::Methods
     extend Elements
 
     attr_reader :type, :name, :parent_element, :browser_element, :before_events, :after_events
@@ -58,10 +59,16 @@ module PageMagic
         clazz.after_events.replace(after_events)
       end
 
+      def load(source)
+        new(Capybara::Node::Simple.new(source))
+      end
+
       # Defines watchers to be used by instances
       # @see Watchers#watch
       def watch(name, method = nil, &block)
-        before_events { watch(name, method, &block) }
+        before_events do
+          watch(name, method: method, &block)
+        end
       end
 
       def ==(other)
@@ -105,10 +112,14 @@ module PageMagic
       end
     end
 
-    def respond_to?(*args)
+    def respond_to_missing?(*args)
       super || contains_element?(args.first) || browser_element.respond_to?(*args) || parent_element.respond_to?(*args)
     end
 
+    # def respond_to_missing?(*args)
+    #   respond_to?(*args)
+    # end
+
     # @!method session
     # get the current session
     # @return [Session] returns the session of the parent page element.

data/lib/page_magic/element/locators.rb

@@ -13,13 +13,13 @@ module PageMagic
       # @return [Element] element definition with the given name
       # @raise [ElementMissingException] raised when element with the given name is not found
       def element_by_name(name, *args)
-        defintion = element_definitions[name]
-        raise ElementMissingException, (ELEMENT_NOT_DEFINED_MSG % name) unless defintion
+        definition = element_definitions[name]
+        raise ElementMissingException, (ELEMENT_NOT_DEFINED_MSG % name) unless definition
 
-        defintion.call(self, *args)
+        definition.call(self, *args)
       end
 
-      # @return [Array] class level defined element definitions
+      # @return [Array<Element>] class level defined element definitions
       def element_definitions
         self.class.element_definitions
       end

data/lib/page_magic/element/not_found.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module PageMagic
+  class Element
+    # class NotFound - Used to represent elements which are missing. All method calls other than
+    # to those that check visibility thrown a {PageMagic::ElementMissingException} exception
+    class NotFound
+      # @private [Capybara::ElementNotFound] exception
+      def initialize(exception)
+        @exception = exception
+      end
+
+      # @return [Boolean] - always false
+      def visible?
+        false
+      end
+
+      # @return [Boolean] - always false
+      def present?
+        false
+      end
+
+      # @raise [PageMagic::ElementMissingException]
+      def method_missing(*_args)
+        raise ElementMissingException, exception.message
+      end
+
+      # @return [Boolean] - always true
+      def respond_to_missing?(*_args)
+        true
+      end
+
+      private
+
+      attr_reader :exception
+    end
+  end
+end

data/lib/page_magic/element/query.rb

@@ -1,44 +1,36 @@
 # frozen_string_literal: true
 
+require_relative 'query/multiple_results'
+require_relative 'query/single_result'
+require_relative 'query/prefetched_result'
 module PageMagic
   class Element
     # class Query - executes query on capybara driver
     class Query
-      # Message template for execptions raised as a result of calling method_missing
-      ELEMENT_NOT_FOUND_MSG = 'Unable to find %s'
+      attr_reader :selector_args, :options
 
-      attr_reader :args, :multiple_results
+      DEFAULT_DECORATOR = proc { |arg| arg }.freeze
 
-      alias multiple_results? multiple_results
-
-      def initialize(args, multiple_results: false)
-        @args = args
-        @multiple_results = multiple_results
+      def initialize(*selector_args, options: {})
+        @selector_args = selector_args
+        @options = options
       end
 
-      def execute(capybara_element)
-        if multiple_results
-          capybara_element.all(*args).to_a.tap do |result|
-            raise Capybara::ElementNotFound if result.empty?
-          end
-        else
-          # TODO - make sure there is a test around this.
-          if args.last.is_a?(Hash)
-            capybara_element.find(*args[0...-1], **args.last)
-          else
-            capybara_element.find(*args)
-          end
-
-
-        end
-      rescue Capybara::Ambiguous => e
-        raise AmbiguousQueryException, e.message
+      # TODO: - test for decoration?
+      # Run query against the scope of the given element
+      # The supplied block will be used to decorate the results
+      # @param [Capybara::Node::Element] capybara_element the element to be searched within
+      # @return [Array<Capybara::Node::Element>] the results
+      # @return [NullElement] when the element is not found
+      def execute(capybara_element, &block)
+        find(capybara_element, &(block || DEFAULT_DECORATOR))
       rescue Capybara::ElementNotFound => e
-        raise ElementMissingException, e.message
+        NotFound.new(e)
       end
 
       def ==(other)
-        other.respond_to?(:args) && args == other.args
+        other.respond_to?(:selector_args) && selector_args == other.selector_args &&
+          other.respond_to?(:options) && options == other.options
       end
     end
   end

data/lib/page_magic/element/query/multiple_results.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module PageMagic
+  class Element
+    class Query
+      # class MultipleResults - use to query for multiple results
+      class MultipleResults < Query
+        # Find multiple elements
+        # The supplied block will be used to decorate the results
+        # @param [Capybara::Node::Element] capybara_element the element to be searched within
+        # @return [Array<Capybara::Node::Element>] the results
+        def find(capybara_element, &block)
+          results = capybara_element.all(*selector_args, **options).to_a.tap do |result|
+            raise Capybara::ElementNotFound if result.empty?
+          end
+          results.collect { |result| block.call(result) }
+        end
+      end
+    end
+  end
+end

data/lib/page_magic/element/query/prefetched_result.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module PageMagic
+  class Element
+    class Query
+      # class PrefetchedResult - used to return element that has already been retrieved
+      class PrefetchedResult < Query
+        def initialize(prefetched_element)
+          super
+          @prefetched_element = prefetched_element
+        end
+
+        # Returns the object provided to `initialize`
+        # The supplied block will be used to decorate the results
+        # @return [Capybara::Node::Element] the object supplied to `initialize`
+        def find(_capybara_element, &block)
+          block.call(prefetched_element)
+        end
+
+        private
+
+        attr_reader :prefetched_element
+      end
+    end
+  end
+end

data/lib/page_magic/element/query/single_result.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module PageMagic
+  class Element
+    class Query
+      # class SingleResult - use to query when only one result should be expected
+      class SingleResult < Query
+        # Find an element
+        # The supplied block will be used to decorate the results
+        # @param [Capybara::Node::Element] capybara_element the element to be searched within
+        # @return [Object] the results
+        def find(capybara_element, &block)
+          block.call capybara_element.find(*selector_args, **options)
+        rescue Capybara::Ambiguous => e
+          raise AmbiguousQueryException, e.message
+        end
+      end
+    end
+  end
+end

data/lib/page_magic/element/selector.rb

@@ -1,43 +1,65 @@
 # frozen_string_literal: true
 
+require_relative 'selector/model'
 module PageMagic
+  # Capybara::Finder
   class Element
     # class Selector - models the selection criteria understood by Capybara
     class Selector
       class << self
-        # Find a Selecor using it's name
+        # Find a Selector using it's name
         # @param [Symbol] name the name of the required Selector in snakecase format. See class constants for available
         #  selectors
         # @return [Selector] returns the predefined selector with the given name
         def find(name)
-          selector = constants.find { |constant| constant.to_s.casecmp(name.to_s).zero? }
-          raise UnsupportedCriteriaException unless selector
+          selector_name = selector_constant_name(name)
+          raise UnsupportedCriteriaException unless selector_name
 
-          const_get(selector)
+          const_get(selector_name)
         end
-      end
 
-      attr_reader :name, :formatter, :exact, :supports_type
+        private
 
+        def selector_constant_name(name)
+          constants.find { |constant| constant.to_s.casecmp(name.to_s).zero? }
+        end
+      end
+
+      # Initialize a new selector
+      # a block can be supplied to decorate the query. E.g.
+      # @example
+      #  Selector.new(supports_type: false) do |arg|
+      #    "*[name='#{arg}']"
+      #  end
+      #
+      # @param [Symbol] selector the identifier for the selector
+      # @param [Boolean] supports_type whether the element type being searched for can be used as part of the query
+      # @param [Boolean] exact whether an exact match is required. E.g. element should include exactly the same text
       def initialize(selector = nil, supports_type: false, exact: false, &formatter)
-        @name = selector
+        @selector = selector
         @formatter = formatter || proc { |arg| arg }
         @supports_type = supports_type
-        @exact = exact
+        @options = {}.tap do |hash|
+          hash[:exact] = true if exact
+        end
       end
 
       # Build selector query parameters for Capybara's find method
       # @param [Symbol] element_type the type of browser element being found. e.g :link
-      # @param [Hash] locator the selection method and its parameter. E.g. text: 'click me'
-      def build(element_type, locator)
-        [].tap do |array|
-          array << element_type if supports_type
-          array << name if name
-          array << formatter.call(locator)
-          array << { exact: true } if exact
-        end
+      # @param [Hash<Symbol,String>] locator the selection method and its parameter. E.g. text: 'click me'
+      def build(element_type, locator, options: {})
+        array = [type(element_type), selector, formatter.call(locator)].compact
+        Model.new(array, self.options.merge(options))
       end
 
+      private
+
+      def type(element_type)
+        supports_type ? element_type : nil
+      end
+
+      attr_reader :supports_type, :options, :selector, :formatter
+
       XPATH = Selector.new(:xpath, supports_type: false)
       ID = Selector.new(:id, supports_type: false)
       LABEL = Selector.new(:field, supports_type: false, exact: true)

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

@@ -9,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)
@@ -20,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

@@ -3,42 +3,35 @@
 module PageMagic
   # Builder for creating ElementDefinitions
   class ElementDefinitionBuilder
-    INVALID_SELECTOR_MSG = 'Pass a locator/define one on the class'
-    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