page_magic 1.2.8 → 2.0.2

data/Makefile

@@ -0,0 +1,17 @@
+.PHONY: help
+DOCKER_IMAGE = lvl-up/page-magic
+MOUNT_DIR = /page_magic
+
+help:
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
+
+docker: ## build project docker image
+	docker build -t $(DOCKER_IMAGE) .
+
+test: ## Run tests
+	docker run -v $(PWD):$(MOUNT_DIR) -w $(MOUNT_DIR) -t $(DOCKER_IMAGE) bundle exec rspec
+
+build: docker ## build gem
+	rake build
+
+all: docker test build ## run all targets before building gem

data/README.md

@@ -56,10 +56,12 @@ Check it out :)
   - [Helper Methods](#helper-methods)
   - [Dynamic Selectors](#dynamic-selectors)
 - [Starting a session](#starting-a-session)
+  - [Using an existing session](#using-an-existing-session)
+  - [Rack applications and Rack::Test](#rack-applications-and-racktest)
 - [Page mapping](#page-mapping)
   - [Mapping against query string parameters](#mapping-against-query-string-parameters)
   - [Mapping against fragment identifiers](#mapping-against-fragment-identifiers)
-- [Loading pages from source](#loading-pages-from-source)
+- [Loading pages/elements from source](#loading-pages/elements-from-source)
 - [Watchers](#watchers)
   - [Method watchers](#method-watchers)
   - [Simple watchers](#simple-watchers)
@@ -325,9 +327,16 @@ session = PageMagic.session(browser: :chrome, url: 'https://www.github.com')
 ```
 
 Your session won't do much besides navigating to the given url until you have [mapped pages](#page-mapping) to it, so 
-take a look at this next! 
+take a look at this next!
 
 **Note** PageMagic supports having multiple sessions using different browsers at the same time :)
+
+## Using an existing session
+If you are introducing PageMagic in to a test suite that already makes use of Capybara, PageMagic can be configured to 
+make use of the session that is already configure like this:
+```ruby
+session = PageMagic.session(session: Capybara.current_session)
+```
  
 ## Rack applications and Rack::Test
 To run a session against a rack application instead of a live site, simply supply the rack application when creating 
@@ -381,16 +390,27 @@ against URL fragments.
 browser.define_page_mappings PageMagic.mapping(fragment: string_or_regex) => ResultsPage                            
 ```
 
-# Loading pages from source
+# Loading pages/elements from source
 PageMagic supports loading page objects using html source. This technique can be useful for getting quick feedback that 
-your templates correctly render based on your view objects. I.e you can test your templates in isolation.
+your templates correctly render based on your view objects. I.e you can test your templates and partials/fragments in isolation.
 ```ruby
 class MyPage
   include PageMagic
+  element(:link, id: 'link_id')
   #element definitions
 end
 
 page_instance = Page.load(html_string)
+page_instance.link.text # returns the link text
+
+
+class CustomElement < PageMagic::Element
+  element(:link, id: 'link_id')
+  #element definitions
+end
+
+page_element = CustomElement.load(html_string)
+page_element.link.text # returns the link text
 ```
 
 # Watchers
@@ -453,7 +473,8 @@ You can register any Capybara compliant driver as follows
 Webkit = PageMagic::Driver.new(:webkit) do |app, options, browser_alias_chosen|
   # Write the code necessary to initialise the driver you have chosen
   require 'capybara/webkit'
-  Capybara::Webkit::Driver.new(app, options)
+  Capybara::Webkit::Driver.new(app, 
+  )
 end
 
 #2. Register driver

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 Bundler.require :test, :development
 
 RuboCop::RakeTask.new
@@ -12,11 +14,19 @@ Jeweler::Tasks.new do |gem|
   gem.license = 'ruby'
   gem.summary = 'Framework for modeling and interacting with webpages'
   gem.description = 'Framework for modeling and interacting with webpages which wraps capybara'
-  gem.email = 'info@lad-tech.com'
+  gem.email = 'info@lvl-up.uk'
   gem.authors = ['Leon Davis']
   gem.required_ruby_version = '>= 2.1'
 end
 
 Jeweler::RubygemsDotOrgTasks.new
 
-task default: [:spec, 'rubocop:auto_correct']
+require 'rake/testtask'
+Rake::TestTask.new do |t|
+  t.libs << 'spec'
+  t.pattern = 'spec/**/*_test.rb'
+  t.warning = true
+  t.verbose = true
+end
+
+task default: [:spec, :test, 'rubocop:auto_correct']

data/VERSION

@@ -1 +1 @@
-1.2.8
+2.0.2

data/circle.yml

@@ -3,4 +3,6 @@ machine:
     version: '2.2'
 test:
   override:
-    - bundle exec rake
+    - bundle exec rake
+  post:
+    - CODECLIMATE_REPO_TOKEN=$CODECLIMATE_REPO_TOKEN bundle exec codeclimate-test-reporter

data/lib/active_support/core_ext/object/to_query.rb

@@ -0,0 +1,84 @@
+require 'cgi'
+
+class Object
+  # Alias of <tt>to_s</tt>.
+  def to_param
+    to_s
+  end
+
+  # Converts an object into a string suitable for use as a URL query string,
+  # using the given <tt>key</tt> as the param name.
+  def to_query(key)
+    "#{CGI.escape(key.to_param)}=#{CGI.escape(to_param.to_s)}"
+  end
+end
+
+class NilClass
+  # Returns +self+.
+  def to_param
+    self
+  end
+end
+
+class TrueClass
+  # Returns +self+.
+  def to_param
+    self
+  end
+end
+
+class FalseClass
+  # Returns +self+.
+  def to_param
+    self
+  end
+end
+
+class Array
+  # Calls <tt>to_param</tt> on all its elements and joins the result with
+  # slashes. This is used by <tt>url_for</tt> in Action Pack.
+  def to_param
+    collect(&:to_param).join '/'
+  end
+
+  # Converts an array into a string suitable for use as a URL query string,
+  # using the given +key+ as the param name.
+  #
+  #   ['Rails', 'coding'].to_query('hobbies') # => "hobbies%5B%5D=Rails&hobbies%5B%5D=coding"
+  def to_query(key)
+    prefix = "#{key}[]"
+
+    if empty?
+      nil.to_query(prefix)
+    else
+      collect { |value| value.to_query(prefix) }.join '&'
+    end
+  end
+end
+
+class Hash
+  # Returns a string representation of the receiver suitable for use as a URL
+  # query string:
+  # @example
+  #  {name: 'David', nationality: 'Danish'}.to_query
+  #  # => "name=David&nationality=Danish"
+  #
+  # An optional namespace can be passed to enclose key names:
+  # @example
+  #  {name: 'David', nationality: 'Danish'}.to_query('user')
+  #  # => "user%5Bname%5D=David&user%5Bnationality%5D=Danish"
+  #
+  # The string pairs "key=value" that conform the query string
+  # are sorted lexicographically in ascending order.
+  #
+  # This method is also aliased as +to_param+.
+  def to_query(namespace = nil)
+    collect do |key, value|
+      unless (value.is_a?(Hash) || value.is_a?(Array)) && value.empty?
+        value.to_query(namespace ? "#{namespace}[#{key}]" : key)
+      end
+    end.compact.sort! * '&'
+  end
+
+  alias to_param to_query
+end

data/lib/page_magic.rb

@@ -1,16 +1,17 @@
-$LOAD_PATH.unshift(File.dirname(__FILE__).to_s)
+# frozen_string_literal: true
+
 require 'capybara'
-require 'page_magic/exceptions'
-require 'page_magic/wait_methods'
-require 'page_magic/watchers'
-require 'page_magic/session'
-require 'page_magic/session_methods'
-require 'page_magic/elements'
-require 'page_magic/element_context'
-require 'page_magic/element'
-require 'page_magic/class_methods'
-require 'page_magic/instance_methods'
-require 'page_magic/drivers'
+require_relative 'page_magic/exceptions'
+require_relative 'page_magic/wait_methods'
+require_relative 'page_magic/watchers'
+require_relative 'page_magic/session'
+require_relative 'page_magic/session_methods'
+require_relative 'page_magic/elements'
+require_relative 'page_magic/element_context'
+require_relative 'page_magic/element'
+require_relative 'page_magic/class_methods'
+require_relative 'page_magic/instance_methods'
+require_relative 'page_magic/drivers'
 
 # module PageMagic - PageMagic is an api for modelling pages in a website.
 module PageMagic
@@ -18,9 +19,9 @@ module PageMagic
 
   # @!method matcher
   # define match critera for loading a page object class
-  # @see Matcher#initialize
-  # @return [Matcher]
-  def_delegator Matcher, :new, :matcher
+  # @see Mapping#initialize
+  # @return [Mapping]
+  def_delegator Mapping, :new, :matcher
 
   class << self
     # @return [Drivers] registered drivers
@@ -31,7 +32,8 @@ module PageMagic
     def included(clazz)
       clazz.class_eval do
         include(InstanceMethods)
-        extend(Elements, ClassMethods)
+        extend ClassMethods
+        extend Elements
       end
     end
 
@@ -40,7 +42,7 @@ module PageMagic
     #   PageMagic.mapping '/', parameters: {project: 'page_magic'}, fragment: 'display'
     # @see Matchers#initialize
     def mapping(path = nil, parameters: nil, fragment: nil)
-      Matcher.new(path, parameters: parameters, fragment: fragment)
+      Mapping.new(path, parameters: parameters, fragment: fragment)
     end
 
     # Visit this page based on the class level registered url
@@ -48,16 +50,21 @@ module PageMagic
     # @param [Symbol] browser name of browser
     # @param [String] url url to start the session on
     # @param [Hash] options browser driver specific options
-    # @return [Session] configured sessoin
-    def session(application: nil, browser: :rack_test, url:, options: {})
-      driver = drivers.find(browser)
-      raise UnspportedBrowserException unless driver
+    # @param [Capybara::Session] session - use you own already configure capybara session e.g. Capybara.current_session
+    # @return [Session] configured session
+    def session(session: nil, url: nil, application: nil, browser: :rack_test, options: {})
+      session ||= begin
+        driver = drivers.find(browser)
+        raise UnsupportedBrowserException unless driver
+
+        Capybara.register_driver browser do |app|
+          driver.build(app, browser: browser, options: options)
+        end
 
-      Capybara.register_driver browser do |app|
-        driver.build(app, browser: browser, options: options)
+        Capybara::Session.new(browser, application)
       end
 
-      Session.new(Capybara::Session.new(browser, application), url)
+      Session.new(session, url)
     end
   end
 end

data/lib/page_magic/class_methods.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module PageMagic
   # module ClassMethods - contains class level methods for PageObjects
   module ClassMethods
@@ -15,6 +17,7 @@ module PageMagic
     # if one has not been set on the page object class it will return a default block that does nothing
     def on_load(&block)
       return @on_load || DEFAULT_ON_LOAD unless block
+
       @on_load = block
     end
 
@@ -27,14 +30,14 @@ module PageMagic
 
     # Visit this page based on the class level registered url
     # @param [Object] application rack application (optional)
-    # @param [Symbol] browser name of browser
+    # @param [Symbol] browser name of browser driver to use
     # @param [Hash] options browser driver specific options
     # @return [Session] active session configured to be using an instance of the page object modeled by this class
     def visit(application: nil, browser: :rack_test, options: {})
       session_options = { browser: browser, options: options, url: url }
       session_options[:application] = application if application
 
-      PageMagic.session(session_options).tap do |session|
+      PageMagic.session(**session_options).tap do |session|
         session.visit(self, url: url)
       end
     end

data/lib/page_magic/comparator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative 'comparator/fuzzy'
+require_relative 'comparator/literal'
+require_relative 'comparator/parameter_map'
+require_relative 'comparator/null'
+
+module PageMagic
+  # class Comparator - used for comparing components used for mapping pages
+  class Comparator
+    class << self
+      def for(comparator)
+        klass = { Regexp => Fuzzy, Hash => ParameterMap, NilClass => Null }.fetch(comparator.class, Literal)
+        klass.new(comparator)
+      end
+    end
+
+    attr_reader :comparator, :fuzzy
+
+    def initialize(comparator, fuzzy)
+      @comparator = comparator
+      @fuzzy = fuzzy
+    end
+
+    def fuzzy?
+      fuzzy
+    end
+
+    def to_s
+      comparator.to_s
+    end
+
+    def ==(other)
+      comparator == other.comparator
+    end
+  end
+end

data/lib/page_magic/comparator/fuzzy.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module PageMagic
+  class Comparator
+    # class Fuzzy - used for modeling and comparing components that are 'fuzzy' i.e. respond to `=~` e.g. a Regexp
+    class Fuzzy < Comparator
+      def initialize(comparator)
+        super(comparator, true)
+      end
+
+      def match?(value)
+        comparator =~ value ? true : false
+      end
+
+      def <=>(other)
+        return -1 if other.is_a?(Null)
+        return 1 unless other.fuzzy?
+
+        0
+      end
+    end
+  end
+end

data/lib/page_magic/comparator/literal.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module PageMagic
+  class Comparator
+    # class Literal - used for modeling and comparing thing directly. E.g. strings
+    class Literal < Comparator
+      def initialize(comparator)
+        super(comparator, false)
+      end
+
+      def match?(value)
+        comparator == value
+      end
+
+      def <=>(other)
+        return 1 if other.fuzzy? || other.is_a?(Null)
+
+        0
+      end
+    end
+  end
+end

data/lib/page_magic/comparator/null.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module PageMagic
+  class Comparator
+    # models mapping used to relate pages to uris
+    class Null < Comparator
+      def initialize(_comparator = nil)
+        super(nil, false)
+      end
+
+      def match?(_value)
+        true
+      end
+
+      def <=>(other)
+        return 0 if other.is_a?(Null)
+
+        1
+      end
+
+      def present?
+        false
+      end
+    end
+  end
+end