site_prism 0.9

data/LICENSE

@@ -0,0 +1,28 @@
+Copyright (c) 2011, Nathaniel Ritmeyer
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
+
+3. Neither the name Nathaniel Ritmeyer nor the names of contributors to
+this software may be used to endorse or promote products derived from this
+software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS
+IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
+OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/lib/site_prism.rb

@@ -0,0 +1,8 @@
+module SitePrism
+  
+end
+
+require 'site_prism/exceptions'
+require 'site_prism/element_container'
+require 'site_prism/page'
+require 'site_prism/section'

data/lib/site_prism/element_container.rb

@@ -0,0 +1,104 @@
+# Contains methods applicable to both {SitePrism::Page}s and {SitePrism::Section}s. Note that they are mixed into the {SitePrism::Page}
+# and {SitePrism::Section} classes so the methods below are used as class methods.
+module SitePrism::ElementContainer
+  
+  # Creates two methods; the first method has the same name as the element_name parameter and returns the capybara element
+  # located by the element_locator parameter when the method is called. The second method generated has a name with a format
+  # of: 'has_#\{element_name}?' which returns true if the element as located by the element_locator parameter exists, false
+  # if it doesn't
+  # @param [Symbol] element_name The name of the element
+  # @param [String] element_locator The CSS locator to find the element
+  # @example
+  #   class HomePage < SitePrism::Page
+  #     element :search_link, 'div.search > a'
+  #   end
+  #   home = HomePage.new
+  #   
+  #   #the element method created 2 methods...
+  #   home.search_link #=> returns the capybara element located by the element_locator parameter
+  #   home.has_search_link? #=> returns true if the capybara element as located by the element_locator exists, false if it doesn't
+  #   
+  #   #The has_search_link? method allows use of magic matchers in rspec/cucumber:
+  #   home.should have_search_link
+  #   home.should_not have_search_link
+  def element element_name, element_locator
+    create_existence_checker element_name, element_locator
+    define_method element_name.to_s do
+      find_one element_locator
+    end
+  end
+  
+  # Works in the same way as {SitePrism::Page.element} in that it will generate two methods; one to check existence of
+  # the element (in the format 'has_#\{element_name}?'), and another to return not a single element, but an array of elements
+  # found by the css locator
+  # @param [Symbol] collection_name The name of the collection
+  # @param [String] collection_locator The CSS locator that returns the list of elements in the collection
+  # @example
+  #   class HomePage < SitePrism::Page
+  #     elements :app_links, '.title-links > a'
+  #   end
+  #   home = HomePage.new
+  #   
+  #   home.should have_app_links
+  #   home.app_links #=> [#<Capybara::Element tag="a">, #<Capybara::Element tag="a">, #<Capybara::Element tag="a">]
+  #   home.app_links.map {|link| link.text}.should == ['Finance', 'Maps', 'Blogs']
+  def elements collection_name, collection_locator
+    create_existence_checker collection_name, collection_locator
+    define_method collection_name.to_s do
+      find_all collection_locator
+    end
+  end
+  alias :collection :elements
+
+  # Creates a method that returns an instance of a {SitePrism::Section}. If a page contains a common section (eg: a search area) that
+  # appears on many pages, create a {SitePrism::Section} for it and then expose it in each {SitePrism::Page} that contains the section.
+  # Say a search engine website displays the search field and search button on each page and they always have the same IDs, they should
+  # be extracted into a {SitePrism::Section} that would look something like this:
+  #
+  #   class SearchArea < SitePrism::Section
+  #     element :search_field, '.q'
+  #     element :search_button, '.btnK'
+  #   end
+  # 
+  # ...then that section could be added to any page as follows:
+  # 
+  #   class SearchPage < SitePrism::Page
+  #     section :search_area, SearchArea, '.tsf-p'
+  #   end
+  #   
+  #   class SearchResultsPage < SitePrism::Page
+  #     section :search_again, SearchArea, '.tsf-p table'
+  #   end
+  # 
+  # The SearchArea section appears on both pages, but can be invoked by methods specific to the page (eg: 'search_area' and 'search_again')
+  # and the root element for the section can be different on the page (eg: '.tsf-p' and '.tsf-p table').
+  # @param [Symbol] the method name to be called against this page or section to return an instance of the {SitePrism::Section} class
+  # @param [Class] the class that models this area of the page
+  # @param [String] the CSS locator for the root element of the section on this page/section
+  def section section_name, section_class, section_locator
+    create_existence_checker section_name, section_locator
+    define_method section_name do
+      section_class.new find_one section_locator
+    end
+  end
+  
+  # Works in the same way as {SitePrism::Page.section} but instead of it returning one section, it returns an array of them. 
+  def sections section_collection_name, section_class, section_collection_locator
+    create_existence_checker section_collection_name, section_collection_locator
+    define_method section_collection_name do
+      find_all(section_collection_locator).collect do |element|
+        section_class.new element
+      end
+    end
+  end
+  
+  private
+  
+  # Creates a method used to check for the existence of the element whose details are passed to it
+  # @param
+  def create_existence_checker element_name, element_locator
+    define_method "has_#{element_name.to_s}?" do
+      element_exists? element_locator
+    end
+  end
+end

data/lib/site_prism/exceptions.rb

@@ -0,0 +1,7 @@
+# SitePrism's exceptions...
+module SitePrism
+  # Raised if you ask a page to load but it hasn't had its url set
+  class NoUrlForPage < StandardError; end
+  # Raised if you check to see if a page is displayed but it hasn't had its url matcher set
+  class NoUrlMatcherForPage < StandardError; end
+end

data/lib/site_prism/page.rb

@@ -0,0 +1,108 @@
+module SitePrism
+  # Subclasses of {SitePrism::Page} represent pages in your app.
+  #   class Home < SitePrism::Page
+  #   end
+  # 
+  # The above is an example of how to make a class representing the home page. There are a number of properties that can be
+  # set on a page - here is an example of a more fully spec'ed out page:
+  #   class Home < SitePrism::Page
+  #     set_url "/"
+  #     set_url_matcher /\/home.htm$/
+  #   end
+  class Page
+    include Capybara::DSL
+    extend ElementContainer
+    
+    # Visits the url associated with this page
+    # @raise [SitePrism::NoUrlForPage] To load a page the url must be set using {.set_url}
+    def load
+      raise SitePrism::NoUrlForPage if url.nil?
+      visit url
+    end
+    
+    # Checks to see if we're on this page or not
+    # @return true if the browser's current url matches the {.url_matcher} that has been set, false if it doesn't
+    # @raise [SitePrism::NoUrlMatcherForPage] To check whether we're on this page or not the url matcher must be set using {.set_url_matcher}
+    # @example
+    #   class SearchPage < SitePrism::Page
+    #     set_url_matcher /\/search.htm$/
+    #   end
+    #   search_page = SearchPage.new
+    #   search_page.load
+    #   puts "We're on the search page" if search_page.displayed?
+    #   search_page.should be_displayed
+    def displayed?
+      raise SitePrism::NoUrlMatcherForPage if url_matcher.nil?
+      !(page.current_url =~ url_matcher).nil?
+    end
+    
+    # Set the url associated with this page
+    # @param [String] page_url the portion of the url that identifies this page when appended onto Capybara's app_host. Calling {SitePrism::Page#load} causes Capybara to visit this page.
+    # @example
+    #   class SearchPage < SitePrism::Page
+    #     set_url "/search.htm"
+    #   end
+    def self.set_url page_url
+      @url = page_url
+    end
+    
+    # Set the url matcher associated with this page
+    # @param [Regexp] page_url_matcher a regular expression that when compared to the current browser url will match if we're on this page or not match if we're not on this page
+    # @example
+    #   class SearchPage < SitePrism::Page
+    #     set_url_matcher /\/search.htm$/
+    #   end
+    def self.set_url_matcher page_url_matcher
+      @url_matcher = page_url_matcher
+    end
+    
+    # Get the url associated with this page
+    # @see SitePrism::Page#url
+    # @return [String] the url originally set in {.set_url}
+    def self.url
+      @url
+    end
+    
+    # Get the url matcher associated with this page
+    # @see SitePrism::Page#url_matcher
+    # @return [Regexp] the url matcher originally set in {.set_url_matcher}
+    def self.url_matcher
+      @url_matcher
+    end
+    
+    # Get the url associated with this page
+    # @see SitePrism::Page.url
+    def url
+      self.class.url
+    end
+    
+    # Get the url matcher associated with this page
+    # @see SitePrism::Page.url_matcher
+    def url_matcher
+      self.class.url_matcher
+    end
+    
+    # Gets the title of the current page
+    # @return [String, nil] the text value of the title element within the page's head block
+    def title
+      title_selector = 'html > head > title'
+      using_wait_time(0) { page.find(title_selector).text if page.has_selector?(title_selector) }
+    end
+    
+    private
+    
+    # Page specific element finder
+    def find_one locator
+      find locator
+    end
+    
+    # Page specific elements finder
+    def find_all locator
+      all locator
+    end
+    
+    def element_exists? locator
+      has_selector? locator
+    end
+  end
+end

data/lib/site_prism/section.rb

@@ -0,0 +1,25 @@
+module SitePrism
+  class Section
+    extend ElementContainer
+    
+    def initialize root_element
+      @root_element = root_element
+    end
+    
+    private
+    
+    # Section specific element finder
+    def find_one locator
+      @root_element.find locator
+    end
+    
+    # Section specific elements finder
+    def find_all locator
+      @root_element.all locator
+    end
+
+    def element_exists? locator
+      @root_element.has_selector? locator
+    end
+  end
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification 
+name: site_prism
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: "0.9"
+platform: ruby
+authors: 
+- Nat Ritmeyer
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-12-22 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: capybara
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.1.1
+  type: :runtime
+  version_requirements: *id001
+description: none just yet...
+email: 
+- nat@natontesting.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/site_prism/element_container.rb
+- lib/site_prism/exceptions.rb
+- lib/site_prism/page.rb
+- lib/site_prism/section.rb
+- lib/site_prism.rb
+- LICENSE
+homepage: http://github.com/natritmeyer/site_prism
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: none just yet...
+test_files: []
+
+has_rdoc: