Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 353 lines (244 sloc) 11.094 kb
8e0b53f @dchelimsky more Upgrade info
dchelimsky authored
1 The [Changelog](changelog) has a complete list of everything that changed, but
2 here are more detailed explanations for those items that warrant them.
9567fe0 @dchelimsky change default_directory to default_path
dchelimsky authored
3
8e0b53f @dchelimsky more Upgrade info
dchelimsky authored
4 # rspec-core-2.7.0.rc1
9567fe0 @dchelimsky change default_directory to default_path
dchelimsky authored
5
8e0b53f @dchelimsky more Upgrade info
dchelimsky authored
6 ## what's new
7
8 ### `rspec` command with no arguments
9
03b4c5c @dchelimsky doc: tweak the upgrade page
dchelimsky authored
10 Now you can just type
11
12 rspec
13
14 to run all the specs in the `spec` directory. If you keep your specs in a
d7161b7 @JonRowe remove deprecated cli option
JonRowe authored
15 different directory, you can override the default with the `--default-path`
03b4c5c @dchelimsky doc: tweak the upgrade page
dchelimsky authored
16 argument in a config file:
9567fe0 @dchelimsky change default_directory to default_path
dchelimsky authored
17
18 # in .rspec
d7161b7 @JonRowe remove deprecated cli option
JonRowe authored
19 --default-path specs
8e0b53f @dchelimsky more Upgrade info
dchelimsky authored
20
21 ### `rspec` command supports multiple line numbers
22
23 Use either of the following to run the examples declared on lines
24 37 and 42 of `a_spec.rb`:
25
26 rspec path/to/a_spec.rb --line_number 37 --line_number 42
27 rspec path/to/a_spec.rb:37:42
28
29 ## what's changed
30
31 ### `skip_bundler` and `gemfile` rake task options are deprecated and have no effect.
32
33 RSpec's rake task invokes the `rspec` command in a subshell. If you invoke
34 `bundle exec rake` or include `Bundler.setup` in your `Rakefile`, then
35 Bundler will be activated in the subshell as well.
36
37 Previously, the rake task managed this for you based on the presence of a
38 `Gemfile`. In 2.7.0.rc1, this is done based on the presence of the
39 `BUNDLE_GEMFILE` environment variable, which is set in the parent shell by Bundler.
9567fe0 @dchelimsky change default_directory to default_path
dchelimsky authored
40
8e0b53f @dchelimsky more Upgrade info
dchelimsky authored
41 In 2.7.0.rc2 (not yet released), the rake task doesn't do anything at all.
42 Turns out Bundler just does the right thing, so rspec doesn't need to do
43 anything.
9567fe0 @dchelimsky change default_directory to default_path
dchelimsky authored
44
edb06bb @dchelimsky update docs
dchelimsky authored
45 # rspec-core-2.6
46
47 ## new APIs for sharing content
48
49 Use `shared_context` together with `include_context` to share before/after
50 hooks, let declarations, and method definitions across example groups.
51
52 Use `shared_examples` together with `include_examples` to share examples
53 across different contexts.
54
55 All of the old APIs are still supported, but these 4 are easy to remember, and
56 serve most use cases.
57
58 See `shared_context` and `shared_examples` under "Example Groups" for more
59 information.
60
61 ## `treat_symbols_as_metadata_keys_with_true_values`
62
63 Yes it's a long name, but it's a great feature, and it's going to be the
64 default behavior in rspec-3. This lets you add metadata to a group or example
65 like this:
66
67 describe "something", :awesome do
68 ...
69
70 And then you can run that group (or example) using the tags feature:
71
72 rspec spec --tag awesome
73
74 We're making this an opt-in for rspec-2.6 because `describe "string", :symbol`
75 is a perfectly legal construct in pre-2.6 releases and we want to maintain
76 compatibility in minor releases as much as is possible.
77
c4a852d @dchelimsky docs
dchelimsky authored
78 # rspec-core-2.3
b7c2195 @dchelimsky Add copies of Upgrade and History to features so they appear in relish.
dchelimsky authored
79
c4a852d @dchelimsky docs
dchelimsky authored
80 ## `config.expect_with`
b7c2195 @dchelimsky Add copies of Upgrade and History to features so they appear in relish.
dchelimsky authored
81
82 Use this to configure RSpec to use rspec/expectations (default),
c4a852d @dchelimsky docs
dchelimsky authored
83 stdlib assertions (Test::Unit with Ruby 1.8, MiniTest with Ruby 1.9),
84 or both:
b7c2195 @dchelimsky Add copies of Upgrade and History to features so they appear in relish.
dchelimsky authored
85
86 RSpec.configure do |config|
87 config.expect_with :rspec # => rspec/expectations
c4a852d @dchelimsky docs
dchelimsky authored
88 config.expect_with :stdlib # => Test::Unit or MinitTest
b7c2195 @dchelimsky Add copies of Upgrade and History to features so they appear in relish.
dchelimsky authored
89 config.expect_with :rspec, :stdlib # => both
90 end
91
92 # rspec-core-2.1
93
94 ## Command line
95
96 ### `--tags`
97
98 Now you can tag groups and examples using metadata and access those tags from
99 the command line. So if you have a group with `:foo => true`:
100
101 describe "something", :foo => true do
102 it "does something" do
103 # ...
104 end
105 end
106
107 ... now you can run just that group like this:
108
109 rspec spec --tags foo
110
111 ### `--fail-fast`
112
113 Add this flag to the command line to tell rspec to clean up and exit after the
114 first failure:
115
116 rspec spec --fail-fast
117
118 ## Metata/filtering
119
120 ### :if and :unless keys
121
122 Use :if and :unless keys to conditionally run examples with simple boolean
123 expressions:
124
125 describe "something" do
05149b5 @JonRowe update docs
JonRowe authored
126 it "does something", :if => RUBY_VERSION == 1.8.7 do
b7c2195 @dchelimsky Add copies of Upgrade and History to features so they appear in relish.
dchelimsky authored
127 # ...
128 end
05149b5 @JonRowe update docs
JonRowe authored
129 it "does something", :unless => RUBY_VERSION == 1.8.7 do
b7c2195 @dchelimsky Add copies of Upgrade and History to features so they appear in relish.
dchelimsky authored
130 # ...
131 end
132 end
133
134 ## Conditionally 'pending' examples
135
136 Make examples pending based on a condition. This is most useful when you
137 have an example that runs in multiple contexts and fails in one of those due to
138 a bug in a third-party dependency that you expect to be fixed in the future.
139
140 describe "something" do
141 it "does something that doesn't yet work right on JRuby" do
142 pending("waiting for the JRuby team to fix issue XYZ", :if => RUBY_PLATFORM == 'java') do
143 # the content of your spec
144 end
145 end
146 end
147
148 This example would run normally on all ruby interpretters except JRuby. On JRuby,
149 it uses the block form of `pending`, which causes the example to still be run and
150 will remain pending as long as it fails. In the future, if you upgraded your
151 JRuby installation to a newer release that allows the example to pass, RSpec
152 will report it as a failure (`Expected pending '...' to fail. No Error was raised.`),
153 so that know that you can remove the call to `pending`.
154
155 # New features in rspec-core-2.0
156
157 ### Runner
158
159 The new runner for rspec-2 comes from Micronaut.
160
161 ### Metadata!
162
163 In rspec-2, every example and example group comes with metadata information
164 like the file and line number on which it was declared, the arguments passed to
165 `describe` and `it`, etc. This metadata can be appended to through a hash
166 argument passed to `describe` or `it`, allowing us to pre and post-process
167 each example in a variety of ways.
168
169 ### Filtering
170
171 The most obvious use is for filtering the run. For example:
172
173 # in spec/spec_helper.rb
174 RSpec.configure do |c|
175 c.filter_run :focus => true
176 end
177
178 # in any spec file
179 describe "something" do
180 it "does something", :focus => true do
181 # ....
182 end
183 end
184
185 When you run the `rspec` command, rspec will run only the examples that have
edb06bb @dchelimsky update docs
dchelimsky authored
186 `:focus => true` in the hash.
b7c2195 @dchelimsky Add copies of Upgrade and History to features so they appear in relish.
dchelimsky authored
187
188 You can also add `run_all_when_everything_filtered` to the config:
189
190 RSpec.configure do |c|
191 c.filter_run :focus => true
192 c.run_all_when_everything_filtered = true
193 end
194
195 Now if there are no examples tagged with `:focus => true`, all examples
196 will be run. This makes it really easy to focus on one example for a
197 while, but then go back to running all of the examples by removing that
198 argument from `it`. Works with `describe` too, in which case it runs
199 all of the examples in that group.
200
201 The configuration will accept a lambda, which provides a lot of flexibility
202 in filtering examples. Say, for example, you have a spec for functionality that
203 behaves slightly differently in Ruby 1.8 and Ruby 1.9. We have that in
204 rspec-core, and here's how we're getting the right stuff to run under the
205 right version:
206
207 # in spec/spec_helper.rb
208 RSpec.configure do |c|
209 c.exclusion_filter = { :ruby => lambda {|version|
210 !(RUBY_VERSION.to_s =~ /^#{version.to_s}/)
211 }}
212 end
213
214 # in any spec file
215 describe "something" do
216 it "does something", :ruby => 1.8 do
217 # ....
218 end
219
220 it "does something", :ruby => 1.9 do
221 # ....
222 end
223 end
224
225 In this case, we're using `exclusion_filter` instead of `filter_run` or
226 `filter`, which indicate _inclusion_ filters. So each of those examples is
227 excluded if we're _not_ running the version of Ruby they work with.
228
229 ### Shared example groups
230
231 Shared example groups are now run in a nested group within the including group
232 (they used to be run in the same group). Nested groups inherit `before`, `after`,
233 `around`, and `let` hooks, as well as any methods that are defined in the parent
234 group.
235
236 This new approach provides better encapsulation, better output, and an
237 opportunity to add contextual information to the shared group via a block
238 passed to `it_should_behave_like`.
239
240 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.
241
cccb32b @cupakromer A few more minor grammar and formatting updates.
cupakromer authored
242 **NOTICE:** An example group including shared examples no longer has access to
243 any of the methods, hooks or state defined inside the shared group. This will
244 break rspec-1 specs that were using shared example groups to extend the behavior
245 of including groups.
b7c2195 @dchelimsky Add copies of Upgrade and History to features so they appear in relish.
dchelimsky authored
246
247 # Upgrading from rspec-1.x
248
249 ### rspec command
250
251 The command to run specs is now `rspec` instead of `spec`.
252
253 rspec ./spec
254
255 #### Co-habitation of rspec-1 and rspec-2
256
257 Early beta versions of RSpec-2 included a `spec` command, which conflicted with
258 the RSpec-1 `spec` command because RSpec-1's was installed by the rspec gem,
259 while RSpec-2's is installed by the rspec-core gem.
260
261 If you installed one of these early versions, the safest bet is to uninstall
262 rspec-1 and rspec-core-2, and then reinstall both. After you do this, you will
263 be able to run rspec-2 like this:
264
265 rspec ./spec
266
267 ... and rspec-1 like this:
268
269 spec _1.3.1_ ./spec
270
271 Rubygems inspects the first argument to any gem executable to see if it's
272 formatted like a version number surrounded by underscores. If so, it uses that
273 version (e.g. `1.3.1`). If not, it uses the most recent version (e.g.
274 `2.0.0`).
275
276 ### rake task
277
278 A few things changed in the Rake task used to run specs:
279
280 1. The file in which it is defined changed from `spec/rake/spectask` to
281 `rspec/core/rake_task`
282
283 2. The `spec_opts` accessor has been deprecated in favor of `rspec_opts`. Also,
284 the `rspec` command no longer supports the `--options` command line option
285 so the options must be embedded directly in the Rakefile, or stored in the
286 `.rspec` files mentioned above.
edb06bb @dchelimsky update docs
dchelimsky authored
287
b7c2195 @dchelimsky Add copies of Upgrade and History to features so they appear in relish.
dchelimsky authored
288 3. The `spec_files` accessor has been replaced by `pattern`.
289
290 # rspec-1
291 require 'spec/rake/spectask'
292
293 Spec::Rake::SpecTask.new do |t|
294 t.spec_opts = ['--options', "\"spec/spec.opts\""]
295 t.spec_files = FileList['spec/**/*.rb']
296 end
297
298 # rspec-2
299 require 'rspec/core/rake_task'
300
301 RSpec::Core::RakeTask.new do |t|
302 t.rspec_opts = ["-c", "-f progress", "-r ./spec/spec_helper.rb"]
303 t.pattern = 'spec/**/*_spec.rb'
304 end
305
306 ### RSpec is the new Spec
307
308 The root namespace (top level module) is now `RSpec` instead of `Spec`, and
309 the root directory under `lib` within all of the `rspec` gems is `rspec` instead of `spec`.
310
311 ### Configuration
312
313 Typically in `spec/spec_helper.rb`, configuration is now done like this:
314
315 RSpec.configure do |c|
316 # ....
317 end
318
319 ### .rspec
320
321 Command line options can be persisted in a `.rspec` file in a project. You
322 can also store a `.rspec` file in your home directory (`~/.rspec`) with global
323 options. Precedence is:
324
325 command line
326 ./.rspec
327 ~/.rspec
328
329 ### `context` is no longer a top-level method
330
331 We removed `context` from the main object because it was creating conflicts with
332 IRB and some users who had `Context` domain objects. `describe` is still there,
333 so if you want to use `context` at the top level, just alias it:
334
335 alias :context :describe
336
337 Of course, you can still use `context` to declare a nested group:
338
339 describe "something" do
340 context "in some context" do
341 it "does something" do
342 # ...
343 end
344 end
345 end
346
347 ### `$KCODE` no longer set implicitly to `'u'`
348
349 In RSpec-1, the runner set `$KCODE` to `'u'`, which impacts, among other
350 things, the behaviour of Regular Expressions when applied to non-ascii
351 characters. This is no longer the case in RSpec-2.
352
Something went wrong with that request. Please try again.