Selenium on Rails

Overview

Selenium on Rails provides an easy way to test Rails application with SeleniumCore.

This plugin does four things:

1. The Selenium Core files don‘t have to pollute /public.



2. No need to create suite files, they are generated on the fly — one
   suite per directory in /test/selenium (suites can be nested).



3. Instead of writing the test cases in HTML you can use a number of better
   formats (see Formats).



4. Loading of fixtures and wiping of session (/selenium/setup).

Installation

1. Install Selenium on Rails: script/plugin install svn.openqa.org/svn/selenium-on-rails/selenium-on-rails



2. If you‘re on Windows, gem install win32-open3



3. If the RedCloth gem is available the Selenese test cases can use it for
   better markup.



4. Run the Rakefile in the plugin‘s directory to run the tests in order
   to see that everything works. (If RedCloth isn‘t installed a few
   tests will fail since they assume RedCloth is installed.)



5. Create a test case: script/generate selenium login



6. Start the server: script/server -e test



7. Point your browser to localhost:3000/selenium



8. If everything works as expected you should see the Selenium test runner.
   The north east frame contains all your test cases (just one for now), and
   the north frame contains your test case.

Formats

The test cases can be written in a number of formats. Which one you choose
is a matter of taste. You can generate your test files by running
script/generate selenium or by creating them manually in your
/test/selenium directory.

Selenese, .sel

Selenese is the dumbest format (in a good way). You just write your
commands delimited by | characters.

 |open|/selenium/setup|

 |open|/|

 |goBack|

If you don‘t want to write Selenese tests by hand you can use SeleniumIDE which has support for
Selenese.

SeleniumIDE makes it super easy to record test and edit them.

RSelenese, .rsel

RSelenese enable you to write your tests in Ruby.

 setup :fixtures => :all

 open '/'

 assert_title 'Home'

 ('a'..'z').each {|c| open :controller => 'user', :action => 'create', :name => c }

See SeleniumOnRails::TestBuilder
for available commands.

HTML/RHTML

You can write your tests in HTML/RHTML but that‘s mostly useful if
you have existing tests you want to reuse.

Partial test cases

If you have some common actions you want to do in several test cases you
can put them in a separate partial test case and include them in your other
test cases.

A partial test case is just like a normal test case besides that its
filename has to start with _:

 #_login.rsel

 open '/login'

 type 'name', name

 type 'password', password

 click 'submit', :wait=>true

To include a partial test case you write like this in a Selenese test case:

 |includePartial|login|name=John Doe|password=eoD nhoJ|

in a RSelenese test case:

 include_partial 'login', :name => 'Jane Doe', :password => 'Jane Doe'.reverse

and in a RHTML test case:

 <%= render :partial => 'login', :locals => {:name = 'Joe Schmo', :password => 'Joe Schmo'.reverse} %>

Configuration

There are a number of settings available. You make them by renaming
config.yml.example to config.yml and make your changes in
that file.

Environments

Per default this plugin is only available in test environment. You can
change this by setting environments, such as:

 #config.yml

 environments:

   - test

   - development

Selenium Core path

If you don‘t want to use the bundled Selenium Core version you can
set selenium_path to the directory where Selenium Core is stored.

 #config.yml

 selenium_path: 'c:\selenium'

test:acceptance

You can run all your Selenium tests as a Rake task.

First, if you‘re on Windows, you have to make sure win32-open3 is
installed. Then you have to configure which browsers you want to run, like
this:

 #config.yml

 browsers:

   firefox: 'c:\Program Files\Mozilla Firefox\firefox.exe'

   ie: 'c:\Program Files\Internet Explorer\iexplore.exe'

Now you‘re all set. First start a server:

 script/server -e test

Then run the tests:

 rake test:acceptance

Now it should work, otherwise let me know!

Store results

If you want to store the results from a test:acceptance you just
need to set in which directory they should be stored:

 #config.yml

 result_dir: 'c:\result'

So when you run rake test:acceptance the tables with the results
will be stored as .html files in that directory.

This can be useful especially for continous integration.

user_extension.js

Selenium has support for user_extension.js which is a way to
extend the functionality of Selenium Core. Selenium on Rails now provides
the means for you to extend it‘s functionality to match.

To get you started, we‘ve included the example files
lib/test_builder_user_accessors.rb.example and
lib/test_builder_user_actions.rb.example that replicate the sample
extensions in Selenium Core‘s user-extensions.js.sample

To get these examples running, simply remove the .example and .sample
extensions from the files and restart your server.

Todo

Standalone mode

More work is needed on test:acceptance on Windows to be able to
start the server when needed.

More setup/teardown support?

Currently there is only support to load fixtures and to wipe the session in
/selenium/setup. Is there a need for more kinds of setups or
teardowns?

More documentation

Not todo

Editor

Creating an editor for the test cases is currently considered out of scope
for this plugin. SeleniumIDE does such a good
job and has support for
the Selenese format.

Credits

• Jon Tirsen, jutopia.tirsen.com
  — initial inspiration



• Eric Kidd, www.randomhacks.net
  — contribution of RSelenese

Information

For more information, check out the website.