Rester is a command line tool to test HTTP APIs. It processes declaratively written request descriptions as a test script, executing and validating the requests as specified.
For instance, a description like the following:
# basic.yml
requests:
basic:
url: https://httpbin.org/anything
validation:
status: 200
is processed as follows:
Rester currently supports:
- Request methods: GET, POST, PUT, DELETE
- Variable substitution
- Post data with respective encoding
- JSON
- query parameters
- forms
- multipart
- Sending headers
- Using response values as substitution variables
- Batch file processing
- Uploading and downloading of files
- Delay between requests
See Upcoming Features for a list of what is planned for future releases.
An example is worth a thousand words - this is how you can use rester to instrument API calls:
# github.yml
variables:
BASE_URL: https://api.github.com/repos/finestructure/Rester
requests:
releases:
url: ${BASE_URL}/releases
validation:
status: 200
json:
# validate the first id in the list (latest release)
# this also captures it as a variable
0:
id: .regex(\d+)
log:
# log the id to the console
- json[0].id
latest_release:
# use the release id to request release details
url: ${BASE_URL}/releases/${releases[0].id}
validation:
status: 200
log:
# log the latest release tag to the console
- json.tag_name
Result:
The examples directory demonstrates further uses of rester. You can also find the output these examples generate in the test snapshot directory.
A few noteworthy examples for common tasks are
github.yml: Use the Github API to fetch and print the latest release version ofrester. Demonstrates the use of response variables and how to index into response arrays and objects as well as how to log responses.multipart.yml: Performs a multipart upload of an image.
The easiest way to run rester is via docker:
docker run --rm -t -v $PWD:/host -w /host finestructure/rester examples/github.yml
It's probably easiest to define an alias:
alias rester="docker run --rm -t -v $PWD:/host -w /host finestructure/rester"
rester examples/basic.yml
A word regarding the docker parameters:
--rmcleans up the container after running-tattaches a tty (this helps with flushing and unicode representation)-v $PWD:/hostmaps your current directory onto/hostinside the container-w /hostsets that/hostdirectory as the working directory inside the container. This way you can simply reference files relative to your working directory and they will be found at the same path inside the container.
Note that if you want to test APIs that are running on localhost, you will also want to add
--network host
to your docker run command. This lets the container run on the host network and allows it to see the host as localhost.
rester requires Swift 5. You can build and install it from source via the Swift Package Manager:
git clone https://github.com/finestructure/rester
cd rester
swift build -c release
On macOS, the easiest way to install and update rester is probably Mint:
brew install mint
mint install finestructure/rester