Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 151 lines (123 sloc) 7.147 kb
833624d Myron Marston Remove travis status icon.
authored
1 # VCR
cff2b84 Myron Marston 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 Myron Marston Use new github markdown syntax features.
authored
7 ``` ruby
8 require 'rubygems'
9 require 'test/unit'
10 require 'vcr'
cff2b84 Myron Marston Changed the readme to markdown format, and re-wrote most of it.
authored
11
aa61962 Myron Marston 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 Myron Marston Changed the readme to markdown format, and re-wrote most of it.
authored
16
aa61962 Myron Marston 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 Myron Marston Changed the readme to markdown format, and re-wrote most of it.
authored
22 end
aa61962 Myron Marston Use new github markdown syntax features.
authored
23 end
24 end
25 ```
cff2b84 Myron Marston 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 Myron Marston 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 Myron Marston 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 Myron Marston Changed the readme to markdown format, and re-wrote most of it.
authored
31
a5ac5bf Myron Marston 1.0.0 release.
authored
32 ## Features
33
34 * Automatically records and replays your HTTP interactions with minimal setup/configuration code.
ea6933b Myron Marston Words.
authored
35 * Supports and works with the HTTP stubbing facilities of multiple libraries. Currently, the
36 following are supported:
bd013c9 Myron Marston 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 Myron Marston Add excon info to readme.
authored
41 * [Excon](https://github.com/geemus/excon)
376be5f Myron Marston README formatting.
authored
42 * Supports multiple HTTP libraries:
ea6933b Myron Marston Words.
authored
43 * [Patron](http://github.com/toland/patron) (when using WebMock)
2fd32ce Myron Marston Curb uses the Curl namespace.
authored
44 * [Curb](http://github.com/taf2/curb) (when using WebMock -- only supports Curl::Easy at the moment)
ea6933b Myron Marston 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 Myron Marston Fix readme links.
authored
48 * [Typhoeus](https://github.com/dbalatero/typhoeus) (Typhoeus::Hydra, but not Typhoeus::Easy or Typhoeus::Multi)
0eef043 Myron Marston Add excon info to readme.
authored
49 * [Excon](https://github.com/geemus/excon)
ea6933b Myron Marston Words.
authored
50 * [Faraday](https://github.com/technoweenie/faraday)
376be5f Myron Marston 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 Myron Marston Documentation update.
authored
53 * Request matching is configurable based on HTTP method, URI, host, path, body and headers.
a5ac5bf Myron Marston 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 Myron Marston 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 Myron Marston 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 Myron Marston Words.
authored
60 * Includes convenient RSpec macro.
a5b0a93 Myron Marston Update README.
authored
61 * Known to work well with many popular ruby libraries including RSpec 1 & 2, Cucumber, Test::Unit,
1991c61 Myron Marston Update README and CHANGELOG with Typhoeus info.
authored
62 Capybara, Mechanize, Rest-Client and HTTParty.
646eab5 Myron Marston Got specs and features to pass on rubinius 1.1.
authored
63 * Extensively tested on 7 different ruby interpretters.
03720a2 Myron Marston Words.
authored
64 * Includes Rack and Faraday middleware.
a5ac5bf Myron Marston 1.0.0 release.
authored
65
ab5e334 Myron Marston The documentation has moved to the wiki.
authored
66 ## Usage
67
aab8b57 Myron Marston Link to relish instead of wiki.
authored
68 Browse the [documentation](http://relishapp.com/myronmarston/vcr) for usage info.
51438f7 Myron Marston 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 Myron Marston The documentation has moved to the wiki.
authored
72
d84800a Myron Marston 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 Myron Marston 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 Myron Marston 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 Myron Marston Add new :update_content_length_header cassette option.
authored
106 length. One solution is to use Psych, the new YAML engine included
fbc1fac Myron Marston 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 Myron Marston 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 Myron Marston Document known issue with syck.
authored
112
e13d215 Myron Marston 1.0.2 release.
authored
113 ## Development
114
115 * Source hosted on [GitHub](http://github.com/myronmarston/vcr).
f68da93 Myron Marston 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 Myron Marston 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 Myron Marston 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 Myron Marston 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 Myron Marston 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 Myron Marston 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 Myron Marston 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 Myron Marston 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 Myron Marston Changed the readme to markdown format, and re-wrote most of it.
authored
134
e9c7e31 Myron Marston 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 Myron Marston Add recent contributors to readme.
authored
140 * [Bradley Isotope](https://github.com/bradleyisotope)
e9c7e31 Myron Marston Updated README.
authored
141 * [Eric Allam](http://github.com/rubymaverick)
b466443 Myron Marston Update contributors.
authored
142 * [Justin Smestad](https://github.com/jsmestad)
2e87813 Myron Marston Words.
authored
143 * [Karl Baum](https://github.com/kbaum)
fb94dec Myron Marston Words.
authored
144 * [Nathaniel Bibler](https://github.com/nbibler)
145 * [Oliver Searle-Barnes](https://github.com/opsb)
d78791e Myron Marston Add recent contributors to readme.
authored
146 * [Wesley Beary](https://github.com/geemus)
e9c7e31 Myron Marston Updated README.
authored
147
cff2b84 Myron Marston Changed the readme to markdown format, and re-wrote most of it.
authored
148 ## Copyright
149
1fdac5e Myron Marston Update copyright year.
authored
150 Copyright (c) 2010-2011 Myron Marston. See LICENSE for details.
Something went wrong with that request. Please try again.