-
Notifications
You must be signed in to change notification settings - Fork 19
/
README
353 lines (228 loc) · 13.9 KB
/
README
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
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
Welcome to the Selenium on Rails README. Exciting isn't it?
Installation for Rails 2.2 and up release
Rails 2.2 changed the way views were rendered in such a way that it broke the version that works for version 2.2. This is the current version.
1. Install Selenium on Rails: script/plugin install http://svn.openqa.org/svn/selenium-on-rails/tags/stable/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 <TestName>
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.
Installation for Rails 2.1 release
Installation for rails versions before Rails 2.1
Rails has been changed in ways that break the original versions of Selenium on Rails. If you're using versions before Rails 2.1 you need to use this release. There are no plans to update this release with new changes or bug fixes unless there is sufficient demand, so if you can update then do so.
1. Install Selenium on Rails: script/plugin install http://svn.openqa.org/svn/selenium-on-rails/tags/pre-rails-2-1/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.
RSelenese, .rsel
RSelenese enable you to write your tests in Ruby. This is my favorite format.
setup :fixtures => :all
open '/'
assert_title 'Home'
('a'..'z').each {|c| open :controller => 'user', :action => 'create', :name => c }
See SeleniumOnRails::TestBuilder for available commands. This is also available in the SeleniumIDE, using the format here. IMPORTANT NOTE: RSelenese generates the HTML tables for Selenium behind the scenes when the page is loaded - ONCE. That means code like this:
(1..10).each do |index|
do something
end
Will only be executed when the test is loaded, not when the test is run. This is a common error and leads to tests that work the first time and fail the second time.
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.
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. This is highly recommended, just as small functions would be recommended in structured programming.
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 in a RSelenese test case:
include_partial 'login', :name => 'Jane Doe', :password => 'Jane Doe'.reverse
in a Selenese test case:
|includePartial|login|name=John Doe|password=eoD nhoJ|
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 selenium.yml.example to selenium.yml and placing it in your rails app's config
file. 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. If you're using a continuous builder this is a great way to integrate selenium into your build process.
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.
= 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
== Installation for Rails 2.1
1. Install Selenium on Rails: script/plugin install http://svn.openqa.org/svn/selenium-on-rails/current/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.
== Installation for rails versions before Rails 2.1
Rails has been changed in ways that break the original versions of Selenium on Rails. If you're using versions before Rails 2.1 you need to use this release. There are no plans to update this release with new changes or bug fixes unless there is sufficient demand, so if you can update then do so.
1. Install Selenium on Rails: script/plugin install http://svn.openqa.org/svn/selenium-on-rails/tags/pre-rails-2-1/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
<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 copying <tt>config.yml.example</tt> to <tt>config/selenium.yml</tt> in your application 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
* Jonas Bengston -- original creator
* Marcos Tapajós http://www.improveit.com.br/en/company/tapajos -- Several useful features
* Ryan Bates, http://railscasts.com -- Fixes for Rails 2.1
* Nando Vieira, http://simplesideias.com.br
* Eric Smith, http://blog.8thlight.com/eric -- Current Maintainer
== Information
For more information, check out the website[http://www.openqa.org/selenium-on-rails/].