Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 191 lines (158 sloc) 8.835 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
af93528 @myronmarston Add travis build status image.
authored
5 [![Build Status](https://secure.travis-ci.org/myronmarston/vcr.png?branch=master)](http://travis-ci.org/myronmarston/vcr)
6
cff2b84 @myronmarston Changed the readme to markdown format, and re-wrote most of it.
authored
7 ## Synopsis
8
aa61962 @myronmarston Use new github markdown syntax features.
authored
9 ``` ruby
10 require 'rubygems'
11 require 'test/unit'
12 require 'vcr'
cff2b84 @myronmarston Changed the readme to markdown format, and re-wrote most of it.
authored
13
d6576e3 @pacoguzman FIX synopsis using configure instead configuration
pacoguzman authored
14 VCR.configure do |c|
aa61962 @myronmarston Use new github markdown syntax features.
authored
15 c.cassette_library_dir = 'fixtures/vcr_cassettes'
430ccd1 @myronmarston Fix readme synopsis to use VCR 2.0 APIs.
authored
16 c.hook_into :webmock # or :fakeweb
aa61962 @myronmarston Use new github markdown syntax features.
authored
17 end
cff2b84 @myronmarston Changed the readme to markdown format, and re-wrote most of it.
authored
18
aa61962 @myronmarston Use new github markdown syntax features.
authored
19 class VCRTest < Test::Unit::TestCase
20 def test_example_dot_com
21 VCR.use_cassette('synopsis') do
22 response = Net::HTTP.get_response(URI('http://www.iana.org/domains/example/'))
23 assert_match /Example Domains/, response.body
cff2b84 @myronmarston Changed the readme to markdown format, and re-wrote most of it.
authored
24 end
aa61962 @myronmarston Use new github markdown syntax features.
authored
25 end
26 end
27 ```
cff2b84 @myronmarston Changed the readme to markdown format, and re-wrote most of it.
authored
28
29 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
30 will replay the response from iana.org when the http request is made. This test is now fast (no real HTTP requests are
31 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
32 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
33
a5ac5bf @myronmarston 1.0.0 release.
authored
34 ## Features
35
36 * Automatically records and replays your HTTP interactions with minimal setup/configuration code.
ea6933b @myronmarston Words.
authored
37 * Supports and works with the HTTP stubbing facilities of multiple libraries. Currently, the
38 following are supported:
bd013c9 @myronmarston Fix readme links.
authored
39 * [FakeWeb](https://github.com/chrisk/fakeweb)
40 * [WebMock](https://github.com/bblimke/webmock)
be71eda @i0rek Update Typhoeus links.
i0rek authored
41 * [Typhoeus](https://github.com/typhoeus/typhoeus)
bd013c9 @myronmarston Fix readme links.
authored
42 * [Faraday](https://github.com/technoweenie/faraday)
0eef043 @myronmarston Add excon info to readme.
authored
43 * [Excon](https://github.com/geemus/excon)
376be5f @myronmarston README formatting.
authored
44 * Supports multiple HTTP libraries:
ea6933b @myronmarston Words.
authored
45 * [Patron](http://github.com/toland/patron) (when using WebMock)
2fd32ce @myronmarston Curb uses the Curl namespace.
authored
46 * [Curb](http://github.com/taf2/curb) (when using WebMock -- only supports Curl::Easy at the moment)
ea6933b @myronmarston Words.
authored
47 * [HTTPClient](http://github.com/nahi/httpclient) (when using WebMock)
48 * [em-http-request](http://github.com/igrigorik/em-http-request) (when using WebMock)
49 * [Net::HTTP](http://www.ruby-doc.org/stdlib/libdoc/net/http/rdoc/index.html) (when using FakeWeb and WebMock)
be71eda @i0rek Update Typhoeus links.
i0rek authored
50 * [Typhoeus](https://github.com/typhoeus/typhoeus) (Typhoeus::Hydra, but not Typhoeus::Easy or Typhoeus::Multi)
0eef043 @myronmarston Add excon info to readme.
authored
51 * [Excon](https://github.com/geemus/excon)
ea6933b @myronmarston Words.
authored
52 * [Faraday](https://github.com/technoweenie/faraday)
376be5f @myronmarston README formatting.
authored
53 * And of course any library built on Net::HTTP, such as [Mechanize](http://github.com/tenderlove/mechanize),
54 [HTTParty](http://github.com/jnunemaker/httparty) or [Rest Client](http://github.com/archiloque/rest-client).
7078765 @myronmarston Update README.
authored
55 * Request matching is configurable based on HTTP method, URI, host, path, body and headers, or you can easily
56 implement a custom request matcher to handle any need.
a5ac5bf @myronmarston 1.0.0 release.
authored
57 * The same request can receive different responses in different tests--just use different cassettes.
7078765 @myronmarston Update README.
authored
58 * The recorded requests and responses are stored on disk in a serialization format of your choice
59 (currently YAML and JSON are built in, and you can easily implement your own custom serializer)
60 and can easily be inspected and edited.
a5ac5bf @myronmarston 1.0.0 release.
authored
61 * Dynamic responses are supported using ERB.
f2cb33e @myronmarston Add documentation about the new :re_record_interval option.
authored
62 * Automatically re-records cassettes on a configurable regular interval to keep them fresh and current.
a5ac5bf @myronmarston 1.0.0 release.
authored
63 * Disables all HTTP requests that you don't explicitly allow.
64 * Simple cucumber integration is provided using tags.
7078765 @myronmarston Update README.
authored
65 * Includes convenient RSpec macro and integration with RSpec 2 metadata.
a5b0a93 @myronmarston Update README.
authored
66 * 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
67 Capybara, Mechanize, Rest-Client and HTTParty.
03720a2 @myronmarston Words.
authored
68 * Includes Rack and Faraday middleware.
a5ac5bf @myronmarston 1.0.0 release.
authored
69
ab5e334 @myronmarston The documentation has moved to the wiki.
authored
70 ## Usage
71
245ae11 @myronmarston Update README.
authored
72 The docs come in two flavors:
51438f7 @myronmarston Add additional links to README.
authored
73
245ae11 @myronmarston Update README.
authored
74 * The [relish docs](http://relishapp.com/myronmarston/vcr) contain
75 example-based documentation (VCR's cucumber suite, in fact). It's a
76 good place to look when you are first getting started with VCR, or if
77 you want to see an example of how to use a feature.
78 * The [rubydoc.info docs](http://rubydoc.info/gems/vcr/frames) contain
79 API documentation. The API docs contain detailed info about all of VCR's
80 public API.
ab5e334 @myronmarston The documentation has moved to the wiki.
authored
81
d46736e @myronmarston A couple more documentation tweaks.
authored
82 See the [Upgrade](https://github.com/myronmarston/vcr/blob/master/Upgrade.md) doc
83 for info about what's new and changed in VCR 2.0.
84
d84800a @myronmarston Add note about release policy using semantic versioning.
authored
85 ## Release Policy
86
87 VCR follows the principles of [semantic versioning](http://semver.org/).
245ae11 @myronmarston Update README.
authored
88 The [API documentation](http://rubydoc.info/gems/vcr/frames) define
d84800a @myronmarston Add note about release policy using semantic versioning.
authored
89 VCR's public API. Patch level releases contain only bug fixes. Minor
90 releases contain backward-compatible new features. Major new releases
91 contain backwards-incompatible changes to the public API.
92
9329f89 @myronmarston Add list of supported ruby interpreters to README.
authored
93 ## Ruby Interpreter Compatibility
94
95 VCR has been tested on the following ruby interpreters:
96
97 * MRI 1.8.7
98 * MRI 1.9.2
245ae11 @myronmarston Update README.
authored
99 * MRI 1.9.3
9329f89 @myronmarston Add list of supported ruby interpreters to README.
authored
100 * REE 1.8.7
54c5608 @myronmarston README updates.
authored
101 * JRuby
102 * Rubinius
9329f89 @myronmarston Add list of supported ruby interpreters to README.
authored
103
245ae11 @myronmarston Update README.
authored
104 Note that as of VCR 2, 1.8.6 and 1.9.1 are not supported.
105
e13d215 @myronmarston 1.0.2 release.
authored
106 ## Development
107
108 * Source hosted on [GitHub](http://github.com/myronmarston/vcr).
617f02d @myronmarston Add link to IRC channel.
authored
109 * Direct questions and discussions to the [IRC channel](irc://irc.freenode.net/vcr) or
110 the [mailing list](http://groups.google.com/group/vcr-ruby).
f68da93 @myronmarston Added link to the new google group.
authored
111 * Report issues on [GitHub Issues](http://github.com/myronmarston/vcr/issues).
e13d215 @myronmarston 1.0.2 release.
authored
112 * Pull requests are very welcome! Please include spec and/or feature coverage for every patch,
113 and create a topic branch for every separate change you make.
4a53a6d @myronmarston Fix contributing link from readme now that it's under source control.
authored
114 * See the [Contributing](https://github.com/myronmarston/vcr/blob/master/CONTRIBUTING.md)
115 guide for instructions on running the specs and features.
67c1823 @myronmarston Fix readme.
authored
116 * Code quality metrics are checked by [Code Climate](https://codeclimate.com/github/myronmarston/vcr).
54b5829 @benjaminoakes Add YARD development dependency and usage notes
benjaminoakes authored
117 * Documentation is generated with [YARD](http://yardoc.org/) ([cheat sheet](http://cheat.errtheblog.com/s/yard/)).
118 To generate while developing:
119
120 ```
121 yard server --reload
122 ```
e13d215 @myronmarston 1.0.2 release.
authored
123
cff2b84 @myronmarston Changed the readme to markdown format, and re-wrote most of it.
authored
124 ## Thanks
125
126 * [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
127 * [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
128 * [Chris Kampmeier](http://github.com/chrisk) for [FakeWeb](http://github.com/chrisk/fakeweb).
129 * [Chris Young](http://github.com/chrisyoung) for [NetRecorder](http://github.com/chrisyoung/netrecorder),
130 the inspiration for VCR.
be71eda @i0rek Update Typhoeus links.
i0rek authored
131 * [David Balatero](https://github.com/dbalatero) for help with [Typhoeus](https://github.com/typhoeus/typhoeus)
1991c61 @myronmarston Update README and CHANGELOG with Typhoeus info.
authored
132 support.
0eef043 @myronmarston Add excon info to readme.
authored
133 * [Wesley Beary](https://github.com/geemus) for help with [Excon](https://github.com/geemus/excon)
134 support.
cff2b84 @myronmarston Changed the readme to markdown format, and re-wrote most of it.
authored
135
e9c7e31 @myronmarston Updated README.
authored
136 Thanks also to the following people who have contributed patches or helpful suggestions:
137
138 * [Aaron Brethorst](http://github.com/aaronbrethorst)
a70c39f @myronmarston Acknowledge sfesekaran for that last fix.
authored
139 * [Avdi Grimm](https://github.com/avdi)
e9c7e31 @myronmarston Updated README.
authored
140 * [Bartosz Blimke](http://github.com/bblimke)
2f3b73c @myronmarston Add Benjamin Oakes to contributors list.
authored
141 * [Benjamin Oakes](https://github.com/benjaminoakes)
e9c7e31 @myronmarston Updated README.
authored
142 * [Ben Hutton](http://github.com/benhutton)
d78791e @myronmarston Add recent contributors to readme.
authored
143 * [Bradley Isotope](https://github.com/bradleyisotope)
b667575 @myronmarston Add Carlos Kirkconnell to contributors list.
authored
144 * [Carlos Kirkconnell](https://github.com/kirkconnell)
0d01bfd @myronmarston Give credit where credit's due.
authored
145 * [Chad Jolly](https://github.com/cjolly)
7af62f4 @myronmarston Words.
authored
146 * [Chris Le](https://github.com/chrisle)
e9c7e31 @myronmarston Updated README.
authored
147 * [Eric Allam](http://github.com/rubymaverick)
0714dbd @myronmarston Add @ezkl to list of contributors in the readme.
authored
148 * [Ezekiel Templin](https://github.com/ezkl)
8c6cd60 @myronmarston Add Flaviu to list of contributors.
authored
149 * [Flaviu Simihaian](https://github.com/closedbracket)
e564ec3 @myronmarston Words.
authored
150 * [Gordon Wilson](https://github.com/gordoncww)
151 * [Ingemar](https://github.com/ingemar)
994a236 @myronmarston Words.
authored
152 * [Jeff Pollard](https://github.com/Fluxx)
b466443 @myronmarston Update contributors.
authored
153 * [Justin Smestad](https://github.com/jsmestad)
2e87813 @myronmarston Words.
authored
154 * [Karl Baum](https://github.com/kbaum)
7e790d6 @myronmarston Update contributors list.
authored
155 * [Michael Lavrisha](https://github.com/vrish88)
a96f0aa @myronmarston Update Changelog.
authored
156 * [Mislav Marohnić](https://github.com/mislav)
fb94dec @myronmarston Words.
authored
157 * [Nathaniel Bibler](https://github.com/nbibler)
158 * [Oliver Searle-Barnes](https://github.com/opsb)
0d01bfd @myronmarston Give credit where credit's due.
authored
159 * [Omer Rauchwerger](https://github.com/rauchy)
4b274c3 @myronmarston Give Paco credit for his contribution.
authored
160 * [Paco Guzmán](https://github.com/pacoguzman)
4fecdff @myronmarston Words.
authored
161 * [playupchris](https://github.com/playupchris)
b8c138a @myronmarston Add ryanb to contributors list.
authored
162 * [Ryan Bates](https://github.com/ryanb)
0520b4e @myronmarston Use sfekaran's full name based on the commit.
authored
163 * [Sathya Sekaran](https://github.com/sfsekaran)
4752496 @myronmarston Some improvements to @tylerhunt's faraday multipart upload fix.
authored
164 * [Tyler Hunt](https://github.com/tylerhunt)
d78791e @myronmarston Add recent contributors to readme.
authored
165 * [Wesley Beary](https://github.com/geemus)
e9c7e31 @myronmarston Updated README.
authored
166
ca6abe8 @myronmarston Add link to REST-assured and re-organize library links.
authored
167 ## Ports in other languages
970140c @myronmarston Add similar libraries to readme.
authored
168
169 * [Betamax](https://github.com/robfletcher/betamax) (Groovy)
170 * [Mimic](https://github.com/acoulton/mimic) (PHP/Kohana)
6723279 @myronmarston Add link to NSURLConnectionVCR.
authored
171 * [Nock](https://github.com/flatiron/nock) (JavaScript/Node)
172 * [NSURLConnectionVCR](https://bitbucket.org/martijnthe/nsurlconnectionvcr) (Objective C)
173 * [TapeDeck.js](https://github.com/EndangeredMassa/TapeDeck.js) (JavaScript)
174 * [VCR.js](https://github.com/elcuervo/vcr.js) (JavaScript)
9795ddb @myronmarston Add links to other VCR ports.
authored
175 * [VCR.py](https://github.com/kevin1024/vcrpy) (Python)
176 * [vcr-clj](https://github.com/ifesdjeen/vcr-clj) (Clojure)
ca6abe8 @myronmarston Add link to REST-assured and re-organize library links.
authored
177
178 ## Similar Libraries in Ruby
179
180 * [Ephemeral Response](https://github.com/sandro/ephemeral_response)
181 * [Net::HTTP Spy](http://github.com/martinbtt/net-http-spy)
182 * [NetRecorder](https://github.com/chrisyoung/netrecorder)
6723279 @myronmarston Add link to NSURLConnectionVCR.
authored
183 * [REST-assured](https://github.com/BBC/REST-assured)
ca6abe8 @myronmarston Add link to REST-assured and re-organize library links.
authored
184 * [Stale Fish](https://github.com/jsmestad/stale_fish)
185 * [WebFixtures](http://github.com/trydionel/web_fixtures)
970140c @myronmarston Add similar libraries to readme.
authored
186
cff2b84 @myronmarston Changed the readme to markdown format, and re-wrote most of it.
authored
187 ## Copyright
188
245ae11 @myronmarston Update README.
authored
189 Copyright (c) 2010-2012 Myron Marston. Released under the terms of the
190 MIT license. See LICENSE for details.
Something went wrong with that request. Please try again.