Stub an http request

stub_request(method = "get", uri = NULL, uri_regex = NULL)

Arguments

method: (character) HTTP method, one of "get", "post", "put", "patch", "head", "delete", "options" - or the special "any" (for any method)
uri: (character) The request uri. Can be a full or partial uri. webmockr can match uri's without the "http" scheme, but does not match if the scheme is "https". required, unless uri_regex given. See UriPattern for more. See the "uri vs. uri_regex" section
uri_regex: (character) A URI represented as regex. required, if uri not given. See examples and the "uri vs. uri_regex" section

Value

an object of class StubbedRequest, with print method describing the stub.

Details

Internally, this calls StubbedRequest which handles the logic

See stub_registry() for listing stubs, stub_registry_clear() for removing all stubs and remove_request_stub() for removing specific stubs

If multiple stubs match the same request, we use the first stub. So if you want to use a stub that was created after an earlier one that matches, remove the earlier one(s).

Note on wi_th(): If you pass query, values are coerced to character class in the recorded stub. You can pass numeric, integer, etc., but all will be coerced to character.

See wi_th() for details on request body/query/headers and to_return() for details on how response status/body/headers are handled

Note

Trailing slashes are dropped from stub URIs before matching

uri vs. uri_regex

When you use uri, we compare the URIs without query params AND also the query params themselves without the URIs.

When you use uri_regex we don't compare URIs and query params; we just use your regex string defined in uri_regex as the pattern for a call to grepl

Mocking writing to disk

See mocking-disk-writing

Error handling

To construct stubs, one uses stub_request() first - which registers the stub in the stub registry. Any additional calls to modify the stub with for example wi_th() or to_return() can error. In those error cases we ideally want to remove (unregister) the stub because you certainly don't want a registered stub that is not exactly what you intended.

When you encounter an error creating a stub you should see a warning message that the stub has been removed, for example:

stub_request("get", "https://httpbin.org/get") %>%
  wi_th(query = mtcars)
#> Error in `wi_th()`:
#> ! z$query must be of class list or partial
#> Run `rlang::last_trace()` to see where the error occurred.
#> Warning message:
#> Encountered an error constructing stub
#> • Removed stub
#> • To see a list of stubs run stub_registry()

Examples

# basic stubbing
stub_request("get", "https://httpbin.org/get")
#> <webmockr stub> 
#>   method: get
#>   uri: https://httpbin.org/get
#>   with: 
#>     query: 
#>     body: 
#>     request_headers: 
#>     auth: 
#>   to_return: 
stub_request("post", "https://httpbin.org/post")
#> <webmockr stub> 
#>   method: post
#>   uri: https://httpbin.org/post
#>   with: 
#>     query: 
#>     body: 
#>     request_headers: 
#>     auth: 
#>   to_return: 

# any method, use "any"
stub_request("any", "https://httpbin.org/get")
#> <webmockr stub> 
#>   method: any
#>   uri: https://httpbin.org/get
#>   with: 
#>     query: 
#>     body: 
#>     request_headers: 
#>     auth: 
#>   to_return: 

# list stubs
stub_registry()
#> <webmockr stub registry> 
#>  Registered Stubs
#>   GET: https://httpbin.org/get
#>   POST: https://httpbin.org/post
#>   ANY: https://httpbin.org/get

# clear all stubs
stub_registry()
#> <webmockr stub registry> 
#>  Registered Stubs
#>   GET: https://httpbin.org/get
#>   POST: https://httpbin.org/post
#>   ANY: https://httpbin.org/get
stub_registry_clear()