Made with ❤︎ by Navendu Pottekkat
What is prawf?
You can use prawf to define tests for your API endpoints and use that definitions to run tests.
Try the Quick Start guide to run prawf without any configurations.
See the docs for additional usage information.
Why use prawf?
Quick Start
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-
prawf init
prawf.json file not found. Would you like to create one? [y/n]? y
INFO[0005] File created. file=prawf.json
INFO[0005] File loaded. file=prawf.json
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-
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-pass path=/posts
INFO[0001] Response received. status code="200 OK"
INFO[0001] [
{
"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"
}
]
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-pass 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] Expected response. contain=yes equal=no keys=no test=pass
INFO[0000] {
"id": 1
} type=contain
Check out the docs for more examples and info on using prawf.
Installation
Create a new directory to download prawf-
mkdir prawf
Download prawf- Go to the releases page to view available downloads.
Replace the URL below with the link to the tar.gz
file for your particular operating system and run the command to download prawf-
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
See the Quick Start guide or the docs to getting started.
Configuring prawf.json
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.
To start, open the prawf.json
file in your project folder. If you do not have a prawf.json
file, run-
prawf init
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
{
"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!"
}
}
}
]
}
}
}
Sending requests
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)
Once you have finished adding your configuration and saved the file, you can run-
prawf run
to start sending requests.
Running tests
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.
Once the configuration is done, run-
prawf test
to start running the test.
Contributing
All contributions are welcome! Please check the Contributing Guidelines to get started.
Join the discussions and let us know what you think!