rsel 0.0.4 → 0.0.5

data/docs/development.md

@@ -1,10 +1,14 @@
 Development
------------
+===========
 
 If you would like to contribute to development of Rsel, create a fork of the
 [Github repository](https://github.com/a-e/rsel), clone your fork, and submit
 pull requests for any improvements you would like to share.
 
+
+Testing
+-------
+
 While developing, you should run the RSpec tests frequently to ensure nothing
 gets broken. You can do this with a single `rake` command:
 
@@ -42,7 +46,8 @@ and stop them:
     $ rake selenium:rc:stop
     $ rake testapp:stop
 
-If you are developing new features, please add spec tests in the `spec`
-directory!
+When the test application is running, you can view the site in your browser by
+visiting http://localhost:8070/. If you are developing new features, please add
+spec tests in the `spec` directory!
 
 Next: [To-do list](todo.md)

data/docs/examples.md

@@ -0,0 +1,119 @@
+Examples
+========
+
+This page presents some example Rsel tests, illustrating how you might use many
+of the built-in methods from a FitNesse wiki page. All of these are based on
+the example web application that you can find in the Rsel `test` directory;
+it's the same one used for running the spec tests in the `spec` directory. See
+[Development](development.md) for instructions on running the server if you'd
+like to execute these examples.
+
+
+Links
+-------------
+
+    | script | selenium test | !-http://localhost:8070-! |
+    | Open browser |
+    | Maximize browser |
+    | Visit | / |
+    | See | Welcome |
+    | See | This is a Sinatra webapp for unit testing Rsel |
+    | Link | About this site | exists |
+    | Click link | About this site |
+    | See | This site is really cool |
+    | See title | About this site |
+    | Click back |
+    | See | This is a Sinatra webapp for unit testing Rsel |
+    | Do not see | This site is really cool |
+    | Close browser |
+
+
+
+Buttons
+-------------
+
+    | script | selenium test | !-http://localhost:8070-! |
+    | Open browser |
+    | Maximize browser |
+    | Visit | /form |
+    | Button | Submit person form | exists |
+    | Click | Submit person form | button |
+    | See | We appreciate your feedback |
+    | Visit | /form |
+    | Button | Submit spouse form | exists | !{within:spouse_form} |
+    | Click | Submit spouse form | button | !{within:spouse_form} |
+    | See | We appreciate your feedback |
+    | Close browser |
+
+
+Checkboxes
+-------------
+
+    | script | selenium test | !-http://localhost:8070-! |
+    | Open browser |
+    | Maximize browser |
+    | Visit | /form |
+    | Enable | I like cheese | checkbox |
+    | Checkbox | I like cheese | is enabled |
+    | Disable | I like cheese | checkbox |
+    | Checkbox | I like cheese | is disabled |
+    | Enable | I like salami | checkbox | !{within:salami_checkbox} |
+    | Checkbox | I like salami | is enabled | !{within:salami_checkbox} |
+    | Disable | I like salami | checkbox | !{within:salami_checkbox} |
+    | Checkbox | I like salami | is disabled | !{within:salami_checkbox} |
+    | Close browser |
+
+
+Dropdowns
+-------------
+
+    | script | selenium test | !-http://localhost:8070-! |
+    | Open browser |
+    | Maximize browser |
+    | Visit | /form |
+    | Dropdown | Height | includes | Short |
+    | Dropdown | Height | includes | Average |
+    | Dropdown | Height | includes | Tall |
+    | Select | Tall | from | Height | dropdown |
+    | Dropdown | Height | equals | Tall |
+    | Select | Short | from | Height | dropdown |
+    | Dropdown | Height | equals | Short |
+    | Close browser |
+
+
+Radiobuttons
+-------------
+
+    | script | selenium test | !-http://localhost:8070-! |
+    | Open browser |
+    | Maximize browser |
+    | Visit | /form |
+    | Select | Briefs | radio |
+    | Radio | Briefs | is enabled |
+    | Radio | Boxers | is disabled |
+    | Select | Boxers | radio | !{within:clothing} |
+    | Radio | Boxers | is enabled | !{within:clothing} |
+    | Radio | Briefs | is disabled | !{within:clothing} |
+    | Close browser |
+
+
+Tables
+-------------
+
+    | script | selenium test | !-http://localhost:8070-! |
+    | Open browser |
+    | Maximize browser |
+    | Visit | /table |
+    | Row | First name, Last name, Email, Actions | exists |
+    | Row | !-Eric, Pierce, epierce@example.com-! | exists |
+    | Enable | Like | checkbox | !{in_row:Marcus} |
+    | Checkbox | Like | is enabled | !{in_row:Marcus} |
+    | Disable | Like | checkbox | !{in_row:Marcus} |
+    | Checkbox | Like | is disabled | !{in_row:Marcus} |
+    | Select | Male | from | Gender | dropdown | !{in_row:Eric} |
+    | Click | Edit | link | !{in_row:Eric} |
+    | See title | Editing Eric |
+    | Close browser |
+
+
+Next: [Customization](custom.md)

data/docs/history.md

@@ -1,6 +1,15 @@
 Rsel History
 ============
 
+0.0.5
+-----
+
+- Allow Selenium-style locators beginning with id=, name=, xpath=, css= etc.
+- Raise a StopTest exception when Selenium is not running (requires updated rubyslim)
+- Locators are now documented
+- Example FitNesse tables are now included
+
+
 0.0.4
 -----
 

data/docs/index.md

@@ -5,9 +5,11 @@ Rsel connects [FitNesse](http://fitnesse.org) to
 [Selenium](http://seleniumhq.org) via [Ruby](http://ruby-lang.org). It allows
 you to use a natural English syntax to write web application tests.
 
-- [Installation & Configuration](install.md)
+- [Installation](install.md)
 - [Usage](usage.md)
+- [Locators](locators.md)
 - [Scoping](scoping.md)
+- [Examples](examples.md)
 - [Customization](custom.md)
 - [Development](development.md)
 - [To-do list](todo.md)

data/docs/locators.md

@@ -0,0 +1,72 @@
+Locators
+========
+
+By default, Selenium accepts a [variety of locator strings](http://release.seleniumhq.org/selenium-remote-control/0.9.2/doc/dotnet/Selenium.html)
+for specifying the element you want to inspect or interact with. While these
+are suitable for programmers and web developers with intimate knowledge of
+their webpages' structure, they are often not intuitive to the average user.
+
+For example, the default behavior of Selenium is to match elements based on
+their `name` attribute. Given this HTML:
+
+    <a name="contact_us_link" href="/contact">Contact Us</a>
+
+To click on the "Concact Us" link using a standard Selenium locator, you'd have
+to do one of the following:
+
+    | click | contact_us_link |
+    | click | link=Contact Us |
+
+This is easy enough, but what if the target element does not have a `name`
+attribute defined? What if the link is an image instead of a piece of text? In
+those cases, you'd have to use a locator string based on `id` (if the element
+has one), `dom`, `xpath`, or `css`. Again, all of these are
+programmer-oriented, and would not make much sense to the average user looking
+at the webpage. While this scheme allows selecting HTML elements with great
+precision, it can become cumbersome to read and write.
+
+The situation becomes even more complex with HTML form elements--text fields,
+dropdowns, checkboxes and the like. While HTML provides a way to semantically
+label these fields, Selenium provides no way to select those fields based on
+their label, aside from using a rather long and complex `xpath` expression.
+For instance, given this HTML:
+
+    <label for="first_name_text_field">First name</label>
+    <input id="first_name_text_field" type="text" />
+
+With Selenium's default selectors, you could do:
+
+    | type | id=first_name_text_field | Eric |
+    | type | xpath=.//input[@id = ../label[.='First name']/@for] | Eric |
+
+Neither of these solutions is very attractive.
+
+For these reasons, Rsel has a simpler locator scheme that matches elements
+based on several likely attributes. Links are matched on `id`, link text, or
+the `alt` text in the case of an image link. Form fields are matched on their
+plain-text label, `name` or `id` attribute. In Rsel, the above examples become
+much easier:
+
+    | click | Contact Us |
+    | Type | Eric | into field | First name |
+
+This allows you to use human-readable locator strings for most HTML elements,
+keeping your test steps free of ugly markup. Refer to the `SeleniumTest` method
+documentation for details on what locator strings are expected for each element.
+
+If you like, you can still pass explicit Selenium-style locators, as long as
+they are prefixed with `id=`, `name=`, `dom=`, `xpath=`, `link=`, or `css=`. If
+you do this, it's up to you to make sure you're using a suitable locator for
+the kind of element you're interacting with. For example, it doesn't make much
+sense to write:
+
+    | Type | Eric | into field | link=Contact Us |
+
+But Rsel won't stop you from trying! One drawback to this approach is that any
+[scoping](scoping.md) clause is ignored. In most cases, it's easier, safer, and
+more readable to use the plain text locator, and rely on Rsel's internal logic
+to find the correct element. This feature is only provided as a workaround for
+the possibility that Rsel's locator scheme is too restrictive for your needs.
+
+Next: [Scoping](scoping.md)
+

data/docs/scoping.md

@@ -79,10 +79,24 @@ operate on checkboxes, dropdowns, or text fields as well.
 Caveat
 ------
 
-One important thing to note is that due to the way FitNesse Slim script tables
-are evaluated, the scoping hash must be added after a cell that contains part
-of the method name. Cells in these tables must contain alternating (function,
-argument) chunks; the way the above example breaks down is:
+The first thing you need to remember when using a scoping hash is that your tables
+must not be fully escaped. This just means you should not include a `!` at the
+beginning of your table, otherwise the hash syntax will be interpreted
+literally, instead of as an embedded hash.
+
+This means you will need to manually escape any cells in your table that
+contain URLs, email addresses, or other auto-interpreted text:
+
+    | script | selenium test | !-http://www.example.com-! |
+    | Open browser                                        |
+    | See           | Welcome                             |
+    | Click         | About   | link | !{within:footer}   |
+    | Close browser                                       |
+
+Another important thing to note is that due to the way FitNesse Slim script
+tables are evaluated, the scoping hash must be added after a cell that contains
+part of the method name. Cells in these tables must contain alternating
+(function, argument) chunks; the way the above example breaks down is:
 
     | Type |              | into |              | field |                |
     |      | 111-222-3333 |      | Phone number |       | !{within:work} |
@@ -104,5 +118,5 @@ have a use case that isn't covered by the existing scopes, please [submit an
 issue](http://github.com/a-e/rsel/issues), or better yet, implement it yourself
 and submit a pull request. See [Development](development.md) for more info.
 
-Next: [Customization](custom.md)
+Next: [Examples](examples.md)
 

data/docs/todo.md

@@ -5,8 +5,10 @@ To-do list
   only support true/false results, with no clear way to report on what went
   wrong (aside from raising an exception, which even then curiously does not
   mark the step as failed)
-- Find a way to abort a test if something goes catastrophically wrong (such as
-  being unable to connect to the Selenium server)
+- Find a way to abort a test if a step fails (will probably require more
+  hacking on rubyslim)
 - Verify the presence of images, allow clicking on images
+- Create a Selenium IDE plugin to generate FitNesse-formatted output for
+  recorded scripts
 
 Next: [History](history.md)

data/docs/usage.md

@@ -1,5 +1,5 @@
 Usage
------
+=====
 
 Once you have created your `SetUp` page, you can create sibling pages with
 tests in them. For instance, continuing with the example from
@@ -46,5 +46,5 @@ driver frowns upon it.)
 See the `SeleniumTest` class documentation for a full list of available methods
 and how to use them.
 
-Next: [Scoping](scoping.md)
+Next: [Locators](locators.md)
 

data/lib/rsel/exceptions.rb

@@ -1,4 +1,4 @@
 module Rsel
   class LocatorNotFound < RuntimeError; end
-  class SeleniumNotRunning < RuntimeError; end
+  class StopTestSeleniumNotRunning < RuntimeError; end
 end

data/lib/rsel/selenium_test.rb

@@ -1,31 +1,29 @@
-require File.join(File.dirname(__FILE__), 'exceptions')
+#require File.join(File.dirname(__FILE__), 'exceptions')
 
 require 'rubygems'
 require 'xpath'
 require 'selenium/client'
+require 'rsel/support'
+require 'rsel/exceptions'
 
 module Rsel
 
-  # Main Selenium-test class.
+  # Main Selenium-test class, and wrapper for all Selenium method calls. This
+  # class is intended to be instantiated in a FitNesse / Slim script table.
+  # May be customized or extended using a subclass.
+  #
+  # @note: Function names beginning with the words 'check', 'ensure', 'reject',
+  # 'note', 'show', or 'start' cannot be called from a Slim script table, since
+  # these are keywords that receive special handling by Slim.
   #
   # @example
   #   !| script | selenium test | http://www.example.com/ |
-  #
-  # NOTE: Function names beginning with these words are forbidden:
-  #
-  # - check
-  # - ensure
-  # - reject
-  # - note
-  # - show
-  # - start
-  #
-  # This is because the above words are keywords in Slim script tables; if
-  # the first cell of a script table begins with any of these words, Slim tries
-  # to apply special handling to them, which usually doesn't do what you want.
+  #   | script | selenium test | !-http://www.example.com/-! |
   #
   class SeleniumTest
 
+    include Support
+
     # Initialize a test, connecting to the given Selenium server.
     #
     # @param [String] url
@@ -59,14 +57,13 @@ module Rsel
     # @example
     #   | Open browser |
     #
-    # @raise [SeleniumNotRunning] if Selenium connection cannot be made
+    # @raise [StopTestSeleniumNotRunning] if Selenium connection cannot be made
     #
     def open_browser
       begin
         @browser.start_new_browser_session
       rescue
-        # TODO: Find a way to make the test abort here
-        raise SeleniumNotRunning, "Could not start Selenium."
+        raise StopTestSeleniumNotRunning, "Could not start Selenium."
       else
         visit @url
       end
@@ -204,7 +201,7 @@ module Rsel
     # @since 0.0.2
     #
     def link_exists(locator, scope={})
-      return @browser.element?(xpath('link', locator, scope))
+      return @browser.element?(loc(locator, 'link', scope))
     end
 
 
@@ -222,7 +219,7 @@ module Rsel
     # @since 0.0.2
     #
     def button_exists(locator, scope={})
-      return @browser.element?(xpath('button', locator, scope))
+      return @browser.element?(loc(locator, 'button', scope))
     end
 
 
@@ -258,7 +255,7 @@ module Rsel
     #
     def type_into_field(text, locator, scope={})
       return_error_status do
-        @browser.type(xpath('field', locator, scope), text)
+        @browser.type(loc(locator, 'field', scope), text)
       end
     end
 
@@ -269,12 +266,14 @@ module Rsel
     #   Label, name, or id of the field you want to type into
     # @param [String] text
     #   What to type into the field
+    # @param [Hash] scope
+    #   Scoping keywords as understood by {#xpath}
     #
     # @example
     #   | Fill in | First name | with | Eric |
     #
-    def fill_in_with(locator, text)
-      type_into_field(text, locator)
+    def fill_in_with(locator, text, scope={})
+      type_into_field(text, locator, scope)
     end
 
 
@@ -290,8 +289,8 @@ module Rsel
     # @example
     #   | Field | First name | contains | Eric |
     #
-    def field_contains(locator, text)
-      @browser.field(xpath('field', locator)).include?(text)
+    def field_contains(locator, text, scope={})
+      @browser.field(loc(locator, 'field', scope)).include?(text)
     end
 
 
@@ -308,7 +307,7 @@ module Rsel
     #   | Field | First name | equals; | Eric | !{within:contact} |
     #
     def field_equals(locator, text, scope={})
-      @browser.field(xpath('field', locator, scope)) == text
+      @browser.field(loc(locator, 'field', scope)) == text
     end
 
 
@@ -324,7 +323,7 @@ module Rsel
     #
     def click(locator, scope={})
       return_error_status do
-        @browser.click(xpath('link_or_button', locator, scope))
+        @browser.click(loc(locator, 'link_or_button', scope))
       end
     end
 
@@ -344,7 +343,7 @@ module Rsel
     #
     def click_link(locator, scope={})
       return_error_status do
-        @browser.click(xpath('link', locator, scope))
+        @browser.click(loc(locator, 'link', scope))
       end
     end
     alias_method :follow, :click_link
@@ -365,7 +364,7 @@ module Rsel
     def click_button(locator, scope={})
       # TODO: Make this fail when the button is disabled
       return_error_status do
-        @browser.click(xpath('button', locator, scope))
+        @browser.click(loc(locator, 'button', scope))
       end
     end
     alias_method :press, :click_button
@@ -386,7 +385,7 @@ module Rsel
     def enable_checkbox(locator, scope={})
       return true if checkbox_is_enabled(locator, scope)
       return_error_status do
-        @browser.click(xpath('checkbox', locator, scope))
+        @browser.click(loc(locator, 'checkbox', scope))
       end
     end
 
@@ -406,7 +405,7 @@ module Rsel
     def disable_checkbox(locator, scope={})
       return true if checkbox_is_disabled(locator, scope)
       return_error_status do
-        @browser.click(xpath('checkbox', locator, scope))
+        @browser.click(loc(locator, 'checkbox', scope))
       end
     end
 
@@ -423,7 +422,7 @@ module Rsel
     #   | Checkbox | send me spam | is enabled | !{within:opt_in} |
     #
     def checkbox_is_enabled(locator, scope={})
-      xp = xpath('checkbox', locator, scope)
+      xp = loc(locator, 'checkbox', scope)
       begin
         enabled = @browser.checked?(xp)
       rescue
@@ -448,7 +447,7 @@ module Rsel
     # @since 0.0.4
     #
     def radio_is_enabled(locator, scope={})
-      xp = xpath('radio_button', locator, scope)
+      xp = loc(locator, 'radio_button', scope)
       begin
         enabled = @browser.checked?(xp)
       rescue
@@ -471,7 +470,7 @@ module Rsel
     #   | Checkbox | send me spam | is disabled | !{within:opt_in} |
     #
     def checkbox_is_disabled(locator, scope={})
-      xp = xpath('checkbox', locator, scope)
+      xp = loc(locator, 'checkbox', scope)
       begin
         enabled = @browser.checked?(xp)
       rescue
@@ -496,7 +495,7 @@ module Rsel
     # @since 0.0.4
     #
     def radio_is_disabled(locator, scope={})
-      xp = xpath('radio_button', locator, scope)
+      xp = loc(locator, 'radio_button', scope)
       begin
         enabled = @browser.checked?(xp)
       rescue
@@ -520,7 +519,7 @@ module Rsel
     #
     def select_radio(locator, scope={})
       return_error_status do
-        @browser.click(xpath('radio_button', locator, scope))
+        @browser.click(loc(locator, 'radio_button', scope))
       end
     end
 
@@ -538,7 +537,7 @@ module Rsel
     #
     def select_from_dropdown(option, locator, scope={})
       return_error_status do
-        @browser.select(xpath('select', locator, scope), option)
+        @browser.select(loc(locator, 'select', scope), option)
       end
     end
 
@@ -577,9 +576,8 @@ module Rsel
     # @since 0.0.2
     #
     def dropdown_equals(locator, option, scope={})
-      # TODO: Apply scope
       begin
-        selected = @browser.get_selected_label(xpath('select', locator))
+        selected = @browser.get_selected_label(loc(locator, 'select', scope))
       rescue
         return false
       else
@@ -618,99 +616,6 @@ module Rsel
       end
     end
 
-
-    # Execute the given block, and return false if it raises an exception.
-    # Otherwise, return true.
-    #
-    # @example
-    #   return_error_status do
-    #     # some code that might raise an exception
-    #   end
-    #
-    def return_error_status
-      begin
-        yield
-      rescue => e
-        #puts e.message
-        #puts e.backtrace
-        return false
-      else
-        return true
-      end
-    end
-
-
-    # Return a Selenium-style xpath generated by calling `XPath::HTML.<kind>`
-    # with the given `locator`.
-    #
-    # @param [String] kind
-    #   What kind of locator you're using (link, button, checkbox, field etc.).
-    #   This must correspond to a method name in `XPath::HTML`.
-    # @param [String] locator
-    #   Name, id, value, label or whatever other locators are accepted by
-    #   `XPath::HTML.<kind>`
-    # @param [Hash] scope
-    #   Keywords to restrict the scope of matching elements
-    # @option scope [String] :within
-    #   Restrict scope to elements having this id, matching `locator` only if
-    #   it's contained within an element with this id.
-    # @option scope [String] :in_row
-    #   Restrict scope to a table row containing this text, matching `locator`
-    #   only if that locator is in the same row as the given text.
-    #
-    # @example
-    #   xpath('link', 'Log in')
-    #   xpath('button', 'Submit')
-    #   xpath('field', 'First name')
-    #   xpath('table_row', ['First', 'Last'])
-    #
-    def xpath(kind, locator, scope={})
-      loc_xp = XPath::HTML.send(kind, locator)
-      if scope[:within]
-        parent = XPath.descendant[XPath.attr(:id).equals(scope[:within])]
-        result = apply_scope(parent, loc_xp)
-      elsif scope[:in_row]
-        row = XPath.descendant(:tr)[XPath.contains(scope[:in_row])]
-        result = apply_scope(row, loc_xp)
-      else
-        result = loc_xp.to_s
-      end
-      return "xpath=#{result}"
-    end
-
-
-    # Restrict the scope of all XPath expressions in `inner` by prepending
-    # `container` to each of them, and return new union expression where
-    # `inner` matches only if it's a child of `container`.
-    #
-    def apply_scope(container, inner)
-      scoped_expressions = xpath_expressions(inner).collect do |expr|
-        container.child(expr)
-      end
-      return XPath::Union.new(*scoped_expressions).to_s
-    end
-
-
-    # Return an array of individual Expressions in the given XPath::Union, or
-    # just `[union]` if it has no sub-expressions. This is an ugly recursive
-    # hack, designed to allow splitting up unions into their constituents for
-    # the purpose of modifying them individually and re-combining them.
-    #
-    # @param [XPath::Union, XPath::Expression] union
-    #   The xpath you want to break down into individual expressions
-    #
-    # @since 0.0.3
-    #
-    def xpath_expressions(union)
-      if union.respond_to?(:expressions)
-        return union.expressions.collect do |expr|
-          xpath_expressions(expr)
-        end.flatten
-      else
-        return [union]
-      end
-    end
-
   end
 end