Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 151 lines (123 sloc) 7.147 kB
833624d @myronmarston Remove travis status icon.
authored
1 # VCR
cff2b84 @myronmarston Changed the readme to markdown format, and re-wrote most of it.
authored
2
3 Record your test suite's HTTP interactions and replay them during future test runs for fast, deterministic, accurate tests.
4
5 ## Synopsis
6
aa61962 @myronmarston Use new github markdown syntax features.
authored
7 ``` ruby
8 require 'rubygems'
9 require 'test/unit'
10 require 'vcr'
cff2b84 @myronmarston Changed the readme to markdown format, and re-wrote most of it.
authored
11
aa61962 @myronmarston Use new github markdown syntax features.
authored
12 VCR.config do |c|
13 c.cassette_library_dir = 'fixtures/vcr_cassettes'
14 c.stub_with :webmock # or :fakeweb
15 end
cff2b84 @myronmarston Changed the readme to markdown format, and re-wrote most of it.
authored
16
aa61962 @myronmarston Use new github markdown syntax features.
authored
17 class VCRTest < Test::Unit::TestCase
18 def test_example_dot_com
19 VCR.use_cassette('synopsis') do
20 response = Net::HTTP.get_response(URI('http://www.iana.org/domains/example/'))
21 assert_match /Example Domains/, response.body
cff2b84 @myronmarston Changed the readme to markdown format, and re-wrote most of it.
authored
22 end
aa61962 @myronmarston Use new github markdown syntax features.
authored
23 end
24 end
25 ```
cff2b84 @myronmarston Changed the readme to markdown format, and re-wrote most of it.
authored
26
27 Run this test once, and VCR will record the http request to `fixtures/vcr_cassettes/synopsis.yml`. Run it again, and VCR
89b3403 @myronmarston Fix synopsis description.
authored
28 will replay the response from iana.org when the http request is made. This test is now fast (no real HTTP requests are
29 made anymore), deterministic (the test will continue to pass, even if you are offline, or iana.org goes down for
ba1ce1f @myronmarston Remove obselete reference to example.com.
authored
30 maintenance) and accurate (the response will contain the same headers and body you get from a real request).
cff2b84 @myronmarston Changed the readme to markdown format, and re-wrote most of it.
authored
31
a5ac5bf @myronmarston 1.0.0 release.
authored
32 ## Features
33
34 * Automatically records and replays your HTTP interactions with minimal setup/configuration code.
ea6933b @myronmarston Words.
authored
35 * Supports and works with the HTTP stubbing facilities of multiple libraries. Currently, the
36 following are supported:
bd013c9 @myronmarston Fix readme links.
authored
37 * [FakeWeb](https://github.com/chrisk/fakeweb)
38 * [WebMock](https://github.com/bblimke/webmock)
39 * [Typhoeus](https://github.com/dbalatero/typhoeus)
40 * [Faraday](https://github.com/technoweenie/faraday)
0eef043 @myronmarston Add excon info to readme.
authored
41 * [Excon](https://github.com/geemus/excon)
376be5f @myronmarston README formatting.
authored
42 * Supports multiple HTTP libraries:
ea6933b @myronmarston Words.
authored
43 * [Patron](http://github.com/toland/patron) (when using WebMock)
2fd32ce @myronmarston Curb uses the Curl namespace.
authored
44 * [Curb](http://github.com/taf2/curb) (when using WebMock -- only supports Curl::Easy at the moment)
ea6933b @myronmarston Words.
authored
45 * [HTTPClient](http://github.com/nahi/httpclient) (when using WebMock)
46 * [em-http-request](http://github.com/igrigorik/em-http-request) (when using WebMock)
47 * [Net::HTTP](http://www.ruby-doc.org/stdlib/libdoc/net/http/rdoc/index.html) (when using FakeWeb and WebMock)
bd013c9 @myronmarston Fix readme links.
authored
48 * [Typhoeus](https://github.com/dbalatero/typhoeus) (Typhoeus::Hydra, but not Typhoeus::Easy or Typhoeus::Multi)
0eef043 @myronmarston Add excon info to readme.
authored
49 * [Excon](https://github.com/geemus/excon)
ea6933b @myronmarston Words.
authored
50 * [Faraday](https://github.com/technoweenie/faraday)
376be5f @myronmarston README formatting.
authored
51 * And of course any library built on Net::HTTP, such as [Mechanize](http://github.com/tenderlove/mechanize),
52 [HTTParty](http://github.com/jnunemaker/httparty) or [Rest Client](http://github.com/archiloque/rest-client).
6d8ec54 @myronmarston Documentation update.
authored
53 * Request matching is configurable based on HTTP method, URI, host, path, body and headers.
a5ac5bf @myronmarston 1.0.0 release.
authored
54 * The same request can receive different responses in different tests--just use different cassettes.
55 * The recorded requests and responses are stored on disk as YAML and can easily be inspected and edited.
56 * Dynamic responses are supported using ERB.
f2cb33e @myronmarston Add documentation about the new :re_record_interval option.
authored
57 * Automatically re-records cassettes on a configurable regular interval to keep them fresh and current.
a5ac5bf @myronmarston 1.0.0 release.
authored
58 * Disables all HTTP requests that you don't explicitly allow.
59 * Simple cucumber integration is provided using tags.
ea6933b @myronmarston Words.
authored
60 * Includes convenient RSpec macro.
a5b0a93 @myronmarston Update README.
authored
61 * Known to work well with many popular ruby libraries including RSpec 1 & 2, Cucumber, Test::Unit,
1991c61 @myronmarston Update README and CHANGELOG with Typhoeus info.
authored
62 Capybara, Mechanize, Rest-Client and HTTParty.
646eab5 @myronmarston Got specs and features to pass on rubinius 1.1.
authored
63 * Extensively tested on 7 different ruby interpretters.
03720a2 @myronmarston Words.
authored
64 * Includes Rack and Faraday middleware.
a5ac5bf @myronmarston 1.0.0 release.
authored
65
ab5e334 @myronmarston The documentation has moved to the wiki.
authored
66 ## Usage
67
aab8b57 @myronmarston Link to relish instead of wiki.
authored
68 Browse the [documentation](http://relishapp.com/myronmarston/vcr) for usage info.
51438f7 @myronmarston Add additional links to README.
authored
69
70 The [VCR talk given at Philly.rb](http://philly-rb-vcr-talk.heroku.com/) also
71 contains good usage info.
ab5e334 @myronmarston The documentation has moved to the wiki.
authored
72
d84800a @myronmarston Add note about release policy using semantic versioning.
authored
73 ## Release Policy
74
75 VCR follows the principles of [semantic versioning](http://semver.org/).
76 The [cucumber features](http://relishapp.com/myronmarston/vcr) define
77 VCR's public API. Patch level releases contain only bug fixes. Minor
78 releases contain backward-compatible new features. Major new releases
79 contain backwards-incompatible changes to the public API.
80
9329f89 @myronmarston Add list of supported ruby interpreters to README.
authored
81 ## Ruby Interpreter Compatibility
82
83 VCR has been tested on the following ruby interpreters:
84
85 * MRI 1.8.6
86 * MRI 1.8.7
87 * MRI 1.9.1
88 * MRI 1.9.2
89 * REE 1.8.7
90 * JRuby 1.5.6
91 * Rubinius 1.2.1
92
fbc1fac @myronmarston Document known issue with syck.
authored
93 ## Known Issues
94
95 * VCR uses YAML to serialize the HTTP interactions to disk in a
96 human-readable, human-editable format. Unfortunately there are bugs
97 in Syck, Ruby's default YAML engine, that cause it to modify strings
98 when serializing them. It appears the the bug is limited to entire
99 lines of whitespace. A string such as `"1\n \n2"` will get changed
100 to `"1\n\n2"` (see [this gist](https://gist.github.com/815754) for
101 example code). In practice, this usually isn't so bad, but it can
102 occassionally cause problems, especially when the recorded
103 response includes a `content_length` header and you are using an
104 HTTP client that relies on this. Mechanize will raise an `EOFError`
105 when the `content_length` header does not match the response body
1e2e011 @myronmarston Add new :update_content_length_header cassette option.
authored
106 length. One solution is to use Psych, the new YAML engine included
fbc1fac @myronmarston Document known issue with syck.
authored
107 in Ruby 1.9. VCR attempts to use Psych if possible, but you may have
108 to [re-compile ruby 1.9](http://rhnh.net/2011/01/31/psych-yaml-in-ruby-1-9-2-with-rvm-and-snow-leopard-osx)
109 to use it. See [this issue](https://github.com/myronmarston/vcr/issues#issue/43)
1e2e011 @myronmarston Add new :update_content_length_header cassette option.
authored
110 for more info. You can also use the `:update_content_length_header`
111 cassette option to ensure the header has the correct value.
fbc1fac @myronmarston Document known issue with syck.
authored
112
e13d215 @myronmarston 1.0.2 release.
authored
113 ## Development
114
115 * Source hosted on [GitHub](http://github.com/myronmarston/vcr).
f68da93 @myronmarston Added link to the new google group.
authored
116 * Direct questions and discussions to the [mailing list](http://groups.google.com/group/vcr-ruby).
117 * Report issues on [GitHub Issues](http://github.com/myronmarston/vcr/issues).
e13d215 @myronmarston 1.0.2 release.
authored
118 * Pull requests are very welcome! Please include spec and/or feature coverage for every patch,
119 and create a topic branch for every separate change you make.
120
ab5e334 @myronmarston The documentation has moved to the wiki.
authored
121 If you find VCR useful, please recommend me on [working with rails](http://workingwithrails.com/person/16590-myron-marston).
cff2b84 @myronmarston Changed the readme to markdown format, and re-wrote most of it.
authored
122
123 ## Thanks
124
125 * [Aslak Hellesøy](http://github.com/aslakhellesoy) for [Cucumber](http://github.com/aslakhellesoy/cucumber).
df1e230 @myronmarston Updated README with info about putting regexes in cassettes.
authored
126 * [Bartosz Blimke](http://github.com/bblimke) for [WebMock](http://github.com/bblimke/webmock).
cff2b84 @myronmarston Changed the readme to markdown format, and re-wrote most of it.
authored
127 * [Chris Kampmeier](http://github.com/chrisk) for [FakeWeb](http://github.com/chrisk/fakeweb).
128 * [Chris Young](http://github.com/chrisyoung) for [NetRecorder](http://github.com/chrisyoung/netrecorder),
129 the inspiration for VCR.
1991c61 @myronmarston Update README and CHANGELOG with Typhoeus info.
authored
130 * [David Balatero](https://github.com/dbalatero) for help with [Typhoeus](https://github.com/pauldix/typhoeus)
131 support.
0eef043 @myronmarston Add excon info to readme.
authored
132 * [Wesley Beary](https://github.com/geemus) for help with [Excon](https://github.com/geemus/excon)
133 support.
cff2b84 @myronmarston Changed the readme to markdown format, and re-wrote most of it.
authored
134
e9c7e31 @myronmarston Updated README.
authored
135 Thanks also to the following people who have contributed patches or helpful suggestions:
136
137 * [Aaron Brethorst](http://github.com/aaronbrethorst)
138 * [Bartosz Blimke](http://github.com/bblimke)
139 * [Ben Hutton](http://github.com/benhutton)
d78791e @myronmarston Add recent contributors to readme.
authored
140 * [Bradley Isotope](https://github.com/bradleyisotope)
e9c7e31 @myronmarston Updated README.
authored
141 * [Eric Allam](http://github.com/rubymaverick)
b466443 @myronmarston Update contributors.
authored
142 * [Justin Smestad](https://github.com/jsmestad)
2e87813 @myronmarston Words.
authored
143 * [Karl Baum](https://github.com/kbaum)
fb94dec @myronmarston Words.
authored
144 * [Nathaniel Bibler](https://github.com/nbibler)
145 * [Oliver Searle-Barnes](https://github.com/opsb)
d78791e @myronmarston Add recent contributors to readme.
authored
146 * [Wesley Beary](https://github.com/geemus)
e9c7e31 @myronmarston Updated README.
authored
147
cff2b84 @myronmarston Changed the readme to markdown format, and re-wrote most of it.
authored
148 ## Copyright
149
1fdac5e @myronmarston Update copyright year.
authored
150 Copyright (c) 2010-2011 Myron Marston. See LICENSE for details.
Something went wrong with that request. Please try again.