page_magic 1.2.8 → 2.0.2

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module PageMagic
   class ElementMissingException < RuntimeError
   end
@@ -20,7 +22,7 @@ module PageMagic
   class TimeoutException < RuntimeError
   end
 
-  class UnspportedBrowserException < RuntimeError
+  class UnsupportedBrowserException < RuntimeError
   end
 
   class UnsupportedCriteriaException < RuntimeError
@@ -34,4 +36,7 @@ module PageMagic
 
   class NotSupportedException < RuntimeError
   end
+
+  class InvalidConfigurationException < StandardError
+  end
 end

data/lib/page_magic/instance_methods.rb

@@ -1,9 +1,14 @@
+# frozen_string_literal: true
+
 module PageMagic
   # module InstanceMethods - provides instance level methods for page objects
   module InstanceMethods
     attr_reader :browser, :session, :browser_element
 
-    include Watchers, SessionMethods, WaitMethods, Element::Locators
+    include Element::Locators
+    include WaitMethods
+    include SessionMethods
+    include Watchers
 
     # Creates a new instance
     # @param [Session] session session that provides gateway to the browser throw the users chosen browser
@@ -14,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
@@ -32,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

data/lib/page_magic/session.rb

@@ -1,12 +1,15 @@
+# frozen_string_literal: true
+
 require 'forwardable'
-require 'page_magic/matcher'
+require_relative 'transitions'
+
 module PageMagic
   # class Session - coordinates access to the browser though page objects.
   class Session
-    URL_MISSING_MSG = 'a path must be mapped or a url supplied'.freeze
-    REGEXP_MAPPING_MSG = 'URL could not be derived because mapping contains Regexps'.freeze
-    INVALID_MAPPING_MSG = 'mapping must be a string or regexp'.freeze
-    UNSUPPORTED_OPERATION_MSG = 'execute_script not supported by driver'.freeze
+    URL_MISSING_MSG = 'a path must be mapped or a url supplied'
+
+    INVALID_MAPPING_MSG = 'mapping must be a string or regexp'
+    UNSUPPORTED_OPERATION_MSG = 'execute_script not supported by driver'
 
     extend Forwardable
 
@@ -18,14 +21,13 @@ module PageMagic
     def initialize(capybara_session, base_url = nil)
       @raw_session = capybara_session
       @base_url = base_url
-      visit(url: base_url) if base_url
-      @transitions = {}
+      define_page_mappings({})
     end
 
     # @return [Object] returns page object representing the currently loaded page on the browser. If no mapping
     # is found then nil returned
     def current_page
-      mapping = find_mapped_page(current_url)
+      mapping = transitions.mapped_page(current_url)
       @current_page = initialize_page(mapping) if mapping
       @current_page
     end
@@ -49,10 +51,7 @@ module PageMagic
     # @option transitions [String] path as literal
     # @option transitions [Regexp] path as a regexp for dynamic matching.
     def define_page_mappings(transitions)
-      @transitions = transitions.collect do |key, value|
-        key = key.is_a?(Matcher) ? key : Matcher.new(key)
-        [key, value]
-      end.to_h
+      @transitions = Transitions.new(transitions)
     end
 
     #  execute javascript on the browser
@@ -73,7 +72,7 @@ module PageMagic
 
     # @param args see {::Object#respond_to?}
     # @return [Boolean] true if self or the current page object responds to the give method name
-    def respond_to?(*args)
+    def respond_to_missing?(*args)
       super || current_page.respond_to?(*args)
     end
 
@@ -91,38 +90,19 @@ module PageMagic
     # @raise [InvalidURLException] if neither a page or url are supplied
     # @raise [InvalidURLException] if the mapped path for a page is a Regexp
     def visit(page = nil, url: nil)
-      target_url = url || begin
-        if (mapping = transitions.key(page))
-          raise InvalidURLException, REGEXP_MAPPING_MSG unless mapping.can_compute_uri?
-          url(base_url, mapping.compute_uri)
-        end
-      end
+      url ||= transitions.url_for(page, base_url: base_url)
 
-      raise InvalidURLException, URL_MISSING_MSG unless target_url
+      raise InvalidURLException, URL_MISSING_MSG unless url
 
-      raw_session.visit(target_url)
+      raw_session.visit(url)
       @current_page = initialize_page(page) if page
       self
     end
 
     private
 
-    def find_mapped_page(url)
-      matches(url).first
-    end
-
-    def matches(url)
-      transitions.keys.find_all { |matcher| matcher.match?(url) }.sort.collect { |match| transitions[match] }
-    end
-
     def initialize_page(page_class)
       page_class.new(self).execute_on_load
     end
-
-    def url(base_url, path)
-      path = path.sub(%r{^/}, '')
-      base_url = base_url.sub(%r{/$}, '')
-      "#{base_url}/#{path}"
-    end
   end
 end

data/lib/page_magic/session_methods.rb

@@ -1,10 +1,12 @@
+# frozen_string_literal: true
+
 require 'forwardable'
 module PageMagic
   # module SessionMethods - contains methods for interacting with the {Session}
   module SessionMethods
     extend Forwardable
 
-    # @!method execute_script
+    # @!method execute_script(script)
     #  execute javascript on the browser
     #  @param [String] script the script to be executed
     #  @return [Object] object returned by the {Session#execute_script}

data/lib/page_magic/transitions.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative 'utils/url'
+require_relative 'mapping'
+
+module PageMagic
+  # class Transitions - used for registering the page classes that should be used against particular paths
+  class Transitions < Hash
+    REGEXP_MAPPING_MSG = 'URL could not be derived because mapping contains Regexps'
+
+    # Create a new transitions object.
+    # @param [Hash{String,PageMagic::Mapping => PageMagic}] transitions a map of paths to pages
+    # @example
+    #  Transitions.new('/path1' => Page1, Matcher.new('/another_*') => AnotherPageClass )
+    def initialize(transitions)
+      super
+      transitions.each do |key, value|
+        key = key.is_a?(Mapping) ? key : Mapping.new(key)
+        self[key] = value
+      end
+    end
+
+    # get the url to be used when visiting the path mapped against the given page
+    # @param [PageMagic] page - the page class to get the mapped path from
+    # @param [String] base_url - the base url of the site to be joined to the mapped path
+    # @return String
+    # @raise InvalidURLException - Raised if it is not possible to generate the url for the mapped page
+    #  i.e. if the mapping is a regular expression.
+    def url_for(page, base_url:)
+      return unless (mapping = key(page))
+      raise InvalidURLException, REGEXP_MAPPING_MSG unless mapping.can_compute_uri?
+
+      PageMagic::Utils::URL.concat(base_url, mapping.compute_uri)
+    end
+
+    # get the page class mapped to the given url
+    # @param [String] url - the url to search against
+    # @return [PageMagic]
+    def mapped_page(url)
+      matches(url).first
+    end
+
+    private
+
+    def matches(url)
+      keys.find_all { |matcher| matcher.match?(url) }.sort.collect { |match| self[match] }
+    end
+  end
+end

data/lib/page_magic/utils/string.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module PageMagic
+  module Utils
+    # module String - contains methods for manipulating strings
+    module String
+      class << self
+        # convert a snake case `String` or `Symbol`
+        # @example
+        #  classify(:snake_case) # => "SnakeCase"
+        # @return [String]
+        def classify(string_or_symbol)
+          string_or_symbol.to_s.split('_').collect(&:capitalize).reduce(:+)
+        end
+      end
+    end
+  end
+end

data/lib/page_magic/utils/url.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module PageMagic
+  module Utils
+    # module String - contains methods for manipulating strings
+    module URL
+      class << self
+        # build a url from a base and path.
+        # @example
+        #  concat('http://base.url/', '/path') # => "http://base.url/path"
+        # @return [String]
+        def concat(base_url, path)
+          path = path.sub(%r{^/}, '')
+          base_url = base_url.sub(%r{/$}, '')
+          "#{base_url}/#{path}"
+        end
+      end
+    end
+  end
+end

data/lib/page_magic/wait_methods.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module PageMagic
   # module WaitMethods - contains methods for waiting
   module WaitMethods
@@ -10,6 +12,7 @@ module PageMagic
       start_time = Time.now
       until Time.now > start_time + timeout_after
         return true if yield == true
+
         sleep retry_every
       end
       raise TimeoutException, 'Action took to long'

data/lib/page_magic/watcher.rb

@@ -1,31 +1,27 @@
+# frozen_string_literal: true
+
 module PageMagic
   # class WatchedElementDefinition - Contains the specification the for checking if an subject has changed
   class Watcher
-    attr_reader :name, :attribute, :last, :block
+    attr_reader :name, :context, :observed_value, :block
 
     # @param [Symbol] name the of the subject being checked
-    # @param [Symbol] method the method that should be called on the subject being checked
     # @example
-    #  Watcher.new(:text)
-    #  Watcher.new do
+    #  Watcher.new(:url) do
     #    session.url
     #  end
-    def initialize(name, method = nil, &block)
+    def initialize(name, context:, &block)
       @name = name
-      @attribute = method
+      @context = context
       @block = block
     end
 
-    # check current value of watched element. The result of the check is stored against {Watcher#last}
-    # a block was specified then this will be executed.
-    # @param [Object] subject - subject to run watcher against
-    def check(subject = nil)
-      @last = if block
-                subject.instance_eval(&block)
-              else
-                object = subject.send(name)
-                attribute ? object.send(attribute) : object
-              end
+    # check current value of watched element. The result of the check can be accessed
+    # by calling {PageMagic::Watcher#last}
+    # if a block was specified to the constructor then this will be executed.
+    # @return [PageMagic::Watcher]
+    def check
+      @observed_value = context.instance_eval(&block)
       self
     end
 
@@ -34,7 +30,6 @@ module PageMagic
     def ==(other)
       other.is_a?(Watcher) &&
         name == other.name &&
-        attribute == other.attribute &&
         block == other.block
     end
   end