{"id":13728481,"url":"https://github.com/rednafi/stress-test-locust","last_synced_at":"2025-08-22T00:41:59.044Z","repository":{"id":38333920,"uuid":"292799549","full_name":"rednafi/stress-test-locust","owner":"rednafi","description":"Template for stress testing with Python, Locust \u0026 Docker","archived":false,"fork":false,"pushed_at":"2024-03-01T19:21:37.000Z","size":354,"stargazers_count":47,"open_issues_count":6,"forks_count":12,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-12-28T10:50:32.832Z","etag":null,"topics":["load-testing","locust","locust-docker","locustio","python","stress-testing"],"latest_commit_sha":null,"homepage":"https://github.com/rednafi/stress-test-locust","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rednafi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2020-09-04T08:54:56.000Z","updated_at":"2024-11-11T00:15:01.000Z","dependencies_parsed_at":"2023-02-17T09:46:36.375Z","dependency_job_id":"652da549-f20b-4aa6-94db-d397fff3be5f","html_url":"https://github.com/rednafi/stress-test-locust","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rednafi%2Fstress-test-locust","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rednafi%2Fstress-test-locust/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rednafi%2Fstress-test-locust/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rednafi%2Fstress-test-locust/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rednafi","download_url":"https://codeload.github.com/rednafi/stress-test-locust/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":233360970,"owners_count":18664579,"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":["load-testing","locust","locust-docker","locustio","python","stress-testing"],"created_at":"2024-08-03T02:00:43.156Z","updated_at":"2025-01-10T14:44:53.837Z","avatar_url":"https://github.com/rednafi.png","language":"Python","funding_links":[],"categories":["Templates"],"sub_categories":["Miscellaneous"],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Stress testing with Locust\n\n\u003c/div\u003e\n\n## Description\n\n[Locust] is a distributed and scalable open-source library that helps you write effective\nload tests in pure Python. This repository demonstrates a modular architecture that can work\nas a template for quickly building a scalable stress testing pipeline with Locust.\n\n## Locust terminology\n\nIf you're unfamiliar with the terminologies and the general workflow of stress testing with\nLocust, then I recommend going through the official [documentation] first. With that out of\nthe way, let's rehash a few terminologies that come up in this context quite often:\n\n**Task:** In Locust, a [Task] is the smallest unit of a test suite. Usually, it means, any\nfunction or method that is decorated with the `@task` decorator.\n\n**TaskSet:** A [TaskSet] is a class that establishes a contextual boundary between different\ngroups of Tasks. You can essentially group multiple similar Tasks inside a TaskSet. Then you\nuse the TaskSets from your User class.\n\n**User:** In Locust, a [User] is a class that executes the tests either directly calling the\nTask methods or using TaskSets.\n\n**_In more complex cases, the tests can further be organized by arranging them in multiple\ntest modules. This template groups the Tasks using TaskSets and places multiple TaskSets in\nseparate test modules to achieve better modularity._**\n\n## Target API\n\nHere, we're using [Rapid API]'s currency exchange [API] to showcase the load testing\nprocedure. The API converts one currency to another using the current exchange rate.\n\n### API anatomy\n\nIt takes three parameters in its query string:\n\n```txt\n1. q    : str - quantity\n2. from : str - currency to convert from\n3. to   : str - currency to convert to\n```\n\nAnd returns the converted value.\n\n### Access the API\n\nSign up for a Rapid API [account] and get your token. You can access the API via cURL like\n(You need to provide your API token in the header):\n\n```sh\ncurl --request GET \\\n     --url 'https://currency-exchange.p.rapidapi.com/exchange?q=1.0\u0026from=USD\u0026to=BDT' \\\n     --header 'x-rapidapi-host: currency-exchange.p.rapidapi.com' \\\n     --header 'x-rapidapi-key: your-api-token'\n```\n\nThe response will look like this:\n\n```txt\n84.91925⏎\n```\n\nOr, you might want to access it via Python. You can do so using the [HTTPx] library like\nthis:\n\n```python\nimport httpx\n\nurl = \"https://currency-exchange.p.rapidapi.com/exchange\"\n\nquerystring = {\"q\": \"1.0\", \"from\": \"USD\", \"to\": \"BDT\"}\n\nheaders = {\n    \"x-rapidapi-host\": \"currency-exchange.p.rapidapi.com\",\n    \"x-rapidapi-key\": \"your-api-token\",\n}\n\nwith httpx.Client(http2=True) as client:\n    response = client.get(url, headers=headers, params=querystring)\n\nprint(response.text)\n```\n\n## Stress testing pipeline\n\nBelow, you can see the core architecture of the load testing pipeline. For brevity's sake,\nfiles regarding containerization, deployment, and dependency management have been omitted.\n\n```txt\nsrc/\n├── locustfiles         # Directory where the load test modules live\n│   ├── __init__.py\n│   ├── bdt_convert.py  # Load test module 1\n│   └── rs_convert.py   # Load test module 2\n├── __init__.py\n├── auth.py             # Auth, login, logout, etc\n├── locust.conf         # Locust configurations\n├── locustfile.py       # Locust entrypoint\n└── settings.py         # Read the environment variables here\n```\n\nThe test suite has three primary components: `setup.py`, `locustfiles`, and the\n`locust.conf` file.\n\n### [setup.py](src/setup.py)\n\nThe common elements required for testing, like `auth`, `login`, and `logout` functions\nreside in the `setup.py` file.\n\n### [locustfiles](src/locustfiles/)\n\nThe load test modules reside in the **`locustfiles`** directory. Test modules import and use\nthe functions in the `setup.py` file before executing each test.\n\nIn the `locustfiles` folder, currently, there are only two load test modules—\n`bdt_convert.py` and `rs_convert.py`. You can name your test modules whatever you want as\nlong as the load testing classes and functions reside here.\n\n-   [bdt_convert.py](src/locustfiles/bdt_convert.py): This module houses a single TaskSet\n    named `BDTConvert` that has two Tasks—`usd_to_bdt` and `bdt_to_usd`. The first Task\n    tests the exchange API when the request query asks for USD to BDT currency conversion\n    and the second Task tests the API while requesting BDT to USD conversion.\n\n-   [rs_convert.py](src/locustfiles/rs_convert.py): The second test module does the same\n    things as the first one; only it tests the APIs while the request query asks for USD to\n    RS conversion and vice versa.\n\n    The reason that there are two similar test modules is just to demonstrate how you\n        can organize your Tasks, TaskSets, and test modules.\n\n-   [locustfile.py](src/locustfile.py): This file works as the entrypoint of the workflow.\n    It imports the TaskSets from the `bdt_convert` and `usd_convert` modules and creates a\n    [HttpUser] that will execute the tasks.\n\n### [locust.conf](src/locust.conf)\n\nThe **`locust.conf`** file defines the configurations like _hostname_, _number_ of\n_workers_, _number of simulated users_, _spawn rate_, etc.\n\n## Run the stress tests locally\n\n-   Make sure you have the latest version of [docker] and docker-compose installed on your\n    machine.\n\n-   Clone this repository and go to the root directory.\n\n-   Place your rapidAPI token in the `.env` file.\n\n-   Run:\n\n    ```sh\n    docker compose up -d\n    ```\n\n    This will spin up a master container and a single worker container that will do the\n    testing. If you want to deploy more workers to do the load testing then run:\n\n    ```sh\n    docker compose up -d --scale worker 2\n    ```\n\n-   To access the Locust GUI, go to [http://localhost:8089/] on your browser. You'll be\n    greeted by a screen like below. You should see that the fields of the form are already\n    filled in since Locust pulls the values from the `locust.conf` file:\n\n    ![locust-signin]\n\n-   Once you've pressed the _start swarming_ button, you'll be taken to the following page:\n\n    ![locust-dashboard]\n\n-   You can start, stop, and control your tests from there.\n\n## Disclaimer\n\nThis dockerized application is production-ready. However, you shouldn't expose your\nenvironment file (.env) in production. Here, it was done only for demonstration purposes.\n\n[locust]: https://locust.io/\n[documentation]: https://docs.locust.io/en/stable/\n[task]: https://docs.locust.io/en/stable/writing-a-locustfile.html#tasks\n[taskset]: https://docs.locust.io/en/stable/writing-a-locustfile.html#tasksets\n[user]: https://docs.locust.io/en/stable/writing-a-locustfile.html#user-class\n[rapid api]: https://rapidapi.com/\n[api]: https://rapidapi.com/fyhao/api/currency-exchange\n[account]: https://rapidapi.com/signup\n[httpx]: https://github.com/encode/httpx\n[httpuser]: https://docs.locust.io/en/stable/writing-a-locustfile.html#making-http-requests\n[docker]: https://www.docker.com/\n[http://localhost:8089/]: http://localhost:8089/\n[locust-signin]:\n    https://user-images.githubusercontent.com/30027932/92285103-51988580-ef25-11ea-9155-c9d3f5dcaf42.png\n[locust-dashboard]:\n    https://user-images.githubusercontent.com/30027932/92285284-b94ed080-ef25-11ea-9f91-3f972fd844f1.png\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frednafi%2Fstress-test-locust","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frednafi%2Fstress-test-locust","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frednafi%2Fstress-test-locust/lists"}