site_prism 2.4 → 2.5

data/README.md

@@ -101,7 +101,6 @@ If you are using cucumber, here's what needs requiring:
 
 ```ruby
 require 'capybara'
-require 'capybara/dsl'
 require 'capybara/cucumber'
 require 'selenium-webdriver'
 require 'site_prism'
@@ -113,7 +112,6 @@ If you're using rspec instead, here's what needs requiring:
 
 ```ruby
 require 'capybara'
-require 'capybara/dsl'
 require 'capybara/rspec'
 require 'selenium-webdriver'
 require 'site_prism'
@@ -181,7 +179,7 @@ SitePrism uses the Addressable gem and therefore allows for parameterized URLs.
 a simple example:
 
 ```ruby
-class UserProfile < SitePris::Page
+class UserProfile < SitePrism::Page
   set_url "/users{/username}"
 end
 ```
@@ -189,7 +187,7 @@ end
 ...and a more complex example:
 
 ```ruby
-class Search < SitePris::Page
+class Search < SitePrism::Page
   set_url "/search{?query*}"
 end
 ```
@@ -211,7 +209,7 @@ to the page using `#load`:
 The `#load` method takes parameters and will apply them to the URL. Using the examples above:
 
 ```ruby
-class UserProfile < SitePris::Page
+class UserProfile < SitePrism::Page
   set_url "/users{/username}"
 end
 
@@ -223,7 +221,7 @@ end
 ...and...
 
 ```ruby
-class Search < SitePris::Page
+class Search < SitePrism::Page
   set_url "/search{?query*}"
 end
 
@@ -913,7 +911,7 @@ end
 ```ruby
 @home = Home.new
 #...
-#home.has_menu? #=> returns true or false
+@home.has_menu? #=> returns true or false
 ```
 
 Again, this allows pretty test code:
@@ -1155,6 +1153,83 @@ end
 @results_page.wait_for_search_results(10) #=> waits for 10 seconds instead of the default capybara timeout
 ```
 
+## Using Capybara Query Options
+
+When querying an element, section or a collection of elements or sections, you may
+supply Capybara query options as arguments to the element and section methods in order
+to refine the results of the query and enable Capybara to wait for all of the conditions
+necessary to properly fulfill your request.
+
+Given the following sample page and elements:
+
+```ruby
+class SearchResultSection < SitePrism::Section
+  element :title, "a.title"
+  element :blurb, "span.result-decription"
+end
+
+class SearchResults < SitePrism::Page
+  element :footer, ".footer"
+  sections :search_results, SearchResultSection, "#results li"
+end
+```
+
+Asserting the attributes of an element or section returned by any method may fail if
+the page has not finished loading the element(s):
+
+```ruby
+@results_page = SearchResults.new
+# ...
+@results_page.search_results.size.should == 25 # This may fail!
+```
+
+The above query can be rewritten to utilize the Capybara :count option when querying for
+the collection, which in turn causes Capybara to expect some number of results to be returned.
+The method calls below will succeed, provided the elements appear on the page within the timeout:
+
+```ruby
+@results_page = SearchResults.new
+# ...
+@results_page.has_search_results? :count => 25
+# OR
+@results_page.search_results :count => 25
+# OR
+@results_page.wait_for_search_results nil, :count => 25 # wait_for_<element_name> expects a timeout value to be passed as the first parameter or nil to use the default timeout value.
+```
+
+Now we can write pretty, non-failing tests without hard coding these options
+into our page and section classes:
+
+```ruby
+Then /^there are search results on the page$/ do
+  @results.page.should have_search_results :count => 25
+end
+```
+
+This is supported for all of the Capybara options including, but not limited to :count, :text,
+:wait, etc. This can also be used when defining page objects. Eg:
+
+```ruby
+class SearchResults < SitePrism::Page
+    element :footer, ".footer"
+    element :view_more, "li", text: "View More"
+    sections :search_results, SearchResultSection, "#results li"
+end
+```
+
+### Methods Supporting Capybara Options
+
+The following element methods allow Capybara options to be passed as arguments to the method:
+
+```ruby
+@results_page.<element_or_section_name> :text => "Welcome!"
+@results_page.has_<element_or_section_name>? :count => 25
+@results_page.has_no_<element_or_section_name>? :text => "Logout"
+@results_page.wait_for_<element_or_section_name> :count => 25
+@results_page.wait_until_<element_or_section_name>_visible :text => "Some ajaxy text appears!"
+@results_page.wait_until_<element_or_section_name>_invisible :text => "Some ajaxy text disappears!"
+```
+
 ## IFrames
 
 SitePrism allows you to interact with iframes. An iframe is declared as
@@ -1232,7 +1307,7 @@ end
 class Home < SitePrism::Page
   set_url "http://www.example.com"
 
-  iframe, :login_area, Login, "#login_and_registration"
+  iframe :login_area, Login, "#login_and_registration"
 end
 
 # cucumber step that performs login
@@ -1248,6 +1323,49 @@ When /^I log in$/ do
 end
 ```
 
+## SitePrism Configuration
+
+SitePrism can be configured to change its behaviour.
+
+### Using Capybara Implicit Waits
+
+By default, SitePrism element and section methods do not utilize
+Capybara's implicit wait methodology and will return immediately if
+the element or section requested is not found on the page.  Add the
+following code to your spec_helper file to enable Capybara's implicit
+wait methodology to pass through:
+
+```ruby
+SitePrism.configure do |config|
+  config.use_implicit_waits = true
+end
+```
+
+This enables you to replace this:
+
+```ruby
+# wait_until methods always wait for the element to be present on the page:
+@search_page.wait_for_search_results
+
+# Element and section methods do not:
+@search_page.search_results
+```
+
+with this:
+
+```ruby
+# With implicit waits enabled, use of wait_until methods is no longer required. This method will
+# wait for the element to be found on the page until the Capybara default timeout is reached.
+@search_page.search_results
+```
+
+## Using SitePrism with VCR
+
+There's a SitePrism plugin called `site_prism.vcr` that lets you use
+SitePrism with the VCR gem. Check it out here:
+
+* https://github.com/nestd/site_prism.vcr
+
 # Epilogue
 
 So, we've seen how to use SitePrism to put together page objects made up

data/lib/site_prism.rb

@@ -1,8 +1,23 @@
-require 'addressable/template'
-require 'site_prism/version'
 require 'site_prism/exceptions'
-require 'site_prism/element_container'
-require 'site_prism/element_checker'
-require 'site_prism/page'
-require 'site_prism/section'
+require 'addressable/template'
+
+module SitePrism
+  autoload :ElementContainer,  'site_prism/element_container'
+  autoload :ElementChecker,  'site_prism/element_checker'
+  autoload :Page,  'site_prism/page'
+  autoload :Section,  'site_prism/section'
+  autoload :Waiter, 'site_prism/waiter'
+  
+  class << self
+    attr_accessor :use_implicit_waits
+
+    def configure
+      yield self
+    end
+  end
+
+  private
+
+  @@use_implicit_waits = false
+end
 

data/lib/site_prism/element_container.rb

@@ -2,16 +2,16 @@ module SitePrism::ElementContainer
 
   def element(element_name, *find_args)
     build element_name, *find_args do
-      define_method element_name.to_s do
-        find_first *find_args
+      define_method element_name.to_s do |*runtime_args|
+        find_first *find_args, *runtime_args
       end
     end
   end
 
   def elements(collection_name, *find_args)
     build collection_name, *find_args do
-      define_method collection_name.to_s do
-        find_all *find_args
+      define_method collection_name.to_s do |*runtime_args|
+        find_all *find_args, *runtime_args
       end
     end
   end
@@ -19,29 +19,32 @@ module SitePrism::ElementContainer
 
   def section(section_name, section_class, *find_args)
     build section_name, *find_args do
-      define_method section_name do
-        section_class.new self, find_first(*find_args)
+      define_method section_name do | *runtime_args |
+        section_class.new self, find_first(*find_args, *runtime_args)
       end
     end
   end
 
   def sections(section_collection_name, section_class, *find_args)
     build section_collection_name, *find_args do
-      define_method section_collection_name do
-        find_all(*find_args).collect do |element|
+      define_method section_collection_name do |*runtime_args|
+        find_all(*find_args, *runtime_args).collect do |element|
           section_class.new self, element
         end
       end
     end
   end
 
-  def iframe(iframe_name, iframe_page_class, iframe_id)
+  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, iframe_id
-    create_nonexistence_checker iframe_name, iframe_id
-    create_waiter iframe_name, iframe_id
+    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 iframe_id.split("#").last do
+      within_frame scope_selector do
         block.call iframe_page_class.new
       end
     end
@@ -87,9 +90,10 @@ module SitePrism::ElementContainer
   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
-        Capybara.using_wait_time 0 do
-          element_exists? *find_args
+      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
@@ -98,9 +102,10 @@ module SitePrism::ElementContainer
   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
-        Capybara.using_wait_time 0 do
-          element_does_not_exist? *find_args
+      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
@@ -109,10 +114,10 @@ module SitePrism::ElementContainer
   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 = Capybara.default_wait_time|
-      Capybara.using_wait_time timeout do
-        element_exists? *find_args
-      end
+      define_method method_name do |timeout = Capybara.default_wait_time, *runtime_args|
+        Capybara.using_wait_time timeout do
+          element_exists? *find_args, *runtime_args
+        end
       end
     end
   end
@@ -120,26 +125,26 @@ module SitePrism::ElementContainer
   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|
-      Timeout.timeout timeout, SitePrism::TimeOutWaitingForElementVisibility do
-        Capybara.using_wait_time 0 do
-          sleep 0.05 while not element_exists? *find_args, visible: true
+      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
+          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|
-      Timeout.timeout timeout, SitePrism::TimeOutWaitingForElementInvisibility do
-        Capybara.using_wait_time 0 do
-          sleep 0.05 while element_exists? *find_args, visible: true
+      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
 
@@ -148,5 +153,13 @@ module SitePrism::ElementContainer
       raise SitePrism::NoSelectorForElement.new("#{self.class.name} => :#{method_name} needs a selector")
     end
   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
 end
 

data/lib/site_prism/exceptions.rb

@@ -2,6 +2,7 @@ module SitePrism
   class NoUrlForPage < StandardError; end
   class NoUrlMatcherForPage < StandardError; end
   class NoSelectorForElement < StandardError; end
+  class TimeoutException < StandardError; end
   class TimeOutWaitingForElementVisibility < StandardError; end
   class TimeOutWaitingForElementInvisibility < StandardError; end
 end

data/lib/site_prism/page.rb

@@ -10,13 +10,19 @@ module SitePrism
       visit expanded_url
     end
 
-    def displayed?
+    def displayed?(seconds = Waiter.default_wait_time)
       raise SitePrism::NoUrlMatcherForPage if url_matcher.nil?
-      !(page.current_url =~ url_matcher).nil?
+      begin
+        Waiter.wait_until_true(seconds) do
+          !(page.current_url =~ url_matcher).nil?
+        end
+      rescue SitePrism::TimeoutException=>e
+        return false
+      end
     end
 
     def self.set_url page_url
-      @url = page_url
+      @url = page_url.to_s
     end
 
     def self.set_url_matcher page_url_matcher

data/lib/site_prism/version.rb

@@ -1,4 +1,4 @@
 module SitePrism
-  VERSION = "2.4"
+  VERSION = "2.5"
 end
 

data/lib/site_prism/waiter.rb

@@ -0,0 +1,21 @@
+module SitePrism
+  class Waiter
+    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."
+    end
+
+    def self.default_wait_time
+      @@default_wait_time
+    end
+
+    private
+
+    @@default_wait_time = Capybara.default_wait_time
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: site_prism
 version: !ruby/object:Gem::Version
-  version: '2.4'
+  version: '2.5'
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-18 00:00:00.000000000 Z
+date: 2013-10-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: capybara
@@ -78,12 +78,13 @@ files:
 - lib/site_prism/page.rb
 - 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: []
-post_install_message: 
+post_install_message: Make sure to add your project/company to https://github.com/natritmeyer/site_prism/wiki/Who-is-using-SitePrism
 rdoc_options: []
 require_paths:
 - lib