1. Introduction

This project is a Bash REST API Test framework.

Main goals:

  1. Executable on Termux or through Docker.

Requirements:

  1. Bash 5.

  2. httpie.

  3. jq.

  4. yq.

Tested with the following platforms/ versions:

Ubuntu 22.04
$ lsb_release -a
No LSB modules are available.
Distributor ID: Ubuntu
Description:    Ubuntu 22.04.1 LTS
Release:        22.04
Codename:       jammy

$ echo $BASH_VERSION
5.1.16(1)-release

$ node --version
v16.18.1

$ json-server --version
0.17.1

$ httpie --version
3.2.1

$ jq --version
jq-1.6

$ yq --version
yq (https://github.com/mikefarah/yq/) version v4.30.5

$ docker --version
Docker version 20.10.12, build 20.10.12-0ubuntu4

2. Running a test REST API Server

2.1. Install and start

The following command will install [json-server] in order to run a REST API with the initial database provided by the file db.yaml.

$ ./api-server.sh install

If the file db.json does not exists it will be automatically generated with a call to [reset-db].

To start the server type:

$ ./api-server.sh start

If you need to start the server in a different port, use the variable PORT like in the following example:

$ PORT=7080 ./api-server.sh start

Also, note that you will need to configure the SERVER_PATH before testing.

2.2. Reset database (to the default contents → db.yaml)

$ ./api.server.sh reset-db

2.3. Restart (reset-db and start)

$ ./api-server.sh restart

2.4. Access the server through ngrok

ngrok offers a clever way to access your local environment through a public link on the Internet.

On another shell, start:

$ ./api-server.sh ngrok

Copy the Forwarding link on ngrok interface to configure $SERVER_PATH before calling the script to test the API. Do this as in the example below:

$ export SERVER_PATH=https://7ea6-2804-7f3-858a-41b3-2ad0-69e1-97d6-c01b.sa.ngrok.io
After shutdown the ngrok server, type: unset SERVER_PATH.

3. Testing the REST API

Alternative 1:

$ ./sample-tests.runner.sh

Alternative 2:

$ ./api-test.framework.sh sample-tests.sh

4. Testing the commands above through Docker

Download the docker-termux script:

$ curl -sSL https://raw.githubusercontent.com/paulojeronimo/dotfiles/master/.scripts/docker/docker-termux -o docker-termux
docker-termux was successfuly tested on macOS and Ubuntu 22.04 environments.

Start it:

$ ./docker-termux

Call the termux-setup.sh this way:

$ clone=false . /mnt/bash-api-test/termux-setup.sh

After this you can run the REST API Server and and test the REST API.