Record and replay your HTTP interactions for fast, deterministic and accurate tests
Go Shell Makefile
Switch branches/tags
Nothing to show
Clone or download
dnaeon Merge pull request #31 from vangent/issue30
Correctly return ContentLength based on the Content-Length header for HTTP HEAD requests
Latest commit aafff18 Aug 14, 2018


Build Status GoDoc Go Report Card codecov

go-vcr simplifies testing by recording your HTTP interactions and replaying them in future runs in order to provide fast, deterministic and accurate testing of your code.

go-vcr was inspired by the VCR library for Ruby.


Install go-vcr by executing the command below:

$ go get


Here is a simple example of recording and replaying etcd HTTP interactions.

You can find other examples in the example directory of this repository as well.

package main

import (



func main() {
	// Start our recorder
	r, err := recorder.New("fixtures/etcd")
	if err != nil {
	defer r.Stop() // Make sure recorder is stopped once done with it

	// Create an etcd configuration using our transport
	cfg := client.Config{
		Endpoints:               []string{""},
		HeaderTimeoutPerRequest: time.Second,
		Transport:               r, // Inject as transport!

	// Create an etcd client using the above configuration
	c, err := client.New(cfg)
	if err != nil {
		log.Fatalf("Failed to create etcd client: %s", err)

	// Get an example key from etcd
	etcdKey := "/foo"
	kapi := client.NewKeysAPI(c)
	resp, err := kapi.Get(context.Background(), etcdKey, nil)

	if err != nil {
		log.Fatalf("Failed to get etcd key %s: %s", etcdKey, err)

	log.Printf("Successfully retrieved etcd key %s: %s", etcdKey, resp.Node.Value)

Custom Request Matching

During replay mode, You can customize the way incoming requests are matched against the recorded request/response pairs by defining a Matcher function. For example, the following matcher will match on method, URL and body:

r, err := recorder.New("fixtures/matchers")
if err != nil {
defer r.Stop() // Make sure recorder is stopped once done with it

r.SetMatcher(func(r *http.Request, i cassette.Request) bool {
    var b bytes.Buffer
	if _, err := b.ReadFrom(r.Body); err != nil {
		return false
	r.Body = ioutil.NopCloser(&b)
	return cassette.DefaultMatcher(r, i) && (b.String() == "" || b.String() == i.Body)


go-vcr is Open Source and licensed under the BSD License