glossary: webfakes glossary

In webfakes: Fake Web Apps for HTTP Testing

webfakes glossary

Description

webfakes glossary

Webfakes glossary

The webfakes package uses vocabulary that is standard for web apps, especially those developed with Express.js, but not necessarily well known to all R package developers.

app

(Also: fake web app, webfakes app.) A web application that can be served by webfakes's web server, typically in another process, an app process. Sometimes we call it a fake web app, to emphasize that we use it for testing real web apps and APIs.

You can create a webfakes app with the new_app() function. A webfakes app is an R object that you can save to disk with saveRDS() , and you can also include it in your package.

You can start an with its ⁠$listen()⁠ method. Since the main R process runs that test suite code, you usually run them in a subprocess, see new_app_process() or local_app_process().

app process

(Also: web server process, webfakes subprocess.) An app process is an R subprocess, started from the main R process, to serve a webfakes app.

You can create an app process object with new_app_process() or local_app_process(). By default the actual process does not start yet, when you create it. You can start it explicitly with the ⁠$start⁠ method of the app process object, or by querying its URL with ⁠$url()⁠ or its port with ⁠$get_port()⁠.

For test cases, you typically start app processes at these places:

• In a setup*.R file, to start an app that the whole test suite can use.

• Alternatively, in a helper*.R file, to start an app that the whole test suite can use, and it works better for interactive development.

• At the beginning of a test file, to create an app for a single test file.

• Inside test_that(), to create an app for a single test block.

See the How-to for details about each.

handler

(Or handler function.) A handler is a route or a middleware.

handler stack

This is a stack of handler functions, which are called by the app one after the other, passing the request and response objects to them. Handlers typically manipulate the request and/or response objects. A terminal handler instructs the app to return the response to the HTTP client. A non-terminal handler tells the app to keep calling handlers, by returning the string "next".

httpbin app

This is an example app, which implements the excellent ⁠https://httpbin.org/⁠ web service. You can use it to simulate certain HTTP responses. It is most handy for HTTP clients, but potentially useful for other tools as well.

Use httpbin_app() to create an instance of this app.

middleware

A middleware is a handler function that is not bound to a path. It is called by the router, like other handler functions. It may manipulate the request or the response, or can have a side effect. Some example built-in middleware functions in webfakes:

• mw_json() parses a request's JSON body into an R object.

• mw_log() logs requests and responses to the screen or to a file.

• mw_static() serves static files from the directory.

You can also write your own middleware functions.

path matching

The router performs path matching when it goes over the handler stack. If the HTTP method and path of a route match the HTTP method and URL of the request, then the handler is called, otherwise it is not. Paths can have parameters and be regular expressions. See ?new_regexp() for regular expressions and "Path parameters" in ?new_app() for parameters.

route

A route is a handler function that is bound to certain paths of you web app. If the request URL matches the path of the route, then the handler function is called, to give it a chance to send the appropriate response. Route paths may have parameters or they can be regular expressions in webfakes.

routing

Routing is the process of going over the handlers stack, and calling handler functions, one after the other, until one handles the request. If a handler function is a route, then the router only calls it if its path matches the request URL.

webfakes documentation built on Oct. 1, 2023, 9:06 a.m.