Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 250 lines (177 sloc) 7.218 kB
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
1 ---
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
2 title: Testing with Sinatra
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
3 layout: default
8c053f5 @rtomayko Minor spelling edits
rtomayko authored
4 id: testing
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
5 ---
6
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
7 Testing with Sinatra
8 ====================
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
9
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
10 **NOTE: Sinatra's built-in test framework has been deprecated. This page uses the new recommended test framework
4d3383c @rtomayko Add links to Rack::Test and note that Sinatra::Test is deprecated
rtomayko authored
11 [Rack::Test](http://gitrdoc.com/brynary/rack-test/tree/master) instead.**
12
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
13 All examples in the follow sections assume that `Test::Unit` is being
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
14 used in an attempt to be as general as possible. See the [Test Framework
15 Examples](#frameworks) for information on using Sinatra's test helpers in
16 other testing environments.
17
18 *NOTE:* There are plenty of apps [in the wild][wild] that are using other
19 testing frameworks.
20
21 Example App: `hello_world.rb`
22 -----------------------------
23
24 The following example app is used to illustrate testing features. This is
25 assumed to be in a file named `hello_world.rb`:
26
27 require 'sinatra'
28
29 get '/' do
f465dd7 @sr Fix hello world test example
sr authored
30 "Hello World #{params[:name]}".strip
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
31 end
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
32
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
33 Using The `Rack::Test` Mixin
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
34 -------------------------------
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
35
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
36 The `Rack::Test` module includes a variety of helper methods for
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
37 simulating requests against an application and asserting expectations about
38 the response. It's typically included directly within the test context and
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
39 makes a few helper methods and attributes available.
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
40
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
41 The following is a simple example that ensures the hello world app functions
42 properly:
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
43
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
44 require 'hello_world'
45 require 'test/unit'
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
46 require 'rack/test'
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
47
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
48 set :environment, :test
49
50 class HelloWorldTest < Test::Unit::TestCase
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
51 include Rack::Test::Methods
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
52
53 def test_it_says_hello_world
54 get '/'
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
55 assert last_response.ok?
56 assert_equal 'Hello World', last_response.body
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
57 end
58
59 def test_it_says_hello_to_a_person
60 get '/', :name => 'Simon'
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
61 assert last_response.body.include?('Simon')
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
62 end
63 end
64
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
65 ### Rack::Test's Mock Request Methods
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
66
67 The `get`, `put`, `post`, `delete`, and `head` methods simulate the
68 respective type of request on the application. Tests typically begin with
69 a call to one of these methods followed by one or more assertions against
70 the resulting response.
71
72 All mock request methods have the same argument signature:
73
74 get '/path', params={}, rack_env={}
75
76 * `/path` is the request path and may optionally include a query string.
77
78 * `params` is a Hash of query/post parameters, a String request body, or
79 `nil`.
80
81 * `rack_env` is a Hash of Rack environment values. This can be used to
82 set request headers and other request related information, such as session
83 data. See the [Rack SPEC][spec] for more information on possible key/values.
84
85 ### Asserting Expectations About The Response
86
87 Once a request method has been invoked, the following attributes are
88 available for making assertions:
89
90 * `app` - The Sinatra application class that handled the mock request.
91
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
92 * `last_request` - The [`Rack::MockRequest`][Rack::MockRequest] used to generate
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
93 the request.
94
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
95 * `last_response` - A [`Rack::MockResponse`][Rack::MockResponse] instance with
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
96 information on the response generated by the application.
97
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
98 Assertions are typically made against the `last_response` object.
99 Consider the following examples:
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
100
101 def test_it_says_hello_world
102 get '/'
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
103 assert last_response.ok?
104 assert_equal 'Hello World'.length.to_s, last_response.header['Content-Length']
105 assert_equal 'Hello World', last_response.body
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
106 end
107
108
109 ### Optional Test Setup
110
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
111 The `Rack::Test` mock request methods send requests to the return value of
112 a method named `app`.
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
113
114 If you're testing a modular application that has multiple `Sinatra::Base`
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
115 subclasses, simply set the `app` method to return your particular class.
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
116
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
117 def app
118 MySinatraApp
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
119 end
120
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
121 ### Making `Rack::Test` available to all test cases
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
122
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
123 If you'd like the `Rack::Test` methods to be available to all test cases
124 without having to include it each time, you can include the `Rack::Test`
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
125 module in the `Test::Unit::TestCase` class:
126
127 require 'test/unit'
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
128 require 'rack/test'
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
129
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
130 class Test::Unit::TestCase
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
131 include Rack::Test::Methods
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
132 end
133
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
134 Now all `TestCase` subclasses will automatically have `Rack::Test`
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
135 available to them.
136
137 Test Framework Examples {#frameworks}
138 -----------------------
139
140 As of version `0.9.1`, Sinatra no longer provides testing framework-specific
141 helpers. Those found in `sinatra/test/*.rb` are deprecated and will be
142 removed in Sinatra `1.0`.
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
143
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
144 ### [RSpec][]
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
145
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
146 Sinatra can be tested under RSpec using the `spec/interop` library. The
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
147 `Rack::Test` module should be included within the `describe` block:
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
148
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
149 require 'hello_world' # <-- your sinatra app
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
150 require 'spec'
151 require 'spec/interop/test'
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
152 require 'rack/test'
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
153
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
154 set :environment, :test
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
155
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
156 describe 'The HelloWorld App' do
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
157 include Rack::Test::Methods
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
158
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
159 it "says hello" do
160 get '/'
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
161 last_response.should be_ok
162 last_response.body.should == 'Hello World'
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
163 end
164 end
165
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
166 Make `Rack::Test` available to all spec contexts by including it in
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
167 `Test::Unit::TestCase`:
168
169 require 'spec'
170 require 'spec/interop/test'
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
171 require 'rack/test'
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
172
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
173 Test::Unit::TestCase.send :include, Rack::Test::Methods
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
174
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
175 ### [Bacon][]
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
176
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
177 Testing with Bacon is similar to `test/unit` and RSpec:
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
178
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
179 require 'hello_world' # <-- your sinatra app
180 require 'bacon'
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
181 require 'rack/test'
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
182
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
183 set :environment, :test
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
184
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
185 describe 'The HelloWorld App' do
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
186 include Rack::Test::Methods
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
187
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
188 it "says hello" do
189 get '/'
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
190 last_response.should.be.ok
191 last_response.body.should.equal 'Hello World'
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
192 end
193 end
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
194
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
195 Make `Rack::Test` available to all spec contexts by including it in
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
196 `Bacon::Context`:
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
197
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
198 class Bacon::Context
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
199 include Rack::Test::Methods
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
200 end
201
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
202 ### [Test::Spec][]
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
203
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
204 The `Rack::Test` module should be included within the context of the
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
205 `describe` block:
206
207 require 'hello_world' # <-- your sinatra app
208 require 'test/spec'
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
209 require 'rack/test'
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
210
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
211 set :environment, :test
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
212
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
213 describe 'The HelloWorld App' do
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
214 include Rack::Test::Methods
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
215
216 it "says hello" do
217 get '/'
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
218 last_response.should.be.ok
219 last_response.body.should.equal 'Hello World'
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
220 end
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
221 end
222
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
223 Make `Rack::Test` available to all spec contexts by including it in
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
224 `Test::Unit::TestCase`:
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
225
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
226 require 'test/spec'
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
227 require 'rack/test'
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
228
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
229 Test::Unit::TestCase.send :include, Rack::Test::Methods
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
230
231 <!-- TODO: Webrat -->
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
232
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
233 See Also
234 --------
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
235
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
236 See the source for [Rack::Test][] for
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
237 more information on `get`, `post`, `put`, `delete` and friends.
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
238
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
239 [Test::Unit]: http://www.ruby-doc.org/stdlib/libdoc/test/unit/rdoc/classes/Test/Unit.html
240 [RSpec]: http://rspec.info
241 [Bacon]: http://github.com/chneukirchen/bacon
242 [Test::Spec]: http://rubyforge.org/projects/test-spec/
d3daf22 @sr Looks like one can't link to HEAD blob anymore
sr authored
243 [Sinatra::Test]: http://github.com/sinatra/sinatra/blob/987d622a52f3eaf28f8f6beb7451c3e43c23f075/test/test_test.rb
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
244 [Rack::Test]: http://github.com/brynary/rack-test/
a0578cf @sr Actually, we can. Thanks raggi :-)
sr authored
245 [test]: http://github.com/sinatra/sinatra/blob/master/test/test_test.rb
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
246 [wild]: /wild.html
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
247 [spec]: http://rack.rubyforge.org/doc/files/SPEC.html
248 [Rack::MockRequest]: http://rack.rubyforge.org/doc/classes/Rack/MockRequest.html
249 [Rack::MockResponse]: http://rack.rubyforge.org/doc/classes/Rack/MockResponse.html
Something went wrong with that request. Please try again.