Skip to content
This repository
branch: master
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 194 lines (125 sloc) 6.535 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193
= Selenium on Rails

== Overview

Selenium on Rails provides an easy way to test Rails application with
SeleniumCore[http://www.openqa.org/selenium-core/].

This plugin does four things:
1. The Selenium Core files don't have to pollute <tt>/public</tt>.
2. No need to create suite files, they are generated on the fly -- one suite per directory in <tt>/test/selenium</tt> (suites can be nested).
3. Instead of writing the test cases in HTML you can use a number of better formats (see <tt>Formats</tt>).
4. Loading of fixtures and wiping of session (<tt>/selenium/setup</tt>).

== Installation

1. Install Selenium on Rails: <tt>script/plugin install http://svn.openqa.org/svn/selenium-on-rails/selenium-on-rails</tt>
2. If you're on Windows, <tt>gem install win32-open3</tt>
3. <i>If the RedCloth gem is available the Selenese test cases can use it for better markup.</i>
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: <tt>script/generate selenium login</tt>
6. Start the server: <tt>script/server -e test</tt>
7. Point your browser to <tt>http://localhost:3000/selenium</tt>
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
<tt>script/generate selenium</tt> or by creating them manually in your
<tt>/test/selenium</tt> 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[http://www.openqa.org/selenium-ide/] which has
support[http://wiki.openqa.org/display/SIDE/SeleniumOnRails] 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
<tt>config.yml.example</tt> to <tt>config.yml</tt> and make your changes in that
file.

=== Environments

Per default this plugin is only available in test environment. You can change
this by setting <tt>environments</tt>, 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
<tt>selenium_path</tt> to the directory where Selenium Core is stored.

 #config.yml
 selenium_path: 'c:\selenium'

== <tt>test:acceptance</tt>

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 <tt>test:acceptance</tt> you just need
to set in which directory they should be stored:

 #config.yml
 result_dir: 'c:\result'

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

This can be useful especially for continous integration.

=== user_extension.js

Selenium has support for <tt>user_extension.js</tt> 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
<tt>lib/test_builder_user_accessors.rb.example</tt> and
<tt>lib/test_builder_user_actions.rb.example</tt> that replicate the sample
extensions in Selenium Core's <tt>user-extensions.js.sample</tt>

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 <tt>test:acceptance</tt> 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
<tt>/selenium/setup</tt>. 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[http://www.openqa.org/selenium-ide/] does such a good
job and has support[http://wiki.openqa.org/display/SIDE/SeleniumOnRails] for
the Selenese format.

== Credits

* Jon Tirsen, http://jutopia.tirsen.com -- initial inspiration[http://wiki.rubyonrails.com/rails/pages/SeleniumIntegration]
* Eric Kidd, http://www.randomhacks.net -- contribution of RSelenese

== Information

For more information, check out the website[http://www.openqa.org/selenium-on-rails/].
Something went wrong with that request. Please try again.