page_magic 1.2.7 → 2.0.0

data/lib/page_magic/comparator/parameter_map.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module PageMagic
+  class Comparator
+    # class Map - used to model parameter matching requirements
+    class ParameterMap < Comparator
+      def initialize(map)
+        comparator = normalise(map).keys.each_with_object({}) do |key, params|
+          params[key] = Comparator.for(map[key])
+        end
+
+        fuzzy = comparator.values.any?(&:fuzzy?)
+        super(comparator, fuzzy)
+      end
+
+      def <=>(other)
+        return 0 if empty? && other.empty?
+        return 1 if other.empty?
+        if (comparator.keys.size <=> other.comparator.keys.size).zero?
+          return literal_matchers.size <=> other.literal_matchers.size
+        end
+
+        0
+      end
+
+      def empty?
+        comparator.empty?
+      end
+
+      def literal_matchers
+        comparator.values.find_all { |matcher| !matcher.fuzzy? }
+      end
+
+      def match?(params)
+        params_copy = normalise(params)
+        comparator.each do |key, value|
+          param = params_copy[key]
+          return false unless value&.match?(param)
+        end
+        true
+      end
+
+      private
+
+      def normalise(hash)
+        hash.keys.each_with_object({}) do |key, map|
+          map[key.to_sym] = hash[key]
+        end
+      end
+    end
+  end
+end

data/lib/page_magic/driver.rb

@@ -1,7 +1,10 @@
+# frozen_string_literal: true
+
 module PageMagic
   # class Driver - instances are factories for drivers used by PageMagic
   class Driver
     attr_reader :supported_browsers, :handler
+
     # Creates a driver definition
     # @example
     #  Driver.new do |rack_application, options|

data/lib/page_magic/drivers.rb

@@ -1,4 +1,7 @@
-require 'page_magic/driver'
+# frozen_string_literal: true
+
+require_relative 'driver'
+require_relative 'utils/string'
 module PageMagic
   # class Drivers - creates an object that can be used to hold driver definitions
   # These PageMagic gets the user's chosen driver from this object.
@@ -16,12 +19,10 @@ module PageMagic
     # Loads drivers defined in files at the given path
     # @param [String] path where the drivers are located
     def load(path = "#{__dir__}/drivers")
-      require 'active_support/inflector'
-
-      Dir["#{path}/*.rb"].each do |driver_file|
+      Dir["#{path}/*.rb"].sort.each do |driver_file|
         require driver_file
         driver_name = File.basename(driver_file)[/(.*)\.rb$/, 1]
-        register self.class.const_get(driver_name.classify)
+        register self.class.const_get(Utils::String.classify(driver_name))
       end
     end
 

data/lib/page_magic/drivers/poltergeist.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 PageMagic::Drivers::Poltergeist = PageMagic::Driver.new(:poltergeist) do |app, options|
   require 'capybara/poltergeist'
   Capybara::Poltergeist::Driver.new(app, options)

data/lib/page_magic/drivers/rack_test.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 PageMagic::Drivers::RackTest = PageMagic::Driver.new(:rack_test) do |app, options|
-  Capybara::RackTest::Driver.new(app, options)
+  Capybara::RackTest::Driver.new(app, **options)
 end

data/lib/page_magic/drivers/selenium.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
+
 PageMagic::Drivers::Selenium = PageMagic::Driver.new(:chrome, :firefox) do |app, options, browser|
-  require 'watir-webdriver'
-  Capybara::Selenium::Driver.new(app, options.dup.merge(browser: browser))
+  require 'watir'
+  Capybara::Selenium::Driver.new(app, **options.dup.merge(browser: browser))
 end

data/lib/page_magic/element.rb

@@ -1,17 +1,26 @@
+# 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
-    EVENT_TYPES = [:set, :select, :select_option, :unselect_option, :click].freeze
+    EVENT_TYPES = %i[set select select_option unselect_option click].freeze
     DEFAULT_HOOK = proc {}.freeze
-    EVENT_NOT_SUPPORTED_MSG = '%s event not supported'.freeze
+    EVENT_NOT_SUPPORTED_MSG = '%s event not supported'
 
-    include SelectorMethods, Watchers, SessionMethods, WaitMethods, Locators
-    extend Elements, SelectorMethods, Forwardable
+    include Locators
+    include WaitMethods
+    include SessionMethods
+    include Watchers
+    include Selector::Methods
+    extend Forwardable
+    extend Selector::Methods
+    extend Elements
 
     attr_reader :type, :name, :parent_element, :browser_element, :before_events, :after_events
 
@@ -24,7 +33,7 @@ module PageMagic
       # @!method before_events
       # If a block is passed in, it adds it to be run before an event is triggered on an element.
       # @see .after_events
-      %i(after_events before_events).each do |method|
+      %i[after_events before_events].each do |method|
         define_method method do |&block|
           instance_variable_name = "@#{method}".to_sym
           instance_variable_value = instance_variable_get(instance_variable_name) || [DEFAULT_HOOK]
@@ -38,6 +47,7 @@ module PageMagic
       # @return [Element]
       def parent_element(page_element = nil)
         return @parent_page_element unless page_element
+
         @parent_page_element = page_element
       end
 
@@ -49,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)
@@ -78,9 +94,7 @@ module PageMagic
     # @raise [NotSupportedException] if the wrapped Capybara element does not support the method
     EVENT_TYPES.each do |method|
       define_method method do |*args|
-        unless browser_element.respond_to?(method)
-          raise NotSupportedException, EVENT_NOT_SUPPORTED_MSG % method
-        end
+        raise NotSupportedException, EVENT_NOT_SUPPORTED_MSG % method unless browser_element.respond_to?(method)
 
         browser_element.send(method, *args)
       end
@@ -91,16 +105,21 @@ module PageMagic
     rescue ElementMissingException
       begin
         return browser_element.send(method, *args, &block) if browser_element.respond_to?(method)
-        return parent_element.send(method, *args, &block)
+
+        parent_element.send(method, *args, &block)
       rescue NoMethodError
         super
       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.
@@ -131,6 +150,7 @@ module PageMagic
     def wrap_events(raw_element)
       EVENT_TYPES.each do |action_method|
         next unless raw_element.respond_to?(action_method)
+
         apply_hooks(raw_element: raw_element,
                     capybara_method: action_method,
                     before_events: before_events,

data/lib/page_magic/element/locators.rb

@@ -1,22 +1,25 @@
+# frozen_string_literal: true
+
 module PageMagic
   # for the benefit of pull review :@
   class Element
     # contains method for finding element definitions
     module Locators
       # message used when raising {ElementMissingException} from methods within this module
-      ELEMENT_NOT_DEFINED_MSG = 'Element not defined: %s'.freeze
+      ELEMENT_NOT_DEFINED_MSG = 'Element not defined: %s'
 
       # find an element definition based on its name
       # @param [Symbol] name name of the element
       # @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
-        defintion.call(self, *args)
+        definition = element_definitions[name]
+        raise ElementMissingException, (ELEMENT_NOT_DEFINED_MSG % name) unless definition
+
+        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,35 +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'.freeze
-
-      attr_reader :args, :multiple_results
+      attr_reader :selector_args, :options
 
-      alias multiple_results? multiple_results
+      DEFAULT_DECORATOR = proc { |arg| arg }.freeze
 
-      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
-          capybara_element.find(*args)
-        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,40 +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
-          const_get(selector)
+          selector_name = selector_constant_name(name)
+          raise UnsupportedCriteriaException unless selector_name
+
+          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)