Swiftpack.co - Package - finestructure/Rester

Rester

Swift 5 Build Status codecov Twitter: @_sa_s

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:

asciicast

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.

Example request sequence

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:

asciicast

More examples

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 of rester. 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.

Running rester

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:

  • --rm cleans up the container after running
  • -t attaches a tty (this helps with flushing and unicode representation)
  • -v $PWD:/host maps your current directory onto /host inside the container
  • -w /host sets that /host directory 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.

Installing rester

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

Github

link
Stars: 32

Used By

Total: 0

Releases

0.8.0 - 2020-07-03 07:03:55

  • Swift 5.2.4
  • Dependency updates

- 2019-12-20 08:21:57

  • swift 5.1.3
  • package update
  • support for parenthesis in regex: .regex(foo(bar))

- 2019-10-12 11:17:52

  • Swift 5.1.1 (Linux)
  • PMKFoundation 3.3.4
  • ValueCodable 0.1.0

- 2019-10-11 15:32:35

  • swift 5.1 / Xcode 11
  • iOS support
  • request cancellation
  • request count in statistics

0.6.1 - 2019-06-06 12:41:01

  • fix macOS build (debug version for now)

0.6.0 - 2019-06-03 10:02:16

  • Swift 5.0.1 (5.0.x snapshot on Linux)
  • set_up step
  • mode: random|sequential
  • .append(json.value) for variables
  • .remove(json.value) for variables
  • when for conditional execution
  • .doesNotEqual() for negative testing
  • Fixes issue#75 (none response for 401 on Linux)

0.5.0 - 2019-04-10 13:22:43

  • Add --stats flag for logging request statistics

0.4.0 - 2019-04-09 12:59:49

  • --loop and --duration parameters to run Rester continuously
  • switch to official Apple/swift:5.0 docker base image
  • dependency updates

- 2019-04-03 15:02:11

  • --insecure flag to suppress SSL certificate validation
  • dependency updates

- 2019-04-01 13:49:20

  • fixes #39

- 2019-03-29 13:04:14

  • dependency updates
  • swift 5
  • adds --version
  • Fixes #34

- 2019-03-26 08:21:42

  • Fixes #17 (elapsed time display on Linux)

- 2019-03-17 14:30:39

  • cleanup & refactor
  • snapshot testing examples

- 2019-03-15 17:15:27

  • log to file

- 2019-03-15 13:15:01

  • multipart post
  • text post
  • file post
  • better logging in case of errors
  • detailed response logging

- 2019-03-10 17:32:04

  • Fixed #16 (timeout parameter placement)
  • Fixed #10 (warn in case of malformed yml, missing keys)

- 2019-03-10 11:36:39

  • moved Value to external dependency finestructure/ValueCodable
  • now building latest image tags
  • removed wait in main in favour of RunLoop.main.run
  • switched to new array indexing syntax obj[1] instead of obj.1 (old syntax still supported)
  • fixed elapsed time display (#17)

Timeout parameter & timing info - 2019-03-01 16:45:07

  • Add --timeout 5 parameter to set request timeout
  • Show timing info for requests:
🚀  Resting Tests/ResterTests/TestData/basic.yml ...

🎬  basic started ...

✅  basic PASSED (0.011s)

Executed 1 tests, with 0 failures

Log delay - 2019-02-26 06:39:50

Log to the console when a delay is set for a request.

Individual request timeout - 2019-02-22 16:21:16

  • Each request has a 5s (to be configurable) timeout instead of a full job timeout of (number of requests) * 5s.
  • More tests for json array parsing and substitution

Log command - 2019-02-21 16:37:34

Added log: to request definition.

requests:
  get_example:
    url: ${API_URL}/anything
    method: GET
    validation:
      status: 200
    log: true

Also supports partials and key paths:

    log:
      - status
      - json
    log:
      - json.foo.bar

Basic feature set - 2019-02-18 16:12:14

  • GET, POST, PUT, DELETE requests
  • send headers
  • send query parameters
  • form and json body
  • validation
    • status codes
    • json responses
    • headers
  • variable substitution
    • file defined
    • environment defined
  • response referencing
  • file batching (Restfile referencing Restfiles)
  • request delays

Initial release - 2019-01-25 12:49:24