{"id":28198020,"url":"https://github.com/synoet/ballast","last_synced_at":"2025-05-16T17:17:26.215Z","repository":{"id":171833000,"uuid":"648475260","full_name":"synoet/ballast","owner":"synoet","description":"⚓ a simple api load testing tool that lets you compare performance snapshots of your api.","archived":false,"fork":false,"pushed_at":"2024-10-04T22:34:34.000Z","size":313,"stargazers_count":39,"open_issues_count":3,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-05T00:46:17.559Z","etag":null,"topics":["api","api-rest","cli","load-testing","rust","snapshot-testing","testing"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/ballast","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/synoet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-02T04:02:36.000Z","updated_at":"2025-04-10T16:36:28.000Z","dependencies_parsed_at":"2024-01-23T14:13:37.012Z","dependency_job_id":null,"html_url":"https://github.com/synoet/ballast","commit_stats":null,"previous_names":["synoet/ballast"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synoet%2Fballast","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synoet%2Fballast/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synoet%2Fballast/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synoet%2Fballast/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/synoet","download_url":"https://codeload.github.com/synoet/ballast/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254573547,"owners_count":22093732,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-rest","cli","load-testing","rust","snapshot-testing","testing"],"created_at":"2025-05-16T17:17:20.592Z","updated_at":"2025-05-16T17:17:26.205Z","avatar_url":"https://github.com/synoet.png","language":"Rust","funding_links":[],"categories":["\u003ca name=\"webdev\"\u003e\u003c/a\u003eWeb development"],"sub_categories":[],"readme":"\n# ⚓ Ballast  \nBallast is a tool for snapshot load testing apis.\n\n![output](https://github.com/synoet/ballast/assets/10552019/498c9ada-4d55-4074-8f82-d6c32c6f558b)\n\n\n\n## Introduction\n#### Installation\n```bash\ncargo install ballast\n```\n\n#### Setup\nCreate a `ballast.json` config file in your directory.\n```json\n{\n  \"endpoints\": [\n    {\n      \"name\": \"GET test\",\n      \"url\":\"http://localhost:8080/test\",\n      \"method\": \"GET\",\n      \"concurrent_requests\": 5,\n      \"cycles\": 10,\n      \"threshold\": 100,\n      \"expected_status\": 500,\n    },\n    {\n      \"name\": \"POST test\",\n      \"url\":\"http://localhost:8080/test\",\n      \"method\": \"POST\",\n      \"concurrent_requests\": 5,\n      \"cycles\": 10,\n      \"threshold\": 100,\n      \"expected_status\": 200,\n      \"headers\": {\n        \"Content-Type\": \"application/json\"\n      },\n      \"body\": {\n        \"payload\": {}\n      }\n    },\n  ]\n}\n```\n\n#### Run\n```bash\nballast # in the directory with ballast.json\n```\n\n## Why?\n**What is snapshot testing?**\n\nSnapshot 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.\n\n**How does this apply to APIs?**\n\nApplying 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.\n\n## Configuration\n**Configuring Tests**   \n`name`: The name you are giving your test.   \n`url`: HTTP endpoint you are testing.   \n`method`: `GET` | `POST` | `PUT` | `DELETE` | `PATCH` | `OPTIONS`   \n`concurrent_requests`: how many concurrent requests to run per testing cycle, you can think of total requests in a test as `concurrent_requests * cycles`   \n`cycles`: number of cycles in a test   \n`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.   \n`headers` *(optional)*: A map of headings to include on the request   \n`body` *(optional)*: some json payload to include in your request   \n`expected_status` *(optional)*: the status you're expecting the endpoint to return if it functions correctly   \n`expected_body` *(optional)*: the expected response for the endpoint   \n`expected_headers` *(optional)*: the expected response headers for the endpoint   \n`ramp` *(optional)*: whether or not we should ramp the request up (default true)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsynoet%2Fballast","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsynoet%2Fballast","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsynoet%2Fballast/lists"}