README.md

Clobbr - test your api's response times

Test your api endpoints to see how well they perform under multiple requests (clobber your apis!), in sequence or parallel.

Quick start

Application

Download on the Mac App Store or the Microsoft Store and start testing your api endpoints.

Command Line (cli)

npx @clobbr/cli run --url "https://api.github.com/zen"

Run npx @clobbr/cli to see all options or head over to @clobbr/cli docs.

Binaries are also available for your favorite OS here ⬇️ 💿.

CI/CD

The cli can be used in a CI context too. See examples with popular CIs here ↗️

What the cli can do

This package can stress-test your API endpoints in various ways so you can get a better idea on how your app would work under a (closer to) real world scenario.

Configure requests, set iterations and analyze response times of your API endpoints in a fashionable ascii chart or jaw-dropping table.

On top of that, get stats on responses such as mean, standard deviation, 5th/95th/99th percentiles and more.

With all that, output to various file formats such as csv, json, yaml and more. Use in your CI of choice or just run it locally.

Usage examples for the cli

Kitchen sink example

npx @clobbr/cli run \
  --url "https://api.github.com/zen" \
  --method POST \
  --iterations 50 \
  --parallel \
  --checks mean=200 median=200 stdDev=50 q5=150 q50=200 q95=250 q99=300 pctOfSuccess=95 \
  --headersPath "headers.json" \
  --dataPath "data.json" \
  --outputFile \
  --outputFormat yaml \
  --table "compact"

This is an advanced run configuration example. Typically, less config is needed. Read on for more.

Define iterations

npx @clobbr/cli run \
  --url "https://api.github.com/zen" \
  --iterations 30

Send requests in parallel

npx @clobbr/cli run \
  --url "https://api.github.com/zen" \
  --iterations 30 \
  --parallel

Display a summary table

npx @clobbr/cli run \
  --url "https://api.github.com/zen" \
  --iterations 30 \
  --table "full"

Display a minimal summary table

npx @clobbr/cli run \
  --url "https://api.github.com/zen" \
  --iterations 30 \
  --table "compact"

Customize Request Method

GET is used as the default request method, but you can pass an optional request method, such as POST, PUT, PATCH, DELETE etc.

npx @clobbr/cli run \
  --url "https://api.github.com/zen" \
  --method OPTIONS

Send Headers

Arbitrary request headers are accepted as a JSON file.

Tip 💡

Passing { Cookie: "val" } adds a cookie to the request.

# headers.json
{
  "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.Et9HFtf9R3",
  "User-Agent": "Mozilla/5.0"
}

npx @clobbr/cli run \
  --url "https://api.github.com/zen" \
  --iterations 20 \
  --headersPath "headers.json"

Send Data

Arbitrary request data is accepted as a JSON file.

# data.json
{
  "id": "17b",
  "user": {
    "firstName": "Jane",
    "lastName": "Doe"
  },
  "visits": 50
}

npx @clobbr/cli run \
  --url "https://api.github.com/zen" \
  --iterations 20 \
  --method "POST" \
  --dataPath "data.json"

Analyze failed request iterations

By default, details on failed iterations are neatly displayed via the table option.

npx @clobbr/cli run \
  --url "https://api.github.com/zen" \
  --iterations 20 \
  --method "POST" \
  --headersPath "headers.json" \
  --dataPath "data.json" \
  --table "compact"

Get results in different file formats

Results will be shown in a human-readable format by default, but you can also get results in JSON, YAML and CSV format.

npx @clobbr/cli run \
  --url "https://api.github.com/zen" \
  --outputFormat json                \
  --outputFile

Run checks against results

Set target values for percentage of success (pctOfSuccess), mean (ms), median (ms), standardDeviation (stdDev in ms) and supported quantiles in ms (q5, q50, q95, q99).

npx @clobbr/cli run \
  --url "https://api.github.com/zen" \
  --checks mean=200 median=200 stdDev=50 q5=150 q50=200 q95=250 q99=300 pctOfSuccess=95

Only include checks that you want to run. If you don't specify a check, it will not be run.

npx @clobbr/cli run \
  --url "https://api.github.com/zen" \
  --checks pctOfSuccess=90

---

---

Save 10s of hours of work by using Shipixen to generate a customized codebases with your branding, pages and blog
― then deploy it to Vercel with 1 click.

Shipixen Create a blog & landing page in minutes with Shipixen. Try the app on shipixen.com.

---

Apihustle is a collection of tools to test, improve and get to know your API inside and out.
apihustle.com

	Shipixen	Create a personalized blog & landing page in minutes	shipixen.com
	Page UI	Landing page UI components for React & Next.js	pageui.dev
	Clobbr	Load test your API endpoints.	clobbr.app
	Crontap	Schedule API calls using cron syntax.	crontap.com
	CronTool	Debug multiple cron expressions on a calendar.	tool.crontap.com

---