porcelain_background: While porcelain makes it easy to test endpoints individually,...

In reside-ic/porcelain: Turn a Package into an HTTP API

While porcelain makes it easy to test endpoints individually, you may still want some integration or end-to-end tests where you bring the entire API up and interact with it from your tests. This class provides a helper for doing this in a way that is reasonably tidy.

Description

While porcelain makes it easy to test endpoints individually, you may still want some integration or end-to-end tests where you bring the entire API up and interact with it from your tests. This class provides a helper for doing this in a way that is reasonably tidy.

While porcelain makes it easy to test endpoints individually, you may still want some integration or end-to-end tests where you bring the entire API up and interact with it from your tests. This class provides a helper for doing this in a way that is reasonably tidy.

Public fields

log

The path to the log file (read-only)

port

The port used by the background server (read-only)

Methods

Public methods

• porcelain_background$new()

• porcelain_background$start()

• porcelain_background$status()

• porcelain_background$stop()

• porcelain_background$url()

• porcelain_background$request()

---

Method new()

Create a background server object

Usage

porcelain_background$new(
  create,
  args = NULL,
  port = NULL,
  log = NULL,
  verbose = FALSE,
  timeout = 60,
  env = NULL
)

Arguments

create

A function that will create an api object

args

Arguments that will be passed to create when creating the api object in the background process

port

The port to use for the background server. If not given then a random free port will be used in the range 8000 to 10000 - you can find the created port using the port field in the resulting object, or use the ⁠$url()⁠ or ⁠$request()⁠ methods.

log

The path to a log file to use

verbose

Logical, indicating if we should print informational messages to the console on start/stop etc.

timeout

The number of seconds to wait for the server to become available. This needs to cover the time taken to spawn the R process, and create your API object (loading all packages needed) up to the point where the server is responsive. In most cases this will take 1-2s but if you use packages that use many S4 methods or run this on a slow computer (e.g., a continuous integration server) it may take longer than you expect. The default is one minute which should be sufficient in almost all cases.

env

A named character vector of environment variables (e.g., c(VARIABLE = "value")) to set in the background process before launching the server. You can use this to control the behaviour of the background server using variables your api recognises. In addition, we export callr::rcmd_safe_env() and the value of PORCELAIN_VALIDATE.

---

Method start()

Start the server. It is an error to try and start a server that is already running.

Usage

porcelain_background$start()

---

Method status()

Return the background server status. This will be one of:

• running: The server is running

• stopped: The server is stopped

• blocked: The server is stopped, but something else is running on the port that we would use

• starting: The server is starting up (not visible in normal usage)

Usage

porcelain_background$status()

---

Method stop()

Stop a running server. If the server is not running, this has no effect.

Usage

porcelain_background$stop()

---

Method url()

Create a url string for the server, interpolating the (possibly random) port number. You can use this in your tests like bg$url("/path")

Usage

porcelain_background$url(path)

Arguments

path

String representing the absolute path

---

Method request()

Run a request to the server, using httr. This presents a similar inteface to the request method on the porcelain object.

Usage

porcelain_background$request(method, path, ...)

Arguments

method

The http method as a string (e.g., "GET"), passed to httr::VERB as the verb argument

path

String representing the absolute path, passed to ⁠$url()⁠

...

Additional arguments passed to httr::VERB, such as query, or the body for a POST request.

reside-ic/porcelain documentation built on July 16, 2025, 6:09 p.m.