site_prism 2.6 → 2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 27fcff1ed1e931ef4062524d0dfcc302cd889dce
-  data.tar.gz: 14fd216ac58ed422963b2acbd0874ff3993382d9
+  metadata.gz: 5cecd18603e2b752a61108228d5d0977ebbd8117
+  data.tar.gz: cdbd3e91b71ce10e2f1fa210c76f7e0abe47307a
 SHA512:
-  metadata.gz: 232a21ab0d139cc1390708d301ea7b4a24540da96a9b02702b6cfe70e8ffa063dce028c177b843dd6b581747bd3015eaeccc0296cfb1763a99de75e2821be701
-  data.tar.gz: 63d72784da0d0e39b8c9649f2f7bb78b566403b4394c69aea4fac56f5427921cf72281a0bc93ecdd3b968b5370240aede5f3f38768399dacf0a70c74173682d3
+  metadata.gz: bf99da3a4830b9bda41b26f548dbd8694e05e14122464c72503790cc00ff32bfc20c29c8d118726df5a9e264bdcfff33345068141b9e982ff95064c879ddee8d
+  data.tar.gz: c21eca71f43629070428a85bf7e7b1661b6a1af2e7d426490ffc4e20dd61ff9355e633a80140795f3296aaad6e0994ad4ff586e28b3e26cad683f8b0355f8013

data/README.md

@@ -29,7 +29,7 @@ class SearchResults < SitePrism::Page
 
   section :menu, MenuSection, "#gbx3"
   sections :search_results, SearchResultSection, "#results li"
-  
+
   def search_result_links
     search_results.map {|sr| sr.title['href']}
   end
@@ -57,9 +57,9 @@ end
 
 Then /^the home page should contain the menu and the search form$/ do
   @home.wait_for_menu # menu loads after a second or 2, give it time to arrive
-  @home.should have_menu
-  @home.should have_search_field
-  @home.should have_search_button
+  expect(@home).to have_menu
+  expect(@home).to have_search_field
+  expect(@home).to have_search_button
 end
 
 When /^I search for Sausages$/ do
@@ -69,17 +69,16 @@ end
 
 Then /^the search results page is displayed$/ do
   @results_page = SearchResults.new
-  @results_page.should be_displayed
+  expect(@results_page).to be_displayed
 end
 
 Then /^the search results page contains 10 individual search results$/ do
   @results_page.wait_for_search_results
-  @results_page.should have_search_results
-  @results_page.search_results.size.should == 10
+  expect(@results_page).to have_search_results count: 10
 end
 
 Then /^the search results contain a link to the wikipedia sausages page$/ do
-  @results_page.search_result_links.should include "http://en.wikipedia.org/wiki/Sausage"
+  expect(@results_page.search_result_links).to include "http://en.wikipedia.org/wiki/Sausage"
 end
 ```
 
@@ -238,61 +237,87 @@ See https://github.com/sporkmonger/addressable for more details on parameterized
 ### Verifying that a particular page is displayed
 
 Automated tests often need to verify that a particular page is
-displayed. Intuitively you'd think that simply checking that the URL
-defined using `set_url` is the current page in the browser would be enough, but experience shows that it's
-not. It is far more robust to check to see if the browser's current url
-matches a regular expression. For example, though `account/1` and `account/2`
-are the same page, their URLs are different. To deal with this,
-SitePrism provides the ability to set a URL matcher.
+displayed. SitePrism can automatically parse your URL template
+and verify that whatever components your template specifies match the
+currently viewed page.  For example, with the following URL template:
 
 ```ruby
 class Account < SitePrism::Page
-  set_url_matcher /\account\/\d+/
+  set_url "/accounts/{id}{?query*}"
 end
 ```
 
-Once a URL matcher is set for a page, you can test to see if it is
-displayed:
+The following test code would pass:
 
 ```ruby
 @account_page = Account.new
-#...
-@account_page.displayed? #=> true or false
+@account_page.load(id: 22, query: { token: "ca2786616a4285bc" })
+
+expect(@account_page.current_url).to end_with "/accounts/22?token=ca2786616a4285bc"
+expect(@account_page).to be_displayed
 ```
 
 Calling `#displayed?` will return true if the browser's current URL
-matches the regular expression for the page and false if it doesn't. So
-in the above example (`account/1` and `account/2`), calling
-`@account_page.displayed?` will return true for both examples.
+matches the page's template and false if it doesn't.
 
-#### Testing for Page display
+#### Specifying parameter values for templated URLs
 
-SitePrism's `#displayed?` predicate method allows for semantic code in
-your test:
+Sometimes you want to verify not just that the current URL matches the
+template, but that you're looking at a specific page matching that
+template.
+
+Given the previous example, if you wanted to ensure that the browser had loaded
+account number 22, you could assert the following:
 
 ```ruby
-Then /^the account page is displayed$/ do
-  @account_page.should be_displayed
-  @some_other_page.should_not be_displayed
-end
+expect(@account_page).to be_displayed(id: 22)
 ```
 
-Another example that demonstrates why using regex instead of string
-comparison for URL checking is when you want to be able to run your
-tests across multiple environments.
+You can even use regular expressions.  If, as a contrived example, you wanted to
+ensure that the browser was displaying an account with an id ending with 2, you could
+say:
 
 ```ruby
-class Login < SitePrism::Page
-  set_url "#{$test_environment}.example.com/login" #=> global var used for demonstration purposes only!!!
-  set_url_matcher /(?:dev|test|www)\.example\.com\/login/
+expect(@account_page).to be_displayed(id: /2\z/)
+```
+
+#### Accessing specific matches from a templated URL in your tests
+
+If passing options to `displayed?` isn't powerful enough to meet your
+needs, you can directly access and assert on the `url_matches` found
+when comparing your page's URL template to the current_url:
+
+```ruby
+@account_page = Account.new
+@account_page.load(id: 22, query: { token: "ca2786616a4285bc", color: 'irrelevant' })
+
+expect(@account_page).to be_displayed(id: 22)
+expect(@account_page.url_matches['query']['token']).to eq "ca2786616a4285bc"
+```
+
+#### Falling back to basic regexp matchers
+
+If SitePrism's built-in URL matching is not sufficient for your needs
+ you can override and use SitePrism's previous support for regular expression-based
+URL matchers by it by calling `set_url_matcher`:
+
+```ruby
+class Account < SitePrism::Page
+  set_url_matcher %r{/accounts/\d+}
 end
 ```
 
-The above example would work for `dev.example.com/login`,
-`test.example.com/login` and `www.example.com/login`; now your tests
-aren't limited to one environment but can verify that they are on the
-correct page regardless of the environment the tests are being executed
-against.
+#### Testing for Page display
+
+SitePrism's `#displayed?` predicate method allows for semantic code in
+your test:
+
+```ruby
+Then /^the account page is displayed$/ do
+  expect(@account_page).to be_displayed
+  expect(@some_other_page).not_to be_displayed
+end
+```
 
 ### Getting the Current Page's URL
 
@@ -306,7 +331,7 @@ end
 @account = Account.new
 #...
 @account.current_url #=> "http://www.example.com/account/123"
-@account.current_url.should include "example.com/account/"
+expect(@account.current_url).to include "example.com/account/"
 ```
 
 ### Page Title
@@ -336,7 +361,7 @@ end
 @account = Account.new
 #...
 @account.secure? #=> true/false
-@account.should be_secure
+expect(@account).to be_secure
 ```
 
 ## Elements
@@ -412,14 +437,14 @@ end
 
 ```ruby
 Then /^the search field exists$/ do
-  @home.should have_search_field
+  expect(@home).to have_search_field
 end
 ```
 
 #### Testing that an element does not exist
 
 To test that an element does not exist on the page, it is not possible to just call
-`#should_not have_search_field`. SitePrism supplies the `#has_no_<element>?` method
+`#not_to have_search_field`. SitePrism supplies the `#has_no_<element>?` method
 that should be used to test for non-existence. Using the above example:
 
 ```ruby
@@ -432,7 +457,7 @@ that should be used to test for non-existence. Using the above example:
 
 ```ruby
 Then /^the search field exists$/ do
-  @home.should have_no_search_field #NB: NOT => @home.should_not_ have_search_field
+  expect(@home).to have_no_search_field #NB: NOT => expect(@home).not_to_ have_search_field
 end
 ```
 
@@ -575,9 +600,9 @@ arrays:
 
 ```ruby
 @friends_page.names.each {|name| puts name.text}
-@friends_page.names.map {|name| name.text}.should == ["Alice", "Bob", "Fred"]
-@friends_page.names.size.should == 3
-@friends_page.should have(3).names
+expect(@friends_page.names.map {|name| name.text}.to eq ["Alice", "Bob", "Fred"]
+expect(@friends_page.names.size).to eq 3
+expect(@friends_page).to have(3).names
 ```
 
 #### Testing for the existence of the element collection
@@ -604,7 +629,7 @@ end
 
 ```ruby
 Then /^there should be some names listed on the page$/ do
-  @friends_page.should have_names
+  expect(@friends_page).to have_names
 end
 ```
 
@@ -641,7 +666,7 @@ to wait for:
 Like the individual elements, calling the `elements` method will create
 two methods: `wait_until_<elements_name>_visible` and
 `wait_until_<elements_name>_invisible`. Calling these methods will cause
-your test to wait for the elements to become visible or invisibe. Using
+your test to wait for the elements to become visible or invisible. Using
 the above example:
 
 ```ruby
@@ -674,7 +699,7 @@ present in the browser, false if they're not all there.
 # and...
 
 Then /^the friends page contains all the expected elements$/ do
-  @friends_page.should be_all_there
+  expect(@friends_page).to be_all_there
 end
 
 ```
@@ -760,7 +785,7 @@ selector that will be used to find the root element of the section; this
 root node becomes the 'scope' of the section.
 
 The following shows that though the same section can appear on multiple
-pages, it can take a different root node: 
+pages, it can take a different root node:
 
 ```ruby
 # define the section that appears on both pages
@@ -826,10 +851,10 @@ end
 
 ```ruby
 Then /^the home page menu contains a link to the various search functions$/ do
-  @home.menu.should have_search
-  @home.menu.search['href'].should include "google.com"
-  @home.menu.should have_images
-  @home.menu.should have_maps
+  expect(@home.menu).to have_search
+  expect(@home.menu.search['href']).to include "google.com"
+  expect(@home.menu).to have_images
+  expect(@home.menu).to have_maps
 end
 ```
 
@@ -917,8 +942,8 @@ end
 Again, this allows pretty test code:
 
 ```ruby
-@home.should have_menu
-@home.should_not have_menu
+expect(@home).to have_menu
+expect(@home).not_to have_menu
 ```
 
 #### Waiting for a section to exist
@@ -981,7 +1006,7 @@ sections within sections within sections within sections!
 
 ```ruby
 
-# define a page that contains an area that contains a section for both logging in and registration, then modelling each of the sub sections seperately
+# define a page that contains an area that contains a section for both logging in and registration, then modelling each of the sub sections separately
 
 class Login < SitePrism::Section
   element :username, "#username"
@@ -1010,8 +1035,8 @@ Then /^I sign in$/ do
   @home = Home.new
   @home.load
   @home.wait_for_login_and_registration
-  @home.should have_login_and_registration
-  @home.login_and_registration.should have_username
+  expect(@home).to have_login_and_registration
+  expect(@home.login_and_registration).to have_username
   @home.login_and_registration.login.username.set "bob"
   @home.login_and_registration.login.password.set "p4ssw0rd"
   @home.login_and_registration.login.sign_in.click
@@ -1022,8 +1047,8 @@ end
 When /^I enter my name into the home page's registration form$/ do
   @home = Home.new
   @home.load
-  @home.login_and_registration.should have_first_name
-  @home.login_and_registration.should have_last_name
+  expect(@home.login_and_registration).to have_first_name
+  expect(@home.login_and_registration).to have_last_name
   @home.login_and_registration.first_name.set "Bob"
   # ...
 end
@@ -1049,7 +1074,7 @@ as an ordinary section:
 
 ```ruby
 @home = Home.new
-@home.menu.should have_title
+expect(@home.menu).to have_title
 ```
 
 ### Section Collections
@@ -1097,10 +1122,10 @@ end
 
 ```ruby
 Then /^there are lots of search_results$/ do
-  @results_page.search_results.size.should == 10
+  expect(@results_page.search_results.size).to eq 10
   @results_page.search_results.each do |search_result|
-    search_result.should have_title
-    search_result.blurb.text.should_not be_nil
+    expect(search_result).to have_title
+    expect(search_result.blurb.text).not_to be_nil
   end
 end
 ```
@@ -1121,7 +1146,7 @@ define a single anonymous section:
 
 ```ruby
 class SearchResults < SitePrism::Page
-  sections :search_results, SearchResultSection, "#results li" do
+  sections :search_results, "#results li" do
     element :title, "a.title"
     element :blurb, "span.result-decription"
   end
@@ -1159,7 +1184,7 @@ end
 
 ```ruby
 Then /^there are search results on the page$/ do
-  @results.page.should have_search_results
+  expect(@results.page).to have_search_results
 end
 ```
 
@@ -1217,7 +1242,7 @@ the page has not finished loading the element(s):
 ```ruby
 @results_page = SearchResults.new
 # ...
-@results_page.search_results.size.should == 25 # This may fail!
+expect(@results_page.search_results.size).to == 25 # This may fail!
 ```
 
 The above query can be rewritten to utilize the Capybara :count option when querying for
@@ -1239,7 +1264,7 @@ into our page and section classes:
 
 ```ruby
 Then /^there are search results on the page$/ do
-  @results.page.should have_search_results :count => 25
+  expect(@results.page).to have_search_results :count => 25
 end
 ```
 
@@ -1267,6 +1292,30 @@ The following element methods allow Capybara options to be passed as arguments t
 @results_page.wait_until_<element_or_section_name>_invisible :text => "Some ajaxy text disappears!"
 ```
 
+## Test views with Page objects
+
+It's possible to use the same page objects of integration tests for view tests, too,
+just pass the rendered HTML to the ```load``` method:
+
+```ruby
+require 'spec_helper'
+
+describe 'admin/things/index' do
+  let(:list_page) { AdminThingsListPage.new }
+  let(:thing) { build(:thing, some_attribute: 'some attribute') }
+
+  it 'contains the things we expect' do
+    assign(:things, [thing])
+
+    render template: 'admin/things/index'
+
+    list_page.load(rendered)
+
+    expect(list_page.rows.first.some_attribute).to have_text('some attribute')
+  end
+end
+```
+
 ## IFrames
 
 SitePrism allows you to interact with iframes. An iframe is declared as
@@ -1311,7 +1360,7 @@ the above example, here's how it's done:
 @page = PageContainingIframe.new
 # ...
 @page.has_my_iframe? #=> true
-@page.should have_my_iframe
+expect(@page).to have_my_iframe
 ```
 
 ### Waiting for an iframe
@@ -1416,12 +1465,12 @@ all over the place. Here's an example of this common problem:
 @home.search_field.set "Sausages"
 @home.search_field.search_button.click
 @results_page = SearchResults.new # <-- noise
-@results_page.should have_search_result_items
+expect(@results_page).to have_search_result_items
 ```
 
 The annoyance (and, later, maintenance nightmare) is having to create
 `@home` and `@results_page`. It would be better to not have to create
-instances of pages all over your tests. 
+instances of pages all over your tests.
 
 The way I've dealt with this problem is to create a class containing
 methods that return instances of the pages. Eg:
@@ -1471,7 +1520,7 @@ When /^I search for Sausages$/ do
 end
 
 Then /^I am on the results page$/ do
-  @app.results_page.should be_displayed
+  expect(@app.results_page).to be_displayed
 end
 
 # etc...
@@ -1480,4 +1529,3 @@ end
 The only thing that needs instantiating is the App class - from then on
 pages don't need to be initialized, they are now returned by methods on
 @app. Maintenance win!
-

data/lib/site_prism.rb

@@ -7,7 +7,8 @@ module SitePrism
   autoload :Page,  'site_prism/page'
   autoload :Section,  'site_prism/section'
   autoload :Waiter, 'site_prism/waiter'
-  
+  autoload :AddressableUrlMatcher, 'site_prism/addressable_url_matcher'
+
   class << self
     attr_accessor :use_implicit_waits
 
@@ -18,6 +19,5 @@ module SitePrism
 
   private
 
-  @@use_implicit_waits = false
+  @use_implicit_waits = false
 end
-

data/lib/site_prism/addressable_url_matcher.rb

@@ -0,0 +1,136 @@
+require 'digest'
+require 'base64'
+
+module SitePrism
+  class AddressableUrlMatcher
+    COMPONENT_NAMES = %w(scheme user password host port path query fragment).map(&:to_sym).freeze
+    COMPONENT_PREFIXES = {
+      query: '?',
+      fragment: '#'
+    }.freeze
+
+    attr_reader :pattern
+
+    def initialize(pattern)
+      @pattern = pattern
+    end
+
+    # @return the hash of extracted mappings from parsing the provided URL according to our pattern,
+    # or nil if the URL doesn't conform to the matcher template.
+    def mappings(url)
+      uri = Addressable::URI.parse(url)
+      result = {}
+      COMPONENT_NAMES.each do |component|
+        component_result = component_matches(component, uri)
+        result = component_result ? result.merge!(component_result) : nil
+        break unless result
+      end
+      result
+    end
+
+    # Determine whether URL matches our pattern, and optionally whether the extracted mappings match
+    # a hash of expected values.  You can specify values as strings, numbers or regular expressions.
+    def matches?(url, expected_mappings = {})
+      actual_mappings = mappings(url)
+      if actual_mappings
+        expected_mappings.empty? ? true : all_expected_mappings_match?(expected_mappings, actual_mappings)
+      else
+        false
+      end
+    end
+
+    private
+
+    def all_expected_mappings_match?(expected_mappings, actual_mappings)
+      expected_mappings.all? do |key, expected_value|
+        actual_value = actual_mappings[key.to_s]
+        case expected_value
+        when Numeric
+          actual_value == expected_value.to_s
+        when Regexp
+          actual_value.match(expected_value)
+        else
+          expected_value == actual_value
+        end
+      end
+    end
+
+    # Memoizes the extracted component templates
+    def component_templates
+      @component_templates ||= extract_component_templates
+    end
+
+    def extract_component_templates
+      COMPONENT_NAMES.each_with_object({}) do |component, component_templates|
+        component_url = to_substituted_uri.public_send(component).to_s
+
+        next unless component_url && component_url != ''
+
+        reverse_substitutions.each_pair do |substituted_value, template_value|
+          component_url = component_url.sub(substituted_value, template_value)
+        end
+
+        component_templates[component] = Addressable::Template.new(component_url.to_s)
+      end.freeze
+    end
+
+    # Returns empty hash if the template omits the component, a set of substitutions if the
+    # provided URI component matches the template component, or nil if the match fails.
+    def component_matches(component, uri)
+      extracted_mappings = {}
+      component_template = component_templates[component]
+      if component_template
+        component_url = uri.public_send(component).to_s
+        unless (extracted_mappings = component_template.extract(component_url))
+          # to support Addressable's expansion of queries, ensure it's parsing the fragment as appropriate (e.g. {?params*})
+          prefix = COMPONENT_PREFIXES[component]
+          return nil unless prefix && (extracted_mappings = component_template.extract(prefix + component_url))
+        end
+      end
+      extracted_mappings
+    end
+
+    # Convert the pattern into an Addressable URI by substituting the template slugs with nonsense strings.
+    def to_substituted_uri
+      url = pattern
+      substitutions.each_pair do |slug, value|
+        url = url.sub(slug, value)
+      end
+      begin
+        Addressable::URI.parse(url)
+      rescue Addressable::URI::InvalidURIError
+        raise SitePrism::InvalidUrlMatcher, 'Could not automatically match your URL.  Note: templated port numbers are not currently supported.'
+      end
+    end
+
+    def substitutions
+      @substitutions ||= slugs.each_with_index.reduce({}) do |memo, slugindex|
+        slug, index = slugindex
+        memo.merge(slug => slug_prefix(slug) + substitution_value(index))
+      end
+    end
+
+    def reverse_substitutions
+      @reverse_substitutions ||= slugs.each_with_index.reduce({}) do |memo, slugindex|
+        slug, index = slugindex
+        memo.merge(slug_prefix(slug) + substitution_value(index) => slug, substitution_value(index) => slug)
+      end
+    end
+
+    def slugs
+      pattern.scan(/\{[^}]+\}/)
+    end
+
+    # If a slug begins with non-alpha characters, it may denote the start of a new component (e.g. query or fragment).
+    # We emit this prefix as part of the substituted slug so that Addressable's URI parser can see it as such.
+    def slug_prefix(slug)
+      matches = slug.match(/\A\{([^A-Za-z]+)/)
+      matches && matches[1] || ''
+    end
+
+    # Generate a repeatable 5 character uniform alphabetical nonsense string to allow parsing as a URI
+    def substitution_value(index)
+      Base64.urlsafe_encode64(Digest::SHA1.digest(index.to_s)).gsub(/[^A-Za-z]/, '')[0..5]
+    end
+  end
+end

data/lib/site_prism/element_checker.rb

@@ -1,8 +1,9 @@
-module SitePrism::ElementChecker
-  def all_there?
-    Capybara.using_wait_time(0) do
-      self.class.mapped_items.all? {|element| send "has_#{element}?" }
+module SitePrism
+  module ElementChecker
+    def all_there?
+      Capybara.using_wait_time(0) do
+        self.class.mapped_items.all? { |element| send "has_#{element}?" }
+      end
     end
   end
 end
-

data/lib/site_prism/element_container.rb

@@ -1,178 +1,185 @@
-module SitePrism::ElementContainer
-
-  def element(element_name, *find_args)
-    build element_name, *find_args do
-      define_method element_name.to_s do |*runtime_args|
-        find_first *find_args, *runtime_args
+module SitePrism
+  module ElementContainer
+    attr_reader :mapped_items
+
+    def element(element_name, *find_args)
+      build element_name, *find_args do
+        define_method element_name.to_s do |*runtime_args, &element_block|
+          self.class.raise_if_block(self, element_name.to_s, !element_block.nil?)
+          find_first(*find_args, *runtime_args)
+        end
       end
     end
-  end
 
-  def elements(collection_name, *find_args)
-    build collection_name, *find_args do
-      define_method collection_name.to_s do |*runtime_args|
-        find_all *find_args, *runtime_args
+    def elements(collection_name, *find_args)
+      build collection_name, *find_args do
+        define_method collection_name.to_s do |*runtime_args, &element_block|
+          self.class.raise_if_block(self, collection_name.to_s, !element_block.nil?)
+          find_all(*find_args, *runtime_args)
+        end
       end
     end
-  end
-  alias :collection :elements
-
-  def section(section_name, *args, &block)
-    section_class, find_args = extract_section_options args, &block
-    build section_name, *find_args do
-      define_method section_name do | *runtime_args |
-        section_class.new self, find_first(*find_args, *runtime_args)
+    alias_method :collection, :elements
+
+    def section(section_name, *args, &block)
+      section_class, find_args = extract_section_options args, &block
+      build section_name, *find_args do
+        define_method section_name do |*runtime_args, &element_block|
+          self.class.raise_if_block(self, section_name.to_s, !element_block.nil?)
+          section_class.new self, find_first(*find_args, *runtime_args)
+        end
       end
     end
-  end
 
-  def sections(section_collection_name, *args, &block)
-    section_class, find_args = extract_section_options args, &block
-    build section_collection_name, *find_args do
-      define_method section_collection_name do |*runtime_args|
-        find_all(*find_args, *runtime_args).collect do |element|
-          section_class.new self, element
+    def sections(section_collection_name, *args, &block)
+      section_class, find_args = extract_section_options args, &block
+      build section_collection_name, *find_args do
+        define_method section_collection_name do |*runtime_args, &element_block|
+          self.class.raise_if_block(self, section_collection_name.to_s, !element_block.nil?)
+          find_all(*find_args, *runtime_args).map do |element|
+            section_class.new self, element
+          end
         end
       end
     end
-  end
 
-  def iframe(iframe_name, iframe_page_class, selector)
-    element_selector = deduce_iframe_element_selector(selector)
-    scope_selector = deduce_iframe_scope_selector(selector)
-    add_to_mapped_items iframe_name
-    create_existence_checker iframe_name, element_selector
-    create_nonexistence_checker iframe_name, element_selector
-    create_waiter iframe_name, element_selector
-    define_method iframe_name do |&block|
-      within_frame scope_selector do
-        block.call iframe_page_class.new
+    def iframe(iframe_name, iframe_page_class, selector)
+      element_selector = deduce_iframe_element_selector(selector)
+      scope_selector = deduce_iframe_scope_selector(selector)
+      add_to_mapped_items iframe_name
+      create_existence_checker iframe_name, element_selector
+      create_nonexistence_checker iframe_name, element_selector
+      create_waiter iframe_name, element_selector
+      define_method iframe_name do |&block|
+        within_frame scope_selector do
+          block.call iframe_page_class.new
+        end
       end
     end
-  end
 
-  def add_to_mapped_items(item)
-    @mapped_items ||= []
-    @mapped_items << item.to_s
-  end
+    def add_to_mapped_items(item)
+      @mapped_items ||= []
+      @mapped_items << item.to_s
+    end
 
-  def mapped_items
-    @mapped_items
-  end
+    def raise_if_block(obj, name, has_block)
+      return unless has_block
+      fail SitePrism::UnsupportedBlock, "#{obj.class}##{name} does not accept blocks, did you mean to define a (i)frame?"
+    end
 
-  private
+    private
 
-  def build(name, *find_args)
-    if find_args.empty?
-      create_no_selector name
-    else
-      add_to_mapped_items name
-      yield
+    def build(name, *find_args)
+      if find_args.empty?
+        create_no_selector name
+      else
+        add_to_mapped_items name
+        yield
+      end
+      add_helper_methods name, *find_args
     end
-    add_helper_methods name, *find_args
-  end
 
-  def add_helper_methods(name, *find_args)
-    create_existence_checker name, *find_args
-    create_nonexistence_checker name, *find_args
-    create_waiter name, *find_args
-    create_visibility_waiter name, *find_args
-    create_invisibility_waiter name, *find_args
-  end
+    def add_helper_methods(name, *find_args)
+      create_existence_checker name, *find_args
+      create_nonexistence_checker name, *find_args
+      create_waiter name, *find_args
+      create_visibility_waiter name, *find_args
+      create_invisibility_waiter name, *find_args
+    end
 
-  def create_helper_method(proposed_method_name, *find_args)
-    if find_args.empty?
-      create_no_selector proposed_method_name
-    else
-      yield
+    def create_helper_method(proposed_method_name, *find_args)
+      if find_args.empty?
+        create_no_selector proposed_method_name
+      else
+        yield
+      end
     end
-  end
 
-  def create_existence_checker(element_name, *find_args)
-    method_name = "has_#{element_name.to_s}?"
-    create_helper_method method_name, *find_args do
-      define_method method_name do |*runtime_args|
-        wait_time = SitePrism.use_implicit_waits ? Capybara.default_wait_time : 0
-        Capybara.using_wait_time wait_time do
-          element_exists? *find_args, *runtime_args
+    def create_existence_checker(element_name, *find_args)
+      method_name = "has_#{element_name}?"
+      create_helper_method method_name, *find_args do
+        define_method method_name do |*runtime_args|
+          wait_time = SitePrism.use_implicit_waits ? Capybara.default_wait_time : 0
+          Capybara.using_wait_time wait_time do
+            element_exists?(*find_args, *runtime_args)
+          end
         end
       end
     end
-  end
 
-  def create_nonexistence_checker(element_name, *find_args)
-    method_name = "has_no_#{element_name.to_s}?"
-    create_helper_method method_name, *find_args do
-      define_method method_name do |*runtime_args|
-        wait_time = SitePrism.use_implicit_waits ? Capybara.default_wait_time : 0
-        Capybara.using_wait_time wait_time do
-          element_does_not_exist? *find_args, *runtime_args
+    def create_nonexistence_checker(element_name, *find_args)
+      method_name = "has_no_#{element_name}?"
+      create_helper_method method_name, *find_args do
+        define_method method_name do |*runtime_args|
+          wait_time = SitePrism.use_implicit_waits ? Capybara.default_wait_time : 0
+          Capybara.using_wait_time wait_time do
+            element_does_not_exist?(*find_args, *runtime_args)
+          end
         end
       end
     end
-  end
 
-  def create_waiter(element_name, *find_args)
-    method_name = "wait_for_#{element_name.to_s}"
-    create_helper_method method_name, *find_args do
-      define_method method_name do |timeout = nil, *runtime_args|
-        timeout = timeout.nil? ? Capybara.default_wait_time : timeout
-        Capybara.using_wait_time timeout do
-          element_exists? *find_args, *runtime_args
+    def create_waiter(element_name, *find_args)
+      method_name = "wait_for_#{element_name}"
+      create_helper_method method_name, *find_args do
+        define_method method_name do |timeout = nil, *runtime_args|
+          timeout = timeout.nil? ? Capybara.default_wait_time : timeout
+          Capybara.using_wait_time timeout do
+            element_exists?(*find_args, *runtime_args)
+          end
         end
       end
     end
-  end
 
-  def create_visibility_waiter(element_name, *find_args)
-    method_name = "wait_until_#{element_name.to_s}_visible"
-    create_helper_method method_name, *find_args do
-      define_method method_name do |timeout = Capybara.default_wait_time, *runtime_args|
-        Timeout.timeout timeout, SitePrism::TimeOutWaitingForElementVisibility do
-          Capybara.using_wait_time 0 do
-            sleep 0.05 while not element_exists? *find_args, *runtime_args, visible: true
+    def create_visibility_waiter(element_name, *find_args)
+      method_name = "wait_until_#{element_name}_visible"
+      create_helper_method method_name, *find_args do
+        define_method method_name do |timeout = Capybara.default_wait_time, *runtime_args|
+          Timeout.timeout timeout, SitePrism::TimeOutWaitingForElementVisibility do
+            Capybara.using_wait_time 0 do
+              sleep 0.05 until element_exists?(*find_args, *runtime_args, visible: true)
+            end
           end
         end
       end
     end
-  end
 
-  def create_invisibility_waiter(element_name, *find_args)
-    method_name = "wait_until_#{element_name.to_s}_invisible"
-    create_helper_method method_name, *find_args do
-      define_method method_name do |timeout = Capybara.default_wait_time, *runtime_args|
-        Timeout.timeout timeout, SitePrism::TimeOutWaitingForElementInvisibility do
-          Capybara.using_wait_time 0 do
-            sleep 0.05 while element_exists? *find_args, *runtime_args, visible: true
+    def create_invisibility_waiter(element_name, *find_args)
+      method_name = "wait_until_#{element_name}_invisible"
+      create_helper_method method_name, *find_args do
+        define_method method_name do |timeout = Capybara.default_wait_time, *runtime_args|
+          Timeout.timeout timeout, SitePrism::TimeOutWaitingForElementInvisibility do
+            Capybara.using_wait_time 0 do
+              sleep 0.05 while element_exists?(*find_args, *runtime_args, visible: true)
+            end
           end
         end
       end
     end
-  end
 
-  def create_no_selector(method_name)
-    define_method method_name do
-      raise SitePrism::NoSelectorForElement.new("#{self.class.name} => :#{method_name} needs a selector")
+    def create_no_selector(method_name)
+      define_method method_name do
+        fail SitePrism::NoSelectorForElement.new, "#{self.class.name} => :#{method_name} needs a selector"
+      end
     end
-  end
 
-  def deduce_iframe_scope_selector(selector)
-    selector.is_a?(Integer) ? selector : selector.split("#").last
-  end
+    def deduce_iframe_scope_selector(selector)
+      selector.is_a?(Integer) ? selector : selector.split('#').last
+    end
 
-  def deduce_iframe_element_selector(selector)
-    selector.is_a?(Integer) ?  "iframe:nth-of-type(#{selector + 1})" : selector
-  end
+    def deduce_iframe_element_selector(selector)
+      selector.is_a?(Integer) ? "iframe:nth-of-type(#{selector + 1})" : selector
+    end
 
-  def extract_section_options(args, &block)
-    if args.first.is_a? Class
-      section_class = args.shift
-    elsif block_given?
-      section_class = Class.new SitePrism::Section, &block
-    else
-      raise ArgumentError.new "You should provide section class either as a block, or as the second argument"
+    def extract_section_options(args, &block)
+      if args.first.is_a? Class
+        section_class = args.shift
+      elsif block_given?
+        section_class = Class.new SitePrism::Section, &block
+      else
+        fail ArgumentError, 'You should provide section class either as a block, or as the second argument'
+      end
+      return section_class, args
     end
-    return section_class, args
   end
 end
-

data/lib/site_prism/exceptions.rb

@@ -1,9 +1,10 @@
 module SitePrism
   class NoUrlForPage < StandardError; end
   class NoUrlMatcherForPage < StandardError; end
+  class InvalidUrlMatcher < StandardError; end
   class NoSelectorForElement < StandardError; end
   class TimeoutException < StandardError; end
   class TimeOutWaitingForElementVisibility < StandardError; end
   class TimeOutWaitingForElementInvisibility < StandardError; end
+  class UnsupportedBlock < StandardError;  end
 end
-

data/lib/site_prism/page.rb

@@ -4,28 +4,54 @@ module SitePrism
     include ElementChecker
     extend ElementContainer
 
-    def load(expansion = {})
-      expanded_url = url(expansion)
-      raise SitePrism::NoUrlForPage if expanded_url.nil?
-      visit expanded_url
+    def page
+      @page || Capybara.current_session
     end
 
-    def displayed?(seconds = Waiter.default_wait_time)
-      raise SitePrism::NoUrlMatcherForPage if url_matcher.nil?
+    def load(expansion_or_html = {})
+      if expansion_or_html.is_a? String
+        @page = Capybara.string(expansion_or_html)
+      else
+        expanded_url = url(expansion_or_html)
+        fail SitePrism::NoUrlForPage if expanded_url.nil?
+        visit expanded_url
+      end
+    end
+
+    def displayed?(*args)
+      expected_mappings = args.last.is_a?(::Hash) ? args.pop : {}
+      seconds = args.length > 0 ? args.first : Waiter.default_wait_time
+      fail SitePrism::NoUrlMatcherForPage if url_matcher.nil?
       begin
-        Waiter.wait_until_true(seconds) do
-          !(page.current_url =~ url_matcher).nil?
-        end
-      rescue SitePrism::TimeoutException=>e
-        return false
+        Waiter.wait_until_true(seconds) { url_matches?(expected_mappings) }
+      rescue SitePrism::TimeoutException
+        false
       end
     end
 
-    def self.set_url page_url
+    def url_matches(seconds = Waiter.default_wait_time)
+      return unless displayed?(seconds)
+
+      if url_matcher.is_a?(Regexp)
+        regexp_backed_matches
+      else
+        template_backed_matches
+      end
+    end
+
+    def regexp_backed_matches
+      url_matcher.match(page.current_url)
+    end
+
+    def template_backed_matches
+      matcher_template.mappings(page.current_url)
+    end
+
+    def self.set_url(page_url)
       @url = page_url.to_s
     end
 
-    def self.set_url_matcher page_url_matcher
+    def self.set_url_matcher(page_url_matcher)
       @url_matcher = page_url_matcher
     end
 
@@ -34,7 +60,7 @@ module SitePrism
     end
 
     def self.url_matcher
-      @url_matcher
+      @url_matcher || url
     end
 
     def url(expansion = {})
@@ -52,21 +78,42 @@ module SitePrism
 
     private
 
-    def find_first *find_args
-      find *find_args
+    def find_first(*find_args)
+      find(*find_args)
     end
 
-    def find_all *find_args
-      all *find_args
+    def find_all(*find_args)
+      all(*find_args)
     end
 
-    def element_exists? *find_args
-      has_selector? *find_args
+    def element_exists?(*find_args)
+      has_selector?(*find_args)
     end
 
-    def element_does_not_exist? *find_args
-      has_no_selector? *find_args
+    def element_does_not_exist?(*find_args)
+      has_no_selector?(*find_args)
+    end
+
+    def url_matches?(expected_mappings = {})
+      if url_matcher.is_a?(Regexp)
+        url_matches_by_regexp?
+      elsif url_matcher.respond_to?(:to_str)
+        url_matches_by_template?(expected_mappings)
+      else
+        fail SitePrism::InvalidUrlMatcher
+      end
+    end
+
+    def url_matches_by_regexp?
+      !regexp_backed_matches.nil?
+    end
+
+    def url_matches_by_template?(expected_mappings)
+      matcher_template.matches?(page.current_url, expected_mappings)
+    end
+
+    def matcher_template
+      @addressable_url_matcher ||= AddressableUrlMatcher.new(url_matcher)
     end
   end
 end
-

data/lib/site_prism/section.rb

@@ -6,7 +6,7 @@ module SitePrism
 
     attr_reader :root_element, :parent
 
-    def initialize parent, root_element 
+    def initialize(parent, root_element)
       @parent, @root_element = parent, root_element
     end
 
@@ -14,16 +14,16 @@ module SitePrism
       root_element.visible?
     end
 
-    def execute_script input
+    def execute_script(input)
       Capybara.current_session.execute_script input
     end
 
-    def evaluate_script input
+    def evaluate_script(input)
       Capybara.current_session.evaluate_script input
     end
 
     def parent_page
-      candidate_page = self.parent
+      candidate_page = parent
       until candidate_page.is_a?(SitePrism::Page)
         candidate_page = candidate_page.parent
       end
@@ -32,25 +32,20 @@ module SitePrism
 
     private
 
-    def find_first *find_args
-      root_element.find *find_args
+    def find_first(*find_args)
+      root_element.find(*find_args)
     end
 
-    def find_all *find_args
-      root_element.all *find_args
+    def find_all(*find_args)
+      root_element.all(*find_args)
     end
 
-    def element_exists? *find_args
-      unless root_element.nil?
-        root_element.has_selector? *find_args
-      end
+    def element_exists?(*find_args)
+      root_element.has_selector?(*find_args) unless root_element.nil?
     end
 
-    def element_does_not_exist? *find_args
-      unless root_element.nil?
-        root_element.has_no_selector? *find_args
-      end
+    def element_does_not_exist?(*find_args)
+      root_element.has_no_selector?(*find_args) unless root_element.nil?
     end
   end
 end
-

data/lib/site_prism/version.rb

@@ -1,4 +1,3 @@
 module SitePrism
-  VERSION = "2.6"
+  VERSION = '2.7'
 end
-

data/lib/site_prism/waiter.rb

@@ -1,21 +1,17 @@
 module SitePrism
   class Waiter
-    def self.wait_until_true(wait_time_seconds=default_wait_time)
+    def self.wait_until_true(wait_time_seconds = default_wait_time)
       start_time = Time.now
       loop do
         return true if yield
         break unless Time.now - start_time <= wait_time_seconds
         sleep(0.05)
       end
-      raise SitePrism::TimeoutException.new, "Timed out while waiting for block to return true."
+      fail SitePrism::TimeoutException, 'Timed out while waiting for block to return true'
     end
 
     def self.default_wait_time
-      @@default_wait_time
+      Capybara.default_wait_time
     end
-
-    private
-
-    @@default_wait_time = Capybara.default_wait_time
   end
-end
+end

metadata

@@ -1,61 +1,67 @@
 --- !ruby/object:Gem::Specification
 name: site_prism
 version: !ruby/object:Gem::Version
-  version: '2.6'
+  version: '2.7'
 platform: ruby
 authors:
 - Nat Ritmeyer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-11 00:00:00.000000000 Z
+date: 2015-04-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: capybara
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.1'
-    - - <
+    - - "<"
       - !ruby/object:Gem::Version
         version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.1'
-    - - <
+    - - "<"
       - !ruby/object:Gem::Version
         version: '3.0'
 - !ruby/object:Gem::Dependency
   name: addressable
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version
         version: 2.3.3
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version
         version: 2.3.3
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - <
+    - - "<"
       - !ruby/object:Gem::Version
         version: '4.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - <
+    - - "<"
       - !ruby/object:Gem::Version
         version: '4.0'
 description: SitePrism gives you a simple, clean and semantic DSL for describing your
@@ -65,6 +71,10 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
+- README.md
+- lib/site_prism.rb
+- lib/site_prism/addressable_url_matcher.rb
 - lib/site_prism/element_checker.rb
 - lib/site_prism/element_container.rb
 - lib/site_prism/exceptions.rb
@@ -72,9 +82,6 @@ files:
 - lib/site_prism/section.rb
 - lib/site_prism/version.rb
 - lib/site_prism/waiter.rb
-- lib/site_prism.rb
-- LICENSE
-- README.md
 homepage: http://github.com/natritmeyer/site_prism
 licenses:
 - BSD3
@@ -85,17 +92,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: 1.9.3
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.3
+rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
 summary: A Page Object Model DSL for Capybara