Skip to content
Newer
Older
100644 119 lines (63 sloc) 5.29 KB
d0c9cac @svenfuchs README
authored Feb 21, 2010
1 <a name="readme"></a>
2
cef0d8a @svenfuchs rename readme
authored Feb 18, 2010
3 h1. Steam
d17dd29 @clemens Add readme and license
clemens authored Nov 4, 2009
4
d0c9cac @svenfuchs README
authored Feb 21, 2010
5 Steam is a headless integration testing tool driving "HtmlUnit":http://htmlunit.sourceforge.net to enable testing JavaScript-driven web sites. In that it is similar to "Culerity":http://github.com/langalex/culerity which drives "Celerity":http://github.com/jarib/celerity (which also drives "HtmlUnit":http://htmlunit.sourceforge.net). See below for a "comparsion":#comparsion.
6
7 <a name="installation"></a>
cff22d7 @clemens Update readme.
clemens authored Nov 5, 2009
8
68291e9 @svenfuchs remove htmlunit from lib/
authored Feb 21, 2010
9 h2. Installation
d17dd29 @clemens Add readme and license
clemens authored Nov 4, 2009
10
11 Steam currently has the following dependencies:
12
13 * Working Java Runtime
d0c9cac @svenfuchs README
authored Feb 21, 2010
14 * HtmlUnit (jar files)
15 * RJB and Locator gems
16
17 Installing Steam as as a gem will automatically install the required RJB and Locator gems:
18
19 pre. $ gem install steam
68291e9 @svenfuchs remove htmlunit from lib/
authored Feb 21, 2010
20
11cd604 @svenfuchs fix Gemfile and update for latest RJB
authored Dec 17, 2010
21 To install HtmlUnit you can download it from "Sourceforge":http://sourceforge.net/projects/htmlunit/files.
68291e9 @svenfuchs remove htmlunit from lib/
authored Feb 21, 2010
22
d0c9cac @svenfuchs README
authored Feb 21, 2010
23 You then need to add HtmlUnit to your Java classpath. The following ways should both work:
68291e9 @svenfuchs remove htmlunit from lib/
authored Feb 21, 2010
24
d0c9cac @svenfuchs README
authored Feb 21, 2010
25 <pre># anywhere during startup, e.g. in features/support/env.rb
26 ENV['CLASSPATH'] = Dir["path/to/your/htmlunit/*.jar"].join(':')
d17dd29 @clemens Add readme and license
clemens authored Nov 4, 2009
27
d0c9cac @svenfuchs README
authored Feb 21, 2010
28 # after steam has been added to the load path, e.g. in features/support/env.rb
29 Steam.config[:html_unit][:java_path] = 'path/to/your/htmlunit'</pre>
d17dd29 @clemens Add readme and license
clemens authored Nov 4, 2009
30
2c28e7e @svenfuchs update readme about mac os x 10.6 java update
authored Dec 17, 2010
31 Since some Mac OS X 10.6 update removed the Java header files that are necessary to compile RJB one also needs to install "Java for Mac OS X 10.6 Update 3 Developer Package":http://connect.apple.com/cgi-bin/WebObjects/MemberSite.woa/wa/downloads
d17dd29 @clemens Add readme and license
clemens authored Nov 4, 2009
32
2c28e7e @svenfuchs update readme about mac os x 10.6 java update
authored Dec 17, 2010
33 Also, if you are on Mac OS X, use `sudo` and get an error saying that "JAVA_HOME is not set" then you need to export the JAVA_HOME variable for RJB. See here for two solutions: "Installing RJB on Mac OS X":http://www.elctech.com/articles/sudo-java_home-and-mac-os-x. The visudo way worked for us. Don't forget to add yourself to the sudoers file, though.
11cd604 @svenfuchs fix Gemfile and update for latest RJB
authored Dec 17, 2010
34
d17dd29 @clemens Add readme and license
clemens authored Nov 4, 2009
35
d0c9cac @svenfuchs README
authored Feb 21, 2010
36 <a name="configuration"></a>
ef0c9ff @fritzek initial config params handling
fritzek authored Nov 11, 2009
37
68291e9 @svenfuchs remove htmlunit from lib/
authored Feb 21, 2010
38 h2. Configuration
ef0c9ff @fritzek initial config params handling
fritzek authored Nov 10, 2009
39
68291e9 @svenfuchs remove htmlunit from lib/
authored Feb 21, 2010
40 You should not need to configure anything. If you do need though have a look at "Steam.config":http://github.com/svenfuchs/steam/blob/master/lib/steam.rb
ef0c9ff @fritzek initial config params handling
fritzek authored Nov 10, 2009
41
68291e9 @svenfuchs remove htmlunit from lib/
authored Feb 21, 2010
42 E.g. in order to tweak the Java load params you can
43
d0c9cac @svenfuchs README
authored Feb 21, 2010
44 pre. Steam.config[:java_load_params] = "-Xmx2048M"
45
88d4809 @svenfuchs update readme
authored Feb 28, 2010
46 If you want to test your application through Cucumber features then you need to setup your Cucumber environment and steps accordingly. You can find an example for a Cucumber setup here: "env.rb":http://github.com/svenfuchs/steam/blob/master/example/cucumber/env.rb.
47
48 Steam is widely compatible with Webrat - many actions are implemented and take the same or very similar parameters as their Webrat equivalent. As a starting point you might want to copy the file "webrat_compatible_steps.rb":http://github.com/svenfuchs/steam/blob/master/example/cucumber/webrat_compatible_steps.rb over to your @features/step_definitions@ directory.
d0c9cac @svenfuchs README
authored Feb 21, 2010
49
50 <a name="usage"></a>
68291e9 @svenfuchs remove htmlunit from lib/
authored Feb 21, 2010
51
52 h2. Usage
d17dd29 @clemens Add readme and license
clemens authored Nov 4, 2009
53
88d4809 @svenfuchs update readme
authored Feb 28, 2010
54 To test your application it needs to be available through http, so usually you want to start a test server:
55
56 <pre>script/server -e test # Rails < 3.0.0
57 rails server -e test # Rails >= 3.0.0
58 rackup -E test # etc.</pre>
d17dd29 @clemens Add readme and license
clemens authored Nov 4, 2009
59
88d4809 @svenfuchs update readme
authored Feb 28, 2010
60 If you have Cucumber set up you should now be able to run your features through Steam in a separate terminal (unless you've detached your server):
d0c9cac @svenfuchs README
authored Feb 21, 2010
61
88d4809 @svenfuchs update readme
authored Feb 28, 2010
62 <pre>cucumber features/*.feature</pre>
63
64 Be sure to restart the server if you make changes to your application. During development it might be useful to enable class reloading on the test server. You also might want to consider having separate environments for development with Cucumber/Steam and running the full test suite, e.g. on CI (where you keep class reloading disabled for faster test runs).
d0c9cac @svenfuchs README
authored Feb 21, 2010
65
66 <a name="demo"></a>
68291e9 @svenfuchs remove htmlunit from lib/
authored Feb 21, 2010
67
68 h2. Demo
69
70 You can find a demo application here: "http://github.com/clemens/steam-demo":http://github.com/clemens/steam-demo
71
72
d0c9cac @svenfuchs README
authored Feb 21, 2010
73 <a name="comparsion"></a>
74
75 h2. Comparsion to others
76
88d4809 @svenfuchs update readme
authored Feb 28, 2010
77 Steam's advantages over plain Webrat:
78
79 * Steam can test your Javascript and CSS, 'nuff said
80
81 Plain Webrat's advantages over Steam:
82
83 * It's still a little bit easier to set up. All full-stack integration testing tools still require you to manage more than one process (i.e. you have to start a server for the application). Webrat can run your tests, the "browser" (session) and application all in the same process, just like classic Rails integration tests.
84
d0c9cac @svenfuchs README
authored Feb 21, 2010
85 Steam's advantages over Culerity/Celerity:
d17dd29 @clemens Add readme and license
clemens authored Nov 4, 2009
86
d0c9cac @svenfuchs README
authored Feb 21, 2010
87 * runs in Ruby MRI and does not require an entire JRuby environment.
88d4809 @svenfuchs update readme
authored Feb 28, 2010
88 * Steam can have the HtmlUnit browser running in the same process as your tests, thus making the whole thing less complex and hard to debug
d0c9cac @svenfuchs README
authored Feb 21, 2010
89 * Steam does not build on Celerity which is a quite heavy-weight Ruby wrapper around HtmlUnit adding a lot of unnecessary code
90 * Steam uses "Locator":http://github.com/svenfuchs/locator
573612a @svenfuchs some minor changes
authored Oct 26, 2009
91
d0c9cac @svenfuchs README
authored Feb 21, 2010
92 Culerity/Celerity's advantages over Steam:
573612a @svenfuchs some minor changes
authored Oct 26, 2009
93
d0c9cac @svenfuchs README
authored Feb 21, 2010
94 * RJB can't resolve the mismatch of Ruby vs Java threads which makes fancy setups impossible to solve
95 * Celerity implements a *lot* of stuff, maybe it contains something you need (e.g. maybe you want to test pop-down windows opening in the background?)
96 * Steam still is in its infancy
d17dd29 @clemens Add readme and license
clemens authored Nov 4, 2009
97
d0c9cac @svenfuchs README
authored Feb 21, 2010
98
99 <a name="acknowledgements"></a>
d17dd29 @clemens Add readme and license
clemens authored Nov 4, 2009
100
68291e9 @svenfuchs remove htmlunit from lib/
authored Feb 21, 2010
101 h2. Acknowledgements
d17dd29 @clemens Add readme and license
clemens authored Nov 4, 2009
102
68291e9 @svenfuchs remove htmlunit from lib/
authored Feb 21, 2010
103 Kudos to "Alexander Lang":http://github.com/langalex for writing "Culerity":http://github.com/langalex/culerity which pioneered full-stack AJAX-enabled integration testing in Rails.
d17dd29 @clemens Add readme and license
clemens authored Nov 4, 2009
104
d0c9cac @svenfuchs README
authored Feb 21, 2010
105
106 <a name="developers"></a>
107
68291e9 @svenfuchs remove htmlunit from lib/
authored Feb 21, 2010
108 h2. Developers
d17dd29 @clemens Add readme and license
clemens authored Nov 4, 2009
109
d0c9cac @svenfuchs README
authored Feb 21, 2010
110 * "Sven Fuchs":http://github.com/svenfuchs
111 * "Clemens Kofler"::http://github.com/clemens
6d9b40e @svenfuchs Locator now has Matchers, so let's add them
authored Feb 27, 2010
112
113
114 TODO
115
116 * explain requirement to start/restart a test server
117 * explain log levels
118
Something went wrong with that request. Please try again.