1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/use_cassette.R
\name{use_cassette}
\alias{use_cassette}
\title{Use a cassette}
\usage{
use_cassette(name, ..., record = "once",
match_requests_on = c("method", "uri"),
update_content_length_header = FALSE, allow_playback_repeats = FALSE,
serialize_with = "yaml", persist_with = "FileSystem",
preserve_exact_body_bytes = FALSE)
}
\arguments{
\item{name}{The name of the cassette. vcr will sanitize this to ensure it
is a valid file name.}
\item{...}{a block of code to evalulate, wrapped in curly braces. required.
if you don't pass a code block you'll get a stop message. if you can't pass
a code block use instead \code{\link[=insert_cassette]{insert_cassette()}}}
\item{record}{The record mode. Default: "once". In the future we'll support
"once", "all", "none", "new_episodes". See \link{recording} for more information}
\item{match_requests_on}{List of request matchers
to use to determine what recorded HTTP interaction to replay. Defaults to
\code{["method", "uri"]}. The built-in matchers are "method", "uri", "host",
"path", "headers" and "body"}
\item{update_content_length_header}{(logical) Whether or
not to overwrite the \code{Content-Length} header of the responses to
match the length of the response body. Default: \code{FALSE}}
\item{allow_playback_repeats}{(logical) Whether or not to
allow a single HTTP interaction to be played back multiple times.
Default: \code{FALSE}.}
\item{serialize_with}{(character) Which serializer to use.
Valid values are "yaml" (default), the only one supported for now.}
\item{persist_with}{(character) Which cassette persister to
use. Default: "file_system". You can also register and use a
custom persister.}
\item{preserve_exact_body_bytes}{(logical) Whether or not
to base64 encode the bytes of the requests and responses for
this cassette when serializing it. See also \code{preserve_exact_body_bytes}
in \code{\link[=vcr_configure]{vcr_configure()}}. Default: \code{FALSE}}
}
\value{
an object of class \code{Cassette}
}
\description{
Use a cassette
}
\details{
A run down of the family of top level \pkg{vcr} functions
\itemize{
\item \code{use_cassette} Initializes a cassette. Returns the inserted
cassette.
\item \code{insert_cassette} Internally used within \code{use_cassette}
\item \code{eject_cassette} ejects the current cassette. The cassette
will no longer be used. In addition, any newly recorded HTTP interactions
will be written to disk.
}
}
\section{Behavior}{
This function handles a few different scenarios:
\itemize{
\item when everything runs smoothly, and we return a \code{Cassette} class object
so you can inspect the cassette, and the cassette is ejected
\item when there is an invalid parameter input on cassette creation,
we fail with a useful message, we don't return a cassette, and the
cassette is ejected
\item when there is an error in calling your passed in code block,
we return with a useful message, and since we use \code{on.exit()}
the cassette is still ejected even though there was an error,
but you don't get an object back
}
}
\section{Cassettes on disk}{
Note that \emph{"eject"} only means that the R session cassette is no longer
in use. If any interactions were recorded to disk, then there is a file
on disk with those interactions.
}
\section{Using with tests (specifically \pkg{testthat})}{
If you wrap your \code{test_that()} block inside your \code{use_cassette()}
block you'll get the correct line numbers from \code{testthat} when there
are errors/warnings/etc. However, if you wrap the \code{use_cassette()}
block inside your \code{test_that()} block, on errors/etc. you'll only
get the line number that that \code{use_cassette()} block starts on,
which is only identifies the code block but not the offending
line itself.
}
\examples{
\dontrun{
library(vcr)
library(crul)
vcr_configure(dir = tempdir())
use_cassette(name = "apple7", {
cli <- HttpClient$new(url = "https://httpbin.org")
resp <- cli$get("get")
})
readLines(file.path(tempdir(), "apple7.yml"))
# preserve exact body bytes - records in base64 encoding
use_cassette("things4", {
cli <- crul::HttpClient$new(url = "https://httpbin.org")
bbb <- cli$get("get")
}, preserve_exact_body_bytes = TRUE)
## see the body string value in the output here
readLines(file.path(tempdir(), "things4.yml"))
# cleanup
unlink(file.path(tempdir(), c("things4.yml", "apple7.yml")))
# with httr
library(vcr)
library(httr)
vcr_configure(dir = tempdir(), log = TRUE)
use_cassette(name = "stuff350", {
res <- GET("https://httpbin.org/get")
})
readLines(file.path(tempdir(), "stuff350.yml"))
use_cassette(name = "catfact456", {
res <- GET("https://catfact.ninja/fact")
})
}
}
\seealso{
\code{\link[=insert_cassette]{insert_cassette()}}, \code{\link[=eject_cassette]{eject_cassette()}}
}
|
