page_magic 1.0.4 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a91450be8cb413b43a99d69e44f488d450dbc110
-  data.tar.gz: f29c4819b1ea546448234b9b4289bb6b176e0829
+  metadata.gz: 4acdbbbed10c450234259833ff79fc6fe45ba7f8
+  data.tar.gz: 3167a8d0be893169dac91a1f449f9713a057189e
 SHA512:
-  metadata.gz: 7786dabc62892b77b1c6d89e8db36ae8adbdeba79c11062f6df7aca65ebace69dd91615b21abaedc235c78431a38c113728b68cb0ac3877c1852eabe44cccba7
-  data.tar.gz: f89a7eba7766d74aa1e6b6f3d82f7471eb7b21bd995b9ccef3c137ea5bf82084a5d25632e286222d546035bdc1c35cac4956e296d1fa7b1c37c28516191d1313
+  metadata.gz: cd8232c273a46b22c349e8819da69f3d12680443bf3493334f0ab549698656d27ab98ddbd0ec0d2957b93038e7ec7735c9dfbfcef831aa20823b0f7cbf39ca18
+  data.tar.gz: be986a4a47b5645fb9629a6c695d090de31c0c969a82bff6f23cbef482cca57ca504acc27002a3de98fe6eafd432726a1d3f41197855e8023a9362c65f718526

data/Gemfile

@@ -2,7 +2,6 @@ source 'https://rubygems.org'
 
 gem 'capybara', '>= 2.5'
 gem 'activesupport', '~> 4'
-gem 'wait', '~> 0'
 
 group :test do
   gem 'watir-webdriver'

data/Gemfile.lock

@@ -18,7 +18,7 @@ GEM
       rack (>= 1.0.0)
       rack-test (>= 0.5.4)
       xpath (~> 2.0)
-    certifi (2015.08.10)
+    certifi (2015.11.20)
     childprocess (0.5.8)
       ffi (~> 1.0, >= 1.0.11)
     cliver (0.3.2)
@@ -43,7 +43,7 @@ GEM
     gherkin3 (3.1.2)
     git (1.2.9.1)
     github-markup (1.4.0)
-    github_api (0.12.4)
+    github_api (0.13.0)
       addressable (~> 2.3)
       descendants_tracker (~> 0.0.4)
       faraday (~> 0.8, < 0.10)
@@ -65,14 +65,16 @@ GEM
       rdoc
     json (1.8.3)
     jwt (1.5.2)
-    mime-types (2.6.2)
+    mime-types (3.0)
+      mime-types-data (~> 3.2015)
+    mime-types-data (3.2015.1120)
     mini_portile (0.6.2)
-    minitest (5.8.2)
+    minitest (5.8.3)
     multi_json (1.11.2)
     multi_test (0.1.2)
     multi_xml (0.5.5)
     multipart-post (2.0.0)
-    nokogiri (1.6.6.2)
+    nokogiri (1.6.6.4)
       mini_portile (~> 0.6.0)
     oauth2 (1.0.0)
       faraday (>= 0.8, < 0.10)
@@ -82,7 +84,7 @@ GEM
       rack (~> 1.2)
     parser (2.2.3.0)
       ast (>= 1.1, < 3.0)
-    poltergeist (1.8.0)
+    poltergeist (1.8.1)
       capybara (~> 2.1)
       cliver (~> 0.3.1)
       multi_json (~> 1.0)
@@ -105,7 +107,7 @@ GEM
       rspec-core (~> 3.4.0)
       rspec-expectations (~> 3.4.0)
       rspec-mocks (~> 3.4.0)
-    rspec-core (3.4.0)
+    rspec-core (3.4.1)
       rspec-support (~> 3.4.0)
     rspec-expectations (3.4.0)
       diff-lcs (>= 1.2.0, < 2.0)
@@ -113,7 +115,7 @@ GEM
     rspec-mocks (3.4.0)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.4.0)
-    rspec-support (3.4.0)
+    rspec-support (3.4.1)
     rubocop (0.35.1)
       astrolabe (~> 1.3)
       parser (>= 2.2.3.0, < 3.0)
@@ -142,7 +144,6 @@ GEM
     tins (1.6.0)
     tzinfo (1.2.2)
       thread_safe (~> 0.1)
-    wait (0.5.2)
     watir-webdriver (0.9.1)
       selenium-webdriver (>= 2.46.2)
     websocket (1.2.2)
@@ -170,6 +171,5 @@ DEPENDENCIES
   rubocop (~> 0.34)
   simplecov
   sinatra
-  wait (~> 0)
   watir-webdriver
   yard (~> 0.8)

data/README.md

@@ -1,4 +1,9 @@
-[![Gem Version](https://badge.fury.io/rb/page_magic.svg)](https://badge.fury.io/rb/page_magic) [![Dependency Status](https://gemnasium.com/Ladtech/page_magic.svg)](https://gemnasium.com/Ladtech/page_magic) [![Circle CI](https://circleci.com/gh/Ladtech/page_magic.svg?style=shield&circle-token=49c8f6869c1e0dc6f3b368e6e22a11fcea3aab8a)](https://circleci.com/gh/Ladtech/page_magic) [![Code Climate](https://codeclimate.com/github/Ladtech/page_magic/badges/gpa.svg)](https://codeclimate.com/github/Ladtech/page_magic) [![Test Coverage](https://codeclimate.com/github/Ladtech/page_magic/badges/coverage.svg)](https://codeclimate.com/github/Ladtech/page_magic/coverage) [![PullReview stats](https://www.pullreview.com/github/Ladtech/page_magic/badges/master.svg?)](https://www.pullreview.com/github/Ladtech/page_magic/reviews/master)
+[![Gem Version](https://badge.fury.io/rb/page_magic.svg)](https://badge.fury.io/rb/page_magic) 
+[![Dependency Status](https://gemnasium.com/Ladtech/page_magic.svg)](https://gemnasium.com/Ladtech/page_magic) 
+[![Circle CI](https://circleci.com/gh/Ladtech/page_magic.svg?style=shield&circle-token=49c8f6869c1e0dc6f3b368e6e22a11fcea3aab8a)](https://circleci.com/gh/Ladtech/page_magic) 
+[![Code Climate](https://codeclimate.com/github/Ladtech/page_magic/badges/gpa.svg)](https://codeclimate.com/github/Ladtech/page_magic) 
+[![Test Coverage](https://codeclimate.com/github/Ladtech/page_magic/badges/coverage.svg)](https://codeclimate.com/github/Ladtech/page_magic/coverage) 
+[![PullReview stats](https://www.pullreview.com/github/Ladtech/page_magic/badges/master.svg?)](https://www.pullreview.com/github/Ladtech/page_magic/reviews/master)
 #PageMagic
 PageMagic is an API for testing web applications. 
 
@@ -13,7 +18,8 @@ Wouldn't it be great if there was a framework that could:
 
 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!
+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!
 # Contents
 
 - [Installation](#installation)
@@ -31,6 +37,8 @@ Give it a try and let us know what you think! There will undoubtedly be things t
   - [Dynamic Selectors](#dynamic-selectors)
 - [Starting a session](#starting-a-session)
 - [Page mapping](#page-mapping)
+  - [Mapping against query string parameters](#mapping-against-query-string-parameters)
+  - [Mapping against fragment identifiers](#mapping-against-fragment-identifiers)
 - [Watchers](#watchers)
   - [Method watchers](#method-watchers)
   - [Simple watchers](#simple-watchers)
@@ -43,210 +51,229 @@ Give it a try and let us know what you think! There will undoubtedly be things t
 `gem install page_magic`
 
 # Quick Start
-Getting started with PageMagic is as easy, try running this:
+Getting started with PageMagic is easy, try running this:
 
 ```ruby
 require 'page_magic'
 
-class Google
+class Github
   include PageMagic
-  url 'https://www.google.com'
+  
+  url 'https://www.github.com'
 
-  text_field :search_field, name: 'q'
-  button :search_button, name: 'btnG'
+  text_field :search_field, name: 'q' do
+    watch(:url)
+    
+    after_events do
+      wait_until { changed?(:url) }
+    end
+  end
 
-  def search term
-    search_field.set term
-    search_button.click
+  def search(project_name)
+    search_field.set "#{project_name}\n"
   end
 end
-
-google = Google.visit(browser: :chrome)
-google.search('page_magic')
+github = Github.visit(browser: chrome)
+github.search('page_magic')
 ```
 
-This example defines a simple page to represent Google's search page, visits it and performs a search. 
+This example defines a page to represent Github's home page, visits it and performs a search. 
 
-This code models a single page and will let you [interact](#interacting-with-elements) with the [elements](#elements) defined on it as well as use the [helper method](Helpers) we defined.
+This code models a single page and will let you [interact](#interacting-with-elements) with the [elements](#elements) 
+defined on it as well as use the [helper method](Helpers) we defined.
 
-You can do lots with PageMagic including [mapping pages](#page-mapping) to a [session](#starting-a-session) so that they are fluidly switched in for you. You can even define [hooks](#hooks) to run when ever a element is interacted with. So what are you wating for? there' no place better to start than the [beginning](#defining-pages). Have fun! :)
+You can do lots with PageMagic including [mapping pages](#page-mapping) to a [session](#starting-a-session) so that 
+they are fluidly switched in for you. You can even define [hooks](#hooks) to run when ever a element is interacted 
+with. So what are you wating for? there's no place better to start than the [beginning](#defining-pages). Have fun! :)
 
 # Defining Pages
 To define something that PageMagic can work with, simply include PageMagic in to a class.
 ```ruby
-class LoginPage
+class Github
   include PageMagic
 end
 ```
 ## Elements
-Defining elements is easy see the example below.
+Defining elements is easy. The following example defines a text field called 'search_field' that can be found using its name which is 'q'
 
 ```ruby
-class LoginPage
+class Github
   include PageMagic
-  text_field(:username, label: 'username')
-  text_field(:password, label: 'password')
-  button(:login_button, text: 'login')
+  
+  text_field :search_field, name: 'q'
 end
 ```
 
 ### Interacting with elements
-Elements are defined with an id which is the name of the method you will use to reference it. In the above example, the textfields and button were defined with the id's, `:username`, `:password`, and `:login_button`
+Elements are defined with an id which is the name of the method you will use to reference it. In the above example, 
+the text field was defined with the ide `:search_field`.
+
+After visiting a page you are will get a `Session` object. Elements can be accessed through the session itself.
 
-After visiting a page with a PageMagic session, you can access all of the elements of that page through the session itself.
 ```ruby
-session.username.set 'joe@blogs.com'
-session.password.set 'passw0rd'
-session.login_button.click
+page.search_field.set 'page_magic'
 ```
+
 #### Multple Results
-Where an element has been scoped to return multple results, these will be returned in an array. These elements can be defined
-using all of the same features as described in this readme and behave in exactly the same way.
+Where an element has been scoped to return multple results, these will be returned in an array. 
 ```ruby
-class LoginPage
-  element :links, css: 'a'
+class ResultsPage
+  include PageMagic
+  element :results, css: '.repo-list-item'
 end
 
-session.link => Array<Element> 
+page.results #=> Array<Element> 
 ```
 
 ### Sub Elements
-If your pages are complex you can use PageMagic to compose pages, their elements and subelements to as many levels as you need to.
+If your pages are complex you can use PageMagic to compose pages, their elements and subelements to as many levels as 
+you need to.
 
 ```ruby
-class MailBox
+class ResultsPage
   include PageMagic
-  
-  element :message, id: 'message_id' do
-    link(:read, text: 'read')
+
+  element :results, css: '.repo-list-item' do
+    element :stats, css: '.repo-list-stats'
+    element :meta_data, css: '.repo-list-meta'
+    link :repo_link, css: 'h3 a'
   end
 end
 ```
+
 Sub elements can be accessed through their parent elements e.g:
-```
-session.message.read.click
+```ruby
+page.results.first.repo_link.click
 ```
 
 ### Custom elements
 PageMagic allows you to define your own custom elements.
 ```ruby
-class Nav < PageMagic::Element
-  selector css: '.nav'
-  
-  element :options, css: '.options' do
-    link(:link1, id: 'link1')
-    link(:link2, id: 'link2')
-    link(:link3, id: 'link3')
-  end
+class SearchField < PageMagic::Element
+  selector name: 'q'
+  # custom stuff
 end
 
-class MyPage 
+class Github 
   include PageMagic
-  element Nav
+  element SearchField
 end
 ```
-If an id is not specified then the name of the element class will be used. The selector for the element can be specified on the class itself or overiden when defining the element on the page. The custom element can also be extended as with other elements.
+
+If an id is not specified then the name of the element class will be used. In the above example the name given to the element of type `SearchField` would be `search_field`. The selector for the element can bespecified on the class itself or overiden when defining the element. The custom element can also be extended as with other elements.
+
 ```ruby
 class MyPage
   include PageMagic
-  element Nav, :navigation, selector: '.custom' do
+  element SearchField, :search, selector: '.custom' do
     link(:extr_link, id: 'extra-link')
   do
 end
 ```
 
 ## Hooks
-PageMagic provides hooks to allow you to interact at the right moments with your pages.
+PageMagic provides hooks to allow you to define actions that are executed when you pages and elements are interacted with.
 
 **Note:** 
-- with hooks you may well find PageMagic's [watchers](#watchers) useful.
-- The following examples wait for actions to happen. You can of course write you own wait code or try out our [wait_until](#waiting) helper:)
+- You may well find PageMagic's [watchers](#watchers) useful.
+- The following examples wait for actions to happen. You can of course write you own wait code or feel free try out our
+ [wait_until](#waiting) helper:)
 
 ### On load hook
-PageMagic lets you define an on_load hook for your pages. This lets you write any custom wait logic you might need 
-before letting execution continue.
+PageMagic lets you define an on_load hook for your pages. This will be executed when the browser thinks the page has been loaded.
+
 ```ruby
-class LoginPage
+class Github
   # ... code defining elements as shown above
   
   on_load do
-    wait_until{login_fields_have_appeared?}
+    # code that needs to run when the page has loaded
   end
 end
 ```
 
 ### Element event hooks
-Frequently, you are going to have to work with pages that make heavy use of ajax. This means that just because you've clicked something, it doesn't mean that the action is finished. For these occasions PageMagic provides `before_events` and `after_events` hooks that you use to perform custom actions and wait for things to happen.
+Frequently, you are going to have to work with pages that make heavy use of ajax. For these occasions PageMagic provides `before_events` 
+and `after_events` hooks that you use to perform custom action.
+
+In the following example we have added watchers and event hooks to the SearchField custom element we defined in the 
+[previous section](#custom-elements). Encapsulating the business logic here means that we can really add value to 
+the pages that reuse this custom element
 
 ```ruby
-class EmailMessagePage
-  include PageMagic
-  ## code defining other elements, such as subject and body
-  
-  link(:delete id: 'delete-message') do
-    after_events do
-      wait_until{fancy_animation_has_disappeared?}
-    end
+class SearchField < PageMagic::Element
+  selector name: 'q'
+  watch(:url)
+  after_events do
+    wait_until { changed?(:url) }
   end
 end
 ```
 
 ## Helper methods
-Using elements that are defined on a page is great, but if you are enacting a procedure through interacting with a few of them then your code could end up with some pretty repetitive code. In this case you can define helper methods instead. 
+Helper methods can be defined to avoid writing repetive page/element specific code outside of your pages and elements.
 
 ```ruby
-class LoginPage
+class Github
   # ... code defining elements as shown above
-  
-  def login(user, pass)
-    username.set user
-    password.set pass
-    login_button.click
+
+  def search(project_name)
+    search_field.set "#{project_name}\n"
   end
 end
 ```
 
 We can interact with helper in the same way as we did page elements.
+
 ```ruby
-session.login('joe', 'blogs')
+page.search('page_magic')
 ```
 
 ## Dynamic Selectors
-In some cases you will able to specify the selector for an element until runtime. PageMagic allows you to handle such situations with support for dynamic selectors.
+In some cases you wont be able to specify the selector for an element until runtime. PageMagic allows you to handle 
+such situations with support for dynamic selectors. In the case of our Github example it would be nice to select a 
+particular result by supplying the owners organisation name. 
 
 ```ruby
-class MailBox
+class ResultsPage
   include PageMagic
-  
-  element :message do |subject:|
-    selector xpath: '//tr[text()="#{subject}"]' 
-    link(:read, text: 'read')
+
+  element :results do |organisation:|
+
+    selector xpath: "//h3/a[contains(text(), '#{organisation}')]/../.."
+
+    # code for sub elements
   end
 end
 ```
-Here we have defined the 'message' element using a block that takes subject argument. This is passed in at run time and given to the xpath selector.
+
+In the above example the selector looks for an element that has a link containing text that includes that organisation.
+The example uses a named parameter and is invoked as follows.
 ```ruby
-session.message(subject: 'test message')
+page.results(organisation: 'Ladtech')
 ```
 
 # Starting a session
 To start a PageMagic session simply decide what browser you want to use and pass it to PageMagic's `.session` method
 ```ruby
-session = PageMagic.session(browser: :chrome, url: 'https://21st-century-mail.com')
+session = PageMagic.session(browser: :chrome, url: 'https://www.github.com)
 ```
 
-Your session won't you do much besides navigating to the given url until you have [mapped pages](#page-mapping) to it, so take a look at this next! 
+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! 
 
-**Note** PageMagic supports having multiple sessions pointed at different urls using different browsers at the same time :)
+**Note** PageMagic supports having multiple sessions using different browsers at the same time :)
  
 ## 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 the session
+To run a session against a rack application instead of a live site, simply supply the rack application when creating 
+the session
+
 ```ruby
 session = PageMagic.session(application: YourRackApp, url: '/path_to_start_at')
 ```
 
-By default PageMagic uses the Rack::Test driver for capybara however you are free to use any browser you like as long as 
-the [driver is registered](#drivers) for it.
+By default PageMagic uses the Rack::Test driver for capybara however you are free to use any browser you like as long 
+as the [driver is registered](#drivers) for it.
 
 ```ruby
 session = PageMagic.session(application: YourRackApp, browser: :your_chosen_browser, url: '/path_to_start_at')
@@ -258,24 +285,39 @@ Out of the box, PageMagic supports the following as parameters to browser:
 - :poltergeist
 - :rack_test
 
-Under the hood, PageMagic is using [Capybara](https://github.com/jnicklas/capybara) so you can register any Capybara specific driver you want. See [below](#registering-a-custom-driver) for how to do this.
+Under the hood, PageMagic is using [Capybara](https://github.com/jnicklas/capybara) so you can register any Capybara 
+compliant driver you want. See [below](#registering-a-custom-driver) for how to do this.
 
-**Note:** We don't want to impose particular driver versions so PageMagic does not list any as dependencies. Therefore you will need add the requiste gem to your Gemfile.
+**Note:** We don't want to impose particular driver versions so PageMagic does not list any as dependencies. Therefore 
+you will need add the requiste gems to your Gemfile.
 
 # Page mapping
-With PageMagic you can map which pages should be used to handle which URL paths. This is a pretty killer feature that will remove a lot of the juggling and bring back fluency to your code!
+With PageMagic you can map which pages should be used to handle which resources. Meaning that when a the page in the browser changes, PageMagic loads the correct PageObject class to handle it. This feature removes a lot of the juggling and brings back fluency to your code!
+
 ```ruby
 # define what pages map to what
-browser.define_page_mappings %r{/messages/\d+} => MessagePage,
-                             '/login' => LoginPage,
-                             '/' => MailBox
+session.define_page_mappings '/' => GitHub, '/search' => ResultsPage
+```
+You can use even use regular expressions and provide more than one mapping to the same page object class.
+
+**Note:** By default mappings are matched against a URL's path. In addition, PageMagic supports mapping against both 
+query string parameters and the fragement identifer (see below). Any combination of these can be used to define a page mapping.
+
+## Mapping against query string parameters
+```ruby
+browser.define_page_mappings PageMagic.mapping(parameters: {parameter_name: string_or_regex}) => ResultsPage                             
+```
+
+## Mapping against fragment identifiers
+JavaScript MVC frameworks allow different resources to be mapped the fragment portion of URLs. That is the part of the URL that follows the [Fragement identififer](https://en.wikipedia.org/wiki/Fragment_identifier) (#). PageMagic supports mapping page_objects 
+against URL fragments.
+
+```ruby
+browser.define_page_mappings PageMagic.mapping(fragment: string_or_regex) => ResultsPage                            
 ```
-You can use even use regular expressions to map multiple paths to the same page. In the above example we are mapping paths that that starts with '/messages/' and are followed by one ore more digits to the `MessagePage` class.
 
 # Watchers
-PageMagic lets you set a watcher on any of the elements that you have defined on your pages. Use watchers to decide when
-things have changed. The `watch` method can be called from anywhere within an element definition. For PageObjects it can
-only be called from within hooks and helper methods.
+PageMagic lets you set a watcher on any element. Use watchers to decide when things have changed. The `watch` method can be called from anywhere within an element definition. For PageObjects it can only be called from within hooks and helper methods.
 
 **Note**: Watchers are not inherited
 
@@ -292,8 +334,9 @@ end
 ```
 
 ## Simple watchers
-Simple watchers use the `watch` method passing two parameters, the first is the name of the element you want to keep an 
-eye and the second is the method that needs to be called to get the value that should be observed.
+Use `watch` method passing two parameters, the first is the name of the element you want to keep 
+an eye on and the second is the method that needs to be called to get the value that should be observed.
+
 ```ruby
 element :product_row, css '.cta' do
   watch(:total, :text)
@@ -303,6 +346,7 @@ element :product_row, css '.cta' do
   end
 end
 ```
+
 ## Custom watchers
 Custom watchers are defined by passing a name and block parameter to the `watch` method. The block returns the value 
 that needs to be observed. Use watch in this way if you need to do something non standard to obtain a value or to 
@@ -320,7 +364,7 @@ end
 ```
 
 # Waiting
-It's inevitable that if there is JavaScript on the page that you are going to have to wait for things to happen before you can move on. PageMagic supplies the `wait_until` method that can be used anywhere you might need it. The wait_until method takes a block that it will execute until either that block returns true or the timeout occurs. See the method docs for details on configuring timeouts and retry intervals.
+It's inevitable that if there is JavaScript on the page that you are going to have to wait for things to happen. PageMagic supplies the `wait_until` method that can be used anywhere you might need it. The wait_until method takes a block that it will execute until either that block returns true or the timeout occurs. See the method docs for details on configuring timeouts and retry intervals.
 
 # Drivers
 ## Registering a custom driver
@@ -339,10 +383,11 @@ end
 PageMagic.drivers.register Webkit
 
 #3. Use registered driver
-session = PageMagic.session(browser: webkit, url: 'https://21st-century-mail.com')
+session = PageMagic.session(browser: webkit, url: 'https://www.github.com')
 ```
 # Cucumber quick start
-You can obviously use PageMagic anywhere you fancy but one of the places you might decide to use it is within a Cucumber test suite. If that's the case something like the following could prove useful.
+You can obviously use PageMagic anywhere you fancy but one of the places you might decide to use it is within a 
+Cucumber test suite. If that's the case something like the following could prove useful.
 
 ## Helper methods
 Put the following in to `features/support/page_magic.rb` to make these helpers available to all of your steps.

data/VERSION

@@ -1 +1 @@
-1.0.4
+1.1.0

data/lib/page_magic.rb

@@ -14,6 +14,14 @@ require 'page_magic/drivers'
 
 # module PageMagic - PageMagic is an api for modelling pages in a website.
 module PageMagic
+  extend SingleForwardable
+
+  # @!method matcher
+  # define match critera for loading a page object class
+  # @see Matcher#initialize
+  # @return [Matcher]
+  def_delegator Matcher, :new, :matcher
+
   class << self
     # @return [Drivers] registered drivers
     def drivers

data/lib/page_magic/exceptions.rb

@@ -11,6 +11,9 @@ module PageMagic
   class InvalidURLException < Exception
   end
 
+  class MatcherInvalidException < Exception
+  end
+
   class TimeoutException < Exception
   end
 

data/lib/page_magic/matcher.rb

@@ -0,0 +1,117 @@
+require 'active_support/core_ext/object/to_query'
+module PageMagic
+  # models mapping used to relate pages to uris
+  class Matcher
+    attr_reader :path, :parameters, :fragment
+
+    # @raise [MatcherInvalidException] if at least one component is not specified
+    def initialize(path = nil, parameters: nil, fragment: nil)
+      fail MatcherInvalidException unless path || parameters || fragment
+      @path = path
+      @parameters = parameters
+      @fragment = fragment
+    end
+
+    # @return [Boolean] true if no component contains a Regexp
+    def can_compute_uri?
+      !fuzzy?(fragment) && !fuzzy?(path) && !fuzzy?(parameters)
+    end
+
+    # @return [String] uri represented by this mapping
+    def compute_uri
+      "#{path}".tap do |uri|
+        uri << "?#{parameters.to_query}" if parameters
+        uri << "##{fragment}" if fragment
+      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_valid?(uri.path) && query_string_valid?(uri.query) && fragment_valid?(uri.fragment)
+    end
+
+    # compare this matcher against another
+    # @param [Matcher] other
+    # @return [Fixnum] -1 = smaller, 0 = equal to, 1 = greater than
+    def <=>(other)
+      [:path, :parameters, :fragment].inject(0) do |result, component|
+        result == 0 ? compare(send(component), other.send(component)) : result
+      end
+    end
+
+    # check equality
+    # @param [Matcher] other
+    # @return [Boolean]
+    def ==(other)
+      return false unless other.is_a?(Matcher)
+      path == other.path && parameters == other.parameters && fragment == other.fragment
+    end
+
+    alias_method :eql?, :==
+
+    private
+
+    def compare(this, other)
+      return presence_comparison(this, other) unless this && other
+      fuzzy_comparison(this, other)
+    end
+
+    def compatible?(string, comparitor)
+      return true if comparitor.nil?
+      if fuzzy?(comparitor)
+        string =~ comparitor ? true : false
+      else
+        string == comparitor
+      end
+    end
+
+    def fragment_valid?(string)
+      compatible?(string, fragment)
+    end
+
+    def fuzzy?(component)
+      return false unless component
+      if component.is_a?(Hash)
+        component.values.any? { |o| fuzzy?(o) }
+      else
+        component.is_a?(Regexp)
+      end
+    end
+
+    def fuzzy_comparison(this, other)
+      if fuzzy?(this)
+        fuzzy?(other) ? 0 : 1
+      else
+        fuzzy?(other) ? -1 : 0
+      end
+    end
+
+    def parameters_hash(string)
+      CGI.parse(string.to_s.downcase).collect { |key, value| [key.downcase, value.first] }.to_h
+    end
+
+    def path_valid?(string)
+      compatible?(string, path)
+    end
+
+    def presence_comparison(this, other)
+      return 0 if this.nil? && other.nil?
+      return 1 if this.nil? && other
+      -1
+    end
+
+    def query_string_valid?(string)
+      return true unless parameters
+      !parameters.any? do |key, value|
+        !compatible?(parameters_hash(string)[key.downcase.to_s], value)
+      end
+    end
+  end
+end

data/lib/page_magic/session.rb

@@ -1,29 +1,30 @@
-require 'wait'
 require 'forwardable'
+require 'page_magic/matcher'
 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 is a Regexp'
+    REGEXP_MAPPING_MSG = 'URL could not be derived because mapping contains Regexps'
     INVALID_MAPPING_MSG = 'mapping must be a string or regexp'
 
     extend Forwardable
 
-    attr_reader :raw_session, :transitions
+    attr_reader :raw_session, :transitions, :base_url
 
     # Create a new session instance
     # @param [Object] capybara_session an instance of a capybara session
-    # @param [String] url url to start the session at.
-    def initialize(capybara_session, url = nil)
+    # @param [String] base_url url to start the session at.
+    def initialize(capybara_session, base_url = nil)
       @raw_session = capybara_session
-      visit(url: url) if url
+      @base_url = base_url
+      visit(url: base_url) if base_url
       @transitions = {}
     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_path)
+      mapping = find_mapped_page(current_url)
       @current_page = initialize_page(mapping) if mapping
       @current_page
     end
@@ -47,7 +48,10 @@ 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
+      @transitions = transitions.collect do |key, value|
+        key = key.is_a?(Matcher) ? key : Matcher.new(key)
+        [key, value]
+      end.to_h
     end
 
     # @!method execute_script
@@ -84,9 +88,9 @@ module PageMagic
     def visit(page = nil, url: nil)
       if url
         raw_session.visit(url)
-      elsif (path = transitions.key(page))
-        fail InvalidURLException, REGEXP_MAPPING_MSG if path.is_a?(Regexp)
-        raw_session.visit(url(current_url, path))
+      elsif (mapping = transitions.key(page))
+        fail InvalidURLException, REGEXP_MAPPING_MSG unless mapping.can_compute_uri?
+        raw_session.visit(url(base_url, mapping.compute_uri))
       else
         fail InvalidURLException, URL_MISSING_MSG
       end
@@ -96,23 +100,16 @@ module PageMagic
 
     private
 
-    def find_mapped_page(path)
-      mapping = transitions.keys.find do |key|
-        matches?(path, key)
-      end
-      transitions[mapping]
+    def find_mapped_page(url)
+      matches(url).first
     end
 
-    def initialize_page(page_class)
-      page_class.new(self).execute_on_load
+    def matches(url)
+      transitions.keys.find_all { |matcher| matcher.match?(url) }.sort.collect { |match| transitions[match] }
     end
 
-    def matches?(string, matcher)
-      if matcher.is_a?(Regexp)
-        string =~ matcher
-      else
-        string == matcher
-      end
+    def initialize_page(page_class)
+      page_class.new(self).execute_on_load
     end
 
     def url(base_url, path)

data/page_magic.gemspec

@@ -2,16 +2,16 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: page_magic 1.0.4 ruby lib
+# stub: page_magic 1.1.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "page_magic"
-  s.version = "1.0.4"
+  s.version = "1.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib"]
   s.authors = ["Leon Davis"]
-  s.date = "2015-11-16"
+  s.date = "2015-11-25"
   s.description = "Framework for modeling and interacting with webpages which wraps capybara"
   s.email = "info@lad-tech.com"
   s.extra_rdoc_files = [
@@ -47,6 +47,7 @@ Gem::Specification.new do |s|
     "lib/page_magic/elements.rb",
     "lib/page_magic/exceptions.rb",
     "lib/page_magic/instance_methods.rb",
+    "lib/page_magic/matcher.rb",
     "lib/page_magic/session.rb",
     "lib/page_magic/session_methods.rb",
     "lib/page_magic/wait_methods.rb",
@@ -67,6 +68,7 @@ Gem::Specification.new do |s|
     "spec/page_magic/element_definition_builder_spec.rb",
     "spec/page_magic/elements_spec.rb",
     "spec/page_magic/instance_methods_spec.rb",
+    "spec/page_magic/matcher_spec.rb",
     "spec/page_magic/session_methods_spec.rb",
     "spec/page_magic/session_spec.rb",
     "spec/page_magic/wait_methods_spec.rb",
@@ -93,7 +95,6 @@ Gem::Specification.new do |s|
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<capybara>, [">= 2.5"])
       s.add_runtime_dependency(%q<activesupport>, ["~> 4"])
-      s.add_runtime_dependency(%q<wait>, ["~> 0"])
       s.add_development_dependency(%q<jeweler>, ["~> 2.0"])
       s.add_development_dependency(%q<rubocop>, ["~> 0.34"])
       s.add_development_dependency(%q<yard>, ["~> 0.8"])
@@ -102,7 +103,6 @@ Gem::Specification.new do |s|
     else
       s.add_dependency(%q<capybara>, [">= 2.5"])
       s.add_dependency(%q<activesupport>, ["~> 4"])
-      s.add_dependency(%q<wait>, ["~> 0"])
       s.add_dependency(%q<jeweler>, ["~> 2.0"])
       s.add_dependency(%q<rubocop>, ["~> 0.34"])
       s.add_dependency(%q<yard>, ["~> 0.8"])
@@ -112,7 +112,6 @@ Gem::Specification.new do |s|
   else
     s.add_dependency(%q<capybara>, [">= 2.5"])
     s.add_dependency(%q<activesupport>, ["~> 4"])
-    s.add_dependency(%q<wait>, ["~> 0"])
     s.add_dependency(%q<jeweler>, ["~> 2.0"])
     s.add_dependency(%q<rubocop>, ["~> 0.34"])
     s.add_dependency(%q<yard>, ["~> 0.8"])

data/spec/page_magic/matcher_spec.rb

@@ -0,0 +1,235 @@
+# rubocop:disable Metrics/ModuleLength
+module PageMagic
+  describe Matcher do
+    describe '#initialize' do
+      context 'no componentes specified' do
+        it 'raises an exeception' do
+          expect { described_class.new }.to raise_exception(MatcherInvalidException)
+        end
+      end
+    end
+    describe '#can_compute_uri?' do
+      context 'regex in path' do
+        it 'returns false' do
+          expect(described_class.new(//).can_compute_uri?).to eq(false)
+        end
+      end
+
+      context 'regex in parameters' do
+        it 'returns false' do
+          expect(described_class.new(parameters: { param: // }).can_compute_uri?).to eq(false)
+        end
+      end
+
+      context 'regexp in fragment' do
+        it 'returns false' do
+          expect(described_class.new(fragment: //).can_compute_uri?).to eq(false)
+        end
+      end
+
+      context 'regexp not present' do
+        it 'returns true' do
+          expect(described_class.new('/').can_compute_uri?).to eq(true)
+        end
+      end
+    end
+
+    describe 'compare' do
+      subject { described_class.new('/') }
+      context 'param 1 not nil' do
+        context 'param 2 not nil' do
+          context 'literal to fuzzy' do
+            it 'returns -1' do
+              expect(subject.instance_eval { compare('/', //) }).to eq(-1)
+            end
+          end
+
+          context 'literal to literal' do
+            it 'returns 0' do
+              expect(subject.instance_eval { compare('/', '/') }).to eq(0)
+            end
+          end
+
+          context 'fuzzy to fuzzy' do
+            it 'returns 0' do
+              expect(subject.instance_eval { compare(//, //) }).to eq(0)
+            end
+          end
+
+          context 'fuzzy to literal' do
+            it 'returns 1' do
+              expect(subject.instance_eval { compare(//, '/') }).to eq(1)
+            end
+          end
+        end
+
+        context 'param2 is nil' do
+          it 'returns -1' do
+            expect(subject.instance_eval { compare('/', nil) }).to eq(-1)
+          end
+        end
+      end
+
+      context 'param1 is nil' do
+        context 'param2 not nil' do
+          it 'returns 1' do
+            expect(subject.instance_eval { compare(nil, '/') }).to eq(1)
+          end
+        end
+
+        context 'param2 nil' do
+          it 'returns 0' do
+            expect(subject.instance_eval { compare(nil, nil) }).to eq(0)
+          end
+        end
+      end
+    end
+
+    describe 'compute_uri' do
+      context 'path present' do
+        it 'returns a uri' do
+          expect(described_class.new('/').compute_uri).to eq('/')
+        end
+      end
+
+      context 'params present' do
+        context '1 param' do
+          it 'returns a uri' do
+            expect(described_class.new(parameters: { a: 1 }).compute_uri).to eq('?a=1')
+          end
+        end
+
+        context 'more than 1 param' do
+          it 'returns a uri' do
+            expect(described_class.new(parameters: { a: 1, b: 2 }).compute_uri).to eq('?a=1&b=2')
+          end
+        end
+      end
+
+      context 'fragment present' do
+        it 'returns a uri' do
+          expect(described_class.new(fragment: 'fragment').compute_uri).to eq('#fragment')
+        end
+      end
+    end
+
+    describe '#matches?' do
+      let(:matching_url) { 'http://www.example.com/path?foo=bar#fragment' }
+      let(:incompatible_url) { 'http://www.example.com/mismatch?miss=match#mismatch' }
+      context 'path requirement exists' do
+        context 'path is literal' do
+          subject do
+            described_class.new('/path')
+          end
+          it 'returns true for an exact match' do
+            expect(subject.match?(matching_url)).to eq(true)
+          end
+
+          it 'returns false when not an exact match' do
+            expect(subject.match?(incompatible_url)).to eq(false)
+          end
+        end
+
+        context 'path is regexp' do
+          subject do
+            described_class.new(/\d/)
+          end
+          it 'returns true for a match on the regexp' do
+            expect(subject.match?('3')).to eq(true)
+          end
+
+          it 'returns false when regexp is not a match' do
+            expect(subject.match?('/mismatch')).to eq(false)
+          end
+        end
+      end
+
+      context 'query string requirement exists' do
+        context 'parameter requirement is a literal' do
+          subject do
+            described_class.new(parameters: { foo: 'bar' })
+          end
+
+          it 'returns true for a match' do
+            expect(subject.match?(matching_url)).to eq(true)
+          end
+
+          it 'returns false when regexp is not a match' do
+            expect(subject.match?(incompatible_url)).to eq(false)
+          end
+        end
+
+        context 'parameter requirement is a regexp' do
+          subject do
+            described_class.new(parameters: { foo: /b[a]r/ })
+          end
+
+          it 'returns true for a match on the regexp' do
+            expect(subject.match?(matching_url)).to eq(true)
+          end
+
+          it 'returns false when regexp is not a match' do
+            expect(subject.match?(incompatible_url)).to eq(false)
+          end
+        end
+      end
+
+      context 'fragment requirement exists' do
+        context 'fragment requirement is a literal' do
+          subject do
+            described_class.new(fragment: 'fragment')
+          end
+
+          it 'returns true for a match' do
+            expect(subject.match?(matching_url)).to eq(true)
+          end
+
+          it 'returns false when regexp is not a match' do
+            expect(subject.match?(incompatible_url)).to eq(false)
+          end
+        end
+
+        context 'fragment requirement is a regexp' do
+          subject do
+            described_class.new(fragment: /fragment/)
+          end
+
+          it 'returns true for a match on the regexp' do
+            expect(subject.match?(matching_url)).to eq(true)
+          end
+
+          it 'returns false when regexp is not a match' do
+            expect(subject.match?(incompatible_url)).to eq(false)
+          end
+        end
+      end
+    end
+
+    describe '<=>' do
+      it 'compares paths' do
+        subject = described_class.new('/')
+        expect(subject).to receive(:compare).with('/', nil).and_return(:result)
+        expect(subject <=> described_class.new(parameters: {})).to eq(:result)
+      end
+
+      context 'paths are equal' do
+        it 'compares parameters' do
+          subject = described_class.new('/', parameters: :params1)
+          expect(subject).to receive(:compare).with('/', '/').and_call_original
+          expect(subject).to receive(:compare).with(:params1, :params2).and_return(:params_result)
+          expect(subject <=> described_class.new('/', parameters: :params2)).to eq(:params_result)
+        end
+      end
+
+      context 'parameters are equal' do
+        it 'compares fragments' do
+          subject = described_class.new('/', parameters: :params, fragment: :frag1)
+          expect(subject).to receive(:compare).with('/', '/').and_call_original
+          expect(subject).to receive(:compare).with(:params, :params).and_call_original
+          expect(subject).to receive(:compare).with(:frag1, :frag2).and_return(:fragment_result)
+          expect(subject <=> described_class.new('/', parameters: :params, fragment: :frag2)).to eq(:fragment_result)
+        end
+      end
+    end
+  end
+end

data/spec/page_magic/session_spec.rb

@@ -4,37 +4,38 @@ module PageMagic
     let(:page) do
       Class.new do
         include PageMagic
+        url 'http://url.com'
       end
     end
 
     subject { described_class.new(browser) }
 
-    let(:url) { 'http://url.com' }
-    let(:browser) { double('browser', current_url: url, visit: nil, current_path: :current_path) }
+    let(:url) { page.url }
+    let(:browser) { double('browser', current_url: "#{url}/somepath", visit: nil, current_path: :current_path) }
 
     describe '#current_page' do
       let(:another_page_class) do
         Class.new do
           include PageMagic
-          url '/another_page1'
+          url 'http://www.example.com/another_page1'
         end
       end
 
       before do
-        subject.define_page_mappings another_page_class.url => another_page_class
+        subject.define_page_mappings '/another_page1' => another_page_class
         subject.visit(page, url: url)
       end
 
       context 'page url has not changed' do
         it 'returns the original page' do
-          allow(browser).to receive(:current_path).and_return(page.url)
+          allow(browser).to receive(:current_url).and_return(page.url)
           expect(subject.current_page).to be_an_instance_of(page)
         end
       end
 
       context 'page url has changed' do
         it 'returns the mapped page object' do
-          allow(browser).to receive(:current_path).and_return(another_page_class.url)
+          allow(browser).to receive(:current_url).and_return(another_page_class.url)
           expect(subject.current_page).to be_an_instance_of(another_page_class)
         end
       end
@@ -52,21 +53,46 @@ module PageMagic
       end
     end
 
+    describe '#define_page_mappings' do
+      context 'mapping includes a literal' do
+        it 'creates a matcher to contain the specification' do
+          subject.define_page_mappings path: :page
+          expect(subject.transitions).to eq(Matcher.new(:path) => :page)
+        end
+      end
+
+      context 'mapping is a matcher' do
+        it 'leaves it intact' do
+          expected_matcher = Matcher.new(:page)
+          subject.define_page_mappings expected_matcher => :page
+          expect(subject.transitions.key(:page)).to be(expected_matcher)
+        end
+      end
+    end
+
+    describe '#execute_script' do
+      it 'calls the execute script method on the capybara session' do
+        expect(browser).to receive(:execute_script).with(:script).and_return(:result)
+        expect(subject.execute_script(:script)).to be(:result)
+      end
+    end
+
     describe '#find_mapped_page' do
       subject do
-        described_class.new(nil).tap do |session|
-          session.define_page_mappings '/page' => :mapped_page_using_string, /page\d/ => :mapped_page_using_regex
-        end
+        described_class.new(nil)
       end
 
-      context 'mapping is string' do
+      context 'match found' do
         it 'returns the page class' do
+          subject.define_page_mappings '/page' => :mapped_page_using_string
           expect(subject.instance_eval { find_mapped_page('/page') }).to be(:mapped_page_using_string)
         end
-      end
-      context 'mapping is regex' do
-        it 'returns the page class' do
-          expect(subject.instance_eval { find_mapped_page('/page2') }).to be(:mapped_page_using_regex)
+
+        context 'more than one match is found' do
+          it 'returns the most specific match' do
+            subject.define_page_mappings %r{/page} => :mapped_page_using_regex, '/page' => :mapped_page_using_string
+            expect(subject.instance_eval { find_mapped_page('/page') }).to eq(:mapped_page_using_string)
+          end
         end
       end
 
@@ -77,10 +103,22 @@ module PageMagic
       end
     end
 
-    describe '#execute_script' do
-      it 'calls the execute script method on the capybara session' do
-        expect(browser).to receive(:execute_script).with(:script).and_return(:result)
-        expect(subject.execute_script(:script)).to be(:result)
+    describe '#matches' do
+      subject do
+        described_class.new(nil)
+      end
+
+      it 'returns matching page mappings' do
+        subject.define_page_mappings '/page' => :mapped_page_using_string
+        expect(subject.instance_eval { matches('/page') }).to eq([:mapped_page_using_string])
+      end
+
+      context 'more than one match on path' do
+        it 'orders the results by specificity ' do
+          subject.define_page_mappings %r{/page} => :mapped_page_using_regex, '/page' => :mapped_page_using_string
+          expected_result = [:mapped_page_using_string, :mapped_page_using_regex]
+          expect(subject.instance_eval { matches('/page') }).to eq(expected_result)
+        end
       end
     end
 
@@ -167,9 +205,9 @@ module PageMagic
           expect(session.current_page).to be_a(page)
         end
 
-        it 'uses the current url and the path in the page mappings' do
+        it 'uses the base url and the path in the page mappings' do
           session.define_page_mappings '/page' => page
-          expect(browser).to receive(:visit).with("#{browser.current_url}/page")
+          expect(browser).to receive(:visit).with("#{url}/page")
           session.visit(page)
         end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: page_magic
 version: !ruby/object:Gem::Version
-  version: 1.0.4
+  version: 1.1.0
 platform: ruby
 authors:
 - Leon Davis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-11-16 00:00:00.000000000 Z
+date: 2015-11-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: capybara
@@ -38,20 +38,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4'
-- !ruby/object:Gem::Dependency
-  name: wait
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: jeweler
   requirement: !ruby/object:Gem::Requirement
@@ -158,6 +144,7 @@ files:
 - lib/page_magic/elements.rb
 - lib/page_magic/exceptions.rb
 - lib/page_magic/instance_methods.rb
+- lib/page_magic/matcher.rb
 - lib/page_magic/session.rb
 - lib/page_magic/session_methods.rb
 - lib/page_magic/wait_methods.rb
@@ -178,6 +165,7 @@ files:
 - spec/page_magic/element_definition_builder_spec.rb
 - spec/page_magic/elements_spec.rb
 - spec/page_magic/instance_methods_spec.rb
+- spec/page_magic/matcher_spec.rb
 - spec/page_magic/session_methods_spec.rb
 - spec/page_magic/session_spec.rb
 - spec/page_magic/wait_methods_spec.rb