rsel 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+Gemfile.lock
+.yardoc/*
+.rvmrc
+selenium-rc.log

data/.yardopts

@@ -0,0 +1,7 @@
+--readme docs/index.md
+--markup markdown
+--no-highlight
+--exclude lib/rsel/selenium.rb
+lib/rsel/*.rb
+-
+docs/*.md

data/Gemfile

@@ -0,0 +1,2 @@
+source :rubygems
+gemspec

data/MIT-LICENSE

@@ -0,0 +1,22 @@
+The MIT License
+
+Copyright (c) 2011 Automation Excellence
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,35 @@
+Rsel
+====
+
+Rsel connects [FitNesse](http://fitnesse.org) to [Selenium](http://seleniumhq.org)
+via [Ruby](http://ruby-lang.org).
+
+[Full documentation is on rdoc.info](http://rdoc.info/github/a-e/rsel/master/frames).
+
+
+Copyright
+---------
+
+The MIT License
+
+Copyright (c) 2011 Automation Excellence
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

data/Rakefile

@@ -0,0 +1,75 @@
+require 'rake'
+require 'net/http'
+require 'selenium/rake/tasks'
+require 'rspec/core/rake_task'
+
+ROOT_DIR = File.expand_path(File.dirname(__FILE__))
+TEST_APP = File.join(ROOT_DIR, 'test', 'app.rb')
+SELENIUM_RC_JAR = File.join(ROOT_DIR, 'test', 'server', 'selenium-server-1.0.3-SNAPSHOT-standalone.jar')
+SELENIUM_RC_LOG = File.join(ROOT_DIR, 'selenium-rc.log')
+
+namespace 'testapp' do
+  desc "Start the test webapp in the background"
+  task :start do
+    puts "Starting the test webapp: #{TEST_APP}"
+    system("ruby #{TEST_APP} &")
+  end
+
+  desc "Stop the test webapp"
+  task :stop do
+    puts "Stopping the test webapp"
+    begin
+      Net::HTTP.get('localhost', '/shutdown', 8070)
+    rescue EOFError
+      # This is expected
+      puts "Test webapp stopped."
+    end
+  end
+end
+
+Selenium::Rake::RemoteControlStartTask.new do |rc|
+  rc.jar_file = SELENIUM_RC_JAR
+  rc.port = 4444
+  rc.background = true
+  rc.timeout_in_seconds = 60
+  rc.wait_until_up_and_running = true
+  rc.log_to = SELENIUM_RC_LOG
+end
+
+Selenium::Rake::RemoteControlStopTask.new do |rc|
+  rc.host = 'localhost'
+  rc.port = 4444
+  rc.timeout_in_seconds = 60
+  rc.wait_until_stopped = true
+end
+
+desc "Run spec tests"
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.pattern = 'spec/**/*_spec.rb'
+  t.rspec_opts = ['--color', '--format doc']
+end
+
+namespace 'servers' do
+  desc "Start the Selenium and testapp servers"
+  task :start do
+    Rake::Task['testapp:start'].invoke
+    Rake::Task['selenium:rc:start'].invoke
+  end
+
+  desc "Stop the Selenium and testapp servers"
+  task :stop do
+    Rake::Task['selenium:rc:stop'].invoke
+    Rake::Task['testapp:stop'].invoke
+  end
+end
+
+desc "Start Selenium and testapp servers, run tests, then stop servers"
+task :test do
+  begin
+    Rake::Task['servers:start'].invoke
+    Rake::Task['spec'].invoke
+  ensure
+    Rake::Task['servers:stop'].invoke
+  end
+end
+

data/docs/custom.md

@@ -0,0 +1,87 @@
+Customization
+-------------
+
+Rsel provides only the most basic imperative navigational steps and
+verification. For real-world testing, you will most likely want to define your
+own steps, built up from the low-level ones provided by Rsel.
+
+It's pretty easy to do this by subclassing `SeleniumTest` and adding your own
+methods to it. Create a sibling directory to your `FitNesseRoot`, named
+something like `custom_rsel`, then create a Ruby file in there. The Ruby file
+can be called whatever you want--it's most logical to name it after your
+application:
+
+- `FitNesseRoot`
+- `custom_rsel`
+  - `my_app_test.rb`
+
+Inside `my_app_test.rb`, you must define a module named after the folder, and a
+class named after the file. You'll also need to include some `require` statements
+to make sure `rsel/selenium` gets loaded. In this case, it should be:
+
+    require `rubygems`            # If you installed Rsel from a gem
+    require `rsel/selenium_test`  # Makes the SeleniumTest class available
+
+    module CustomRsel
+      class MyAppTest < Rsel::SeleniumTest
+        # Custom methods go here
+      end
+    end
+
+Inside your custom class, you can define any methods you want, and you can call
+any of the methods defined in the `Rsel::SeleniumTest` class. For example,
+let's say the login process for your application consists of three steps:
+
+    | Fill in | Username | with | admin   |
+    | Fill in | Password | with | letmein |
+    | Press   | Login                     |
+
+If you're logging in a lot, you may want a single-step login method. Here's how
+you might define one:
+
+    module CustomRsel
+      class MyAppTest < Rsel::SeleniumTest
+
+        # Login with the given username and password
+        #
+        # Example:
+        #   | Login as | admin | with password | letmein |
+        #
+        def login_as_with_password(username, password)
+          fill_in_with("Username", username)
+          fill_in_with("Password", password)
+          press("Login")
+        end
+
+      end
+    end
+
+In your FitNesse `SetUp` page, rather than (or in addition to) importing the `Rsel` module,
+import your custom module:
+
+    !| import    |
+    | CustomRsel |
+
+Note that this name must match the `module` line in your Ruby file, and the
+folder where your Ruby file resides must be the lowercase_and_underscore
+version of that same module name. Finally, in your actual test table, instead of:
+
+    !| script | selenium test | ... |
+
+You'll use:
+
+    !| script | my app test | ... |
+
+This will ensure that the `MyAppTest` class will be used for evaluating the
+steps contained in that table.
+
+It's worth noting that the `SeleniumTest` class (and hence any derived classes)
+have a `@browser` attribute referring to the underlying `Selenium::Client::Driver`
+instance, which includes
+[a wealth of methods](http://rdoc.info/github/ph7/selenium-client/master/Selenium/Client/Driver)
+for interacting with webpages and performing verifications. If `SeleniumTest`
+itself does not provide the methods you need, you can use the `@browser`
+attribute directly.
+
+Next: [Development](development.md)
+

data/docs/development.md

@@ -0,0 +1,48 @@
+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.
+
+While developing, you should run the RSpec tests frequently to ensure nothing
+gets broken. You can do this with a single `rake` command:
+
+    $ rake test
+
+This will do the following:
+
+- Start the Sinatra test application (code in `test/app.rb` and `test/views/*.erb`)
+- Start the Selenium server (the `.jar` file in `test/server`)
+- Run RSpec
+- Stop the Selenium server
+- Stop the Sinatra test application
+
+Since there's a large startup cost associated with all of this (in particular
+the Selenium server), when running frequent tests you may want to start those
+up and keep them running. There are rake tasks for that also:
+
+    $ rake servers:start
+
+Now do:
+
+    $ rake spec
+
+as many times as you want. When you're done, manually stop the servers:
+
+    $ rake servers:stop
+
+You can also start the Selenium and Sinatra testapp servers individually:
+
+    $ rake selenium:rc:start
+    $ rake testapp:start
+
+and stop them:
+
+    $ rake selenium:rc:stop
+    $ rake testapp:stop
+
+If you are developing new features, please add spec tests in the `spec`
+directory!
+
+Next: [To-do list](todo.md)

data/docs/index.md

@@ -0,0 +1,13 @@
+Rsel
+====
+
+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)
+- [Usage](usage.md)
+- [Customization](custom.md)
+- [Development](development.md)
+- [To-do list](todo.md)
+

data/docs/install.md

@@ -0,0 +1,33 @@
+Installation & Configuration
+----------------------------
+
+To install Rsel from a gem:
+
+    $ gem install rsel
+
+If you have the following test hierarchy:
+
+- `FitNesseRoot`
+  - `SeleniumTests`
+    - `SetUp`
+    - `LoginTest`
+
+You should define the requisite `rubyslim` options in the `SeleniumTests` page content:
+
+    !define TEST_SYSTEM {slim}
+    !define TEST_RUNNER {rubyslim}
+    !define COMMAND_PATTERN {rubyslim}
+
+If you're using Bundler, you may need to use:
+
+    !define TEST_SYSTEM {slim}
+    !define TEST_RUNNER {bundle exec rubyslim}
+    !define COMMAND_PATTERN {bundle exec rubyslim}
+
+Finally, put this in your `SeleniumTests.SetUp` page:
+
+    !| import |
+    | Rsel    |
+
+Next: [Usage](usage.md)
+

data/docs/todo.md

@@ -0,0 +1,15 @@
+To-do list
+----------
+
+- Pass better error messages back to FitNesse. It seems that Slim script tables
+  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)
+
+Some additional step methods needed:
+
+- dropdown_includes
+- dropdown_equals
+

data/docs/usage.md

@@ -0,0 +1,50 @@
+Usage
+-----
+
+Once you have created your `SetUp` page, you can create sibling pages with
+tests in them. For instance, continuing with the example from
+[Installation & Configuration](install.md), your `SeleniumTests.LoginTest`
+might look like this:
+
+    !| script | selenium test | http://www.mysite.com |
+    | Open browser                                    |
+    | Fill in       | Username | with | castle        |
+    | Fill in       | Password | with | beckett       |
+    | Click button  | Log in                          |
+    | Page loads in | 5        | seconds or less      |
+    | See           | Logged in as castle             |
+    | Close browser                                   |
+
+Before running a test, you must make sure you have Selenium Server installed and running.
+Download [selenium-server-standalone-x.x.x.jar](http://seleniumhq.org/download/), and start
+it up like this:
+
+    $ java -jar selenium-server-standalone-x.x.x.jar
+
+By default, the server runs on port 4444, and this is the port that Rsel uses
+unless you tell it otherwise. Rsel also assumes that you're running
+selenium-server on your localhost (that is, the same host where FitNesse is
+running); if you need to use a different host or port number, pass those as
+arguments to the first line of the table. For example, if you are running
+selenium-server on `my.selenium.host`, port `4455`, do this:
+
+    !| script | selenium test | http://www.mysite.com | my.selenium.host | 4455 |
+
+The first argument after `selenium test` is the URL of the site you will be testing.
+This URL is loaded when you call `Open browser`, and all steps that follow are
+assumed to stay within the same domain. You can navigate around the site by
+clicking links and filling in forms just as a human user would; you can also go
+directly to a specific path within the domain with the `Visit` method:
+
+    | Visit | /some/path       |
+    | Visit | /some/other/path |
+
+These paths are evaluated relative to the domain your test is running in. (It's
+theoretically possible to navigate to a different domain, but the Selenium
+driver frowns upon it.)
+
+See the `SeleniumTest` class documentation for a full list of available methods
+and how to use them.
+
+Next: [Customization](custom.md)
+

data/lib/rsel.rb

@@ -0,0 +1,4 @@
+require 'rsel/selenium_test'
+
+module Rsel
+end

data/lib/rsel/exceptions.rb

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

data/lib/rsel/selenium_test.rb

@@ -0,0 +1,524 @@
+require File.join(File.dirname(__FILE__), 'exceptions')
+
+require 'rubygems'
+require 'xpath'
+require 'selenium/client'
+
+module Rsel
+
+  # Main Selenium-test class.
+  #
+  # @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.
+  #
+  class SeleniumTest
+
+    # Initialize a test, connecting to the given Selenium server.
+    #
+    # @param [String] url
+    #   Full URL, including http://, of the system under test
+    # @param [String] host
+    #   IP address or hostname where selenium-server is running
+    # @param [String] port
+    #   Port number of selenium-server
+    # @param [String] browser
+    #   Which browser to test with
+    #
+    # @example
+    #   | script | selenium test | http://site.to.test/ |
+    #   | script | selenium test | http://site.to.test/ | 192.168.0.3 | 4445 |
+    #
+    def initialize(url, host='localhost', port='4444', browser='*firefox')
+      @url = url
+      @browser = Selenium::Client::Driver.new(
+        :host => host,
+        :port => port,
+        :browser => browser,
+        :url => url)
+    end
+
+    attr_reader :url, :browser
+
+
+    # Start the session and open a browser to the URL defined at the start of
+    # the test.
+    #
+    # @example
+    #   | Open browser |
+    #
+    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."
+      else
+        visit @url
+      end
+    end
+
+
+    # Stop the session and close the browser window.
+    #
+    # @example
+    #   | Close browser |
+    #
+    def close_browser
+      @browser.close_current_browser_session
+      return true
+    end
+
+
+    # Load an absolute URL or a relative path in the browser.
+    #
+    # @param [String] path_or_url
+    #   Relative path or absolute URL to load. Absolute URLs must be in the
+    #   same domain as the URL that was passed to {#initialize}.
+    #
+    # @example
+    #   | Visit | http://www.automation-excellence.com |
+    #   | Visit | /software |
+    #
+    def visit(path_or_url)
+      return_error_status do
+        @browser.open(path_or_url)
+      end
+    end
+
+
+    # Click the Back button to navigate to the previous page.
+    #
+    # @example
+    #   | Click back |
+    #
+    def click_back
+      return_error_status do
+        @browser.go_back
+      end
+    end
+
+
+    # Reload the current page.
+    #
+    # @example
+    #   | refresh page |
+    #
+    def refresh_page
+      return_error_status do
+        @browser.refresh
+      end
+    end
+
+
+    # Maximize the browser window. May not work in some browsers.
+    #
+    # @example
+    #   | maximize browser |
+    #
+    def maximize_browser
+      @browser.window_maximize
+      return true
+    end
+
+
+    # Ensure that the given text appears on the current page.
+    #
+    # @param [String] text
+    #   Plain text that should be visible on the current page
+    #
+    # @example
+    #   | See | Welcome, Marcus |
+    #
+    def see(text)
+      return @browser.text?(text)
+    end
+
+
+    # Ensure that the given text does not appear on the current page.
+    #
+    # @param [String] text
+    #   Plain text that should not be visible on the current page
+    #
+    # @example
+    #   | Do not see | Take a hike |
+    #
+    def do_not_see(text)
+      return !@browser.text?(text)
+    end
+
+
+    # Ensure that the current page has the given title text.
+    #
+    # @param [String] title
+    #   Text of the page title that you expect to see
+    #
+    # @example
+    #   | See title | Our Homepage |
+    #
+    def see_title(title)
+      return (@browser.get_title == title)
+    end
+
+
+    # Ensure that the current page does not have the given title text.
+    #
+    # @param [String] title
+    #   Text of the page title that you should not see
+    #
+    # @example
+    #   | Do not see title | Someone else's homepage |
+    #
+    def do_not_see_title(title)
+      return !(@browser.get_title == title)
+    end
+
+
+    # Type a value into the given field.
+    #
+    # @param [String] text
+    #   What to type into the field
+    # @param [String] locator
+    #   Label, name, or id of the field you want to type into
+    #
+    # @example
+    #   | Type | Dale | into field | First name |
+    #   | Type | Dale | into | First name | field |
+    #
+    def type_into_field(text, locator)
+      return_error_status do
+        @browser.type(xpath('field', locator), text)
+      end
+    end
+
+
+    # Fill in a field with the given text.
+    #
+    # @param [String] locator
+    #   Label, name, or id of the field you want to type into
+    # @param [String] text
+    #   What to type into the field
+    #
+    # @example
+    #   | Fill in | First name | with | Eric |
+    #
+    def fill_in_with(locator, text)
+      type_into_field(text, locator)
+    end
+
+
+    # Verify that a text field contains the given text.
+    # The field may include additional text, as long as the
+    # expected value is in there somewhere.
+    #
+    # @param [String] locator
+    #   Label, name, or id of the field you want to inspect
+    # @param [String] text
+    #   Text to expect in the field
+    #
+    # @example
+    #   | Field | First name | contains | Eric |
+    #
+    def field_contains(locator, text)
+      @browser.field(xpath('field', locator)).include?(text)
+    end
+
+
+    # Verify that a text field's value equals the given text.
+    # The value must match exactly.
+    #
+    # @param [String] locator
+    #   Label, name, or id of the field you want to inspect
+    # @param [String] text
+    #   Text to expect in the field
+    #
+    # @example
+    #   | Field | First name | equals | Eric |
+    #
+    def field_equals(locator, text)
+      @browser.field(xpath('field', locator)) == text
+    end
+
+
+    # Click on a link or button, and wait for a page to load.
+    #
+    # @param [String] locator
+    #   Text, value or id of the link or button to click
+    #
+    # @example
+    #   | Click | Next   |
+    #   | Click | Logout |
+    #
+    def click(locator)
+      return_error_status do
+        @browser.click(xpath('link_or_button', locator))
+      end
+    end
+
+
+    # Click on a link.
+    #
+    # @param [String] locator
+    #   Link text or id of the anchor element
+    #
+    # @example
+    #   | Click | Logout | link |
+    #   | Click link | Logout |
+    #
+    def click_link(locator)
+      return_error_status do
+        @browser.click(xpath('link', locator))
+      end
+    end
+
+
+    # Alias for {#click_link}.
+    #
+    # @example
+    #   | Follow | Logout |
+    #
+    def follow(locator)
+      click_link(locator)
+    end
+
+
+    # Press a button.
+    #
+    # @param [String] locator
+    #   Button text, value, or id of the button
+    #
+    # @example
+    #   | Click | Login | button |
+    #   | Click button | Login |
+    #
+    def click_button(locator)
+      return_error_status do
+        @browser.click(xpath('button', locator))
+      end
+    end
+
+
+    # Alias for {#click_button}
+    #
+    # @example
+    #   | Press | Search |
+    #
+    def press(locator)
+      click_button(locator)
+    end
+
+
+    # Enable (check) a checkbox.
+    #
+    # @param [String] locator
+    #   Label, value, or id of the checkbox to check
+    #
+    # @example
+    #   | Enable | Send me spam | checkbox |
+    #   | Enable checkbox | Send me spam |
+    #
+    def enable_checkbox(locator)
+      return_error_status do
+        @browser.check(xpath('checkbox', locator))
+      end
+    end
+
+
+    # Disable (uncheck) a checkbox.
+    #
+    # @param [String] locator
+    #   Label, value, or id of the checkbox to uncheck
+    #
+    # @example
+    #   | Disable | Send me spam | checkbox |
+    #   | Disable checkbox | Send me spam |
+    #
+    def disable_checkbox(locator)
+      return_error_status do
+        @browser.uncheck(xpath('checkbox', locator))
+      end
+    end
+
+
+    # Verify that a given checkbox or radiobutton is enabled (checked)
+    #
+    # @param [String] locator
+    #   Label, value, or id of the checkbox to inspect
+    #
+    # @example
+    #   | Checkbox is enabled | send me spam |
+    #   | Checkbox | send me spam | is enabled |
+    #
+    def checkbox_is_enabled(locator)
+      begin
+        enabled = @browser.checked?(xpath('checkbox', locator))
+      rescue
+        return false
+      else
+        return enabled
+      end
+    end
+
+
+    # Verify that a given checkbox or radiobutton is disabled (unchecked)
+    #
+    # @param [String] locator
+    #   Label, value, or id of the checkbox to inspect
+    #
+    # @example
+    #   | Checkbox is disabled | send me spam |
+    #
+    def checkbox_is_disabled(locator)
+      begin
+        enabled = @browser.checked?(xpath('checkbox', locator))
+      rescue
+        return false
+      else
+        return !enabled
+      end
+    end
+
+
+    # Select a radio button.
+    #
+    # @param [String] locator
+    #   Label, id, or name of the radio button to select
+    #
+    # @example
+    #   | Select | female | radio |
+    #   | Select radio | female |
+    #
+    def select_radio(locator)
+      return_error_status do
+        @browser.click(xpath('radio_button', locator))
+      end
+    end
+
+
+    # Alias for {#checkbox_is_disabled}
+    #
+    # @example
+    #   | Radio is disabled | medium |
+    #   | Radio | medium | is disabled |
+    #
+    def radio_is_disabled(locator)
+      checkbox_is_disabled(locator)
+    end
+
+
+    # Alias for {#checkbox_is_enabled}
+    #
+    # @example
+    #   | Radio is enabled | medium |
+    #   | Radio | medium | is enabled |
+    #
+    def radio_is_enabled(locator)
+      checkbox_is_enabled(locator)
+    end
+
+
+    # Select a value from a dropdown/combo box.
+    #
+    # @param [String] value
+    #   The value to choose from the dropdown
+    # @param [String] locator
+    #   Label, name, or id of the dropdown
+    #
+    # @example
+    #   | select | Tall | from | Height | dropdown |
+    #   | select | Tall | from dropdown | Height |
+    #
+    def select_from_dropdown(value, locator)
+      return_error_status do
+        @browser.select(xpath('select', locator), value)
+      end
+    end
+
+
+    # Pause for a certain number of seconds.
+    #
+    # @param [String, Int] seconds
+    #   How many seconds to pause
+    #
+    # @example
+    #   | Pause | 5 | seconds |
+    #
+    def pause_seconds(seconds)
+      sleep seconds.to_i
+      return true
+    end
+
+
+    # Wait some number of seconds for the current page request to finish.
+    # Fails if the page does not finish loading within the specified time.
+    #
+    # @param [String, Int] seconds
+    #   How long to wait for before timing out
+    #
+    # @example
+    #   | Page loads in | 10 | seconds or less |
+    #
+    def page_loads_in_seconds_or_less(seconds)
+      return_error_status do
+        @browser.wait_for_page_to_load("#{seconds}000")
+      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 for 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 locator the `XPath::HTML.<kind>`
+    #   method accepts.
+    #
+    # @example
+    #   xpath('link', 'Log in')
+    #   xpath('button', 'Submit')
+    #   xpath('field', 'First name')
+    #
+    def xpath(kind, locator)
+      # Doing explicit string-join here, so it'll work with older versions
+      # of the XPath module that don't have `Union#to_s` defined.
+      "xpath=" + XPath::HTML.send(kind, locator).to_xpaths.join(' | ')
+    end
+
+  end
+end
+
+
+