Introduction

prawf run

INFO[0000] File loaded.                                  file=prawf.json
INFO[0000] Running test.                                 test=sample-test url="https://jsonplaceholder.typicode.com"

INFO[0000] Creating request.                             method=GET name=get-post path=/posts
INFO[0000] Response received.                            status code="200 OK"
INFO[0000] [
  {
    "userId": 1,
    "id": 1,
    "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
    "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
  }
] 

INFO[0000] Creating request.                             method=POST name=post-post path=/posts
INFO[0001] Response received.                            status code="201 Created"
INFO[0001] {
  "body": "If you haven't already, check out prawf to test your REST API endpoints",
  "title": "prawf is amazing!",
  "userId": 1,
  "id": 101
}

🧪 prawf is a lightweight and easy-to-use HTTP API testing framework.

You can easily define your tests in a prawf.json file and use the prawf CLI to run tests with it.

Try the Quick Start guide to run prawf without any configurations.

Here are some reasons why you might want to use prawf-

🏋️‍♂️ Lightweight- Does not add any overhead to your software

🧰 Cross platform- Compiled to a binary and works on Windows, Mac and Linux

📝 Declarative tests- Forget all those flags you use to send a request and write your tests in a file

🧱 Structured logs- Get structured logs so you do not have to spend hours debugging

🚰 Built-in CI/CD support- Ship your applications bug free by adding to your CI/CD pipelines

🔓 Free and open-source- It is and it always will be

Quick Start

Create a new prawf.json config file-

prawf init

This will create the file in your current directory-

prawf.json file not found. Would you like to create one? [y/n]? y
INFO[0002] File created.                                 file=prawf.json
INFO[0002] File loaded.                                  file=prawf.json

Default prawf.json file-

{
  "current": "sample-test",
  "tests": {
    "sample-test": {
      "url": "https://jsonplaceholder.typicode.com",
      "methods": [
        {
          "name": "get-post",
          "path": "/posts",
          "method": "get",
          "query": {
            "id": 1
          },
          "expect": {
            "contain": {
              "id": 22
            },
            "keys": [
              "id"
            ],
            "equal": {
              "id": 22
            }
          }
        },
        {
          "name": "post-post",
          "path": "/posts",
          "method": "post",
          "header": {
            "Content-type": "application/json; charset=UTF-8"
          },
          "body": {
            "body": "If you haven't already, check out prawf to test your REST API endpoints",
            "title": "prawf is amazing!",
            "userId": 1
          },
          "expect": {}
        }
      ]
    }
  }
}

Send requests to endpoints specified in the prawf.json file-

prawf run

INFO[0000] File loaded.                                  file=prawf.json
INFO[0000] Running test.                                 test=sample-test url="https://jsonplaceholder.typicode.com"

INFO[0000] Creating request.                             method=GET name=get-post path=/posts
INFO[0000] Response received.                            status code="200 OK"
INFO[0000] [
  {
    "userId": 1,
    "id": 1,
    "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
    "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
  }
] 

INFO[0000] Creating request.                             method=POST name=post-post path=/posts
INFO[0001] Response received.                            status code="201 Created"
INFO[0001] {
  "body": "If you haven't already, check out prawf to test your REST API endpoints",
  "title": "prawf is amazing!",
  "userId": 1,
  "id": 101
}

Test the endpoints as specified in the prawf.json file-

prawf test

INFO[0000] File loaded.                                  file=prawf.json
INFO[0000] Running test.                                 test=sample-test url="https://jsonplaceholder.typicode.com"

INFO[0000] Creating request.                             method=GET name=get-post path=/posts
INFO[0000] Response received.                            status code="200 OK"
INFO[0000] [
  {
    "userId": 1,
    "id": 1,
    "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
    "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
  }
] 

ERRO[0000] Expected response.                            contain=yes equal=yes keys=yes test=fail
ERRO[0000] {
  "id": 22
  }                              type=equal
ERRO[0000] {
  "id": 22
  }                              type=contain
ERRO[0000] [id]                                          type=keys

INFO[0000] Creating request.                             method=POST name=post-post path=/posts
INFO[0001] Response received.                            status code="201 Created"
INFO[0001] {
  "body": "If you haven't already, check out prawf to test your REST API endpoints",
  "title": "prawf is amazing!",
  "userId": 1,
  "id": 101
}

Install prawf- See the Installation guide.
Open up your project folder. If you do have a project yet and is just testing prawf, you can create an empty folder.
Create a new prawf.json config file.

By default, prawf will initialise the prawf.json configuration file with the API endpoints from jsonplaceholder.typicode.com. You can use this for testing out the capabilities of prawf.

Edit the prawf.json configuration file if you are testing a custom application. You can leave it as it is if you are just testing out prawf. See Configuring prawf.json for more details.
Send requests to endpoints specified in the prawf.json file.
Test the endpoints as specified in the prawf.json file.

Installation

Create a new directory to download prawf-

mkdir prawf

Download prawf (Available downloads). Replace the URL below with the URL to the tar.gz file you require-

curl -OL https://github.com/prawf/prawf-cli/releases/latest/download/prawf_0.0.1-alpha_Linux_x86_64.tar.gz

Extract the package. Replace the file name with the filename of your download-

tar -xvzf prawf_0.0.1-alpha_Linux_x86_64.tar.gz

Add prawf to your path(Linux, macOS)-

export PATH=$PWD:$PATH

Check your installation-

prawf version

prawf is available on Windows, Mac and Linux. Check the releases for a list of available downloads.

See the Quick Start guide to get started.

Configuring Tests

To start, open the prawf.json file in your project folder. If you do not have a prawf.json file, run-

prawf init

The prawf.json config file will contain all your tests. You can define tests by specifying the endpoints request details and provide the expected responses to test with.

See the Quick Start guide for more details on getting started.

Once you have the prawf.json file initialised, open it on a text editor.

Available Configurations

The following could be configured in the prawf.json file. See the example below-

current- Represents the focused test. Users can define multiple tests and the test mentioned in current will be used for running tests.

tests - Array of tests. Users can define multiple tests here with a test name as mentioned below.

test-name- Name of the test. Its value contains the test.

url- The URL the current test is interested in.

methods- Array of methods to test the URL on.

name- Name of the method.

path- The path which will be added to the URL.

method- Type of HTTP request.

query- The query to add to the request.

header- The header to add to the request.

body- The body to add to the request.

expect- Represents what to look for in the response for testing.

keys- To check if the keys mentioned are present in the response.

contain- To check if the key-value pairs are present in the response.

equal- To check if the response if exactly equal to the present value.

Example prawf.json file

An example json file created when you run prawf init

{
  "current": "sample-test",
  "tests": {
    "sample-test": {
      "url": "https://jsonplaceholder.typicode.com",
      "methods": [
        {
          "name": "get-pass",
          "path": "/posts",
          "method": "get",
          "query": {
            "id": 1
          },
          "expect": {
            "contain": {
              "id": 1
            }
          }
        },
        {
          "name": "get-fail",
          "path": "/posts",
          "method": "get",
          "query": {
            "id": 3
          },
          "expect": {
            "keys": [
              "uuid"
            ]
          }
        },
        {
          "name": "post-pass",
          "path": "/posts",
          "method": "post",
          "header": {
            "Content-type": "application/json; charset=UTF-8"
          },
          "body": {
            "body": "If you haven't already, check out prawf to test your REST API endpoints",
            "title": "prawf is amazing!",
            "userId": 1
          },
          "expect": {
            "equal": {
              "body": "If you haven't already, check out prawf to test your REST API endpoints",
              "title": "prawf is amazing!",
              "userId": 1
            }
          }
        },
        {
          "name": "put-pass",
          "path": "/posts/1",
          "method": "put",
          "header": {
            "Content-type": "application/json; charset=UTF-8"
          },
          "body": {
            "body": "Give us a star on GitHub/prawf!",
            "id": 1,
            "title": "prawf is awesome!",
            "userId": 1
          },
          "expect": {
            "contain": {
              "title": "prawf is awesome!"
            }
          }
        }
      ]
    }
  }
}

This is an example prawf.json config file that is generated when you run prawf init.

You can use this config file as a template to write your own tests.

Sending Requests

Once you have finished adding your configuration and saved the file, you can run-

prawf run

Using prawf, you can send requests to your API endpoints and view the responses.

You can configure your endpoint URLs, paths and methods on your prawf.json file. (See Available Configurations)

Running tests

Once the configuration is done, run-

prawf test

You can also automate the testing process by declaring it in the prawf.json file. (See Available Configurations)

These tests will be run automatically and structured logs will printed on the screen.

Contributing

Thank you for your interest in contributing to prawf!

📃 🐛 💡 ⚙️ Contributions of any kind are welcome here! It could be changes to documentation, reporting bugs, requesting for features and also contributing code.

Before you start, please go through the Code of Conduct.

All changes are made through pull requests. Please check the GithHub Flow

We use discussions for communicating. Please use it to share your ideas.

To report bugs and track features, we use issues. Please use the appropriate issue template while creating a new issue.

The docs are built in a separate repository. Any changes to the docs should be made there.

Setting up the development environment

Fork this repo and clone your fork to your local machine-

git clone https://github.com/<your-user-name>/prawf-cli.git

Or

gh repo clone <your-user-name>/prawf-cli

Inside the repo run-

make

You can then run-

./prawf <name of the command>

prawf-cli is written in Golang.

To run the development environment, you should install the latest version of Go. See their downloads page.