/
README.Rmd
145 lines (109 loc) · 4.9 KB
/
README.Rmd
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
143
144
145
---
output: github_document
editor_options:
markdown:
wrap: sentence
canonical: true
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, setup, echo = FALSE, message = FALSE}
knitr::opts_chunk$set(
comment = "#>",
tidy = FALSE,
error = FALSE,
fig.width = 8,
fig.height = 8)
```
# webfakes
> Your own web server for happy HTTP testing
<!-- badges: start -->
[](https://github.com/r-lib/webfakes/actions)
[](https://CRAN.R-project.org/package=webfakes)
[](https://app.codecov.io/gh/r-lib/webfakes?branch=main)
[](https://github.com/r-lib/webfakes/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->
Lightweight fake web apps for testing.
Built using the [civetweb](https://github.com/civetweb/civetweb) embedded web server.
## Features
- Complete web app framework, define handlers for HTTP requests in R.
- Write your own app for your custom test cases; our use app similar to the `https://httpbin.org` API, so often you don't need to write your own web app (e.g. if you are writing an HTTP client (httr, curl, crul).
- Run one web app per test suite, per test file or per test case.
- Flexible path matching, with parameters and regular expressions.
- Built in templating system using glue or bring your own template engine.
- Middleware to parse JSON, multipart and URL encoded request bodies.
- A web app is just an R object. It can be saved to disk, copied to another R process, etc.
- A web app is extensible, by adding new routes and middleware to it.
- Helper functions for sending JSON, files from disk, etc.
- App-specific environment to store any data including data from requests to the fake app.
- After a web app is launched from R, you can interact with it from R but also from the command line, your browser, etc. Nice for debugging.
- The web server runs in the R process, so it has no problems with local firewalls.
- Multi-threaded web server supports concurrent HTTP requests.
- Limit download speed to simulate low bandwidth.
## Optional dependencies
- The jsonlite package is needed for the `mw_json()` middleware, the `response$send_json()` method and the `httpbin_app()` app.
- The glue package is needed for the `tmpl_glue()` template engine.
- The callr package is needed for `new_app_process()` and `local_app_process` to work.
- The `/brotli` endpoint of `httpbin_app()` needs the brotli package.
- The `/deflate` endpoint of `httpbin_app()` needs the zip package.
- The `/digest-auth` endpoint of `httpbin_app()` needs the digest package.
- `git_app()` requires the processx package.
## Installation
Install the release version from CRAN:
``` r
install.packages("webfakes")
```
## Usage
Start a web app at the beginning of your tests or test file, and stop it after.
Here is an example with the testthat package.
Suppose you want to test that your `get_hello()` function can query an API:
```{r include = FALSE}
library(testthat)
```
`local_app_process()` helps you clean up the web server process after the test block, or test file.
It is similar to the `withr::local_*` functions.
``` r
app <- webfakes::new_app()
app$get("/hello/:user", function(req, res) {
res$send(paste0("Hello ", req$params$user, "!"))
})
web <- webfakes::local_app_process(app)
test_that("can use hello API", {
url <- web$url("/hello/Gabor")
expect_equal(get_hello(url), "Hello Gabor!")
})
```
When testing HTTP clients you can often use the built in `httpbin_app()`:
```{r eval = FALSE}
httpbin <- webfakes::local_app_process(webfakes::httpbin_app())
```
```{r include = FALSE}
suppressMessages(
httpbin <- webfakes::local_app_process(webfakes::httpbin_app())
)
```
```{r}
test_that("HTTP errors are caught", {
url <- httpbin$url("/status/404")
resp <- httr::GET(url)
expect_error(httr::stop_for_status(resp), class = "http_404")
})
```
## Documentation
See <https://webfakes.r-lib.org>
## Links
### Other solutions for HTTP testing in R:
- [vcr](https://github.com/ropensci/vcr)
- [httptest](https://github.com/nealrichardson/httptest)
### R web application frameworks
webfakes focuses on testing, these packages are for writing real web apps:
- [shiny](https://github.com/rstudio/shiny)
- [opencpu](https://www.opencpu.org/)
- [plumber](https://github.com/rstudio/plumber)
- [fiery](https://github.com/thomasp85/fiery)
- [RestRserve](https://github.com/rexyai/RestRserve)
## Code of Conduct
Please note that the fs project is released with a
[Contributor Code of Conduct](https://webfakes.r-lib.org/dev/CODE_OF_CONDUCT.html).
By contributing to this project, you agree to abide by its terms.
## License
MIT © RStudio