Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 261 lines (185 sloc) 7.444 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
86f6eb3 @tannerburson Mention that you have to return Sinatra::Application from def app
tannerburson authored
53 def app
54 Sinatra::Application
55 end
56
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
57 def test_it_says_hello_world
58 get '/'
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
59 assert last_response.ok?
60 assert_equal 'Hello World', last_response.body
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
61 end
62
63 def test_it_says_hello_to_a_person
64 get '/', :name => 'Simon'
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
65 assert last_response.body.include?('Simon')
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
66 end
67 end
68
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
69 ### Rack::Test's Mock Request Methods
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
70
71 The `get`, `put`, `post`, `delete`, and `head` methods simulate the
72 respective type of request on the application. Tests typically begin with
73 a call to one of these methods followed by one or more assertions against
74 the resulting response.
75
76 All mock request methods have the same argument signature:
77
78 get '/path', params={}, rack_env={}
79
80 * `/path` is the request path and may optionally include a query string.
81
82 * `params` is a Hash of query/post parameters, a String request body, or
83 `nil`.
84
85 * `rack_env` is a Hash of Rack environment values. This can be used to
86 set request headers and other request related information, such as session
87 data. See the [Rack SPEC][spec] for more information on possible key/values.
88
89 ### Asserting Expectations About The Response
90
91 Once a request method has been invoked, the following attributes are
92 available for making assertions:
93
94 * `app` - The Sinatra application class that handled the mock request.
95
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
96 * `last_request` - The [`Rack::MockRequest`][Rack::MockRequest] used to generate
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
97 the request.
98
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
99 * `last_response` - A [`Rack::MockResponse`][Rack::MockResponse] instance with
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
100 information on the response generated by the application.
101
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
102 Assertions are typically made against the `last_response` object.
103 Consider the following examples:
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
104
105 def test_it_says_hello_world
106 get '/'
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
107 assert last_response.ok?
108 assert_equal 'Hello World'.length.to_s, last_response.header['Content-Length']
109 assert_equal 'Hello World', last_response.body
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
110 end
111
112
113 ### Optional Test Setup
114
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
115 The `Rack::Test` mock request methods send requests to the return value of
116 a method named `app`.
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
117
118 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
119 subclasses, simply set the `app` method to return your particular class.
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
120
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
121 def app
122 MySinatraApp
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
123 end
124
86f6eb3 @tannerburson Mention that you have to return Sinatra::Application from def app
tannerburson authored
125 If you're using a classic style Sinatra application, then you need to return an
126 instance of `Sinatra::Application`.
127
128 def app
129 Sinatra::Application
130 end
131
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
132 ### Making `Rack::Test` available to all test cases
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
133
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
134 If you'd like the `Rack::Test` methods to be available to all test cases
135 without having to include it each time, you can include the `Rack::Test`
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
136 module in the `Test::Unit::TestCase` class:
137
138 require 'test/unit'
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
139 require 'rack/test'
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
140
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
141 class Test::Unit::TestCase
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
142 include Rack::Test::Methods
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
143 end
144
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
145 Now all `TestCase` subclasses will automatically have `Rack::Test`
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
146 available to them.
147
148 Test Framework Examples {#frameworks}
149 -----------------------
150
151 As of version `0.9.1`, Sinatra no longer provides testing framework-specific
152 helpers. Those found in `sinatra/test/*.rb` are deprecated and will be
153 removed in Sinatra `1.0`.
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
154
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
155 ### [RSpec][]
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
156
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
157 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
158 `Rack::Test` module should be included within the `describe` block:
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
159
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
160 require 'hello_world' # <-- your sinatra app
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
161 require 'spec'
162 require 'spec/interop/test'
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
163 require 'rack/test'
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
164
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
165 set :environment, :test
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
166
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
167 describe 'The HelloWorld App' do
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
168 include Rack::Test::Methods
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
169
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
170 it "says hello" do
171 get '/'
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
172 last_response.should be_ok
173 last_response.body.should == 'Hello World'
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
174 end
175 end
176
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
177 Make `Rack::Test` available to all spec contexts by including it in
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
178 `Test::Unit::TestCase`:
179
180 require 'spec'
181 require 'spec/interop/test'
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
182 require 'rack/test'
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
183
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
184 Test::Unit::TestCase.send :include, Rack::Test::Methods
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
185
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
186 ### [Bacon][]
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
187
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
188 Testing with Bacon is similar to `test/unit` and RSpec:
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
189
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
190 require 'hello_world' # <-- your sinatra app
191 require 'bacon'
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
192 require 'rack/test'
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
193
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
194 set :environment, :test
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
195
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
196 describe 'The HelloWorld App' do
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
197 include Rack::Test::Methods
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
198
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
199 it "says hello" do
200 get '/'
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
201 last_response.should.be.ok
202 last_response.body.should.equal 'Hello World'
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
203 end
204 end
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
205
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
206 Make `Rack::Test` available to all spec contexts by including it in
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
207 `Bacon::Context`:
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
208
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
209 class Bacon::Context
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
210 include Rack::Test::Methods
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
211 end
212
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
213 ### [Test::Spec][]
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
214
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
215 The `Rack::Test` module should be included within the context of the
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
216 `describe` block:
217
218 require 'hello_world' # <-- your sinatra app
219 require 'test/spec'
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
220 require 'rack/test'
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
221
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
222 set :environment, :test
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
223
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
224 describe 'The HelloWorld App' do
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
225 include Rack::Test::Methods
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
226
227 it "says hello" do
228 get '/'
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
229 last_response.should.be.ok
230 last_response.body.should.equal 'Hello World'
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
231 end
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
232 end
233
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
234 Make `Rack::Test` available to all spec contexts by including it in
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
235 `Test::Unit::TestCase`:
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
236
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
237 require 'test/spec'
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
238 require 'rack/test'
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
239
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
240 Test::Unit::TestCase.send :include, Rack::Test::Methods
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
241
242 <!-- TODO: Webrat -->
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
243
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
244 See Also
245 --------
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
246
7a7fd4c @tannerburson Cleaning up the testing docs to work with Rack::Test
tannerburson authored
247 See the source for [Rack::Test][] for
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
248 more information on `get`, `post`, `put`, `delete` and friends.
78cbc0e @dashdotat Bootstrapping of changes to doc for testing
dashdotat authored
249
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
250 [Test::Unit]: http://www.ruby-doc.org/stdlib/libdoc/test/unit/rdoc/classes/Test/Unit.html
251 [RSpec]: http://rspec.info
252 [Bacon]: http://github.com/chneukirchen/bacon
253 [Test::Spec]: http://rubyforge.org/projects/test-spec/
d3daf22 @sr Looks like one can't link to HEAD blob anymore
sr authored
254 [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
255 [Rack::Test]: http://github.com/brynary/rack-test/
a0578cf @sr Actually, we can. Thanks raggi :-)
sr authored
256 [test]: http://github.com/sinatra/sinatra/blob/master/test/test_test.rb
4043048 @sr Explain how to install and use Sinatra::Test
sr authored
257 [wild]: /wild.html
11372f2 @rtomayko Finish up test doc for now [#123]
rtomayko authored
258 [spec]: http://rack.rubyforge.org/doc/files/SPEC.html
259 [Rack::MockRequest]: http://rack.rubyforge.org/doc/classes/Rack/MockRequest.html
260 [Rack::MockResponse]: http://rack.rubyforge.org/doc/classes/Rack/MockResponse.html
Something went wrong with that request. Please try again.