Move along.

Selenium RC Fu is a fantastic system for testing Ruby On Rails applications. It is the blending of xUnit testing with Selenium. Selenium is a cool system that operates your browser as if a human were sitting there moving the mouse pressing buttons and keys.

Selenium RC Fu is also a remarkable example of the power of open source. It's selenium remotely controlled by rails and ruby. You can learn more about it by viewing the slides for Full-stack webapp testing with Selenium and Rails presented by my colleagues Alex Chaffee and Brian Takita at the SDForum Silicon Valley Ruby Conference.

Now that you are excited about Selenium RC Fu, by law I must inform you that this wonderful testing tool comes with some costs. First, this is the daisy cutter of testing -- problems will be detected, but it won't be too specific about those problems. A failed selenium test will likely only tell you some expected text was not present on the page -- you have to do some digging to discover the real problem.

It's also slow. To be fair, a lot of software is running to do this testing.

So use selenium testing sparingly. A good strategy is to restrict selenium testing to "happy path" testing. These happy path tests become a compliment to other more focused and faster unit and integration tests.

Getting Started With Selenium RC Fu

Selenium RC Fu is hosted at rubyforge.org in the "pivotal.rb" project. It's not well documented and a little hard to find. The primary documentation is the README File.

Step 1 is to add it to your project:

script/plugin install svn://rubyforge.org/var/svn/pivotalrb/seleniumrc_fu/trunk

Building Your Tests

Create your tests in app/tests/selenium. The basic structure mirrors the other test types:

require File.dirname(__FILE__) + "/selenium_helper"
class HappyPathsTest < MyProject::SeleniumTestCase

  def test_nav_bar
      ...
  end

  def test_about
      ...
  end

  # more tests
end

Note that HappyPathsTest extends something called MyProject::SeleniumTestCase. Selenium RC Fu provides a sample selenium helper file that suggests this convention for name spacing your tests.

For the happy paths tests I simply wanted to go to a page and know that the page loads. A pattern I learned from my colleague Shifra is:

1. Pick something you know is on the target page, but not on the current page. Let's call it 'evidence'. Assert that evidence is not present on the current page.
2. go to the target page
3. assert that evidence is present on the target page.

This process ensures that you are moving about as you expect. Here's an example from my project:

  def test_tasks
    ...

    assert_element_not_present "xpath=//h1[text()='The Daily Planet']"
    click_and_wait "link=The Daily Planet"
    assert_element_present "xpath=//h1[text()='The Daily Planet']"

    ...    
  end

I repeated this simple pattern for every path.

Selenium Functions/Assertions/Commands

Here are the functions and assertions I used in my tests:

• click_and_wait locator
• go_back
• wait_for_page_to_load
• type locator, text
• assert_text_present text
• assert_text_not_present text
• assert_equal value1, value2

Many of the functions require a 'locator' argument. This needs to identify a single element on the page. Often the name or id of an element is sufficient, but you may need to use an XPath. Check the docs for more information on element locators.

These functions were sufficient for me. Look for more in vendor/plugins/seleniumrc_fu/lib/seleniumrc_fu/selenium_dsl.rb.

Selenium RC Fu comes with some rake commands too (from rake -T selenium):

rake selenium:restart_servant           # Stop and start the selenium servant (the server that launches browsers) on localhost
rake selenium:run_server                # Run the selenium servant in the foreground
rake selenium:server                    # Run the selenium remote-control server
rake selenium:start_servant             # Start the selenium servant (the server that launches browsers) on localhost
rake selenium:stop_servant              # Stop the selenium servant (the server that launches browsers) on localhost
rake selenium:test                      # Run a selenium test file (default test/selenium/selenium_suite)
rake selenium:test_with_server_started  # Run the selenium tests in Firefox

Running Your Tests

You can run your selenium tests individually or as part of a suite. Selenium RC Fu comes with a suite script in the vendor/plugins/seleniumnrc_fu/sample directory. Drop that in your test/selenium directory.

The selenium server must be running before running individual tests. You can start the server with the rake command rake selenium:server. Once the server is running you run your tests from the command line or via the suite.

You can also run the suite with the command rake selenium:test. This command is smart enough to start the server if it's not already running. However, when the server is started by this mechanism it's a little more work to stop it. You can stop the server with a simple ^c if it was started via the rake selenium:server command.

Make It So

That's really all you need to build your tests, but here are few more things that may help.

Site Diagram

A site diagram is handy for building your happy paths tests. There will be a lot of paths through the site and marking the paths on the diagram as you visit them is an easy way to track your progress. On the diagram you need to indicate both pages and the paths to those pages.

The later is really important. It's the paths that you will be testing with your happy path selenium testing. Often there are buttons, links, or other controls such as check boxes that may touch the server and reload the current page, or just update the current page via ajax. Be sure to add these to your navigation diagram.

Here's the diagram I used for my site.

Selenium IDE

You can code your tests by hand using Selenium RC Fu functions but it's easier if you use
Selenium IDE. This is a Firefox plugin that records your activity. That activity is available in various selenium dialects and can be pasted into your tests. Unfortunately, it does not have output for Selenium RC Fu. Nonetheless I still found it useful. I simply clicked through my application while Selenium IDE was recording, pasted the resulting selenium commands into my tests, then converted those commands to equivalent Selenium RC Fu commands. For example:

Output from Selenium IDE:

@selenium.click "link=My Account"
@selenium.wait_for_page_to_load "30000"
assert @selenium.is_text_present("Update Account")

Becomes:

click_and_wait "link=My Account"
assert_text_present "Update Account"

Test Data

Your selenium tests will be exercising your application just like standard unit or integration tests. These tests require data and there are a variety of techniques to make data available to your tests. Building your happy path tests is easier if you have fixture data and that fixture data is loaded in your development environment via rake db:fixtures:load. If you use fixture scenarious, it is handy to have a scenario for selenium testing, which you would load with something like rake db:scenario:load SCENARIO=selenium.

With your fixtures loaded in your development environment you can see exactly what is present during testing and the selenium IDE will record exactly what is played back by selenium.

XPath Checker

Usually Selenium IDE can assign a locator that simply works but there are times when it can't. Using XPath Checker you can right click on an element and it will display an XPath to that element. You can also experiment with varitions and XPath Checker will list all of the elements on the page that can be identified by that XPath.

That's it. Let me know how it goes.