site_prism 0.9.9 → 1.0

data/README.md

@@ -0,0 +1,962 @@
+# SitePrism
+_A Page Object Model DSL for Capybara_
+
+SitePrism gives you a simple, clean and semantic DSL for describing your site using the Page Object Model pattern, for use with Capybara in automated acceptance testing.
+
+Find the pretty documentation here: http://rdoc.info/gems/site_prism/frames
+
+## Synopsis
+
+Here's an overview of how SitePrism is designed to be used:
+
+```ruby
+# define our site's pages
+
+class Home < SitePrism::Page
+  set_url "http://www.google.com"
+  set_url_matcher /google.com\/?/
+
+  element :search_field, "input[name='q']"
+  element :search_button, "button[name='btnK']"
+  elements :footer_links, "#footer a"
+  section :menu, MenuSection, "#gbx3"
+end
+
+class SearchResults < SitePrism::Page
+  set_url_matcher /google.com\/results\?.*/
+
+  section :menu, MenuSection, "#gbx3"
+  sections :search_results, SearchResultSection, "#results li"
+end
+
+# define sections used on multiple pages or multiple times on one page
+
+class MenuSection < SitePrism::Section
+  element :search, "a.search"
+  element :images, "a.image-search"
+  element :maps, "a.map-search"
+end
+
+class SearchResultSection < SitePrism::Section
+  element :title, "a.title"
+  element :blurb, "span.result-decription"
+end
+
+# now for some tests
+
+When /^I navigate to the google home page$/ do
+  @home = Home.new
+  @home.load
+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
+end
+
+When /^I search for Sausages$/ do
+  @home.search_field.set "Sausages"
+  @home.search_button.click
+end
+
+Then /^the search results page is displayed$/ do
+  @results_page = SearchResults.new
+  @results_page.should 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
+end
+
+Then /^the search results contain a link to the wikipedia sausages page$/ do
+  @results_page.search_results.map {|sr| sr.title['href']}.should include "http://en.wikipedia.org/wiki/Sausage"
+end
+```
+
+Now for the details...
+
+## Setup
+
+### Installation
+
+To install SitePrism:
+
+```bash
+gem install site_prism
+```
+
+### Using SitePrism with Cucumber
+
+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'
+```
+
+### Using SitePrism with RSpec
+
+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'
+```
+
+## Introduction to the Page Object Model
+
+The Page Object Model is a test automation pattern that aims to create
+an abstraction of your site's user interface that can be used in tests.
+The most common way to do this is to model each page as a class, and
+to then use instances of those classes in your tests.
+
+If a class represents a page then each element of the page is
+represented by a method that, when called, returns a reference to that
+element that can then be acted upon (clicked, set text value), or
+queried (is it enabled? visible?).
+
+SitePrism is based around this concept, but goes further as you'll see
+below by also allowing modelling of repeated sections that appear on
+muliple pages, or many times on a page using the concept of sections.
+
+## Pages
+
+As you might be able to guess from the name, pages are fairly central to
+the Page Object Model. Here's how SitePrism models them:
+
+### Creating a Page Model
+
+The simplest page is one that has nothing defined in it. Here's an
+example of how to begin modelling a home page:
+
+```ruby
+class Home < SitePrism::Page
+end
+```
+
+The above has nothing useful defined, only the name.
+
+### Adding a URL
+
+A page usually has a URL. If you want to be able to navigate to a page,
+you'll need to set its URL. Here's how:
+
+```ruby
+class Home < SitePrism::Page
+  set_url "http://www.google.com"
+end
+```
+
+Note that setting a URL is optional - you only need to set a url if you want to be able to navigate
+directly to that page. It makes sense to set the URL for a page model of a home
+page or a login page, but probably not a search results page.
+
+### Navigating to the Page
+
+Once the URL has been set (using `set_url`), you can navigate directly
+to the page using `#load`:
+
+```ruby
+@home_page = Home.new
+@home_page.load
+```
+
+This will tell which ever capybara driver you have configured to
+navigate to the URL set against that page's class.
+
+### 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.
+
+```ruby
+class Account < SitePrism::Page
+  set_url_matcher /\account\/\d+/
+end
+```
+
+Once a URL matcher is set for a page, you can test to see if it is
+displayed:
+
+```ruby
+@account_page = Account.new
+#...
+@account_page.displayed? #=> true or false
+```
+
+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.
+
+#### Testing for Page display
+
+SitePrism's `#displayed?` predicate method allows for semantic code in
+your test:
+
+```ruby
+Then /^the account page is displayed$/ do
+  @account_page.should be_displayed
+  @some_other_page.should_not be_displayed
+end
+```
+
+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.
+
+```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/
+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.
+
+#### Page Title
+
+Getting a page's title isn't hard:
+
+```ruby
+class Account < SitePrism::Page
+end
+
+@account = Account.new
+#...
+@account.title #=> "Welcome to Your Account"
+```
+
+## Elements
+
+Pages are made up of elements (text fields, buttons, combo boxes, etc),
+either individual elements or groups of them. Examples of individual
+elements would be a search field or a company logo image; examples of
+element collections would be items in any sort of list, eg: menu items,
+images in a carousel, etc.
+
+### Individual Elements
+
+To interact with individual elements, they need to be defined as part of
+the relevant page. SitePrism makes this easy:
+
+```ruby
+class Home < SitePrism::Page
+  element :search_field, "input[name='q']"
+end
+```
+
+Here we're adding a search field to the Home page. The `element` method
+takes 2 arguments: the name of the element as a symbol, and a css selector
+as a string.
+
+#### Accessing the individual element
+
+The `element` method will add a number of methods to instances of the
+particular Page class. The first method to be added is the name of the
+element. So using the following example:
+
+```ruby
+class Home < SitePrism::Page
+  set_url "http://www.google.com"
+
+  element :search_field, "input[name='q']"
+end
+```
+
+... the following shows how to get hold of the search field:
+
+```ruby
+@home_page = Home.new
+@home.load
+
+@home.search_field #=> will return the capybara element found using the selector
+@home.search_field.set "the search string" #=> since search_field returns a capybara element, you can use the capybara API to deal with it
+@home.search_field.text #=> standard method on a capybara element; returns a string
+```
+
+#### Testing for the existence of the element
+
+Another method added to the Page class by the `element` method is the
+`has_<element name>?` method. Using the same example as above:
+
+```ruby
+class Home < SitePrism::Page
+  set_url "http://www.google.com"
+
+  element :search_field, "input[name='q']"
+end
+```
+
+... you can test for the existence of the element on the page like this:
+
+```ruby
+@home_page = Home.new
+@home.load
+@home.has_search_field? #=> returns true if it exists, false if it doesn't
+```
+
+...which makes for nice test code:
+
+```ruby
+Then /^the search field exists$/ do
+  @home.should have_search_field
+end
+```
+
+#### Waiting for an element to appear on a page
+
+The final method added by calling `element` is the `wait_for_<element_name>` method.
+Calling the method will cause the test to wait for the Capybara's
+default wait time for the element to exist. It is also possible to use a
+custom amount of time to wait. Using the same example as above:
+
+```ruby
+class Home < SitePrism::Page
+  set_url "http://www.google.com"
+
+  element :search_field, "input[name='q']"
+end
+```
+
+... you can wait for the search field to exist like this:
+
+```ruby
+@home_page = Home.new
+@home.load
+@home.wait_for_search_field
+# or...
+@home.wait_for_search_field(10) #will wait for 10 seconds for the search field to appear
+```
+
+#### Summary of what the element method provides:
+
+Given:
+
+```ruby
+class Home < SitePrism::Page
+  element :search_field, "input[name='q']"
+end
+```
+
+...then the following methods are available:
+
+```ruby
+@home.search_field
+@home.has_search_field?
+@home.wait_for_search_field
+@home.wait_for_search_field(10)
+```
+
+### Element Collections
+
+Sometimes you don't want to deal with an individual element but rather
+with a collection of similar elements, for example, a list of names. To
+enable this, SitePrism provides the `elements` method on the Page class.
+Here's how it works:
+
+```ruby
+class Friends < SitePrism::Page
+  elements :names, "ul#names li a"
+end
+```
+
+Just like the `element` method, the `elements` method takes 2 arguments:
+the first being the name of the elements as a symbol, the second is the
+css selector that would return the array of capybara elements.
+
+#### Accessing the elements
+
+Just like the `element` method, the `elements` method adds a few methods
+to the Page class. The first one is of the name of the element
+collection which returns an array of capybara elements that match the
+css selector. Using the example above:
+
+```ruby
+class Friends < SitePrism::Page
+  elements :names, "ul#names li a"
+end
+```
+
+You can access the element collection like this:
+
+```ruby
+@friends_page = Friends.new
+# ...
+@friends_page.names #=> [<Capybara::Element>, <Capybara::Element>, <Capybara::Element>]
+```
+
+With that you can do all the normal things that are possible with
+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
+```
+
+#### Testing for the existence of the element collection
+
+Just like the `element` method, the `elements` method adds a method to
+the page that will allow you to check for the existence of the
+collection, called `has_<element collection name>?`. As long as there is
+at least 1 element in the array, the method will return true, otherwise
+false. For example, with the following page:
+
+```ruby
+class Friends < SitePrism::Page
+  elements :names, "ul#names li a"
+end
+```
+
+... the following method is available:
+
+```ruby
+@friends_page.has_names? #=> returns true if at least one element is found using the relevant selector
+```
+
+...which allows for pretty test code:
+
+```ruby
+Then /^there should be some names listed on the page$/ do
+  @friends_page.should have_names
+end
+```
+
+#### Waiting for the element collection
+
+Just like for an individual element, the tests can be told to wait for
+the existence of the element collection. The `elements` method adds a
+`wait_for_<element collection name>` method that will wait for
+Capybara's default wait time until at least 1 element is found that
+matches the selector. For example, with the following page:
+
+```ruby
+class Friends < SitePrism::Page
+  elements :names, "ul#names li a"
+end
+
+```
+
+... you can wait for the existence of a list of names like this:
+
+```ruby
+@friends_page.wait_for_names
+```
+
+Again, you can customise the wait time by supplying a number of seconds
+to wait for:
+
+```ruby
+@friends_page.wait_for_names(10)
+```
+
+### Checking that all mapped elements are present on the page
+
+Throughout my time in test automation I keep getting asked to provide the
+ability to check that all elements that should be on the page are on the
+page. Why people would want to test this, I don't know. But if that's
+what you want to do, SitePrism provides the `#all_there?` method that
+will return true if all mapped elements (and sections... see below) are
+present in the browser, false if they're not all there.
+
+```ruby
+@friends_page.all_there? #=> true/false
+
+# and...
+
+Then /^the friends page contains all the expected elements$/ do
+  @friends_page.should be_all_there
+end
+
+```
+
+## Sections
+
+SitePrism allows you to model sections of a page that appear on multiple
+pages or that appear a number of times on a page separately from Pages.
+SitePrism provides the Section class for this task.
+
+### Individual Sections
+
+In the same way that SitePrism provides `element` and `elements`, it
+provides `section` and `sections`. The first returns an instance of a
+page section, the secont returns an array of section instances, one for
+each capybara element found by the supplied css selector. What follows
+is an explanation of `section`.
+
+
+#### Defining a Section
+
+A section is similar to a page in that it inherits from a SitePrism
+class:
+
+```ruby
+class MenuSection < SitePrism::Section
+end
+```
+
+At the moment, this section does nothing.
+
+#### Adding a section to a page
+
+Pages include sections that's how SitePrism works. Here's a page that
+includes the above `MenuSection` section:
+
+```ruby
+class Home < SitePrism::Page
+  section :menu, MenuSection, "#gbx3"
+end
+```
+
+The way to add a section to a page (or another section -
+SitePrism allows adding sections to sections) is to call the `section`
+method. It takes 3 arguments: the first is the name of the section as
+referred to on the page (sections that appear on multiple pages can be
+named differently). The second argument is the class of which an
+instance will be created to represent the page section, and the third
+argument is a css selector that identifies the root node of the section
+on this page (note that the css selector can be different for different
+pages as the whole point of sections is that they can appear in
+different places on different pages).
+
+#### Accessing a page's section
+
+The `section` method (like the `element` method) adds a few methods to
+the page or section class it was called against. The first method that
+is added is one that returns an instance of the section, the method name
+being the first argument to the `section` method. Here's an example:
+
+```ruby
+# the section:
+
+class MenuSection < SitePrism::Section
+end
+
+# the page that includes the section:
+
+class Home < SitePrism::Page
+  section :menu, MenuSection, "#gbx3"
+end
+
+# the page and section in action:
+
+@home = Home.new
+@home.menu #=> <MenuSection...>
+```
+
+When the `menu` method is called against `@home`, an instance of
+`MenuSection` (the second argument to the `section` method) is returned.
+The third argument that is passed to the `section` method is the css
+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: 
+
+```ruby
+# define the section that appears on both pages
+
+class MenuSection < SitePrism::Section
+end
+
+# define 2 pages, each containing the same section
+
+class Home < SitePrism::Page
+  section :menu, MenuSection, "#gbx3"
+end
+
+class SearchResults < SitePrism::Page
+  section :menu, MenuSection, "#gbx48"
+end
+```
+
+You can see that the `MenuSection` is used in both the `Home` and
+`SearchResults` pages, but each has slightly different root node. The
+capybara element that is found by the css selector becomes the root node
+for the relevant page's instance of the `MenuSection` section.
+
+#### Adding elements to a section
+
+This works just the same as adding elements to a page:
+
+```ruby
+class MenuSection < SitePrism::Section
+  element :search, "a.search"
+  element :images, "a.image-search"
+  element :maps, "a.map-search"
+end
+```
+
+Note that the css selectors used to find elements are searched for
+within the scope of the root element of that section. The search for the
+element won't be page-wide but it will only look in the section.
+
+When the section is added to a page...
+
+```ruby
+class Home < SitePrism::Page
+  section :menu, MenuSection, "#gbx3"
+end
+```
+
+...then the section's elements can be accessed like this:
+
+```ruby
+@home = Home.new
+@home.load
+
+@home.menu.search #=> returns a capybara element representing the link to the search page
+@home.menu.search.click #=> clicks the search link in the home page menu
+@home.menu.search['href'] #=> returns the value for the href attribute of the capybara element representing the search link
+@home.menu.has_images? #=> returns true or false based on whether the link is present in the section on the page
+@home.menu.wait_for_images #=> waits for capybara's default wait time until the element appears in the page section
+
+```
+
+...which leads to some pretty test code:
+
+```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
+end
+```
+
+#### Testing for the existence of a section
+
+Just like elements, it is possible to test for the existence of a
+section. The `section` method adds a method called `has_<section name>?`
+to the page or section it's been added to - same idea as what the
+`has_<element name>?` method. Given the following setup:
+
+```ruby
+class MenuSection < SitePrism::Section
+  element :search, "a.search"
+  element :images, "a.image-search"
+  element :maps, "a.map-search"
+end
+
+class Home < SitePrism::Page
+  section :menu, MenuSection, "#gbx3"
+end
+```
+
+... you can check whether the section is present on the page or not:
+
+```ruby
+@home = Home.new
+#...
+#home.has_menu? #=> returns true or false
+```
+
+Again, this allows pretty test code:
+
+```ruby
+@home.should have_menu
+@home.should_not have_menu
+```
+
+#### Waiting for a section to appear
+
+The final method added to the page or section by the `section` method is
+`wait_for_<section name>`. Similar to what `element` does, this method
+waits for the section to appear - the test will wait up to capybara's
+default wait time until the root node of the element exists on the
+page/section that our section was added to. Given the following setup:
+
+```ruby
+class MenuSection < SitePrism::Section
+  element :search, "a.search"
+  element :images, "a.image-search"
+  element :maps, "a.map-search"
+end
+
+class Home < SitePrism::Page
+  section :menu, MenuSection, "#gbx3"
+end
+```
+
+... we can wait for the menu section to appear on the page like this:
+
+```ruby
+@home.wait_for_menu
+@home.wait_for_menu(10) # waits for 10 seconds instead of capybara's default timeout
+```
+
+#### Sections within sections
+
+You are not limited to adding sections only to pages; you can nest
+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
+
+class Login < SitePrism::Section
+  element :username, "#username"
+  element :password, "#password"
+  element :sign_in, "button"
+end
+
+class Registration < SitePrism::Section
+  element :first_name, "#first_name"
+  element :last_name, "#last_name"
+  element :next_step, "button.next-reg-step"
+end
+
+class LoginRegistrationForm < SitePrism::Section
+  section :login, Login, "div.login-area"
+  section :registration, Registration, "div.reg-area"
+end
+
+class Home < SitePrism::Page
+  section :login_and_registration, LoginRegistrationForm, "div.login-registration"
+end
+
+# how to login (fatuous, but demonstrates the point):
+
+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
+  @home.login_and_registration.login.username.set "bob"
+  @home.login_and_registration.login.password.set "p4ssw0rd"
+  @home.login_and_registration.login.sign_in.click
+end
+
+# how to sign up:
+
+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
+  @home.login_and_registration.first_name.set "Bob"
+  # ...
+end
+```
+
+### Section Collections
+
+An individual section represents a discrete section of a page, but often
+sections are repeated on a page, an example is a search result listing -
+each listing contains a title, a url and a description of the content.
+It makes sense to model this only once and then to be able to access
+each instance of a search result on a page as an array of SitePrism
+sections. To achieve this, SitePrism provides the `sections` method that
+can be called in a page or a section.
+
+The only difference between `section` and `sections` is that whereas the
+first returns an instance of the supplied section class, the second
+returns an array containing as many instances of the section class as
+there are capybara elements found by the supplied css selector. This is
+better explained in code :)
+
+#### Adding a Section collection to a page (or other section)
+
+Given the following setup:
+
+```ruby
+class SearchResultSection < SitePrism::Section
+  element :title, "a.title"
+  element :blurb, "span.result-decription"
+end
+
+class SearchResults < SitePrism::Page
+  sections :search_results, SearchResultSection, "#results li"
+end
+```
+
+... it is possible to access each of the search results:
+
+```ruby
+@results_page = SearchResults.new
+# ...
+@results_page.search_results.each do |search_result|
+  puts search_result.title.text
+end
+```
+
+... which allows for pretty tests:
+
+```ruby
+Then /^there are lots of search_results$/ do
+  @results_page.search_results.size.should == 10
+  @results_page.search_results.each do |search_result|
+    search_result.should have_title
+    search_result.blurb.text.should_not be_nil
+  end
+end
+```
+
+The css selector that is passed as the 3rd argument to the
+`sections` method ("#results li") is used to find a number of capybara
+elements. Each capybara element found using the css selector is used to
+create a new instance of the `SearchResultSection` and becomes its root
+element. So if the css selector finds 3 `li` elements, calling
+`search_results` will return an array containing 3 instances of
+`SearchResultSection`, each with one of the `li` elements as it's root
+element.
+
+#### Testing for existence of Sections
+
+Using the example above, it is possible to test for the existence of the
+sections. As long as there is at least one section in the array, the
+sections exist. The `sections` method adds a `has_<sections name>?`
+method to the page/section that our section has been added to. Given the
+following example:
+
+```ruby
+class SearchResultSection < SitePrism::Section
+  element :title, "a.title"
+  element :blurb, "span.result-decription"
+end
+
+class SearchResults < SitePrism::Page
+  sections :search_results, SearchResultSection, "#results li"
+end
+```
+
+... here's how to test for the existence of the section:
+
+```ruby
+@results_page = SearchResults.new
+# ...
+@results_page.has_search_results?
+```
+
+...which allows pretty tests:
+
+```ruby
+Then /^there are search results on the page$/ do
+  @results.page.should have_search_results
+end
+```
+
+#### Waiting for sections to appear
+
+The final method added by `sections` to the page/section we're adding
+our sections to is `wait_for_<sections name>`. It will wait for
+capybara's default wait time for there to be at least one instance of
+the section in the array of sections. For example:
+
+```ruby
+class SearchResultSection < SitePrism::Section
+  element :title, "a.title"
+  element :blurb, "span.result-decription"
+end
+
+class SearchResults < SitePrism::Page
+  sections :search_results, SearchResultSection, "#results li"
+end
+```
+
+... here's how to wait for the section:
+
+```ruby
+@results_page = SearchResults.new
+# ...
+@results_page.wait_for_search_results
+@results_page.wait_for_search_results(10) #=> waits for 10 seconds instead of the default capybara timeout
+```
+
+
+# Epilogue
+
+So, we've seen how to use SitePrism to put together page objects made up
+of pages, elements and sections. But how to organise this stuff? There
+are a few ways of saving yourself having to create instances of pages
+all over the place. Here's an example of this common problem:
+
+```ruby
+@home = Home.new
+@home.load
+@home.search_field.set "Sausages"
+@home.search_field.search_button.click
+@results_page = SearchResults.new
+@results_page.should 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. 
+
+The way I've dealt with this problem is to create a class containing
+methods that return instances of the pages. Eg:
+
+```ruby
+# our pages
+
+class Home < SitePrism::Page
+  #...
+end
+
+class SearchResults < SitePrism::Page
+  #...
+end
+
+class Maps < SitePrism::Page
+  #...
+end
+
+# here's the app class that represents our entire site:
+
+class App
+  def home
+    Home.new
+  end
+
+  def results_page
+      SearchResults.new
+  end
+
+  def maps
+    Maps.new
+  end
+end
+
+# and here's how to use it:
+
+#first line of the test...
+Given /^I start on the home page$/ do
+  @app = App.new
+  @app.home.load
+end
+
+When /^I search for Sausages$/ do
+  @app.home.search_field.set "sausages"
+  @app.home.search_button.click
+end
+
+# etc...
+```
+
+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/element_container.rb

@@ -1,26 +1,5 @@
-# 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 = nil
     if element_locator.nil?
       define_method element_name.to_s do
@@ -36,20 +15,6 @@ module SitePrism::ElementContainer
     create_waiter element_name, element_locator
   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 = nil
     if collection_locator.nil?
       define_method collection_name.to_s do
@@ -66,31 +31,6 @@ module SitePrism::ElementContainer
   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
     add_element_name section_name
     create_existence_checker section_name, section_locator
@@ -100,7 +40,6 @@ module SitePrism::ElementContainer
     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
     add_element_name section_collection_name
     create_existence_checker section_collection_name, section_collection_locator
@@ -112,21 +51,17 @@ module SitePrism::ElementContainer
     end
   end
 
-  # Adds the element name to the list of known elements
   def add_element_name element_name
     @element_names ||= []
     @element_names << element_name
   end
 
-  # Returns list of known element names
   def element_names
     @element_names
   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
     method_name = "has_#{element_name.to_s}?"
     if element_locator.nil?
@@ -142,7 +77,6 @@ module SitePrism::ElementContainer
     end
   end
 
-  # Creates a method used to wait for an element to appear - uses the default capybara wait time
   def create_waiter element_name, element_locator
     method_name = "wait_for_#{element_name.to_s}"
     if element_locator.nil?

data/lib/site_prism/exceptions.rb

@@ -1,10 +1,6 @@
-# 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
-  # Raised if you ask for an element that hasn't got a locator (i.e. a pending element)
   class NoLocatorForElement < StandardError; end
 end
 

data/lib/site_prism/page.rb

@@ -1,90 +1,43 @@
 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
     include ElementChecker
     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) }
@@ -92,22 +45,18 @@ module SitePrism
 
     private
 
-    # Page specific element finder
     def find_one locator
       find locator
     end
 
-    # Page specific elements finder
     def find_all locator
       all locator
     end
 
-    # Page specific element existence check
     def element_exists? locator
       has_selector? locator
     end
 
-    # Page specific element waiter
     def element_waiter locator
       wait_until { element_exists? locator }
     end

data/lib/site_prism/section.rb

@@ -23,22 +23,18 @@ module SitePrism
 
     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
 
-    # Section specific element existence check
     def element_exists? locator
       @root_element.has_selector? locator
     end
 
-    # Section specific element waiter
     def element_waiter locator
       Capybara.current_session.wait_until { element_exists? locator }
     end

data/lib/site_prism/version.rb

@@ -1,3 +1,4 @@
 module SitePrism
-  VERSION = "0.9.9"
+  VERSION = "1.0"
 end
+

metadata

@@ -2,7 +2,7 @@
 name: site_prism
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.9.9
+  version: "1.0"
 platform: ruby
 authors: 
 - Nat Ritmeyer
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-03-24 00:00:00 Z
+date: 2012-04-19 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: capybara
@@ -52,6 +52,7 @@ files:
 - lib/site_prism/version.rb
 - lib/site_prism.rb
 - LICENSE
+- README.md
 homepage: http://github.com/natritmeyer/site_prism
 licenses: []