Quizzical

Quizzical is a command-line utility for the testing and documentation of JSON APIs. Both tests and specs are specified through CURL commands, piped to an assertion checker provided with the criteria defining success.

Installation

To install quizzical or update to the latest version, perform the following command in the terminal.

$ git clone https://github.com/mattneary/Quizzical.git; \
  cd Quizzical/lib; ./install.sh

Testing and Spec Generation

To test a script of curls, run the following.

quizzical tests.sh

To generate docs from the same file, run this, as a function of tests and an output markdown file.

quizzical tests.sh docs.md

Getting Started

Quizzical solves a very specific problem - testing a JSON API with CURL. CURL has a very clear and concise notation for expressing the specifications of an API in docs, etc. Additionally, CURL is a cross-platform standard in HTTP requests. All tests are of the following form.

curl -s http://localhost:8080/api/boards/123 | \
  $assert "board access" success=true

The curl progress dialogues are suppressed with -s, and then the response is piped to the assertion checker script. A name for the test and criteria are passed as arguments. These criteria are assessed on the JSON response, with @ being a special symbol for equality with the entire response, e.g., @={}.

Additionally, if you are curling a raw file, you can specify "#raw" as the criterion and tests will not be checked based on content.