page_magic 2.0.0.alpha1 → 2.0.0

data/lib/page_magic/session.rb

@@ -1,12 +1,13 @@
 # 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'
-    REGEXP_MAPPING_MSG = 'URL could not be derived because mapping contains Regexps'
+
     INVALID_MAPPING_MSG = 'mapping must be a string or regexp'
     UNSUPPORTED_OPERATION_MSG = 'execute_script not supported by driver'
 
@@ -20,13 +21,13 @@ module PageMagic
     def initialize(capybara_session, base_url = nil)
       @raw_session = capybara_session
       @base_url = 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
@@ -50,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
@@ -74,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
 
@@ -92,39 +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

@@ -6,7 +6,7 @@ module PageMagic
   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

@@ -5,6 +5,10 @@ module PageMagic
     # 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

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/watcher.rb

@@ -3,31 +3,25 @@
 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
 
@@ -36,7 +30,6 @@ module PageMagic
     def ==(other)
       other.is_a?(Watcher) &&
         name == other.name &&
-        attribute == other.attribute &&
         block == other.block
     end
   end

data/lib/page_magic/watchers.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'page_magic/watcher'
+require_relative 'watcher'
 
 module PageMagic
   # module Watchers - contains methods for adding watchers and checking them
@@ -11,25 +11,27 @@ module PageMagic
     # @return [Boolean] true if a change is detected
     def changed?(name)
       watched_element = watcher(name)
-      watched_element.last != watched_element.check(self).last
+      watched_element.observed_value != watched_element.check.observed_value
     end
 
     # register a new watcher
-    # @param [Object] name of the watcher/element
-    # @param [Symbol] method - the method on the watched element to check
-    # @yieldreturn [Object] the value that should be checked
-    # @example
-    #  watch(:price, :text)
-    # @example
-    #  watch(:something) do
+    # @overload watch(:price, context: object, method: :text)
+    #  @param [Symbol] name of the watcher/element
+    #  @param [Object] context the object that is being watched - defaults to self
+    #  @param [Symbol] method - the method on the watched element to check
+    # @overload watch(:text)
+    #  @param [Symbol] method - the method on the watched element to check
+    # @overload watch(:text, &blk)
+    #  @param [Symbol] name of the watcher/element
+    #  @yieldreturn [Object] the value that should be checked
+    #  @example
+    #   watch(:something) do
     #   # more complicated code to get value
-    # end
-    def watch(name, method = nil, &block)
-      raise ElementMissingException, (ELEMENT_MISSING_MSG % name) unless block || respond_to?(name)
-
-      watched_element = block ? Watcher.new(name, &block) : Watcher.new(name, method)
+    #   end
+    def watch(name, context: self, method: nil, &blk)
+      watcher = blk ? Watcher.new(name, context: context, &blk) : watch_method(name, context: context, method: method)
       watchers.delete_if { |w| w.name == name }
-      watchers << watched_element.check(self)
+      watchers << watcher.check
     end
 
     # retrieve a watcher given its name
@@ -43,5 +45,16 @@ module PageMagic
     def watchers
       @watchers ||= []
     end
+
+    private
+
+    def watch_method(name, context:, method:)
+      subject = method || name
+      raise ElementMissingException, (ELEMENT_MISSING_MSG % subject) unless context.respond_to?(subject)
+
+      Watcher.new(name, context: context) do
+        public_send(subject)
+      end
+    end
   end
 end

data/spec/page_magic/class_methods_spec.rb

@@ -1,65 +1,92 @@
 # frozen_string_literal: true
 
-module PageMagic
-  describe ClassMethods do
-    subject do
+RSpec.describe PageMagic::ClassMethods do
+  describe '#load' do
+    subject(:page_class) do
       Class.new.tap do |clazz|
         clazz.extend(described_class)
-        clazz.include(InstanceMethods)
+        clazz.include(PageMagic::InstanceMethods)
       end
     end
 
-    describe '#load' do
-      let(:page_title) { 'page title' }
-      let(:page_source) do
-        <<-HTML
+    let(:page_title) { 'page title' }
+    let(:page_source) do
+      <<-HTML
           <html>
             <head><title>#{page_title}</title></head>
           </html>
-        HTML
-      end
+      HTML
+    end
 
-      it 'returns an instance using that source' do
-        expect(subject.load(page_source).title).to eq(page_title)
+    it 'returns an instance using that source' do
+      expect(page_class.load(page_source).title).to eq(page_title)
+    end
+  end
+
+  describe 'on_load' do
+    subject(:page_class) do
+      Class.new.tap do |clazz|
+        clazz.extend(described_class)
       end
     end
 
-    describe 'on_load' do
-      context 'block not set' do
-        it 'returns a default block' do
-          expect(subject.on_load).to be(described_class::DEFAULT_ON_LOAD)
-        end
+    context 'when a block is not set' do
+      it 'returns a default block' do
+        expect(page_class.on_load).to be(described_class::DEFAULT_ON_LOAD)
       end
+    end
 
-      context 'block set' do
-        it 'returns that block' do
-          expected_block = proc {}
-          subject.on_load(&expected_block)
-          expect(subject.on_load).to be(expected_block)
-        end
+    context 'when a block is set' do
+      it 'returns that block' do
+        expected_block = proc {}
+        page_class.on_load(&expected_block)
+        expect(page_class.on_load).to be(expected_block)
       end
     end
+  end
 
-    describe '#url' do
-      it 'get/sets a value' do
-        subject.url(:url)
-        expect(subject.url).to eq(:url)
+  describe '#url' do
+    subject(:page_class) do
+      Class.new.tap do |clazz|
+        clazz.extend(described_class)
       end
     end
 
-    describe '#visit' do
-      include_context :webapp_fixture
-      it 'passes all options to create an active session on the registered url' do
-        subject.url '/page1'
-        expect(PageMagic).to receive(:session).with(application: rack_app,
-                                                    options: {},
-                                                    browser: :rack_test,
-                                                    url: subject.url).and_call_original
+    it 'get/sets a value' do
+      page_class.url(:url)
+      expect(page_class.url).to eq(:url)
+    end
+  end
 
-        session = subject.visit(application: rack_app, options: {}, browser: :rack_test)
+  describe '#visit' do
+    subject(:page_class) do
+      Class.new.tap do |clazz|
+        clazz.extend(described_class)
+        clazz.include(PageMagic::InstanceMethods)
+        clazz.url ''
+      end
+    end
 
-        expect(session.title).to eq('page1')
+    let(:rack_app) do
+      Class.new do
+        def self.call(_env)
+          [200, {}, ['<html><head><title>page1</title></head></html>']]
+        end
       end
     end
+
+    it 'passes all options to create an active session on the registered url' do
+      allow(PageMagic).to receive(:session).and_call_original
+
+      page_class.visit(application: rack_app, options: {}, browser: :rack_test)
+
+      expected_option = { application: rack_app, options: {}, browser: :rack_test, url: page_class.url }
+      expect(PageMagic).to have_received(:session).with(expected_option)
+    end
+
+    it 'returns a session' do
+      session = page_class.visit(application: rack_app, options: {}, browser: :rack_test)
+      expect(session).to be_kind_of(PageMagic::Session)
+    end
   end
 end

data/spec/page_magic/comparator/fuzzy_spec.rb

@@ -0,0 +1,44 @@
+RSpec.describe PageMagic::Comparator::Fuzzy do
+  describe '#fuzzy?' do
+    context 'when one value is fuzzy' do
+      it 'returns true' do
+        map = described_class.new(//)
+        expect(map).to be_fuzzy
+      end
+    end
+  end
+
+  describe 'match?' do
+    context 'when comparator contains the parameter' do
+      it 'returns true' do
+        expect(described_class.new(/f*o/)).to be_match('foo')
+      end
+    end
+
+    context 'when comparator does not contains the parameter' do
+      it 'returns false' do
+        expect(described_class.new(/f*o/)).not_to be_match('bar')
+      end
+    end
+  end
+
+  describe '#<=>' do
+    context 'when other is `Null`' do
+      it 'is lesser' do
+        expect(described_class.new(//) <=> PageMagic::Comparator::Null.new).to be(-1)
+      end
+    end
+
+    context 'when other is `Fuzzy`' do
+      it 'is equal' do
+        expect(described_class.new(//) <=> described_class.new(//)).to be 0
+      end
+    end
+
+    context 'when other is `Literal`' do
+      it 'is greater' do
+        expect(described_class.new(//) <=> PageMagic::Comparator::Literal.new('/')).to be 1
+      end
+    end
+  end
+end