page_magic 1.2.7 → 2.0.0

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

@@ -20,6 +20,25 @@ Well PageMagic might just be the answer!
 
 Give it a try and let us know what you think! There will undoubtedly be things that can be improved and issues that 
 we are not aware of so your feedback/pull requests are greatly appreciated!
+
+##Under the hood
+Under the hood PageMagic uses the totally brilliant [Capybara](https://github.com/teamcapybara/capybara) to benefit from its amazing cross browser support.
+ 
+PageMagic builds on top of Capybara to build resuable models for webpages and website structure.
+ 
+##What about the other PageObject frameworks out there?
+PageMagic isn't the first [PageObject](https://martinfowler.com/bliki/PageObject.html) framework to be written, indeed there are others out there that are totaly awesome e.g:
+- [PageObject](https://github.com/cheezy/page-object)
+- [SitePrism](https://github.com/natritmeyer/site_prism)
+
+Whilst these APIs are great, PageMagic goes much further in the power it provides for:
+ - [modelling pages](defining-pages) and page components 
+ - defining the [wait logic](#hooks) and [watchers](#watchers) that are required to build robust page objects that work reliably with javascript rich webpages.
+ - Supporting [page transitions](#page-mapping)
+ 
+Check it out :)
+
+ 
 # Contents
 
 - [Installation](#installation)
@@ -40,7 +59,7 @@ we are not aware of so your feedback/pull requests are greatly appreciated!
 - [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)
@@ -157,6 +176,19 @@ After visiting a page you are will get a `Session` object. Elements can be acces
 ```ruby
 page.search_field.set 'page_magic'
 ```
+PageMagic sits on top of [Capybara](https://github.com/teamcapybara/capybara) and ultimately returns capybara elements elements for you interact with. Interacting with the element types above is done by calling the following methods:
+
+ element     | method 
+ ---         | --- 
+ text_field  | set(String)
+ checkbox    | set(Boolean)
+ radio       | choose(String)
+ link        | click
+ text_area   | set(String)
+ select_list | select(String)
+ 
+Typically you will not need to know much about Capybara itself but there will be times when you want to interact with elements at a lower level.In this case please see Capybara's [API](http://www.rubydoc.info/github/jnicklas/capybara/Capybara/Node/Element) For more information.
+ 
 
 ### Sub Elements
 If your pages are complex you can use PageMagic to compose pages, their elements and subelements to as many levels as 
@@ -349,16 +381,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
@@ -421,7 +464,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.7
+2.0.0

data/circle.yml

@@ -1,6 +1,8 @@
 machine:
   ruby:
-    version: '2.1'
+    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,10 +50,10 @@ 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: {})
+    # @return [Session] configured session
+    def session(url: nil, application: nil, browser: :rack_test, options: {})
       driver = drivers.find(browser)
-      raise UnspportedBrowserException unless driver
+      raise UnsupportedBrowserException unless driver
 
       Capybara.register_driver browser do |app|
         driver.build(app, browser: browser, options: options)

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