Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 224 lines (160 sloc) 10.923 kb
cff2b84 @myronmarston Changed the readme to markdown format, and re-wrote most of it.
authored
1 # VCR
2
3 Record your test suite's HTTP interactions and replay them during future test runs for fast, deterministic, accurate tests.
4
5 ## Installation
6
7 gem install vcr
8
9 You'll also need either [FakeWeb](http://github.com/chrisk/fakeweb) or [WebMock](http://github.com/bblimke/webmock):
10
11 gem install fakeweb
12
13 or
14
15 gem install webmock
16
17 ## Synopsis
18
19 require 'test/unit'
20 require 'vcr'
21
22 VCR.config do |c|
23 c.cassette_library_dir = 'fixtures/vcr_cassettes'
24 c.http_stubbing_library = :fakeweb # or :webmock
25 end
26
27 class VCRTest < Test::Unit::TestCase
28 def test_example_dot_com
29 response = VCR.use_cassette('synopsis', :record => :new_episodes) do
30 Net::HTTP.get_response(URI.parse('http://example.com/'))
31 end
32 assert_match /You have reached this web page by typing.*example\.com/, response.body
33 end
34 end
35
36 Run this test once, and VCR will record the http request to `fixtures/vcr_cassettes/synopsis.yml`. Run it again, and VCR
37 will replay the response from example.com when the http request is made. This test is now fast (no real HTTP requests are
38 made anymore), deterministic (the test will continue to pass, even if you are offline, or example.com goes down for
39 maintenance) and accurate (the response from example.com will contain the same headers and body you get from a real request).
40
41 ## Cassettes
42
43 Cassettes are the medium to which VCR records HTTP interactions, and the medium from which it replays them.
44 While a cassette is in use, new HTTP requests (or "new episodes", as VCR calls them) either get
45 recorded, or an error will be raised, depending on the cassette's `:record` mode (see below). When you use
46 a cassette that contains previously recorded HTTP interactions, it registers them with the http stubbing
47 library of your choice (fakeweb or webmock) so that HTTP requests get the recorded response. Between test
48 runs, cassettes are stored on disk as YAML files in your configured cassette library directory.
49
50 Each cassette can be configured with a couple options:
51
52 * `:record`: Specifies a record mode for this cassette.
53 * `:allow_real_http`: You can use this to force VCR to always allow a real HTTP request for particular URIs.
54
55 For example, to prevent the VCR cassette from recording and replaying requests to google.com, you could use:
56
57 lambda { |uri| uri.host == 'google.com' }
58
59 All non-google requests would be recorded/replayed as normal. You can also set this to `:localhost`,
60 which is syntactic sugar for:
61
62 lambda { |uri| uri.host == 'localhost' }
63
64 This is particularly useful for using VCR with [capybara](http://github.com/jnicklas/capybara)
65 and any of its javascript drivers (see below for more info).
66
67 ## Record modes
68
69 VCR supports 3 record modes. You can set a default record mode in your configuration (see below)
70 and a per-cassette record mode when inserting a cassette. The record modes are:
71
72 * `:new_episodes`: Previously recorded HTTP interactions will be replayed. New HTTP interactions will be recorded.
73 * `:all`: Previously recorded HTTP interactions will be ignored. All HTTP interactions will be recorded.
74 * `:none`: Previously recorded HTTP interactions will be replayed. New HTTP interactions will result in an error.
75
76 ## Configuration
77
78 require 'vcr'
79
80 VCR.config do |c|
81 c.cassette_library_dir = File.join(Rails.root, 'features', 'fixtures', 'cassette_library')
82 c.http_stubbing_library = :fakeweb
83 c.default_cassette_options = { :record => :none }
84 end
85
86 This can go pretty much wherever, as long as this code is run before your tests, specs or scenarios. I tend
87 to put it in `spec/support/vcr.rb`, `test/support/vcr.rb` or `features/support/vcr.rb`. You can set the following
88 configuration options:
89
90 * `cassette_library_dir`: VCR will save the cassette YAML files to this directory.
91 * `http_stubbing_library`: Which http stubbing library to use. Currently `:fakeweb` and `:webmock` are supported.
92 This is currently optional--VCR will try to guess based on the presence or absence of the `FakeWeb` or `WebMock`
93 constants, but this is mostly done to assist users upgrading from VCR 0.3.1, which only worked with fakeweb and
94 didn't have this option. I recommend you explicitly configure this.
95 * `default_cassette_options`: The default options for your cassettes. These will be overriden by any options you
96 set on each individual cassette.
97
98 ## Usage with your favorite ruby test/spec framework
99
100 VCR can easily be used with any ruby test or spec framework. Usually, you'll want to use `VCR.use_cassette`:
101
102 VCR.use_cassette('geocoding/Seattle, WA', :record => :new_episodes) do
103 # do something that makes an HTTP request
104 end
105
106 Alternately, you can insert and eject a cassette with individual method calls from setup/before and teardown/after:
107
108 describe "Some object that makes an HTTP request" do
109 before(:each) do
110 VCR.insert_cassette('geocoding/Seattle, WA', :record => :new_episodes)
111 end
112
113 it "does something that makes an HTTP request"
114
115 after(:each) do
116 VCR.eject_cassette
117 end
118 end
119
120 ## Usage with Cucumber
121
122 VCR provides additional support for cucumber. You can of course use `VCR.use_cassette` within a step definition,
123 and that's the recommended way for any of your custom step definitions. But many times I find myself using generic
124 step definitions provided by another library (such as the webrat/capybara web steps generated by cucumber-rails),
125 and you don't want to modify these. VCR provides cucumber tagging support to help in these cases.
126
127 First, tag your scenario with something descriptive:
128
129 @facebook_http_request
130 Scenario: Sign up with facebook connect
131
132 Then let VCR know about this tag, in `features/support/vcr.rb` (or some similar support file):
133
134 VCR.cucumber_tags do |t|
135 t.tags '@facebook_http_request', '@twitter_status_update', :record => :none
136 t.tags '@another_scenario_tag'
137 end
138
139 For each of the tags you specify in your `cucumber_tags` block, VCR will set up the appropriate
140 [Before and After hooks](http://wiki.github.com/aslakhellesoy/cucumber/hooks) to use a cassette
141 for the entire scenario. The tag (minus the '@') will be used as the cassette name, and it'll
142 go in the `cucumber_tags` subdirectory of the configured cassette library directory.
143
144 If the last argument to `#tags` is a hash, VCR will use it as the options for the named cassettes.
145
146 ## Usage with Capybara
147
148 When you use any of the javascript-enabled drivers (selenium, celerity, culerity) with
149 [capybara](http://github.com/jnicklas/capybara), it'll need to ping the app running on localhost.
150 Set the `:allow_real_http => :localhost` option on your cassettes to allow this (or set it as a
151 default cassette option in your configuration).
152
153 ## Suggested Workflow
154
155 First, configure VCR as I have above. I like setting the default record mode to `:none`
156 so that no new HTTP requests are made without me explicitly allowing it.
157
158 When an HTTP request is made, you'll get an error such as:
159
160 Real HTTP connections are disabled. Unregistered request: get http://example.com
161
162 Find the place that is making the HTTP request (the backtrace should help here). If you've already recorded this HTTP
163 request to a cassette from a different test, you can simply re-use the cassette. Use `VCR.use_cassette`, as
164 shown above. You may also want to refactor this into a helper method that sets up the VCR cassette and does whatever
165 makes the HTTP request:
166
167 def set_user_address(user, address, city, state)
168 VCR.use_cassette("geocoding/#{address}, #{city}, #{state}", :record => :new_episodes) do
169 user.address.update_attributes!(:address => address, :city => city, :state => state)
170 end
171 end
172
173 In this case, I've used a dynamic cassette name based on the address being geocoded. That way, each separate address
174 gets a different cassette, and tests that set the same user address will reuse the same cassette. I've also set
175 the record mode to `:new_episodes` so that VCR will automatically record geocoding requests for a new address
176 to a new cassette, without me having to change any code.
177
178 If the HTTP request that triggered the error is new, you'll have to record it for the first time. Simply use
179 `VCR.use_cassette` with the record mode set to `:new_episodes` or `:all`. Run the test again, and VCR will
180 record the HTTP interaction. I usually remove the record mode at this point so that it uses the default
181 of `:none` in the future. Future test runs will get the recorded response, and if your code changes so
182 that it is making a new HTTP request, you'll be notified by an error as shown above.
183
184 ## Ruby Version Compatibility
185
186 VCR works on ruby [1.8.6](http://integrity186.heroku.com/vcr), [1.8.7](http://integrity187.heroku.com/vcr) and
187 [1.9.1](http://integrity191.heroku.com/vcr).
188
189 ## Notes, etc.
190
191 * The objects serialized to the cassette YAML files changed with the 0.4 release. Cassettes recorded with
192 older versions of VCR will not work with VCR 0.4.0 and later. However, VCR provides a rake task to migrate
193 your old cassettes to the new format--see the [changelog](http://github.com/myronmarston/vcr/blob/master/CHANGELOG.md)
194 for more info.
195 * The cassette name determines the name of the library file for the given cassette. Strings or symbols are fine,
196 and you can include any characters, but spaces and invalid file name characters will be removed
197 before the cassette reads or writes to its library file.
198 * You can use a directory separator (i.e. '/') in your cassette names to cause it to use a subdirectory
199 of the cassette library directory. The cucumber tagging support uses this.
200 * VCR maintains a simple stack of cassettes. This allows you to nest them as deeply as you want.
201 This is particularly useful when you have a cucumber step definition that uses a cassette, and
202 you also want to use a cassette for the entire scenario using the tagging support.
203
204 ## Note on Patches/Pull Requests
205
206 * Fork the project.
207 * Make your feature addition or bug fix.
208 * Add tests for it. This is important so I don't break it in a
209 future version unintentionally.
210 * Commit, do not mess with rakefile, version, or history.
211 (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
212 * Send me a pull request. Bonus points for topic branches.
213
214 ## Thanks
215
216 * [Aslak Hellesøy](http://github.com/aslakhellesoy) for [Cucumber](http://github.com/aslakhellesoy/cucumber).
217 * [Bartosz Blimke](http://github.com/bblimke) for [WebMock](http://github.com/bblimke/webmock)
218 * [Chris Kampmeier](http://github.com/chrisk) for [FakeWeb](http://github.com/chrisk/fakeweb).
219 * [Chris Young](http://github.com/chrisyoung) for [NetRecorder](http://github.com/chrisyoung/netrecorder),
220 the inspiration for VCR.
221
222 ## Copyright
223
224 Copyright (c) 2010 Myron Marston. See LICENSE for details.
Something went wrong with that request. Please try again.