Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 323 lines (224 sloc) 9.849 kb
b92b697 David Chelimsky words
dchelimsky authored
1 # rspec-core-2.2
5a5208d David Chelimsky History
dchelimsky authored
2
3 ## FASTER!
4
5 Made several small optimizations that all add up to a considerable improvement
6 in performance. Using a simple benchmark:
7
8 generate 5000 example groups,
9 each with one example,
10 each with one passing expectation
11
12 Run using ruby-1.9.2 on Mac OS X w/ 3.06 G
13
14 * rspec-2.1
15 * loaded in 0.85 on avg
16 * ran in 2.61 on avg
17 * rspec-2.2
18 * loaded in 0.73 on avg (~15% improvement)
19 * ran in 0.94 on avg (~64% improvement**)
20
21 ** this does _not_ mean your suite will be 64% faster, but it does mean that
22 the overhead incurred by RSpec in your suite should be roughly 64% less.
2466831 David Chelimsky Make debugger statements _just work_
dchelimsky authored
23
24 ## Command line
25
26 ### --debug/-d is now deprecated
27
28 This command line option is now has no effect (other than a deprecation
29 warning). To use the debugger, just add a `debugger` statement anywhere in your
30 code. As long as you have ruby-debug installed, it will just work. If you
31 don't, then you'll get a friendly warning telling you what's going on, but
32 execution will continue.
33
34 # rspec-core-2.1
4828e77 David Chelimsky add Upgrade information
dchelimsky authored
35
1a2f899 David Chelimsky words
dchelimsky authored
36 ## Command line
4828e77 David Chelimsky add Upgrade information
dchelimsky authored
37
1a2f899 David Chelimsky words
dchelimsky authored
38 ### `--tags`
1c03b2a David Chelimsky words
dchelimsky authored
39
1a2f899 David Chelimsky words
dchelimsky authored
40 Now you can tag groups and examples using metadata and access those tags from
41 the command line. So if you have a group with `:foo => true`:
4828e77 David Chelimsky add Upgrade information
dchelimsky authored
42
1a2f899 David Chelimsky words
dchelimsky authored
43 describe "something", :foo => true do
44 it "does something" do
45 # ...
46 end
4828e77 David Chelimsky add Upgrade information
dchelimsky authored
47 end
48
1a2f899 David Chelimsky words
dchelimsky authored
49 ... now you can run just that group like this:
fc37841 David Chelimsky tweak Upgrade.markdown
dchelimsky authored
50
1a2f899 David Chelimsky words
dchelimsky authored
51 rspec spec --tags foo
d0ea23a add instructions for updating Bones-generated Rakefiles
Chuck Remes authored
52
1a2f899 David Chelimsky words
dchelimsky authored
53 ### `--fail-fast`
d0ea23a add instructions for updating Bones-generated Rakefiles
Chuck Remes authored
54
1a2f899 David Chelimsky words
dchelimsky authored
55 Add this flag to the command line to tell rspec to clean up and exit after the
56 first failure:
d0ea23a add instructions for updating Bones-generated Rakefiles
Chuck Remes authored
57
1a2f899 David Chelimsky words
dchelimsky authored
58 rspec spec --fail-fast
d0ea23a add instructions for updating Bones-generated Rakefiles
Chuck Remes authored
59
1a2f899 David Chelimsky words
dchelimsky authored
60 ## Metata/filtering
73c15a1 David Chelimsky words
dchelimsky authored
61
1a2f899 David Chelimsky words
dchelimsky authored
62 ### :if and :unless keys
d0ea23a add instructions for updating Bones-generated Rakefiles
Chuck Remes authored
63
1a2f899 David Chelimsky words
dchelimsky authored
64 Use :if and :unless keys to conditionally run examples with simple boolean
65 expressions:
73c15a1 David Chelimsky words
dchelimsky authored
66
1a2f899 David Chelimsky words
dchelimsky authored
67 describe "something" do
68 it "does something", :if => RUBY_VERSION == 1.8.6 do
69 # ...
70 end
71 it "does something", :unless => RUBY_VERSION == 1.8.6 do
72 # ...
73 end
d0ea23a add instructions for updating Bones-generated Rakefiles
Chuck Remes authored
74 end
75
1a2f899 David Chelimsky words
dchelimsky authored
76 ## Conditionally 'pending' examples
48903d1 David Chelimsky document removal of top level context method
dchelimsky authored
77
3f9ed75 Myron Marston Improve explanation of new conditionally pending feature.
myronmarston authored
78 Make examples pending based on a condition. This is most useful when you
79 have an example that runs in multiple contexts and fails in one of those due to
80 a bug in a third-party dependency that you expect to be fixed in the future.
48903d1 David Chelimsky document removal of top level context method
dchelimsky authored
81
82 describe "something" do
3f9ed75 Myron Marston Improve explanation of new conditionally pending feature.
myronmarston authored
83 it "does something that doesn't yet work right on JRuby" do
84 pending("waiting for the JRuby team to fix issue XYZ", :if => RUBY_PLATFORM == 'java') do
85 # the content of your spec
86 end
1a2f899 David Chelimsky words
dchelimsky authored
87 end
88 end
5271992 David Chelimsky add note to Upgrade.markdown about RSpec-2 _not_ setting
dchelimsky authored
89
3f9ed75 Myron Marston Improve explanation of new conditionally pending feature.
myronmarston authored
90 This example would run normally on all ruby interpretters except JRuby. On JRuby,
91 it uses the block form of `pending`, which causes the example to still be run and
92 will remain pending as long as it fails. In the future, if you upgraded your
93 JRuby installation to a newer release that allows the example to pass, RSpec
94 will report it as a failure (`Expected pending '...' to fail. No Error was raised.`),
95 so that know that you can remove the call to `pending`.
5271992 David Chelimsky add note to Upgrade.markdown about RSpec-2 _not_ setting
dchelimsky authored
96
2eb3c72 David Chelimsky Revert "Make debugger statements _just work_"
dchelimsky authored
97 # New features in rspec-core-2.0
4828e77 David Chelimsky add Upgrade information
dchelimsky authored
98
99 ### Runner
100
101 The new runner for rspec-2 comes from Micronaut.
102
103 ### Metadata!
104
105 In rspec-2, every example and example group comes with metadata information
106 like the file and line number on which it was declared, the arguments passed to
107 `describe` and `it`, etc. This metadata can be appended to through a hash
108 argument passed to `describe` or `it`, allowing us to pre and post-process
109 each example in a variety of ways.
110
1c03b2a David Chelimsky words
dchelimsky authored
111 ### Filtering
112
4828e77 David Chelimsky add Upgrade information
dchelimsky authored
113 The most obvious use is for filtering the run. For example:
114
115 # in spec/spec_helper.rb
bcb1dfa David Chelimsky change top-level module from Rspec to RSpec
dchelimsky authored
116 RSpec.configure do |c|
4828e77 David Chelimsky add Upgrade information
dchelimsky authored
117 c.filter_run :focus => true
118 end
119
120 # in any spec file
121 describe "something" do
122 it "does something", :focus => true do
123 # ....
124 end
125 end
126
127 When you run the `rspec` command, rspec will run only the examples that have
128 `:focus => true` in the hash.
129
130 You can also add `run_all_when_everything_filtered` to the config:
131
bcb1dfa David Chelimsky change top-level module from Rspec to RSpec
dchelimsky authored
132 RSpec.configure do |c|
4828e77 David Chelimsky add Upgrade information
dchelimsky authored
133 c.filter_run :focus => true
134 c.run_all_when_everything_filtered = true
135 end
136
137 Now if there are no examples tagged with `:focus => true`, all examples
138 will be run. This makes it really easy to focus on one example for a
139 while, but then go back to running all of the examples by removing that
140 argument from `it`. Works with `describe` too, in which case it runs
141 all of the examples in that group.
142
143 The configuration will accept a lambda, which provides a lot of flexibility
144 in filtering examples. Say, for example, you have a spec for functionality that
145 behaves slightly differently in Ruby 1.8 and Ruby 1.9. We have that in
146 rspec-core, and here's how we're getting the right stuff to run under the
147 right version:
148
149 # in spec/spec_helper.rb
bcb1dfa David Chelimsky change top-level module from Rspec to RSpec
dchelimsky authored
150 RSpec.configure do |c|
4828e77 David Chelimsky add Upgrade information
dchelimsky authored
151 c.exclusion_filter = { :ruby => lambda {|version|
152 !(RUBY_VERSION.to_s =~ /^#{version.to_s}/)
153 }}
154 end
155
156 # in any spec file
157 describe "something" do
158 it "does something", :ruby => 1.8 do
159 # ....
160 end
161
162 it "does something", :ruby => 1.9 do
163 # ....
164 end
165 end
166
167 In this case, we're using `exclusion_filter` instead of `filter_run` or
168 `filter`, which indicate _inclusion_ filters. So each of those examples is
169 excluded if we're _not_ running the version of Ruby they work with.
669880e David Chelimsky words
dchelimsky authored
170
171 ### Shared example groups
172
173 Shared example groups are now run in a nested group within the including group
174 (they used to be run in the same group). Nested groups inherit `before`, `after`,
175 `around`, and `let` hooks, as well as any methods that are defined in the parent
176 group.
177
73f6199 David Chelimsky more words (finished baking the half-baked words from the last commit)
dchelimsky authored
178 This new approach provides better encapsulation, better output, and an
179 opportunity to add contextual information to the shared group via a block
180 passed to `it_should_behave_like`.
669880e David Chelimsky words
dchelimsky authored
181
bb722e4 David Chelimsky a link is a link, but does it look like one?
dchelimsky authored
182 See [features/example\_groups/shared\_example\_group.feature](http://github.com/rspec/rspec-core/blob/master/features/example_groups/shared_example_group.feature) for more information.
669880e David Chelimsky words
dchelimsky authored
183
73f6199 David Chelimsky more words (finished baking the half-baked words from the last commit)
dchelimsky authored
184 NOTICE: The including example groups no longer have access to any of the
185 methods, hooks, or state defined inside a shared group. This will break specs
186 that were using shared example groups to extend the behavior of including
187 groups in any way besides their intended purpose: to add examples to a group.
1a2f899 David Chelimsky words
dchelimsky authored
188
189 # Upgrading from rspec-1.x
190
191 ### rspec command
192
193 The command to run specs is now `rspec` instead of `spec`.
194
195 rspec ./spec
196
197 #### Co-habitation of rspec-1 and rspec-2
198
199 Early beta versions of RSpec-2 included a `spec` command, which conflicted with
200 the RSpec-1 `spec` command because RSpec-1's was installed by the rspec gem,
201 while RSpec-2's is installed by the rspec-core gem.
202
203 If you installed one of these early versions, the safest bet is to uninstall
204 rspec-1 and rspec-core-2, and then reinstall both. After you do this, you will
205 be able to run rspec-2 like this:
206
207 rspec ./spec
208
209 ... and rspec-1 like this:
210
211 spec _1.3.1_ ./spec
212
213 Rubygems inspects the first argument to any gem executable to see if it's
214 formatted like a version number surrounded by underscores. If so, it uses that
215 version (e.g. `1.3.1`). If not, it uses the most recent version (e.g.
216 `2.0.0`).
217
218 ### rake task
219
220 A few things changed in the Rake task used to run specs:
221
222 1. The file in which it is defined changed from `spec/rake/spectask` to
223 `rspec/core/rake_task`
224
225 2. The `spec_opts` accessor has been deprecated in favor of `rspec_opts`. Also,
226 the `rspec` command no longer supports the `--options` command line option
227 so the options must be embedded directly in the Rakefile, or stored in the
228 `.rspec` files mentioned above.
229
230 3. In RSpec-1, the rake task would read in rcov options from an `rcov.opts`
231 file. This is ignored by RSpec-2. RCov options are now set directly on the Rake
232 task:
233
234 RSpec::Core::RakeTask.new(:rcov) do |t|
235 t.rcov_opts = %q[--exclude "spec"]
236 end
237
238 3. The `spec_files` accessor has been replaced by `pattern`.
239
240 # rspec-1
241 require 'spec/rake/spectask'
242
243 Spec::Rake::SpecTask.new do |t|
244 t.spec_opts = ['--options', "\"spec/spec.opts\""]
245 t.spec_files = FileList['spec/**/*.rb']
246 end
247
248 # rspec-2
249 require 'rspec/core/rake_task'
250
251 RSpec::Core::RakeTask.new do |t|
252 t.rspec_opts = ["-c", "-f progress", "-r ./spec/spec_helper.rb"]
253 t.pattern = 'spec/**/*_spec.rb'
254 end
255
256 ### autotest
257
258 RSpec-2 works with autotest as follows:
259
260 rspec --configure autotest
261
262 This adds `./autotest/discover.rb` with:
263
264 Autotest.add_discovery { "rspec2" }
265
266 Now, on the command line just type:
267
268 autotest
269
270 Or, if you're using bundler:
271
272 bundle exec autotest
273
274 The `autospec` command is a thing of the past.
275
276 ### RSpec is the new Spec
277
278 The root namespace (top level module) is now `RSpec` instead of `Spec`, and
279 the root directory under `lib` within all of the `rspec` gems is `rspec` instead of `spec`.
280
281 ### Configuration
282
283 Typically in `spec/spec_helper.rb`, configuration is now done like this:
284
285 RSpec.configure do |c|
286 # ....
287 end
288
289 ### .rspec
290
291 Command line options can be persisted in a `.rspec` file in a project. You
292 can also store a `.rspec` file in your home directory (`~/.rspec`) with global
293 options. Precedence is:
294
295 command line
296 ./.rspec
297 ~/.rspec
298
299 ### `context` is no longer a top-level method
300
301 We removed `context` from the main object because it was creating conflicts with
302 IRB and some users who had `Context` domain objects. `describe` is still there,
303 so if you want to use `context` at the top level, just alias it:
304
305 alias :context :describe
306
307 Of course, you can still use `context` to declare a nested group:
308
309 describe "something" do
310 context "in some context" do
311 it "does something" do
312 # ...
313 end
314 end
315 end
316
317 ### `$KCODE` no longer set implicitly to `'u'`
318
319 In RSpec-1, the runner set `$KCODE` to `'u'`, which impacts, among other
320 things, the behaviour of Regular Expressions when applied to non-ascii
321 characters. This is no longer the case in RSpec-2.
322
Something went wrong with that request. Please try again.