⚓ Ballast

Ballast is a tool for snapshot load testing apis.

Introduction

Installation

cargo install ballast

Setup

Create a ballast.json config file in your directory.

{
  "endpoints": [
    {
      "name": "GET test",
      "url":"http://localhost:8080/test",
      "method": "GET",
      "concurrent_requests": 5,
      "cycles": 10,
      "threshold": 100,
      "expected_status": 500,
    },
    {
      "name": "POST test",
      "url":"http://localhost:8080/test",
      "method": "POST",
      "concurrent_requests": 5,
      "cycles": 10,
      "threshold": 100,
      "expected_status": 200,
      "headers": {
        "Content-Type": "application/json"
      },
      "body": {
        "payload": {}
      }
    },
  ]
}

Run

ballast # in the directory with ballast.json

Why?

What is snapshot testing?

Snapshot testing is a commonly used technique for testing UI frameworks such as Jest + React. It involves capturing a "snapshot" of the DOM at a specific point and using it as a reference for comparison after making changes.

How does this apply to APIs?

Applying a similar approach, when running a load test, ballast automatically generates a snapshot of your test. By comparing performance to a snapshot after making changes, API developers can assess how these changes affect performance.

Configuration

Configuring Tests
name: The name you are giving your test.
url: HTTP endpoint you are testing.
method: GET | POST | PUT | DELETE | PATCH | OPTIONS
concurrent_requests: how many concurrent requests to run per testing cycle, you can think of total requests in a test as concurrent_requests * cycles
cycles: number of cycles in a test
threshold: This is the acceptable deviation of average response time for a test to be successful. by default it is 250ms. Response time is used to measure the requests success if all other expected values match.
headers (optional): A map of headings to include on the request
body (optional): some json payload to include in your request
expected_status (optional): the status you're expecting the endpoint to return if it functions correctly
expected_body (optional): the expected response for the endpoint
expected_headers (optional): the expected response headers for the endpoint
ramp (optional): whether or not we should ramp the request up (default true)