[ { "path": ".dockerignore", "content": "locust.egg-info/**\nlocustio.egg-info/**\nbuild/\n.coverage\ndocs/_build\n# Dockerfile # We'd like to ignore this, but it messes up scm_version's detection because it thinks the checkout is dirty\n" }, { "path": ".git-blame-ignore-revs", "content": "# Migrate code style to Black\n7c0fcc213d3988f6e7c6ffef63b24afe00e5fbd9\n2e7a8b5697a98d1d314d6fc3ef0589f81f09d7fe\n# upgrade code style to 3.6 using pyupgrade\n6ec972f4dbb880bf0c7a11809e6c1ba194c9784c\n# upgrade code style to use f-strings using flynt\n313b80f27f525441c449593a3aeaf38389f63c13\n# upgrade typing annotations using fix-future-annotations\nb5324820b299b1fe7da0608f0cc8ec47f58b1e40\n# upgrade code style to 3.8 using pyupgrade\n60f3bceacc4ab9567433d40ae3ed280750f55ff1\n# sort imports using ruff\nf99e9df700a8020e4c1967eb42dcb37ddd26e296\n# apply ruff 0.3.0\n64428a0b4dfc75a00b175b4231db33704d8f5d36\n# apply ruff 0.10.0\n92268e16d5666d429ccea1742ecb90475f284c89\n496c5bd40347b97f917ccacfaf57ceed8f6690b5\n" }, { "path": ".gitattributes", "content": "# Set default behaviour, in case users don't have core.autocrlf set.\n* text=auto\n\n# Explicitly declare text files we want to always be normalized and converted \n# to native line endings on checkout.\n*.c text\n*.h text\n*.py text\n*.js text\n*.rst text\n*.css text\n*.html text\n\n# Declare files that will always have CRLF line endings on checkout.\n*.sln text eol=crlf\n\n# Denote all files that are truly binary and should not be modified.\n*.png binary\n*.jpg binary\n*.gif binary\n" }, { "path": ".github/CONTRIBUTING.md", "content": "## Release Process\n\n * Install github_changelog_generator (https://github.com/github-changelog-generator/github-changelog-generator/) if not installed \n * Run github_changelog_generator to update `CHANGELOG.md`\n - `make changelog`\n * Update `locust/__init__.py` with new version number: `__version__ = \"VERSION\"`\n * Make git tag\n * Push git tag\n * Update Automated Builds configuration in Docker Hub so that the newly created \n git tag is built as the \"latest\" docker tag\n" }, { "path": ".github/ISSUE_TEMPLATE/bug.yml", "content": "name: Bug\ndescription: Report an error\nlabels: [\"bug\"]\nbody:\n - type: checkboxes\n attributes:\n label: Prerequisites\n options:\n - label: I am using [the latest version of Locust](https://github.com/locustio/locust/releases/)\n required: true\n - label: I am reporting a bug, not asking a question\n required: true\n\n - type: markdown\n attributes:\n value: |\n If you just need help with something, then:\n\n * [Check the documentation](https://docs.locust.io/en/stable/)\n * [Check the FAQ in the wiki](https://github.com/locustio/locust/wiki/FAQ) \n * [Check the Github Discussions](https://github.com/orgs/locustio/discussions) \n * Search [Stack Overflow](https://stackoverflow.com/questions/tagged/locust), or [ask there](https://stackoverflow.com/questions/ask) yourself. If you tag your question with `locust` we will see it.\n * Ask on [Locust's slack](https://locustio.slack.com) [(sign up here)](https://communityinviter.com/apps/locustio/locust)\n\n - type: textarea\n attributes:\n label: Description\n description: What happened, and what did you want/expect to happen?\n validations:\n required: true\n\n - type: input\n attributes:\n label: Command line\n description: |\n For example: locust -f mylocustfile.py -t 10s --headless\n validations:\n required: true\n\n - type: textarea\n attributes:\n label: Locustfile contents\n description: Please remove everything that isn't necessary to trigger the issue.\n render: python3\n validations:\n required: true\n\n - type: input\n attributes:\n label: Python version\n validations:\n required: true\n\n - type: input\n attributes:\n label: Locust version\n validations:\n required: true\n\n - type: input\n attributes:\n label: Operating system\n validations:\n required: true\n" }, { "path": ".github/ISSUE_TEMPLATE/config.yml", "content": "blank_issues_enabled: false\n" }, { "path": ".github/ISSUE_TEMPLATE/feature_request.yml", "content": "name: Feature request\ndescription: Suggest an improvement\nlabels: [\"feature request\"]\nbody:\n - type: checkboxes\n attributes:\n label: Prerequisites\n options:\n - label: I am using [the latest version of Locust](https://github.com/locustio/locust/releases/)\n required: true\n - label: I am suggesting a new feature, not asking a question\n required: true\n\n - type: markdown\n attributes:\n value: |\n If you just need help with something, then:\n\n * [Check the documentation](https://docs.locust.io/en/stable/)\n * [Check the FAQ in the wiki](https://github.com/locustio/locust/wiki/FAQ) \n * [Check the Github Discussions](https://github.com/orgs/locustio/discussions) \n * Search [Stack Overflow](https://stackoverflow.com/questions/tagged/locust), or [ask there](https://stackoverflow.com/questions/ask) yourself. If you tag your question with `locust` we will see it.\n * Ask on [Locust's slack](https://locustio.slack.com) [(sign up here)](https://communityinviter.com/apps/locustio/locust)\n\n - type: textarea\n attributes:\n label: Description\n description: Describe what feature you are missing, and what alternatives you have considered.\n validations:\n required: true\n" }, { "path": ".github/dependabot.yaml", "content": "version: 2\n\nupdates:\n - package-ecosystem: github-actions\n directory: /\n schedule:\n interval: semiannually\n groups:\n all_dependencies:\n patterns:\n - \"*\"\n\n - package-ecosystem: uv\n directory: /\n schedule:\n interval: semiannually\n\n - package-ecosystem: npm\n directory: /locust/webui\n schedule:\n interval: semiannually\n groups:\n eslint:\n patterns:\n - \"*eslint*\"\n vite:\n patterns:\n - \"*vite*\"\n react:\n patterns:\n - \"*react*\"\n emotion:\n patterns:\n - \"*emotion*\"\n mui:\n patterns:\n - \"*mui*\"\n" }, { "path": ".github/workflows/stale.yml", "content": "name: Mark stale issues\n\non:\n schedule:\n - cron: \"30 1 * * *\"\n workflow_dispatch:\n\npermissions:\n contents: read\n\njobs:\n stale:\n permissions:\n issues: write # for actions/stale to close stale issues\n pull-requests: write # for actions/stale to close stale PRs\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/stale@v10\n with:\n repo-token: ${{ secrets.GITHUB_TOKEN }}\n stale-issue-message: \"This issue is stale because it has been open 60 days with no activity. Remove stale label or comment or this will be closed in 20 days.\"\n close-issue-message: \"This issue was closed because it has been marked stale for 20 days with no activity. This does not necessarily mean that the issue is bad, but it most likely means that nobody is willing to take the time to fix it. If you have found Locust useful, then consider contributing a fix yourself!\"\n stale-pr-message: \"This PR is stale because it has been open 60 days with no activity. Remove stale label or comment or this will be closed in 20 days.\"\n close-pr-message: \"This PR was closed because it has been marked stale for 20 days with no activity.\"\n days-before-close: 20\n" }, { "path": ".github/workflows/tests.yml", "content": "name: Tests\n\non:\n push:\n branches:\n - master\n tags:\n - \"*\"\n paths-ignore:\n - \"**.md\"\n pull_request:\n paths-ignore:\n - \"**.md\"\n\npermissions:\n contents: read\n\ndefaults:\n run:\n shell: bash\n\njobs:\n #-------------------------\n # Building\n #-------------------------\n\n build_package:\n name: Build and Cache Packages\n runs-on: ubuntu-latest\n outputs:\n tag: ${{ steps.set_tag.outputs.tag }}\n tag_short: ${{ steps.set_tag_short.outputs.tag_short }}\n branch: ${{ steps.set_branch.outputs.branch }}\n is_merge_commit: ${{ steps.set_is_merge_commit.outputs.is_merge_commit }}\n is_tag_build: ${{ steps.set_is_tag_build.outputs.is_tag_build }}\n python_version: ${{ steps.set_python_version.outputs.python_version }}\n\n steps:\n - uses: actions/checkout@v6\n with:\n fetch-depth: 0\n fetch-tags: true\n\n - uses: actions/setup-python@v6\n with:\n python-version: \"3.11\"\n\n - uses: astral-sh/setup-uv@v7\n with:\n version: \"0.9.7\"\n enable-cache: true\n cache-dependency-glob: |\n \"pyproject.toml\"\n \"uv.lock\"\n\n - run: uv venv\n\n # # ensure uv.lock doesnt contain anything not in pyproject.toml\n # - run: uv lock --check\n\n - name: Install the project\n run: uv sync\n\n # any local changes would make hatch-vcs set a \"local version\" (+dev0...), so we ignore any uv.lock updates:\n - run: git update-index --assume-unchanged uv.lock\n\n # Install node and yarn in order to build the front end during packaging\n - name: Set Node.js 22.x\n uses: actions/setup-node@v6\n with:\n node-version: 22.x\n cache: \"yarn\"\n cache-dependency-path: locust/webui/yarn.lock\n\n # Build and upload the project artifacts only once\n - name: Build Python project and front end\n run: uv build\n\n - name: Upload Python dist as Artifact\n uses: actions/upload-artifact@v7\n with:\n name: python-dist\n path: dist/*\n\n - name: Upload Web UI as Artifact\n uses: actions/upload-artifact@v7\n with:\n name: webui-dist\n path: locust/webui/dist/*\n\n - name: Build UI library\n run: yarn webui:build:lib\n\n - name: Upload web UI library as Artifact\n uses: actions/upload-artifact@v7\n with:\n name: webui-lib-dist\n path: locust/webui/lib\n\n # Set workflow metadata in one place so we can pull it out later\n - id: set_tag\n run: echo \"tag=$(uv run hatch version)\" | tee -a \"$GITHUB_OUTPUT\"\n - id: set_tag_short\n run: echo \"tag_short=$(uv run hatch version | cut -d '.' -f1-3)\" | tee -a \"$GITHUB_OUTPUT\"\n - id: set_branch\n run: echo \"branch=${{ github.head_ref || github.ref_name }}\" | tee -a \"$GITHUB_OUTPUT\"\n - id: set_is_merge_commit\n run: echo \"is_merge_commit=$( [ $(git rev-list --count $GITHUB_SHA^@) -eq 2 ] && echo 'true' || echo 'false' )\" | tee -a \"$GITHUB_OUTPUT\"\n - id: set_is_tag_build\n run: echo \"is_tag_build=${{ startsWith(github.event.ref, 'refs/tags') }}\" | tee -a \"$GITHUB_OUTPUT\"\n - id: set_python_version\n run: echo \"python_version=$(python -VV | sha256sum | cut -d' ' -f1)\" | tee -a \"$GITHUB_OUTPUT\"\n\n print_metadata:\n name: Display metadata for build\n runs-on: ubuntu-latest\n needs: build_package\n steps:\n - run: |\n echo \"tag: ${{ needs.build_package.outputs.tag }}\"\n echo \"tag_short: ${{ needs.build_package.outputs.tag_short }}\"\n echo \"branch: ${{ needs.build_package.outputs.branch }}\"\n echo \"is_merge_commit: ${{ needs.build_package.outputs.is_merge_commit }}\"\n echo \"is_tag_build: ${{ needs.build_package.outputs.is_tag_build }}\"\n echo \"python_version: ${{ needs.build_package.outputs.python_version }}\"\n\n #-------------------------\n # Testing\n #-------------------------\n\n tests:\n name: ${{ matrix.name }}\n runs-on: ${{ matrix.os }}\n needs: build_package\n\n strategy:\n fail-fast: false\n matrix:\n include:\n # Static analysis and utilities\n - {\n name: \"Ruff\",\n python: \"3.12\",\n os: ubuntu-latest,\n group: \"lint\",\n env: \"lint:format\",\n }\n - {\n name: \"Mypy\",\n python: \"3.12\",\n os: ubuntu-latest,\n group: \"lint\",\n env: \"lint:types\",\n }\n\n # Verification of builds and other aspects\n - {\n name: \"Docs Build\",\n python: \"3.12\",\n os: ubuntu-latest,\n group: \"docs\",\n env: \"docs:build\",\n }\n\n # OS Integration tests\n - {\n name: \"Linux\",\n python: \"3.12\",\n os: ubuntu-latest,\n group: \"test\",\n env: \"integration_test_ci:fail_fast\",\n }\n - {\n name: \"Windows\",\n python: \"3.12\",\n os: windows-latest,\n group: \"test\",\n env: \"integration_test_ci:fail_fast\",\n }\n - {\n name: \"Linux_pytest_locustfile\",\n python: \"3.12\",\n os: ubuntu-latest,\n group: \"test\",\n env: \"integration_test_ci:test_pytest\",\n }\n # MacOS behaves super badly on GH actions right now, so let's disable it for the time being\n # - { name: \"MacOS\", python: '3.12', os: macos-latest, group: \"test\", env: \"integration_test_ci:fail_fast\" }\n\n # Unit tests on Python versions\n - {\n name: \"Python 3.14\",\n python: \"3.14\",\n os: ubuntu-latest,\n group: \"test\",\n env: \"test:all\",\n }\n - {\n name: \"Python 3.13\",\n python: \"3.13\",\n os: ubuntu-latest,\n group: \"test\",\n env: \"test:all\",\n }\n - {\n name: \"Python 3.12\",\n python: \"3.12\",\n os: ubuntu-latest,\n group: \"test\",\n env: \"test:all\",\n }\n - {\n name: \"Python 3.11\",\n python: \"3.11\",\n os: ubuntu-latest,\n group: \"test\",\n env: \"test:all\",\n }\n - {\n name: \"Python 3.10\",\n python: \"3.10\",\n os: ubuntu-latest,\n group: \"test\",\n env: \"test:all\",\n }\n\n steps:\n - uses: actions/checkout@v6\n with:\n fetch-depth: 0\n\n - uses: actions/setup-python@v6\n with:\n python-version: ${{ matrix.python }}\n\n - uses: astral-sh/setup-uv@v7\n with:\n version: \"0.9.7\"\n enable-cache: true\n cache-dependency-glob: |\n \"pyproject.toml\"\n \"uv.lock\"\n\n - run: uv venv --python ${{ matrix.python }}\n\n # Install what we need to run hatch envs but not the project itself\n - name: Install CI dependencies\n run: uv sync --group ${{ matrix.group }} --no-install-package locust\n\n # Grab the built artifacts to ensure we're testing what we eventually publish\n - name: Download Python dist\n uses: actions/download-artifact@v8\n with:\n name: python-dist\n path: dist\n\n - name: Download WebUI dist\n uses: actions/download-artifact@v8\n with:\n name: webui-dist\n path: locust/webui/dist\n\n - name: Run tests\n run: uv run --group ${{ matrix.group }} hatch run +py=${{ matrix.python }} ${{ matrix.env }}\n\n test_docker_image:\n name: Test Docker Image\n runs-on: ubuntu-latest\n needs: build_package\n\n steps:\n - uses: actions/checkout@v6\n with:\n fetch-depth: 0\n\n # Grab the built artifacts to ensure we're testing what we eventually publish\n - name: Download Python dist\n uses: actions/download-artifact@v8\n with:\n name: python-dist\n path: dist\n\n # Set up Docker daemon dependencies for building and publishing\n - name: Set up QEMU\n uses: docker/setup-qemu-action@v3\n - name: Set up Docker Buildx\n uses: docker/setup-buildx-action@v3\n\n # Build and load Docker image to the local daemon\n - name: Build and push\n uses: docker/build-push-action@v6\n with:\n context: .\n file: ./Dockerfile.ci\n platforms: linux/amd64\n load: true\n tags: locustio/locust:${{ github.sha }}-test\n\n # Run a basic test on the image\n - name: Test docker image\n run: |\n docker run --rm locustio/locust:${{ github.sha }}-test --version\n\n test_webui:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v6\n - uses: actions/setup-node@v6\n with:\n node-version: 22.x\n cache: \"yarn\"\n cache-dependency-path: locust/webui/yarn.lock\n - name: yarn install\n uses: borales/actions-yarn@v5\n with:\n cmd: install\n dir: locust/webui\n - name: yarn build\n uses: borales/actions-yarn@v5\n with:\n cmd: build\n dir: locust/webui\n - name: yarn test\n uses: borales/actions-yarn@v5\n with:\n cmd: test\n dir: locust/webui\n - name: yarn lint\n uses: borales/actions-yarn@v5\n with:\n cmd: lint\n dir: locust/webui\n - name: yarn type-check\n uses: borales/actions-yarn@v5\n with:\n cmd: type-check\n dir: locust/webui\n\n # -------------------------\n # Publishing\n # -------------------------\n\n publish-docker:\n needs: [tests, test_webui, test_docker_image, build_package]\n if: github.repository_owner == 'locustio' && ( github.ref == 'refs/heads/master' || startsWith(github.event.ref, 'refs/tags') )\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v6\n with:\n fetch-depth: 0\n\n # Download Python dist artifact\n - name: Download Python dist\n uses: actions/download-artifact@v8\n with:\n name: python-dist\n path: dist\n\n # Download Web UI lib artifact\n - name: Download UI lib\n uses: actions/download-artifact@v8\n with:\n name: webui-lib-dist\n path: locust/webui/lib\n\n # Staged docker builds using exports/artifacts is currently difficult using multi-arch builds with buildx\n # So let's just build it here\n\n # Set docker image and tag values\n - name: Docker meta\n id: docker_meta\n uses: docker/metadata-action@v5\n with:\n images: locustio/locust\n tags: |\n type=raw,value=latest,enable=${{ needs.build_package.outputs.is_tag_build }}\n type=raw,value=${{ needs.build_package.outputs.tag }}\n type=raw,value=${{ needs.build_package.outputs.branch }}\n\n - uses: docker/login-action@v3\n with:\n username: locustbuild\n password: ${{ secrets.DOCKER_HUB_ACCESS_TOKEN }}\n - name: Set up QEMU\n uses: docker/setup-qemu-action@v3\n - name: Set up Docker Buildx\n uses: docker/setup-buildx-action@v3\n\n - name: Build and (optionally) push docker image\n uses: docker/build-push-action@v6\n with:\n context: .\n file: ./Dockerfile.ci\n platforms: linux/amd64,linux/arm64\n push: ${{ github.event_name != 'pull_request' }}\n tags: ${{ steps.docker_meta.outputs.tags }}\n\n publish-pypi:\n needs: [tests, test_webui, test_docker_image, build_package]\n if: github.repository_owner == 'locustio' && ( github.ref == 'refs/heads/master' || startsWith(github.event.ref, 'refs/tags') )\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v6\n with:\n fetch-depth: 0\n\n # Download Python dist artifact\n - name: Download Python dist\n uses: actions/download-artifact@v8\n with:\n name: python-dist\n path: dist\n\n # Download Web UI lib artifact\n - name: Download UI lib\n uses: actions/download-artifact@v8\n with:\n name: webui-lib-dist\n path: locust/webui/lib\n\n - name: Publish to PyPI\n uses: pypa/gh-action-pypi-publish@release/v1\n with:\n user: __token__\n password: ${{ secrets.PYPI_API_TOKEN }}\n skip-existing: true\n\n - name: yarn install\n uses: borales/actions-yarn@v5\n with:\n cmd: install\n dir: locust/webui\n\n # Set pre-release version\n - name: yarn version\n uses: borales/actions-yarn@v5\n if: github.ref == 'refs/heads/master'\n with:\n cmd: version ${{ needs.build_package.outputs.tag_short }}-next-${{ github.run_id }}\n dir: locust/webui\n\n # Set tag build version\n - name: yarn version\n uses: borales/actions-yarn@v5\n if: startsWith(github.event.ref, 'refs/tags')\n with:\n cmd: version ${{ github.ref_name }}\n dir: locust/webui\n\n - name: yarn config\n uses: borales/actions-yarn@v5\n with:\n cmd: config set npmAuthToken ${{ secrets.NPM_AUTH_TOKEN }}\n dir: locust/webui\n\n # Publish UI lib\n - uses: borales/actions-yarn@v5\n name: Publish package on NPM\n if: github.ref == 'refs/heads/master'\n with:\n cmd: npm publish --tag next\n dir: locust/webui\n\n # On tag builds\n - uses: borales/actions-yarn@v5\n name: Publish package on NPM\n if: startsWith(github.event.ref, 'refs/tags')\n with:\n cmd: npm publish\n dir: locust/webui\n" }, { "path": ".gitignore", "content": "*.pyc\nlocust.wpr\nlocust.egg-info/**\nlocustio.egg-info/**\nlocust/_version.py\nlocust/test/mock_*.py\ndocs/_build/**\ndocs/cli-help-output.txt\ndocs/config-options.rst\nmock.*.egg\nweb_test_*.csv\nerr.txt\nout.txt\n.eggs/\ndist/**\n.idea/**\n*.iml\n*.ipr\n.vagrant\nbuild/\n.coverage\ndocs/env-options.rst\n.editorconfig\n__pycache__\n.pytest_cache\n.sass-cache/\n.env\nyarn-error.log\n.venv\n.DS_Store\n.python-version\nlocust/webui/dist/**\n.coverage*" }, { "path": ".pre-commit-config.yaml", "content": "repos:\n - repo: https://github.com/astral-sh/ruff-pre-commit\n # Ruff version.\n rev: v0.10.0 # Pin the same version in the pyproject.toml file\n hooks:\n # Run the linter.\n - id: ruff\n args: [--fix]\n # Run the formatter.\n - id: ruff-format\n - repo: local\n hooks:\n - id: yarn-lint\n name: yarn lint\n files: ^locust/webui/\n entry: bash -c \"cd locust/webui && yarn lint\"\n language: system\n pass_filenames: false\n" }, { "path": ".readthedocs.yaml", "content": "version: 2\n\n# Set the version of Python and other tools you might need\nbuild:\n os: ubuntu-22.04\n tools:\n python: \"3.12\"\n jobs:\n post_checkout:\n - git fetch --unshallow || true\n post_install:\n - python -m pip install uv\n - SKIP_PRE_BUILD=true UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH uv sync --group docs\n\nsphinx:\n configuration: docs/conf.py\n" }, { "path": ".vscode/extensions.json", "content": "{\n \"recommendations\": [\n \"charliermarsh.ruff\",\n \"ms-python.mypy-type-checker\"\n ]\n}" }, { "path": ".vscode/launch.json", "content": "{\n \"version\": \"0.2.0\",\n \"configurations\": [\n {\n \"name\": \"Run current file\",\n \"type\": \"debugpy\",\n \"request\": \"launch\",\n \"program\": \"${file}\",\n \"console\": \"integratedTerminal\",\n \"gevent\": true\n },\n {\n \"name\": \"Run current locust scenario headless\",\n \"type\": \"debugpy\",\n \"request\": \"launch\",\n \"module\": \"locust\",\n \"args\": [\n \"-f\",\n \"${file}\",\n \"--headless\",\n \"--users=5\"\n ],\n \"console\": \"integratedTerminal\",\n \"gevent\": true\n },\n {\n \"name\": \"Run current locust scenario, autostart\",\n \"type\": \"debugpy\",\n \"request\": \"launch\",\n \"module\": \"locust\",\n \"args\": [\n \"-f\",\n \"${file}\",\n \"--users=5\",\n \"--autostart\",\n \"--print-stats\",\n \"-L=ERROR\"\n ],\n \"console\": \"integratedTerminal\",\n \"gevent\": true\n },\n {\n \"name\": \"(test debug only)\",\n \"type\": \"debugpy\",\n \"request\": \"launch\",\n \"gevent\": true,\n \"purpose\": [\"debug-test\"]\n }\n ]\n}" }, { "path": ".vscode/launch_locust.json", "content": "{\n \"version\": \"0.2.0\",\n \"configurations\": [\n {\n \"name\": \"Locust: 5 users, with specific config file\",\n \"type\": \"python\",\n \"request\": \"launch\",\n \"module\": \"locust\",\n \"args\": [\n \"-f\",\n \"${file}\",\n \"--headless\",\n \"--users=5\",\n \"--config=${fileDirname}/../locust.conf\"\n ],\n \"console\": \"integratedTerminal\",\n \"gevent\": true\n }\n ]\n}" }, { "path": ".vscode/settings.json", "content": "{\n \"editor.formatOnSave\": true,\n \"files.exclude\": {\n \".pytest_cache/**/*\": true,\n \"**/*.pyc\": true,\n \"**/locust.wpr\": true,\n \"locust.egg-info/**\": true,\n \"locustio.egg-info/**\": true,\n \"docs/_build/**\": true,\n \"docs/cli-help-output.txt\": true,\n \"docs/config-options.rst\": true,\n \"**/mock.*.egg\": true,\n \"dist/**\": true,\n \".idea/**\": true,\n \"**/*.iml\": true,\n \"**/*.ipr\": true,\n \"**/.vagrant\": true,\n \"**/build/\": true,\n \"**/.coverage\": true,\n \"**/.tox/\": true,\n \"docs/env-options.rst\": true,\n \"**/.editorconfig\": true,\n \"**/__pycache__\": true,\n \"locust/_version.py\": true,\n \"**/web_test_*.csv\": true,\n \"**/.eggs/\": true,\n \"**/.pytest_cache\": true,\n \"**/.sass-cache/\": true,\n \"locust/contrib/.mypy_cache/**/*\": true,\n \"locust/user/.mypy_cache/**/*\": true,\n \"**/.mypy_cache\": true,\n \"**/.ruff_cache\": true,\n \"locust/test/mock_*.py\": true,\n \"**/err.txt\": true,\n \"**/out.txt\": true,\n \"**/.venv\": true\n },\n \"restructuredtext.confPath\": \"${workspaceFolder}/docs\",\n \"[python]\": {\n \"editor.formatOnSave\": true,\n \"editor.codeActionsOnSave\": {\n \"source.fixAll\": \"explicit\",\n \"source.organizeImports\": \"explicit\"\n },\n \"editor.defaultFormatter\": \"charliermarsh.ruff\"\n },\n \"python.testing.pytestEnabled\": true,\n \"python.testing.unittestEnabled\": false\n}" }, { "path": "CHANGELOG.md", "content": "# Detailed changelog\nThe most important changes can also be found in [the documentation](https://docs.locust.io/en/latest/changelog.html).\n\n## [2.43.3](https://github.com/locustio/locust/tree/2.43.3) (2026-02-12)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.43.2...2.43.3)\n\n**Closed issues:**\n\n- Documentation Improvement - Event hooks [\\#3338](https://github.com/locustio/locust/issues/3338)\n\n**Merged pull requests:**\n\n- Bump diff from 8.0.2 to 8.0.3 in /locust/webui [\\#3349](https://github.com/locustio/locust/pull/3349) ([dependabot[bot]](https://github.com/apps/dependabot))\n- Bump lodash from 4.17.21 to 4.17.23 in /locust/webui [\\#3348](https://github.com/locustio/locust/pull/3348) ([dependabot[bot]](https://github.com/apps/dependabot))\n- Bump cryptography from 43.0.3 to 46.0.5 [\\#3347](https://github.com/locustio/locust/pull/3347) ([dependabot[bot]](https://github.com/apps/dependabot))\n- Bump tar from 7.4.3 to 7.5.7 in /locust/webui [\\#3346](https://github.com/locustio/locust/pull/3346) ([dependabot[bot]](https://github.com/apps/dependabot))\n- Bump @isaacs/brace-expansion from 5.0.0 to 5.0.1 in /locust/webui [\\#3345](https://github.com/locustio/locust/pull/3345) ([dependabot[bot]](https://github.com/apps/dependabot))\n- Add missing event hook parameter documentation [\\#3344](https://github.com/locustio/locust/pull/3344) ([veeceey](https://github.com/veeceey))\n\n## [2.43.2](https://github.com/locustio/locust/tree/2.43.2) (2026-02-01)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.43.1...2.43.2)\n\n**Merged pull requests:**\n\n- Bump flask-cors from 6.0.1 to 6.0.2 [\\#3343](https://github.com/locustio/locust/pull/3343) ([dependabot[bot]](https://github.com/apps/dependabot))\n- Bump hatch from 1.16.2 to 1.16.3 [\\#3342](https://github.com/locustio/locust/pull/3342) ([dependabot[bot]](https://github.com/apps/dependabot))\n- Bump werkzeug from 3.1.4 to 3.1.5 [\\#3341](https://github.com/locustio/locust/pull/3341) ([dependabot[bot]](https://github.com/apps/dependabot))\n- Bump opentelemetry-exporter-otlp-proto-grpc from 1.39.0 to 1.39.1 [\\#3340](https://github.com/locustio/locust/pull/3340) ([dependabot[bot]](https://github.com/apps/dependabot))\n- Bump sphinx-rtd-theme from 3.0.2 to 3.1.0 [\\#3339](https://github.com/locustio/locust/pull/3339) ([dependabot[bot]](https://github.com/apps/dependabot))\n- Update operator docs [\\#3333](https://github.com/locustio/locust/pull/3333) ([amadeuppereira](https://github.com/amadeuppereira))\n\n## [2.43.1](https://github.com/locustio/locust/tree/2.43.1) (2026-01-12)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.43.0...2.43.1)\n\n**Merged pull requests:**\n\n- Bump packages [\\#3331](https://github.com/locustio/locust/pull/3331) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Stabilize tests [\\#3326](https://github.com/locustio/locust/pull/3326) ([amadeuppereira](https://github.com/amadeuppereira))\n- Stabilize tests [\\#3325](https://github.com/locustio/locust/pull/3325) ([amadeuppereira](https://github.com/amadeuppereira))\n- Bump @emotion/styled from 11.14.0 to 11.14.1 in /locust/webui in the emotion group [\\#3322](https://github.com/locustio/locust/pull/3322) ([dependabot[bot]](https://github.com/apps/dependabot))\n- Bump the eslint group in /locust/webui with 5 updates [\\#3319](https://github.com/locustio/locust/pull/3319) ([dependabot[bot]](https://github.com/apps/dependabot))\n- Bump the all\\_dependencies group with 2 updates [\\#3318](https://github.com/locustio/locust/pull/3318) ([dependabot[bot]](https://github.com/apps/dependabot))\n\n## [2.43.0](https://github.com/locustio/locust/tree/2.43.0) (2025-12-30)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.42.6...2.43.0)\n\n**Closed issues:**\n\n- Support for requests \\>=2.32.5 \\(compatibility with LangChain/AI ecosystem\\) [\\#3307](https://github.com/locustio/locust/issues/3307)\n- Multiple select in web UI for custom arguments [\\#3260](https://github.com/locustio/locust/issues/3260)\n- Suggestion to Add \"iter\\_lines\" Support for \"FastHttpUser\" in Locust [\\#3018](https://github.com/locustio/locust/issues/3018)\n\n**Merged pull requests:**\n\n- Provide a better error message when spawn rate is set to zero [\\#3317](https://github.com/locustio/locust/pull/3317) ([amadeuppereira](https://github.com/amadeuppereira))\n- Support requests\\>=2.32.5, reimplement the fix previously there for only loading ssl certificates once [\\#3316](https://github.com/locustio/locust/pull/3316) ([amadeuppereira](https://github.com/amadeuppereira))\n- Remove references to locust.cloud now that it is shutting down [\\#3314](https://github.com/locustio/locust/pull/3314) ([amadeuppereira](https://github.com/amadeuppereira))\n- Allow users to stop test run by raising StopTest, use it on missing host in locustfile \\(and no --host param\\) [\\#3313](https://github.com/locustio/locust/pull/3313) ([amadeuppereira](https://github.com/amadeuppereira))\n- Locust Cloud demo tab: update domain from auth.locust.cloud to app.locust.cloud [\\#3312](https://github.com/locustio/locust/pull/3312) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Solving the iter\\_lines problem [\\#3311](https://github.com/locustio/locust/pull/3311) ([MasterKey-Pro](https://github.com/MasterKey-Pro))\n- Refactor parse\\_options [\\#3310](https://github.com/locustio/locust/pull/3310) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Capture stacktrace on KeyboardInterrupt on greenlets [\\#3306](https://github.com/locustio/locust/pull/3306) ([amadeuppereira](https://github.com/amadeuppereira))\n- Bump js-yaml from 4.1.0 to 4.1.1 in /locust/webui [\\#3305](https://github.com/locustio/locust/pull/3305) ([dependabot[bot]](https://github.com/apps/dependabot))\n- Bump glob from 10.4.5 to 10.5.0 in /locust/webui [\\#3304](https://github.com/locustio/locust/pull/3304) ([dependabot[bot]](https://github.com/apps/dependabot))\n\n## [2.42.6](https://github.com/locustio/locust/tree/2.42.6) (2025-11-29)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.42.5...2.42.6)\n\n**Fixed bugs:**\n\n- After Locust upgrade, parameter 'headless = true' in conf file does not work as expected. [\\#3225](https://github.com/locustio/locust/issues/3225)\n\n**Merged pull requests:**\n\n- Don't import pytest unless it is really needed, to speed up startup [\\#3302](https://github.com/locustio/locust/pull/3302) ([cyberw](https://github.com/cyberw))\n- refactor case statements and update to use 3.10 set syntax [\\#3301](https://github.com/locustio/locust/pull/3301) ([cyberw](https://github.com/cyberw))\n- Update OTel setup [\\#3300](https://github.com/locustio/locust/pull/3300) ([amadeuppereira](https://github.com/amadeuppereira))\n- Use match-case instead of gigantic if-elif statement when handling zmq messages in master-worker communication [\\#3299](https://github.com/locustio/locust/pull/3299) ([cyberw](https://github.com/cyberw))\n- Add OTel documentation [\\#3298](https://github.com/locustio/locust/pull/3298) ([amadeuppereira](https://github.com/amadeuppereira))\n- Improve tests [\\#3297](https://github.com/locustio/locust/pull/3297) ([amadeuppereira](https://github.com/amadeuppereira))\n- Log duplicate client\\_ready messages as debug instead of info level [\\#3296](https://github.com/locustio/locust/pull/3296) ([cyberw](https://github.com/cyberw))\n- Add otel unit tests [\\#3295](https://github.com/locustio/locust/pull/3295) ([amadeuppereira](https://github.com/amadeuppereira))\n- Only log \"OpenTelemetry enabled\" message when success [\\#3294](https://github.com/locustio/locust/pull/3294) ([amadeuppereira](https://github.com/amadeuppereira))\n- Fix Toml Parser Being Called on Conf Files [\\#3293](https://github.com/locustio/locust/pull/3293) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- GH Actions: Bump actions/checkout from 5 to 6 in the all\\_dependencies group [\\#3287](https://github.com/locustio/locust/pull/3287) ([dependabot[bot]](https://github.com/apps/dependabot))\n\n## [2.42.5](https://github.com/locustio/locust/tree/2.42.5) (2025-11-20)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.42.4...2.42.5)\n\n**Merged pull requests:**\n\n- Log when otel is enabled [\\#3284](https://github.com/locustio/locust/pull/3284) ([amadeuppereira](https://github.com/amadeuppereira))\n\n## [2.42.4](https://github.com/locustio/locust/tree/2.42.4) (2025-11-20)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.42.3...2.42.4)\n\n**Closed issues:**\n\n- bumb pytest to support 9.x [\\#3262](https://github.com/locustio/locust/issues/3262)\n\n**Merged pull requests:**\n\n- Avoid duplicated action run on pull requests [\\#3282](https://github.com/locustio/locust/pull/3282) ([jairhenrique](https://github.com/jairhenrique))\n- Forward explicitly set request name to OTEL span [\\#3281](https://github.com/locustio/locust/pull/3281) ([amadeuppereira](https://github.com/amadeuppereira))\n- Verbose request span name [\\#3279](https://github.com/locustio/locust/pull/3279) ([amadeuppereira](https://github.com/amadeuppereira))\n- Add OpenTelemetry flag [\\#3278](https://github.com/locustio/locust/pull/3278) ([amadeuppereira](https://github.com/amadeuppereira))\n- Disable uv.lock check in GH action [\\#3277](https://github.com/locustio/locust/pull/3277) ([cyberw](https://github.com/cyberw))\n- Add otlp http exporter dependency [\\#3276](https://github.com/locustio/locust/pull/3276) ([amadeuppereira](https://github.com/amadeuppereira))\n- Add OpenTelemetry support [\\#3275](https://github.com/locustio/locust/pull/3275) ([amadeuppereira](https://github.com/amadeuppereira))\n- Bump the eslint group in /locust/webui with 11 updates [\\#3270](https://github.com/locustio/locust/pull/3270) ([dependabot[bot]](https://github.com/apps/dependabot))\n- Includes npm and uv on dependabot file [\\#3269](https://github.com/locustio/locust/pull/3269) ([jairhenrique](https://github.com/jairhenrique))\n- Enables FURB ruff lint [\\#3265](https://github.com/locustio/locust/pull/3265) ([jairhenrique](https://github.com/jairhenrique))\n- Updates pytest dependency range [\\#3263](https://github.com/locustio/locust/pull/3263) ([jairhenrique](https://github.com/jairhenrique))\n- Allow multiple dropdown in Web UI [\\#3261](https://github.com/locustio/locust/pull/3261) ([jFompe](https://github.com/jFompe))\n\n## [2.42.3](https://github.com/locustio/locust/tree/2.42.3) (2025-11-15)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.42.2...2.42.3)\n\n**Merged pull requests:**\n\n- Bump the all\\_dependencies group with 7 updates [\\#3266](https://github.com/locustio/locust/pull/3266) ([dependabot[bot]](https://github.com/apps/dependabot))\n- Creates dependabot file to keep gh actions updated [\\#3264](https://github.com/locustio/locust/pull/3264) ([jairhenrique](https://github.com/jairhenrique))\n- GH Actions: update uv version, ensure uv.lock doesn't contain anything not in pyproject.toml [\\#3259](https://github.com/locustio/locust/pull/3259) ([cyberw](https://github.com/cyberw))\n- Fix single line .conf files incorrectly being treated as toml [\\#3257](https://github.com/locustio/locust/pull/3257) ([cyberw](https://github.com/cyberw))\n\n## [2.42.2](https://github.com/locustio/locust/tree/2.42.2) (2025-11-06)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.42.1...2.42.2)\n\n**Merged pull requests:**\n\n- Bump locust-cloud version, fixing an issue with .conf-files [\\#3256](https://github.com/locustio/locust/pull/3256) ([cyberw](https://github.com/cyberw))\n- Revert \"modified ui\\_extra\\_args\\_dict function to pick arguments\" [\\#3255](https://github.com/locustio/locust/pull/3255) ([cyberw](https://github.com/cyberw))\n- Update uv.lock [\\#3254](https://github.com/locustio/locust/pull/3254) ([cyberw](https://github.com/cyberw))\n- remove setuptools from dependencies [\\#3253](https://github.com/locustio/locust/pull/3253) ([dotlambda](https://github.com/dotlambda))\n- fix: MQTT client\\_id and protocol not passed down to Client [\\#3252](https://github.com/locustio/locust/pull/3252) ([ionutab](https://github.com/ionutab))\n\n## [2.42.1](https://github.com/locustio/locust/tree/2.42.1) (2025-10-27)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.42.0...2.42.1)\n\n**Merged pull requests:**\n\n- Add VS Code Extension and k8s operator to documentation [\\#3251](https://github.com/locustio/locust/pull/3251) ([cyberw](https://github.com/cyberw))\n- Bump vite from 6.3.5 to 6.4.1 in /locust/webui [\\#3249](https://github.com/locustio/locust/pull/3249) ([dependabot[bot]](https://github.com/apps/dependabot))\n- Bumped the gRPC example server’s worker pool to 100 [\\#3248](https://github.com/locustio/locust/pull/3248) ([sonianuj287](https://github.com/sonianuj287))\n- modified ui\\_extra\\_args\\_dict function to pick arguments [\\#3245](https://github.com/locustio/locust/pull/3245) ([sonianuj287](https://github.com/sonianuj287))\n\n## [2.42.0](https://github.com/locustio/locust/tree/2.42.0) (2025-10-17)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.41.6...2.42.0)\n\n**Fixed bugs:**\n\n- Extend Locust UI with new tab does not work [\\#3240](https://github.com/locustio/locust/issues/3240)\n- Reset button not working after stopping the run [\\#3197](https://github.com/locustio/locust/issues/3197)\n\n**Merged pull requests:**\n\n- Avoid using most recent python-requests because it may introduce performance issues [\\#3244](https://github.com/locustio/locust/pull/3244) ([cyberw](https://github.com/cyberw))\n- Introduce DNSUser [\\#3243](https://github.com/locustio/locust/pull/3243) ([cyberw](https://github.com/cyberw))\n- Fix reset button not working after stopping the run [\\#3238](https://github.com/locustio/locust/pull/3238) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Added readme badge for supported python versions [\\#3237](https://github.com/locustio/locust/pull/3237) ([Nirzak](https://github.com/Nirzak))\n- loosen dependency on gevent [\\#3236](https://github.com/locustio/locust/pull/3236) ([bollwyvl](https://github.com/bollwyvl))\n\n## [2.41.6](https://github.com/locustio/locust/tree/2.41.6) (2025-10-10)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.41.5...2.41.6)\n\n**Merged pull requests:**\n\n- Officially support Python 3.14 and test it [\\#3235](https://github.com/locustio/locust/pull/3235) ([cyberw](https://github.com/cyberw))\n\n## [2.41.5](https://github.com/locustio/locust/tree/2.41.5) (2025-10-06)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.41.4...2.41.5)\n\n**Merged pull requests:**\n\n- Use www host instead of bare locust.cloud in examples and tests [\\#3234](https://github.com/locustio/locust/pull/3234) ([cyberw](https://github.com/cyberw))\n\n## [2.41.4](https://github.com/locustio/locust/tree/2.41.4) (2025-10-06)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.41.3...2.41.4)\n\n**Merged pull requests:**\n\n- Fix Unsafe Template Arg [\\#3232](https://github.com/locustio/locust/pull/3232) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n\n## [2.41.3](https://github.com/locustio/locust/tree/2.41.3) (2025-10-01)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.41.2...2.41.3)\n\n**Merged pull requests:**\n\n- Make workers correctly ignore the --run-time flag [\\#3230](https://github.com/locustio/locust/pull/3230) ([cyberw](https://github.com/cyberw))\n- Enhance MilvusUser constructor to support additional collection parameters [\\#3229](https://github.com/locustio/locust/pull/3229) ([zhuwenxing](https://github.com/zhuwenxing))\n\n## [2.41.2](https://github.com/locustio/locust/tree/2.41.2) (2025-09-29)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.41.1...2.41.2)\n\n**Fixed bugs:**\n\n- Locust pytest plugin option '--host' conflicts with common user options; suggest renaming to '--locust-host' [\\#3227](https://github.com/locustio/locust/issues/3227)\n\n**Merged pull requests:**\n\n- Pytest plugin: Workaround issue with potential duplicate --host argument definition [\\#3228](https://github.com/locustio/locust/pull/3228) ([cyberw](https://github.com/cyberw))\n- Fix Alignment of View Column Selector [\\#3226](https://github.com/locustio/locust/pull/3226) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n\n## [2.41.1](https://github.com/locustio/locust/tree/2.41.1) (2025-09-25)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.41.0...2.41.1)\n\n## [2.41.0](https://github.com/locustio/locust/tree/2.41.0) (2025-09-25)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.40.5...2.41.0)\n\n**Fixed bugs:**\n\n- Master doesn't distribute user equally among workers [\\#3209](https://github.com/locustio/locust/issues/3209)\n\n**Merged pull requests:**\n\n- Suggest possibly misspelled command line arguments \\(Did you mean ...\\) [\\#3224](https://github.com/locustio/locust/pull/3224) ([cyberw](https://github.com/cyberw))\n- Add Locust Feedback Form [\\#3223](https://github.com/locustio/locust/pull/3223) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Add MqttUser [\\#3216](https://github.com/locustio/locust/pull/3216) ([ionutab](https://github.com/ionutab))\n\n## [2.40.5](https://github.com/locustio/locust/tree/2.40.5) (2025-09-17)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.40.4...2.40.5)\n\n**Merged pull requests:**\n\n- Avoid wrapping fast response in response context manager when not needed [\\#3222](https://github.com/locustio/locust/pull/3222) ([cyberw](https://github.com/cyberw))\n\n## [2.40.4](https://github.com/locustio/locust/tree/2.40.4) (2025-09-11)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.40.3...2.40.4)\n\n**Merged pull requests:**\n\n- Avoid pytest style locustfiles capturing keyboard input [\\#3219](https://github.com/locustio/locust/pull/3219) ([cyberw](https://github.com/cyberw))\n\n## [2.40.3](https://github.com/locustio/locust/tree/2.40.3) (2025-09-11)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.40.2...2.40.3)\n\n**Merged pull requests:**\n\n- Bump requests minimum version [\\#3218](https://github.com/locustio/locust/pull/3218) ([cyberw](https://github.com/cyberw))\n- Make ResponseContextManager.raise\\_for\\_status\\(\\) consider calls to failure\\(\\) and success\\(\\) [\\#3217](https://github.com/locustio/locust/pull/3217) ([cyberw](https://github.com/cyberw))\n\n## [2.40.2](https://github.com/locustio/locust/tree/2.40.2) (2025-09-08)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.40.1...2.40.2)\n\n**Fixed bugs:**\n\n- Python 3.13: KeyError: 'name' on request\\_meta in ResponseContextManager.\\_\\_exit\\_\\_ [\\#3207](https://github.com/locustio/locust/issues/3207)\n\n**Merged pull requests:**\n\n- Refactor SocketIOUser to create separate SocketIOClient class [\\#3211](https://github.com/locustio/locust/pull/3211) ([cyberw](https://github.com/cyberw))\n- Refactor clients.ResponseContextManager and fix gc issue [\\#3210](https://github.com/locustio/locust/pull/3210) ([cyberw](https://github.com/cyberw))\n\n## [2.40.1](https://github.com/locustio/locust/tree/2.40.1) (2025-09-05)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.40.0...2.40.1)\n\n**Fixed bugs:**\n\n- 2.40.0 with pytest and xdist [\\#3202](https://github.com/locustio/locust/issues/3202)\n\n**Merged pull requests:**\n\n- Move pytest plugin to its own directory, to prevent accidental import [\\#3205](https://github.com/locustio/locust/pull/3205) ([cyberw](https://github.com/cyberw))\n- Pytest plugin: Delay imports to avoid monkey patching until someone uses the fixtures [\\#3204](https://github.com/locustio/locust/pull/3204) ([cyberw](https://github.com/cyberw))\n\n## [2.40.0](https://github.com/locustio/locust/tree/2.40.0) (2025-09-04)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.39.1...2.40.0)\n\n**Fixed bugs:**\n\n- HTTP response 0 [\\#3199](https://github.com/locustio/locust/issues/3199)\n\n**Merged pull requests:**\n\n- Avoid exception in HttpUser if requests has lost track of the request it made [\\#3201](https://github.com/locustio/locust/pull/3201) ([cyberw](https://github.com/cyberw))\n- Support pytests as locustfiles [\\#3200](https://github.com/locustio/locust/pull/3200) ([cyberw](https://github.com/cyberw))\n- Refactor FastHttpSession to be more like HttpSession [\\#3198](https://github.com/locustio/locust/pull/3198) ([cyberw](https://github.com/cyberw))\n- Update Dockerfile base to Python 3.13 [\\#3193](https://github.com/locustio/locust/pull/3193) ([adaamz](https://github.com/adaamz))\n\n## [2.39.1](https://github.com/locustio/locust/tree/2.39.1) (2025-08-29)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.39.0...2.39.1)\n\n**Merged pull requests:**\n\n- Avoid broken gevent version for now [\\#3196](https://github.com/locustio/locust/pull/3196) ([cyberw](https://github.com/cyberw))\n- Remove duplicated line in pyproject.toml [\\#3195](https://github.com/locustio/locust/pull/3195) ([JumboBear](https://github.com/JumboBear))\n\n## [2.39.0](https://github.com/locustio/locust/tree/2.39.0) (2025-08-19)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.38.1...2.39.0)\n\n**Merged pull requests:**\n\n- Add SocketIOUser [\\#3189](https://github.com/locustio/locust/pull/3189) ([cyberw](https://github.com/cyberw))\n- Add MilvusUser and example [\\#3168](https://github.com/locustio/locust/pull/3168) ([zhuwenxing](https://github.com/zhuwenxing))\n\n## [2.38.1](https://github.com/locustio/locust/tree/2.38.1) (2025-08-12)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.38.0...2.38.1)\n\n**Closed issues:**\n\n- Support for markov chains to describe a user's behavior [\\#3156](https://github.com/locustio/locust/issues/3156)\n- Switch docker base image to one with uv preinstalled [\\#3061](https://github.com/locustio/locust/issues/3061)\n\n**Merged pull requests:**\n\n- FastHttpUser: Dont send zstd in Accept-Encoding header [\\#3188](https://github.com/locustio/locust/pull/3188) ([cyberw](https://github.com/cyberw))\n- Fix test flakyness and update error message [\\#3187](https://github.com/locustio/locust/pull/3187) ([amadeuppereira](https://github.com/amadeuppereira))\n\n## [2.38.0](https://github.com/locustio/locust/tree/2.38.0) (2025-08-07)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.37.14...2.38.0)\n\n**Fixed bugs:**\n\n- Failures table sorting is reset to ascending after a few seconds [\\#3184](https://github.com/locustio/locust/issues/3184)\n- argparse.ArgumentError: argument --profile: conflicting option string: --profile \\(locust==2.37.14\\) [\\#3180](https://github.com/locustio/locust/issues/3180)\n\n**Merged pull requests:**\n\n- Webui: Fix useSortByField [\\#3185](https://github.com/locustio/locust/pull/3185) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Optimize unit tests [\\#3183](https://github.com/locustio/locust/pull/3183) ([amadeuppereira](https://github.com/amadeuppereira))\n- Support for list based custom arguments [\\#3181](https://github.com/locustio/locust/pull/3181) ([mickdwyer](https://github.com/mickdwyer))\n- Bump form-data from 4.0.0 to 4.0.4 in /locust/webui [\\#3179](https://github.com/locustio/locust/pull/3179) ([dependabot[bot]](https://github.com/apps/dependabot))\n- Webui: Hide no Host Warning when one is Provided [\\#3177](https://github.com/locustio/locust/pull/3177) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Add MarkovTaskSet [\\#3176](https://github.com/locustio/locust/pull/3176) ([Matthieu-Beauchamp](https://github.com/Matthieu-Beauchamp))\n- Add yarn lint precommit [\\#3175](https://github.com/locustio/locust/pull/3175) ([cyberw](https://github.com/cyberw))\n\n## [2.37.14](https://github.com/locustio/locust/tree/2.37.14) (2025-07-16)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.37.13...2.37.14)\n\n**Merged pull requests:**\n\n- Web UI: Fix Chart Zoom Slider [\\#3174](https://github.com/locustio/locust/pull/3174) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Web UI: Improve Locust Cloud Tab [\\#3172](https://github.com/locustio/locust/pull/3172) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n\n## [2.37.13](https://github.com/locustio/locust/tree/2.37.13) (2025-07-15)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.37.12...2.37.13)\n\n**Fixed bugs:**\n\n- Locust can't install on alpine linux anymore [\\#3166](https://github.com/locustio/locust/issues/3166)\n\n**Closed issues:**\n\n- Decouple the JavaScript asset code from the report [\\#3064](https://github.com/locustio/locust/issues/3064)\n\n**Merged pull requests:**\n\n- Remove safe\\_name from /stats/requests response [\\#3171](https://github.com/locustio/locust/pull/3171) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Web UI: Shrink Bundle Size [\\#3169](https://github.com/locustio/locust/pull/3169) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n\n## [2.37.12](https://github.com/locustio/locust/tree/2.37.12) (2025-07-08)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.37.11...2.37.12)\n\n**Fixed bugs:**\n\n- Error shutting down when using processes [\\#3161](https://github.com/locustio/locust/issues/3161)\n- 1279 Locust instances makes master run at 100% continously [\\#3142](https://github.com/locustio/locust/issues/3142)\n\n**Merged pull requests:**\n\n- Attempt to increase open file limit \\(RLIMIT\\_NOFILE\\) even on master. [\\#3162](https://github.com/locustio/locust/pull/3162) ([cyberw](https://github.com/cyberw))\n- Bump brace-expansion from 1.1.11 to 1.1.12 in /locust/webui [\\#3160](https://github.com/locustio/locust/pull/3160) ([dependabot[bot]](https://github.com/apps/dependabot))\n\n## [2.37.11](https://github.com/locustio/locust/tree/2.37.11) (2025-06-23)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.37.10...2.37.11)\n\n**Fixed bugs:**\n\n- FastHttpUser uses incorrect regex to hide home directory [\\#3159](https://github.com/locustio/locust/issues/3159)\n\n**Closed issues:**\n\n- Define a list of paths to simulate an user journey [\\#3150](https://github.com/locustio/locust/issues/3150)\n- export the results as a json file [\\#3089](https://github.com/locustio/locust/issues/3089)\n\n**Merged pull requests:**\n\n- Forward locustfiles to locust cloud [\\#3157](https://github.com/locustio/locust/pull/3157) ([amadeuppereira](https://github.com/amadeuppereira))\n- Web UI: Always Warn of Invalid Host [\\#3155](https://github.com/locustio/locust/pull/3155) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n\n## [2.37.10](https://github.com/locustio/locust/tree/2.37.10) (2025-06-07)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.37.9...2.37.10)\n\n**Merged pull requests:**\n\n- Revert accidental removal of --json-file option [\\#3154](https://github.com/locustio/locust/pull/3154) ([brtkwr](https://github.com/brtkwr))\n\n## [2.37.9](https://github.com/locustio/locust/tree/2.37.9) (2025-06-05)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.37.8...2.37.9)\n\n**Merged pull requests:**\n\n- Web UI: Fix host field name missing if host is not required [\\#3152](https://github.com/locustio/locust/pull/3152) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n\n## [2.37.8](https://github.com/locustio/locust/tree/2.37.8) (2025-06-05)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.37.7...2.37.8)\n\n**Closed issues:**\n\n- Support gevent \\>= 25.4.1 [\\#3143](https://github.com/locustio/locust/issues/3143)\n\n**Merged pull requests:**\n\n- Bump locust-cloud dependency, allow 25.x versions of gevent [\\#3151](https://github.com/locustio/locust/pull/3151) ([cyberw](https://github.com/cyberw))\n\n## [2.37.7](https://github.com/locustio/locust/tree/2.37.7) (2025-06-03)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.37.6...2.37.7)\n\n**Merged pull requests:**\n\n- Web Ui: Add host field validation [\\#3149](https://github.com/locustio/locust/pull/3149) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n\n## [2.37.6](https://github.com/locustio/locust/tree/2.37.6) (2025-05-28)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.37.5...2.37.6)\n\n**Fixed bugs:**\n\n- Documentation is Now Missing Table of \"All available configuration options\" [\\#3144](https://github.com/locustio/locust/issues/3144)\n\n**Merged pull requests:**\n\n- Fix Docs Config Options [\\#3145](https://github.com/locustio/locust/pull/3145) ([amadeuppereira](https://github.com/amadeuppereira))\n\n## [2.37.5](https://github.com/locustio/locust/tree/2.37.5) (2025-05-22)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.37.4...2.37.5)\n\n**Fixed bugs:**\n\n- Web UI Does Not Switch to Details Page Immediately on Test Start in Current Version [\\#3128](https://github.com/locustio/locust/issues/3128)\n\n**Merged pull requests:**\n\n- Do not require locustfile on specific locust-cloud arguments [\\#3141](https://github.com/locustio/locust/pull/3141) ([amadeuppereira](https://github.com/amadeuppereira))\n\n## [2.37.4](https://github.com/locustio/locust/tree/2.37.4) (2025-05-19)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.37.3...2.37.4)\n\n## [2.37.3](https://github.com/locustio/locust/tree/2.37.3) (2025-05-14)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.37.2...2.37.3)\n\n**Merged pull requests:**\n\n- Webui: Warn on Missing Host [\\#3140](https://github.com/locustio/locust/pull/3140) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n\n## [2.37.2](https://github.com/locustio/locust/tree/2.37.2) (2025-05-13)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.37.1...2.37.2)\n\n**Fixed bugs:**\n\n- p95 response time increases with the number of unique URLs [\\#3134](https://github.com/locustio/locust/issues/3134)\n- FastResponse.failure\\(\\) takes 1 positional argument but 2 were given [\\#3084](https://github.com/locustio/locust/issues/3084)\n\n**Merged pull requests:**\n\n- Webui: Block Submitting SwarmForm in Distributed Mode with no Workers [\\#3138](https://github.com/locustio/locust/pull/3138) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Fixes \\#3134 - Improve the performance of the `/stats/requests` endpoint [\\#3136](https://github.com/locustio/locust/pull/3136) ([orf](https://github.com/orf))\n- Bump vite from 6.3.2 to 6.3.4 in /locust/webui [\\#3132](https://github.com/locustio/locust/pull/3132) ([dependabot[bot]](https://github.com/apps/dependabot))\n\n## [2.37.1](https://github.com/locustio/locust/tree/2.37.1) (2025-05-07)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.37.0...2.37.1)\n\n**Fixed bugs:**\n\n- --json-file always creates empty file [\\#3130](https://github.com/locustio/locust/issues/3130)\n\n**Closed issues:**\n\n- Forced Dependency Updates \\(e.g., python-socketio\\) May Cause Version Mismatch with Java Services [\\#3129](https://github.com/locustio/locust/issues/3129)\n\n**Merged pull requests:**\n\n- Fix --json-file \\(actually save data to file\\) [\\#3131](https://github.com/locustio/locust/pull/3131) ([zed](https://github.com/zed))\n\n## [2.37.0](https://github.com/locustio/locust/tree/2.37.0) (2025-05-05)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.36.2...2.37.0)\n\n**Merged pull requests:**\n\n- Webui: Fix Failing Tests [\\#3126](https://github.com/locustio/locust/pull/3126) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Update uv to 0.7.2 [\\#3125](https://github.com/locustio/locust/pull/3125) ([cyberw](https://github.com/cyberw))\n- Add command line option to export json results into a file [\\#3124](https://github.com/locustio/locust/pull/3124) ([ajt89](https://github.com/ajt89))\n- Add locust exporter import \\(used in Locust Cloud\\) [\\#3122](https://github.com/locustio/locust/pull/3122) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- fix error message to be idiomatically correct English [\\#3121](https://github.com/locustio/locust/pull/3121) ([davidxia](https://github.com/davidxia))\n- Web UI: Use mutations for state buttons [\\#3120](https://github.com/locustio/locust/pull/3120) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n\n## [2.36.2](https://github.com/locustio/locust/tree/2.36.2) (2025-04-25)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.36.1...2.36.2)\n\n**Merged pull requests:**\n\n- Remove circular dependency for locust-cloud [\\#3119](https://github.com/locustio/locust/pull/3119) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n\n## [2.36.1](https://github.com/locustio/locust/tree/2.36.1) (2025-04-24)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.36.0...2.36.1)\n\n**Merged pull requests:**\n\n- Fix setting version for tag and pre-release [\\#3118](https://github.com/locustio/locust/pull/3118) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n\n## [2.36.0](https://github.com/locustio/locust/tree/2.36.0) (2025-04-24)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.35.0...2.36.0)\n\n**Merged pull requests:**\n\n- Bump locust-cloud dependency to 1.20.0 and remove it from docs dependencies [\\#3117](https://github.com/locustio/locust/pull/3117) ([cyberw](https://github.com/cyberw))\n- Fix yarn publish [\\#3116](https://github.com/locustio/locust/pull/3116) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Web Ui: Ensure form element has name [\\#3115](https://github.com/locustio/locust/pull/3115) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Web UI: Add profile field [\\#3113](https://github.com/locustio/locust/pull/3113) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Restrict gevent versions to ensure compatibility [\\#3112](https://github.com/locustio/locust/pull/3112) ([amadeuppereira](https://github.com/amadeuppereira))\n- Bump vite [\\#3111](https://github.com/locustio/locust/pull/3111) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Web UI: Optionally Extend Advanced Options [\\#3110](https://github.com/locustio/locust/pull/3110) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Yarn Berry: Update publish command [\\#3108](https://github.com/locustio/locust/pull/3108) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Web UI: Fix npm publish failing [\\#3107](https://github.com/locustio/locust/pull/3107) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- chore: set yarn to yarn berry [\\#3104](https://github.com/locustio/locust/pull/3104) ([schwannden](https://github.com/schwannden))\n- Refactoring: Extract locustfile content merger from main function [\\#3102](https://github.com/locustio/locust/pull/3102) ([insspb](https://github.com/insspb))\n- Refactoring: Extract validate stats configuration from main function [\\#3101](https://github.com/locustio/locust/pull/3101) ([insspb](https://github.com/insspb))\n- Add locust-cloud as a dependency, update sphinx and some other docs stuff [\\#3097](https://github.com/locustio/locust/pull/3097) ([amadeuppereira](https://github.com/amadeuppereira))\n\n## [2.35.0](https://github.com/locustio/locust/tree/2.35.0) (2025-04-16)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.34.1...2.35.0)\n\n**Merged pull requests:**\n\n- Bump vite from 6.2.5 to 6.2.6 in /locust/webui [\\#3098](https://github.com/locustio/locust/pull/3098) ([dependabot[bot]](https://github.com/apps/dependabot))\n- Webui: Add credentials to stop and reset requests [\\#3096](https://github.com/locustio/locust/pull/3096) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Webui: Add history fallback [\\#3095](https://github.com/locustio/locust/pull/3095) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Web UI: Add optional base url for locust requests to an external API [\\#3094](https://github.com/locustio/locust/pull/3094) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Webui: adding profile argument and display in html report [\\#3093](https://github.com/locustio/locust/pull/3093) ([schwannden](https://github.com/schwannden))\n\n## [2.34.1](https://github.com/locustio/locust/tree/2.34.1) (2025-04-09)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.34.0...2.34.1)\n\n**Merged pull requests:**\n\n- Bump vite from 6.2.4 to 6.2.5 in /locust/webui [\\#3091](https://github.com/locustio/locust/pull/3091) ([dependabot[bot]](https://github.com/apps/dependabot))\n- Drop support for Python 3.9 [\\#3090](https://github.com/locustio/locust/pull/3090) ([cyberw](https://github.com/cyberw))\n\n## [2.34.0](https://github.com/locustio/locust/tree/2.34.0) (2025-04-06)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.33.2...2.34.0)\n\n**Merged pull requests:**\n\n- Fix missing optional argument definitions in PostKwargs [\\#3088](https://github.com/locustio/locust/pull/3088) ([kairi003](https://github.com/kairi003))\n- Bump vite from 6.2.1 to 6.2.4 in /locust/webui [\\#3087](https://github.com/locustio/locust/pull/3087) ([dependabot[bot]](https://github.com/apps/dependabot))\n- Web UI: Offset Graph Legend so There's no Overlap on Mobile / Narrow Screens [\\#3086](https://github.com/locustio/locust/pull/3086) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- FastHttpUser: Dont crash if parameters are passed to failure\\(\\) when someone forgot catch\\_response=True [\\#3085](https://github.com/locustio/locust/pull/3085) ([cyberw](https://github.com/cyberw))\n- Make the Locust UI Responsive [\\#3083](https://github.com/locustio/locust/pull/3083) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Add OpenAI User and example [\\#3081](https://github.com/locustio/locust/pull/3081) ([cyberw](https://github.com/cyberw))\n\n## [2.33.2](https://github.com/locustio/locust/tree/2.33.2) (2025-03-14)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.33.1...2.33.2)\n\n**Fixed bugs:**\n\n- There was a heartbeat disconnect during the pressure test [\\#3065](https://github.com/locustio/locust/issues/3065)\n\n**Closed issues:**\n\n- Error Logging in FastHttpUser [\\#2937](https://github.com/locustio/locust/issues/2937)\n\n**Merged pull requests:**\n\n- Bump @babel/runtime from 7.22.15 to 7.26.10 in /locust/webui [\\#3080](https://github.com/locustio/locust/pull/3080) ([dependabot[bot]](https://github.com/apps/dependabot))\n- Update ruff to 0.10.0 [\\#3079](https://github.com/locustio/locust/pull/3079) ([cyberw](https://github.com/cyberw))\n- Optimize unit tests [\\#3078](https://github.com/locustio/locust/pull/3078) ([cyberw](https://github.com/cyberw))\n- Webui: Bump Vite Version for Dependabot [\\#3074](https://github.com/locustio/locust/pull/3074) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Update uv to 0.6.5 and optimize docker start time [\\#3073](https://github.com/locustio/locust/pull/3073) ([cyberw](https://github.com/cyberw))\n\n## [2.33.1](https://github.com/locustio/locust/tree/2.33.1) (2025-03-08)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.33.0...2.33.1)\n\n**Fixed bugs:**\n\n- --iterations with locust==2.33.0 and locust-plugins==4.5.3 [\\#3071](https://github.com/locustio/locust/issues/3071)\n- uv.lock ends up in root of site-packages [\\#3053](https://github.com/locustio/locust/issues/3053)\n\n**Merged pull requests:**\n\n- Fix html file naming crash, simplify code [\\#3072](https://github.com/locustio/locust/pull/3072) ([cyberw](https://github.com/cyberw))\n\n## [2.33.0](https://github.com/locustio/locust/tree/2.33.0) (2025-02-22)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.32.10...2.33.0)\n\n**Fixed bugs:**\n\n- UnboundLocalError: local variable 'user\\_count' referenced before assignment [\\#3051](https://github.com/locustio/locust/issues/3051)\n\n**Merged pull requests:**\n\n- docs: update python-requests documentation links [\\#3059](https://github.com/locustio/locust/pull/3059) ([n0h0](https://github.com/n0h0))\n- dos: correct venv activation path in docs [\\#3058](https://github.com/locustio/locust/pull/3058) ([n0h0](https://github.com/n0h0))\n- Use enter to automatically open web UI in default browser [\\#3057](https://github.com/locustio/locust/pull/3057) ([cyberw](https://github.com/cyberw))\n- Update vite to 6.0.11 [\\#3056](https://github.com/locustio/locust/pull/3056) ([cyberw](https://github.com/cyberw))\n- Remove uv lock file from build artifacts [\\#3055](https://github.com/locustio/locust/pull/3055) ([mquinnfd](https://github.com/mquinnfd))\n- Improve error message on missing user\\_count or spawn\\_rate in swarm payload [\\#3052](https://github.com/locustio/locust/pull/3052) ([cyberw](https://github.com/cyberw))\n- Enable HTML Report Filename Parsing [\\#3049](https://github.com/locustio/locust/pull/3049) ([ktchani](https://github.com/ktchani))\n- FastHttpUser: Accept brotli and zstd compression encoding [\\#3048](https://github.com/locustio/locust/pull/3048) ([kamilbednarz](https://github.com/kamilbednarz))\n- Bump vitest from 2.1.6 to 2.1.9 in /locust/webui [\\#3044](https://github.com/locustio/locust/pull/3044) ([dependabot[bot]](https://github.com/apps/dependabot))\n\n## [2.32.10](https://github.com/locustio/locust/tree/2.32.10) (2025-02-18)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.32.9...2.32.10)\n\n**Closed issues:**\n\n- Switch from Poetry to uv [\\#3033](https://github.com/locustio/locust/issues/3033)\n\n**Merged pull requests:**\n\n- Add uv lock file to builds [\\#3047](https://github.com/locustio/locust/pull/3047) ([mquinnfd](https://github.com/mquinnfd))\n- Use uv/hatch instead of Poetry [\\#3039](https://github.com/locustio/locust/pull/3039) ([mquinnfd](https://github.com/mquinnfd))\n\n## [2.32.9](https://github.com/locustio/locust/tree/2.32.9) (2025-02-10)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.32.8...2.32.9)\n\n**Fixed bugs:**\n\n- Cannot Update Custom options in the Web UI when Default Value is None [\\#3011](https://github.com/locustio/locust/issues/3011)\n\n**Merged pull requests:**\n\n- Update docs for stats.py file [\\#3038](https://github.com/locustio/locust/pull/3038) ([gabriel-check24](https://github.com/gabriel-check24))\n- Add iter\\_lines Method to FastHttpSession Class [\\#3024](https://github.com/locustio/locust/pull/3024) ([MasterKey-Pro](https://github.com/MasterKey-Pro))\n- Fix issue where empty WebUI property is not parsed correctly [\\#3012](https://github.com/locustio/locust/pull/3012) ([timhovius](https://github.com/timhovius))\n\n## [2.32.8](https://github.com/locustio/locust/tree/2.32.8) (2025-01-30)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.32.7...2.32.8)\n\n## [2.32.7](https://github.com/locustio/locust/tree/2.32.7) (2025-01-30)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.32.6...2.32.7)\n\n**Merged pull requests:**\n\n- Web UI: Allow Showing Only an Error Message on the Login Page [\\#3037](https://github.com/locustio/locust/pull/3037) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Allow Empty Tables when Filtering [\\#3036](https://github.com/locustio/locust/pull/3036) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Allow xAxis and Grid to be Configured in Echarts [\\#3035](https://github.com/locustio/locust/pull/3035) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Code quality: Fix unused imports and switch on related ruff check [\\#3034](https://github.com/locustio/locust/pull/3034) ([insspb](https://github.com/insspb))\n- Add tab with locust cloud features [\\#3032](https://github.com/locustio/locust/pull/3032) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- fix readme image ref links [\\#3031](https://github.com/locustio/locust/pull/3031) ([changchaishi](https://github.com/changchaishi))\n\n## [2.32.6](https://github.com/locustio/locust/tree/2.32.6) (2025-01-13)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.32.5...2.32.6)\n\n**Merged pull requests:**\n\n- Update Dockerfile to use Python 3.12 as base [\\#3029](https://github.com/locustio/locust/pull/3029) ([vejmoj1](https://github.com/vejmoj1))\n- Update tests to check for hostname instead of fqdn [\\#3027](https://github.com/locustio/locust/pull/3027) ([ajt89](https://github.com/ajt89))\n- Move some argument parsing/validation from main.py to argument\\_parser.py and remove deprecated parameter --hatch-rate [\\#3026](https://github.com/locustio/locust/pull/3026) ([ftb-skry](https://github.com/ftb-skry))\n- pin poetry-core version to \\<2.0.0 in pyproject.toml [\\#3025](https://github.com/locustio/locust/pull/3025) ([mgor](https://github.com/mgor))\n- Optimize run time of some unit tests [\\#3020](https://github.com/locustio/locust/pull/3020) ([cyberw](https://github.com/cyberw))\n\n## [2.32.5](https://github.com/locustio/locust/tree/2.32.5) (2024-12-22)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.32.4...2.32.5)\n\n**Merged pull requests:**\n\n- Make cpu usage check sleep BEFORE the first check, and make it slightly less frequent [\\#3014](https://github.com/locustio/locust/pull/3014) ([cyberw](https://github.com/cyberw))\n- FastHttpUser: Fix ssl loading performance issue by avoiding to load certs when they wont be used anyway [\\#3013](https://github.com/locustio/locust/pull/3013) ([cyberw](https://github.com/cyberw))\n- Treat exceptions in init event handler as fatal [\\#3009](https://github.com/locustio/locust/pull/3009) ([cyberw](https://github.com/cyberw))\n- Add create store export [\\#3004](https://github.com/locustio/locust/pull/3004) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n\n## [2.32.4](https://github.com/locustio/locust/tree/2.32.4) (2024-12-01)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.32.3...2.32.4)\n\n**Fixed bugs:**\n\n- Number of requests lower than expected in web UI [\\#3000](https://github.com/locustio/locust/issues/3000)\n- Reports download links do not contain web-base-path [\\#2998](https://github.com/locustio/locust/issues/2998)\n- Setuptools CVE-2024-6345 [\\#2995](https://github.com/locustio/locust/issues/2995)\n- When using exclude-tags to exclude more than two tags, this setting will not take effect [\\#2994](https://github.com/locustio/locust/issues/2994)\n\n**Merged pull requests:**\n\n- Allow showing auth info on blank page [\\#3002](https://github.com/locustio/locust/pull/3002) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Number of requests lower than expected in web UI [\\#3001](https://github.com/locustio/locust/pull/3001) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Webui links should be relative [\\#2999](https://github.com/locustio/locust/pull/2999) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Dependency and node version bump [\\#2997](https://github.com/locustio/locust/pull/2997) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Fix example in docs [\\#2993](https://github.com/locustio/locust/pull/2993) ([daniloakamine](https://github.com/daniloakamine))\n- Add Input Type to Login Form [\\#2992](https://github.com/locustio/locust/pull/2992) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Update configuration.rst to show minimalistic config example [\\#2990](https://github.com/locustio/locust/pull/2990) ([vkuehn](https://github.com/vkuehn))\n- Fix README Images for PyPi [\\#2989](https://github.com/locustio/locust/pull/2989) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n\n## [2.32.3](https://github.com/locustio/locust/tree/2.32.3) (2024-11-17)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.32.2...2.32.3)\n\n**Fixed bugs:**\n\n- Setuptools CVE-2022-40897 [\\#2986](https://github.com/locustio/locust/issues/2986)\n- master crash with different version worker [\\#2975](https://github.com/locustio/locust/issues/2975)\n\n**Merged pull requests:**\n\n- Ensure we never use old version of setuptools [\\#2988](https://github.com/locustio/locust/pull/2988) ([cyberw](https://github.com/cyberw))\n- README Themed Screenshots [\\#2985](https://github.com/locustio/locust/pull/2985) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- When specifying locustfile fia url, output start of response text when it wasnt valid python [\\#2983](https://github.com/locustio/locust/pull/2983) ([cyberw](https://github.com/cyberw))\n- Use debug log level for first 5s of waiting for workers to be ready. [\\#2982](https://github.com/locustio/locust/pull/2982) ([cyberw](https://github.com/cyberw))\n- Add option for Extra Options to be Required [\\#2981](https://github.com/locustio/locust/pull/2981) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Update ruff mypy [\\#2978](https://github.com/locustio/locust/pull/2978) ([tdadela](https://github.com/tdadela))\n- Fix crash with older worker version requesting locustfile from master [\\#2976](https://github.com/locustio/locust/pull/2976) ([cyberw](https://github.com/cyberw))\n- Use f-strings instead of old style string interpolation [\\#2974](https://github.com/locustio/locust/pull/2974) ([tdadela](https://github.com/tdadela))\n\n## [2.32.2](https://github.com/locustio/locust/tree/2.32.2) (2024-11-08)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.32.1...2.32.2)\n\n**Fixed bugs:**\n\n- Requests not ramping up after switching to using pydantic in django project [\\#2960](https://github.com/locustio/locust/issues/2960)\n- The locust chart shows that data is still being recorded after the timed run time expires [\\#2910](https://github.com/locustio/locust/issues/2910)\n\n**Closed issues:**\n\n- Downloading report should provide a meaningful human name [\\#2931](https://github.com/locustio/locust/issues/2931)\n- Hard coded path make it impossible to host the UI on a path \\(instead of the domain root\\) [\\#2909](https://github.com/locustio/locust/issues/2909)\n\n**Merged pull requests:**\n\n- Fix Incorrectly Updating Stat History [\\#2972](https://github.com/locustio/locust/pull/2972) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Webui Add Markdown Support for Auth Page [\\#2969](https://github.com/locustio/locust/pull/2969) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Fix Web Base Path Env Variable [\\#2967](https://github.com/locustio/locust/pull/2967) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Locust Configurable Web Base Path [\\#2966](https://github.com/locustio/locust/pull/2966) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Fix Auth Args Type [\\#2965](https://github.com/locustio/locust/pull/2965) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Webui Add Auth Info to Auth Page [\\#2963](https://github.com/locustio/locust/pull/2963) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Fix doc link [\\#2961](https://github.com/locustio/locust/pull/2961) ([tjandy98](https://github.com/tjandy98))\n- Report name [\\#2947](https://github.com/locustio/locust/pull/2947) ([obriat](https://github.com/obriat))\n\n## [2.32.1](https://github.com/locustio/locust/tree/2.32.1) (2024-10-29)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.32.0...2.32.1)\n\n**Closed issues:**\n\n- Add option to enable different statistics in the chart menu [\\#2946](https://github.com/locustio/locust/issues/2946)\n\n**Merged pull requests:**\n\n- Webui Echarts Redraw Request Lines if Changed [\\#2953](https://github.com/locustio/locust/pull/2953) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Webui Add Custom Form to Auth Page [\\#2952](https://github.com/locustio/locust/pull/2952) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Webui Override Markdown HTML Link with MUI Link [\\#2951](https://github.com/locustio/locust/pull/2951) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Webui Fix Echarts Axis Formatting [\\#2950](https://github.com/locustio/locust/pull/2950) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Webui Echarts Time Axis Should be Localized [\\#2949](https://github.com/locustio/locust/pull/2949) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Add Google Analytics to docs.locust.io [\\#2948](https://github.com/locustio/locust/pull/2948) ([heyman](https://github.com/heyman))\n- LocustBadStatusCode without url param in fasthttp [\\#2944](https://github.com/locustio/locust/pull/2944) ([swaalt](https://github.com/swaalt))\n- Web UI Remove Default Value for Select if Value is Provided [\\#2943](https://github.com/locustio/locust/pull/2943) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Web UI Auth Add Password Visibility Toggle [\\#2941](https://github.com/locustio/locust/pull/2941) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n\n## [2.32.0](https://github.com/locustio/locust/tree/2.32.0) (2024-10-15)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.31.8...2.32.0)\n\n**Fixed bugs:**\n\n- logfile is erroniously written when there are many workers. [\\#2927](https://github.com/locustio/locust/issues/2927)\n- Form field for users, spawn rate, and run time still visible in UI although CustomShape defined without use\\_common\\_options. [\\#2924](https://github.com/locustio/locust/issues/2924)\n- --html with --process 4 then get ValueError: StatsEntry.use\\_response\\_times\\_cache must be set to True [\\#2908](https://github.com/locustio/locust/issues/2908)\n- IPV6 check doesn't work as expected on AWS EKS [\\#2787](https://github.com/locustio/locust/issues/2787)\n\n**Merged pull requests:**\n\n- Log deprecation warning for Python 3.9 [\\#2940](https://github.com/locustio/locust/pull/2940) ([cyberw](https://github.com/cyberw))\n- Run tests on python 3.13 too [\\#2939](https://github.com/locustio/locust/pull/2939) ([cyberw](https://github.com/cyberw))\n- Web UI - Fix Line Chart [\\#2935](https://github.com/locustio/locust/pull/2935) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Modern UI - Fix Hide Common Options [\\#2934](https://github.com/locustio/locust/pull/2934) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Allow alerts and errors on new and edit form [\\#2932](https://github.com/locustio/locust/pull/2932) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Add error message to swarm form [\\#2930](https://github.com/locustio/locust/pull/2930) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Disable --csv for workers when using --processes. [\\#2929](https://github.com/locustio/locust/pull/2929) ([cyberw](https://github.com/cyberw))\n- Decide if ipv6 can work [\\#2923](https://github.com/locustio/locust/pull/2923) ([nc-marco](https://github.com/nc-marco))\n- Webui Add Form Alert [\\#2922](https://github.com/locustio/locust/pull/2922) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Add faq item: Basic auth \\(Authorization header\\) does not work after redirection [\\#2921](https://github.com/locustio/locust/pull/2921) ([obriat](https://github.com/obriat))\n- Add CSRF example [\\#2920](https://github.com/locustio/locust/pull/2920) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Web UI Add Exports for Library [\\#2919](https://github.com/locustio/locust/pull/2919) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- lower log level for unnecessary --autostart argument [\\#2918](https://github.com/locustio/locust/pull/2918) ([cyberw](https://github.com/cyberw))\n\n## [2.31.8](https://github.com/locustio/locust/tree/2.31.8) (2024-09-28)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.31.7...2.31.8)\n\n**Merged pull requests:**\n\n- Log locust-cloud version if it is installed [\\#2916](https://github.com/locustio/locust/pull/2916) ([cyberw](https://github.com/cyberw))\n- Web UI Auth submit should submit a POST request [\\#2915](https://github.com/locustio/locust/pull/2915) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Url in template arg [\\#2914](https://github.com/locustio/locust/pull/2914) ([fletelli42](https://github.com/fletelli42))\n- Fix RTD versioning with a deep git clone [\\#2913](https://github.com/locustio/locust/pull/2913) ([mquinnfd](https://github.com/mquinnfd))\n\n## [2.31.7](https://github.com/locustio/locust/tree/2.31.7) (2024-09-25)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.31.4.dev9994...2.31.7)\n\n**Merged pull requests:**\n\n- Fix Dependabot Complaints [\\#2912](https://github.com/locustio/locust/pull/2912) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Improve Web UI Logging [\\#2911](https://github.com/locustio/locust/pull/2911) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Pin python versions to avoid gh caching issue + always Install Dependencies, even when it looks like there was a cache hit [\\#2907](https://github.com/locustio/locust/pull/2907) ([cyberw](https://github.com/cyberw))\n- Fix Login Manager Error Message [\\#2905](https://github.com/locustio/locust/pull/2905) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Log locust version earlier [\\#2904](https://github.com/locustio/locust/pull/2904) ([cyberw](https://github.com/cyberw))\n- Add Mongodb test example [\\#2903](https://github.com/locustio/locust/pull/2903) ([guel-codes](https://github.com/guel-codes))\n\n## [2.31.4.dev9994](https://github.com/locustio/locust/tree/2.31.4.dev9994) (2024-09-16)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.31.4.dev9993...2.31.4.dev9994)\n\n## [2.31.4.dev9993](https://github.com/locustio/locust/tree/2.31.4.dev9993) (2024-09-16)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.31.4.dev9992...2.31.4.dev9993)\n\n## [2.31.4.dev9992](https://github.com/locustio/locust/tree/2.31.4.dev9992) (2024-09-16)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.31.4.dev9991...2.31.4.dev9992)\n\n## [2.31.4.dev9991](https://github.com/locustio/locust/tree/2.31.4.dev9991) (2024-09-16)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.31.4.dev999...2.31.4.dev9991)\n\n## [2.31.4.dev999](https://github.com/locustio/locust/tree/2.31.4.dev999) (2024-09-16)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.31.6...2.31.4.dev999)\n\n## [2.31.6](https://github.com/locustio/locust/tree/2.31.6) (2024-09-15)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.31.5...2.31.6)\n\n**Fixed bugs:**\n\n- RPS vs Total Running Users [\\#2895](https://github.com/locustio/locust/issues/2895)\n- Overwriting weight by config-users may lead to crash [\\#2852](https://github.com/locustio/locust/issues/2852)\n- FastHttpSession requests typing for the json argument should support lists [\\#2842](https://github.com/locustio/locust/issues/2842)\n- Dockerfile warning [\\#2811](https://github.com/locustio/locust/issues/2811)\n\n**Closed issues:**\n\n- Cleaning up the build process [\\#2857](https://github.com/locustio/locust/issues/2857)\n- Simplify GitHub Actions using install-poetry [\\#2822](https://github.com/locustio/locust/issues/2822)\n\n**Merged pull requests:**\n\n- Add Error Message for Accessing Login Manager without --web-login [\\#2902](https://github.com/locustio/locust/pull/2902) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Update Webui README [\\#2901](https://github.com/locustio/locust/pull/2901) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Add worker\\_count = 1 to LocalRunner for parity with MasterRunner [\\#2900](https://github.com/locustio/locust/pull/2900) ([tarkatronic](https://github.com/tarkatronic))\n- Remove redundant None in Any | None annotations [\\#2892](https://github.com/locustio/locust/pull/2892) ([tdadela](https://github.com/tdadela))\n- Fix \\_kl\\_generator by filtering nonpositive User weights [\\#2891](https://github.com/locustio/locust/pull/2891) ([tdadela](https://github.com/tdadela))\n- Update README.md [\\#2889](https://github.com/locustio/locust/pull/2889) ([JonanOribe](https://github.com/JonanOribe))\n- Filename from URL Should Strip Query Params [\\#2887](https://github.com/locustio/locust/pull/2887) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Simplify Generator annotations - PEP 696 [\\#2886](https://github.com/locustio/locust/pull/2886) ([tdadela](https://github.com/tdadela))\n- Fix FastHttpSession.request json typing [\\#2885](https://github.com/locustio/locust/pull/2885) ([tdadela](https://github.com/tdadela))\n\n## [2.31.5](https://github.com/locustio/locust/tree/2.31.5) (2024-08-30)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.31.4...2.31.5)\n\n**Fixed bugs:**\n\n- Pressure testing is over, but RPS and Users still have data [\\#2870](https://github.com/locustio/locust/issues/2870)\n\n**Merged pull requests:**\n\n- Ensure we don't accidentally hide errors while importing in locust-cloud or locust-plugins [\\#2881](https://github.com/locustio/locust/pull/2881) ([cyberw](https://github.com/cyberw))\n- Add publishing dependency on build package step [\\#2880](https://github.com/locustio/locust/pull/2880) ([mquinnfd](https://github.com/mquinnfd))\n- Build pipeline tweaks - docker tagging [\\#2879](https://github.com/locustio/locust/pull/2879) ([mquinnfd](https://github.com/mquinnfd))\n- Webui Remove chart initial data fetch [\\#2878](https://github.com/locustio/locust/pull/2878) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Document use with uvx and remove openssl version from --version output [\\#2877](https://github.com/locustio/locust/pull/2877) ([cyberw](https://github.com/cyberw))\n- Web UI Remove Scroll to Zoom [\\#2876](https://github.com/locustio/locust/pull/2876) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Cleaning and improvements in the Build Pipeline [\\#2873](https://github.com/locustio/locust/pull/2873) ([mquinnfd](https://github.com/mquinnfd))\n- WebUI: Correct types for form select [\\#2872](https://github.com/locustio/locust/pull/2872) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n\n## [2.31.4](https://github.com/locustio/locust/tree/2.31.4) (2024-08-26)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.31.3...2.31.4)\n\n**Merged pull requests:**\n\n- Webui Allow changing select input size [\\#2871](https://github.com/locustio/locust/pull/2871) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Webui Replace Logo SVG [\\#2867](https://github.com/locustio/locust/pull/2867) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Add favicon that looks good in light color theme [\\#2866](https://github.com/locustio/locust/pull/2866) ([heyman](https://github.com/heyman))\n- Webui Add build lib command to package.json [\\#2865](https://github.com/locustio/locust/pull/2865) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Web UI Github Action Publish steps must Build lib [\\#2864](https://github.com/locustio/locust/pull/2864) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Fix npm publish issue [\\#2863](https://github.com/locustio/locust/pull/2863) ([cyberw](https://github.com/cyberw))\n- GH actions: Update names of publish steps. Don't run prerelease steps when no prerelease is actually going to be published [\\#2862](https://github.com/locustio/locust/pull/2862) ([cyberw](https://github.com/cyberw))\n- Webui Fix Version Tag in NPM Prerelease Step [\\#2861](https://github.com/locustio/locust/pull/2861) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Webui Fix NPM Publish Step [\\#2860](https://github.com/locustio/locust/pull/2860) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Web UI as a Library NPM Release [\\#2858](https://github.com/locustio/locust/pull/2858) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Add PostgresUser to examples [\\#2836](https://github.com/locustio/locust/pull/2836) ([guel-codes](https://github.com/guel-codes))\n\n## [2.31.3](https://github.com/locustio/locust/tree/2.31.3) (2024-08-15)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.31.2...2.31.3)\n\n**Fixed bugs:**\n\n- Brew installed locust missing UI assets [\\#2831](https://github.com/locustio/locust/issues/2831)\n- response avg time is NaN [\\#2829](https://github.com/locustio/locust/issues/2829)\n- Windows Action Runs Wrong Version of Locust [\\#2796](https://github.com/locustio/locust/issues/2796)\n\n**Merged pull requests:**\n\n- Web UI Remove Echarts startValue [\\#2855](https://github.com/locustio/locust/pull/2855) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Update GitHub action versions [\\#2853](https://github.com/locustio/locust/pull/2853) ([cyberw](https://github.com/cyberw))\n- Improve docs for --class-picker/--config-users and give better error messages if json is bad [\\#2851](https://github.com/locustio/locust/pull/2851) ([cyberw](https://github.com/cyberw))\n- Add missing margin between Logo and Host in Navbar [\\#2850](https://github.com/locustio/locust/pull/2850) ([heyman](https://github.com/heyman))\n- Web UI Should use Built-In Echarts Time Axis [\\#2847](https://github.com/locustio/locust/pull/2847) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Webui Notification Improvements [\\#2846](https://github.com/locustio/locust/pull/2846) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Use new logo in web UI + some minor improvements [\\#2844](https://github.com/locustio/locust/pull/2844) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Webui Add Scatterplot Support [\\#2840](https://github.com/locustio/locust/pull/2840) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n\n## [2.31.2](https://github.com/locustio/locust/tree/2.31.2) (2024-08-06)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.31.1...2.31.2)\n\n**Merged pull requests:**\n\n- Prebuild UI in PyPi publish steps so that even source distributions contain web UI code [\\#2839](https://github.com/locustio/locust/pull/2839) ([mquinnfd](https://github.com/mquinnfd))\n- Add Tests for Web UI Line Chart [\\#2838](https://github.com/locustio/locust/pull/2838) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Documentation: Configure html\\_baseurl and jinja on RTD [\\#2837](https://github.com/locustio/locust/pull/2837) ([plaindocs](https://github.com/plaindocs))\n\n## [2.31.1](https://github.com/locustio/locust/tree/2.31.1) (2024-08-05)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.31.0...2.31.1)\n\n**Merged pull requests:**\n\n- Fix issue with downloading HTML report, update package.json for webui build [\\#2834](https://github.com/locustio/locust/pull/2834) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n\n## [2.31.0](https://github.com/locustio/locust/tree/2.31.0) (2024-08-05)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.30.0...2.31.0)\n\n**Merged pull requests:**\n\n- Fix docker build for release [\\#2830](https://github.com/locustio/locust/pull/2830) ([cyberw](https://github.com/cyberw))\n- Github Actions: Use node 20.x \\(fix PyPI Release and pre-Release Steps\\) [\\#2828](https://github.com/locustio/locust/pull/2828) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Improve Echarts and Expose Line and Axis Configuration [\\#2826](https://github.com/locustio/locust/pull/2826) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Bump Node [\\#2825](https://github.com/locustio/locust/pull/2825) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Integrations for Locust Cloud [\\#2824](https://github.com/locustio/locust/pull/2824) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Fix HTML Report Stats Table [\\#2817](https://github.com/locustio/locust/pull/2817) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Locust UI Charts Should Change Color Based on Theme [\\#2815](https://github.com/locustio/locust/pull/2815) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Locust UI as a Module [\\#2804](https://github.com/locustio/locust/pull/2804) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Log a message if total fixed\\_count is higher than number of users to spawn [\\#2793](https://github.com/locustio/locust/pull/2793) ([cyberw](https://github.com/cyberw))\n- Simplify fixed\\_count Users generation in UsersDispatcher.\\_user\\_gen [\\#2783](https://github.com/locustio/locust/pull/2783) ([tdadela](https://github.com/tdadela))\n- URL Directory, and Multi-File Support for Locustfile Distribution [\\#2766](https://github.com/locustio/locust/pull/2766) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n\n## [2.30.0](https://github.com/locustio/locust/tree/2.30.0) (2024-07-31)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.29.1...2.30.0)\n\n**Fixed bugs:**\n\n- Locust / pypy fails with \"AttributeError: module 'gc' has no attribute 'freeze'\" error. [\\#2818](https://github.com/locustio/locust/issues/2818)\n- Worker sometimes fails to send heartbeat after upgrade to urllib3\\>=1.26.16 [\\#2812](https://github.com/locustio/locust/issues/2812)\n- Web UI lacking asset [\\#2781](https://github.com/locustio/locust/issues/2781)\n\n**Closed issues:**\n\n- Charts Update Is Delayed [\\#2771](https://github.com/locustio/locust/issues/2771)\n- Use `itertools.cycle` in `SequentialTaskSet` [\\#2740](https://github.com/locustio/locust/issues/2740)\n- `SequentialTaskSet` handles task weights in an inconsistent way [\\#2739](https://github.com/locustio/locust/issues/2739)\n\n**Merged pull requests:**\n\n- Update poetry windows tests [\\#2821](https://github.com/locustio/locust/pull/2821) ([mquinnfd](https://github.com/mquinnfd))\n- Fix pypy gc.freeze\\(\\) AttributeError [\\#2819](https://github.com/locustio/locust/pull/2819) ([jimoleary](https://github.com/jimoleary))\n- Fix Dockerfile style warning [\\#2814](https://github.com/locustio/locust/pull/2814) ([mehrdadbn9](https://github.com/mehrdadbn9))\n- Avoid deadlock in gevent/urllib3 connection pool \\(fixes occasional worker heartbeat timeouts\\) [\\#2813](https://github.com/locustio/locust/pull/2813) ([tdadela](https://github.com/tdadela))\n- Replace total avg response time with 50 percentile \\(avg was broken\\) [\\#2806](https://github.com/locustio/locust/pull/2806) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Add example of a bottlenecked server and use that test to make a new graph for the docs [\\#2805](https://github.com/locustio/locust/pull/2805) ([cyberw](https://github.com/cyberw))\n- Fix tests on windows [\\#2803](https://github.com/locustio/locust/pull/2803) ([mquinnfd](https://github.com/mquinnfd))\n- Provide warning for local installs where yarn is not present [\\#2801](https://github.com/locustio/locust/pull/2801) ([mquinnfd](https://github.com/mquinnfd))\n- Fix Extend Webui Example [\\#2800](https://github.com/locustio/locust/pull/2800) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Correctly set version from Poetry in published builds [\\#2791](https://github.com/locustio/locust/pull/2791) ([mquinnfd](https://github.com/mquinnfd))\n- Fix StatsEntry docstring [\\#2784](https://github.com/locustio/locust/pull/2784) ([tdadela](https://github.com/tdadela))\n- dispatch benchmark test improvements [\\#2780](https://github.com/locustio/locust/pull/2780) ([tdadela](https://github.com/tdadela))\n- Typing: strict optional in dispatch.py [\\#2779](https://github.com/locustio/locust/pull/2779) ([tdadela](https://github.com/tdadela))\n- new events for heartbeat and usage monitor [\\#2777](https://github.com/locustio/locust/pull/2777) ([mgor](https://github.com/mgor))\n- FastHttpSession requests typing [\\#2775](https://github.com/locustio/locust/pull/2775) ([tdadela](https://github.com/tdadela))\n- Remove Line Chart Default Zoom [\\#2774](https://github.com/locustio/locust/pull/2774) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- FastHttpSession: Enable passing json as a positional argument for post\\(\\) and stop converting response times to int [\\#2772](https://github.com/locustio/locust/pull/2772) ([tdadela](https://github.com/tdadela))\n- SequentialTaskSet: Allow weighted tasks and dict in .tasks [\\#2742](https://github.com/locustio/locust/pull/2742) ([bakhtos](https://github.com/bakhtos))\n- Implement Poetry build system \\(mainly so we don't have to commit dynamically generated front end bundles to git\\) [\\#2725](https://github.com/locustio/locust/pull/2725) ([mquinnfd](https://github.com/mquinnfd))\n\n## [2.29.1](https://github.com/locustio/locust/tree/2.29.1) (2024-06-25)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.29.0...2.29.1)\n\n**Fixed bugs:**\n\n- locust/webui/dist/index.html script errors. [\\#2753](https://github.com/locustio/locust/issues/2753)\n\n**Merged pull requests:**\n\n- Option to Skip Monkey Patching with LOCUST\\_SKIP\\_MONKEY\\_PATCH [\\#2765](https://github.com/locustio/locust/pull/2765) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- HttpSession: Improve error message when someone forgot to pass catch\\_response=True + small optimization [\\#2762](https://github.com/locustio/locust/pull/2762) ([cyberw](https://github.com/cyberw))\n- Add JavaScript to MIME types for Windows Operating Systems [\\#2759](https://github.com/locustio/locust/pull/2759) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Add proxy support for FastHttpUser [\\#2758](https://github.com/locustio/locust/pull/2758) ([NicoAdrian](https://github.com/NicoAdrian))\n- Httpsession requests typing [\\#2699](https://github.com/locustio/locust/pull/2699) ([tdadela](https://github.com/tdadela))\n\n## [2.29.0](https://github.com/locustio/locust/tree/2.29.0) (2024-06-07)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.28.0...2.29.0)\n\n**Fixed bugs:**\n\n- The time of the downloaded html report is not correct [\\#2691](https://github.com/locustio/locust/issues/2691)\n- Event spawning\\_complete fires every time a user is created [\\#2671](https://github.com/locustio/locust/issues/2671)\n- Delay at startup and high cpu usage on Windows in Python 3.12 [\\#2555](https://github.com/locustio/locust/issues/2555)\n\n**Closed issues:**\n\n- Log a warning if getting locustfile from master takes more than 60s [\\#2748](https://github.com/locustio/locust/issues/2748)\n- Show the reset button even after stopping a test [\\#2723](https://github.com/locustio/locust/issues/2723)\n- Add date to charts in web UI [\\#2678](https://github.com/locustio/locust/issues/2678)\n\n**Merged pull requests:**\n\n- Send logs from workers to master and improve log viewer tab in the Web UI [\\#2750](https://github.com/locustio/locust/pull/2750) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Add Logging to download\\_locustfile\\_from\\_master [\\#2749](https://github.com/locustio/locust/pull/2749) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Modify timestamp generation to remove deprecation warning [\\#2738](https://github.com/locustio/locust/pull/2738) ([JavierUhagon](https://github.com/JavierUhagon))\n- Docs: Fix API TOC [\\#2737](https://github.com/locustio/locust/pull/2737) ([plaindocs](https://github.com/plaindocs))\n- Docs: Fix sphinx and theme upgrade [\\#2736](https://github.com/locustio/locust/pull/2736) ([plaindocs](https://github.com/plaindocs))\n- Docs: Fix theme [\\#2735](https://github.com/locustio/locust/pull/2735) ([plaindocs](https://github.com/plaindocs))\n- Docs: Import wiki to docs [\\#2734](https://github.com/locustio/locust/pull/2734) ([plaindocs](https://github.com/plaindocs))\n- Mention installing Locust in Building the Docs [\\#2733](https://github.com/locustio/locust/pull/2733) ([plaindocs](https://github.com/plaindocs))\n- Docs: Upgrade Sphinx to latest version \\(7.3.7\\) [\\#2732](https://github.com/locustio/locust/pull/2732) ([plaindocs](https://github.com/plaindocs))\n- Add date and zoom to charts in web UI [\\#2731](https://github.com/locustio/locust/pull/2731) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Use requests 2.32.2 or higher for Python 3.12 [\\#2730](https://github.com/locustio/locust/pull/2730) ([cyberw](https://github.com/cyberw))\n- The time of the downloaded HTML report is not correct [\\#2729](https://github.com/locustio/locust/pull/2729) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Ensure spawning\\_complete only happens once on workers [\\#2728](https://github.com/locustio/locust/pull/2728) ([cyberw](https://github.com/cyberw))\n- Improve confusing log messages if someone accidentally accesses the Web UI over HTTPS [\\#2727](https://github.com/locustio/locust/pull/2727) ([cyberw](https://github.com/cyberw))\n- Show Reset Button when Test is Stopped [\\#2726](https://github.com/locustio/locust/pull/2726) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n\n## [2.28.0](https://github.com/locustio/locust/tree/2.28.0) (2024-05-23)\n\n[Full Changelog](https://github.com/locustio/locust/compare/2.27.0...2.28.0)\n\n**Fixed bugs:**\n\n- The Charts presentation in the report downloaded by locust is problematic [\\#2706](https://github.com/locustio/locust/issues/2706)\n- Locust insists on using IPv6 despite being in an IPv4 stack. [\\#2689](https://github.com/locustio/locust/issues/2689)\n- When there is an error in the FAILURES of the front-end page when there is a worker, there is no escape. [\\#2674](https://github.com/locustio/locust/issues/2674)\n\n**Closed issues:**\n\n- Pin the headers and aggregated row to the top and bottom of the window [\\#2688](https://github.com/locustio/locust/issues/2688)\n- Remove legacy UI [\\#2673](https://github.com/locustio/locust/issues/2673)\n- TaskSet's `_task_queue` should be a `collections.deque`? [\\#2653](https://github.com/locustio/locust/issues/2653)\n\n**Merged pull requests:**\n\n- Pin the headers to the top of the window [\\#2717](https://github.com/locustio/locust/pull/2717) ([JavierUhagon](https://github.com/JavierUhagon))\n- Dont enable ipv6 for zmq if no ipv6 stack exists [\\#2715](https://github.com/locustio/locust/pull/2715) ([cyberw](https://github.com/cyberw))\n- Give better error message if User subclass doesnt call base constructor [\\#2713](https://github.com/locustio/locust/pull/2713) ([cyberw](https://github.com/cyberw))\n- Stop quoting error messages an extra time in distributed mode [\\#2712](https://github.com/locustio/locust/pull/2712) ([cyberw](https://github.com/cyberw))\n- Lower log levels for exceptions in flask [\\#2711](https://github.com/locustio/locust/pull/2711) ([cyberw](https://github.com/cyberw))\n- Stop HTML escaping errors for /stats/requests endpoint [\\#2710](https://github.com/locustio/locust/pull/2710) ([cyberw](https://github.com/cyberw))\n- Update Stats History on HTML Report [\\#2709](https://github.com/locustio/locust/pull/2709) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- Logging: Only print hostname instead of FQDN [\\#2705](https://github.com/locustio/locust/pull/2705) ([cyberw](https://github.com/cyberw))\n- Remove legacy UI [\\#2703](https://github.com/locustio/locust/pull/2703) ([andrewbaldwin44](https://github.com/andrewbaldwin44))\n- WebUI: update users, spawn\\_rate, host and run\\_time in `parsed_options` \\(for LoadShapes that might access it\\) [\\#2656](https://github.com/locustio/locust/pull/2656) ([raulparada](https://github.com/raulparada))\n\n\n\n\\* *This Changelog was automatically generated by [github_changelog_generator](https://github.com/github-changelog-generator/github-changelog-generator)*\n" }, { "path": "Dockerfile", "content": "# This is a local-use Docker image which illustrates the end-to-end build process for Locust\n\n# Stage 1: Build web front end\nFROM node:22.0.0-alpine AS webui-builder\n\nADD locust/webui locust/webui\nADD package.json .\n\n# long yarn timeout necessary in certain network environments\nRUN yarn webui:install --production --network-timeout 60000\nRUN yarn webui:build\n\n# Stage 2: Build Locust package (make sure any changes here are also reflected in Dockerfile.ci)\nFROM python:3.13-slim AS base\n\nFROM base AS builder\nRUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates git\n# there are no wheels for some packages (geventhttpclient?) for arm64/aarch64, so we need some build dependencies there\nRUN if [ -n \"$(arch | grep 'arm64\\|aarch64')\" ]; then apt install -y --no-install-recommends gcc python3-dev; fi\nRUN python -m venv /opt/venv\nENV PATH=\"/opt/venv/bin:$PATH\"\nENV SKIP_PRE_BUILD=\"true\"\nCOPY . /build\nWORKDIR /build\n# clear locally built assets, dist remains part of the docker context for CI purposes\nRUN rm -rf dist\n# bring in the prebuilt front-end before package installation\nCOPY --from=webui-builder locust/webui/dist locust/webui/dist\n\n# Build the Python project\nENV UV_PROJECT_ENVIRONMENT=\"/opt/venv\"\nADD https://astral.sh/uv/0.7.2/install.sh /uv-installer.sh\nRUN sh /uv-installer.sh && rm /uv-installer.sh\nENV PATH=\"/root/.local/bin/:$PATH\"\nRUN uv build && \\\n pip install dist/*.whl\n\n# Stage 3: Runtime image\nFROM base\nCOPY --from=builder /opt/venv /opt/venv\nENV PATH=\"/opt/venv/bin:$PATH\"\n# turn off python output buffering\nENV PYTHONUNBUFFERED=1\nRUN useradd --create-home locust\n# ensure correct permissions\nRUN chown -R locust /opt/venv\n# perform initial bytecode compilation (brings down total startup time from ~0.9s to ~0.6s)\nRUN locust --version\nUSER locust\nWORKDIR /home/locust\nEXPOSE 8089 5557\nENTRYPOINT [\"locust\"]\n" }, { "path": "Dockerfile.ci", "content": "# This is the image pushed to Dockerhub, containing the built and tested Locust package\n\n# Stage 1: Install Locust package\nFROM python:3.13-slim AS base\n\nFROM base AS builder\nRUN apt-get update && apt-get install -y git \n# there are no wheels for some packages (geventhttpclient?) for arm64/aarch64, so we need some build dependencies there\nRUN if [ -n \"$(arch | grep 'arm64\\|aarch64')\" ]; then apt install -y --no-install-recommends gcc python3-dev; fi\nRUN python -m venv /opt/venv\nENV PATH=\"/opt/venv/bin:$PATH\"\n\n# Install the built Python dist\nCOPY ./dist dist\nRUN pip install dist/*.whl\n\n# Stage 2: Runtime image\nFROM base\nCOPY --from=builder /opt/venv /opt/venv\nENV PATH=\"/opt/venv/bin:$PATH\"\n# turn off python output buffering\nENV PYTHONUNBUFFERED=1\nRUN useradd --create-home locust\n# ensure correct permissions\nRUN chown -R locust /opt/venv\n# perform initial bytecode compilation (brings down total startup time from ~0.9s to ~0.6s)\nRUN locust --version\nUSER locust\nWORKDIR /home/locust\nEXPOSE 8089 5557\nENTRYPOINT [\"locust\"]\n" }, { "path": "LICENSE", "content": "The MIT License\n\nCopyright (c) 2009-2025, Carl Byström, Jonatan Heyman, Lars Holmberg\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\nTHE SOFTWARE." }, { "path": "Makefile", "content": "test:\n\tpytest -vv locust/test\n\n.PHONY: build\nbuild: check-uv check-yarn\n\tuv build\n\ninstall: check-uv\n\tuv sync\n\n.SILENT:\n.PHONY: check-uv\ncheck-uv:\n\tcommand -v uv >/dev/null 2>&1 || { echo >&2 \"Locust requires the uv binary to be available in this shell to build the Python package.\\nSee: https://docs.locust.io/en/stable/developing-locust.html#install-locust-for-development\"; exit 1; }\n\n.SILENT:\n.PHONY: check-yarn\ncheck-yarn:\n\tcommand -v yarn >/dev/null 2>&1 || { echo >&2 \"Locust requires the yarn binary to be available in this shell to build the web front-end.\\nSee: https://docs.locust.io/en/stable/developing-locust.html#making-changes-to-locust-s-web-ui\"; exit 1; }\n\nfrontend_build:\n\tyarn webui:install && yarn webui:build\n\nrelease: build\n\ttwine upload dist/*\n\nsetup_docs_dependencies:\n\tuv sync --all-groups\n\nbuild_docs: setup_docs_dependencies\n\tsphinx-build -b html docs/ docs/_build/\n\n# This command can be used to serve the built documentation at http://localhost for\n# easier offline viewing\n.SILENT:\n.PHONY: serve_docs\nserve_docs:\n\techo \"Serving docs at http://localhost:80\"\n\tpython -m http.server 80 -d docs/_build\n\nchangelog:\n\t@echo \"Not supported any more. Run ./generate_changelog.py instead!\"\n" }, { "path": "README.md", "content": "# Locust\n\n[![PyPI](https://img.shields.io/pypi/v/locust.svg)](https://pypi.org/project/locust/)\n[![Supported Python Versions](https://img.shields.io/pypi/pyversions/locust?color=brightgreen)](https://pypi.org/project/locust/)\n[![Downloads](https://static.pepy.tech/personalized-badge/locust?period=total&units=INTERNATIONAL_SYSTEM&left_color=GREY&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/locust)\n[![GitHub contributors](https://img.shields.io/github/contributors/locustio/locust.svg)](https://github.com/locustio/locust/graphs/contributors)\n[![Support Ukraine Badge](https://bit.ly/support-ukraine-now)](https://github.com/support-ukraine/support-ukraine)\n\nLocust is an open source performance/load testing tool for HTTP and other protocols. Its developer-friendly approach lets you define your tests in regular Python code.\n\nLocust tests can be run from command line or using its web-based UI. Throughput, response times and errors can be viewed in real time and/or exported for later analysis.\n\nYou can import regular Python libraries into your tests, and with Locust's pluggable architecture it is infinitely expandable. Unlike when using most other tools, your test design will never be limited by a GUI or domain-specific language.\n\nTo get started right away, head over to the [documentation](http://docs.locust.io/en/stable/installation.html).\n\n## Features\n\n#### Write user test scenarios in plain old Python\n\nIf you want your users to loop, perform some conditional behaviour or do some calculations, you just use the regular programming constructs provided by Python. Locust runs every user inside its own greenlet (a lightweight process/coroutine). This enables you to write your tests like normal (blocking) Python code instead of having to use callbacks or some other mechanism. Because your scenarios are “just python” you can use your regular IDE, and version control your tests as regular code (as opposed to some other tools that use XML or binary formats)\n\n```python\nfrom locust import HttpUser, task, between\n\nclass QuickstartUser(HttpUser):\n wait_time = between(1, 2)\n\n def on_start(self):\n self.client.post(\"/login\", json={\"username\":\"foo\", \"password\":\"bar\"})\n\n @task\n def hello_world(self):\n self.client.get(\"/hello\")\n self.client.get(\"/world\")\n\n @task(3)\n def view_item(self):\n for item_id in range(10):\n self.client.get(f\"/item?id={item_id}\", name=\"/item\")\n```\n\n#### Distributed & Scalable - supports hundreds of thousands of users\n\nLocust makes it easy to run load tests distributed over multiple machines. It is event-based (using [gevent](http://www.gevent.org/)), which makes it possible for a single process to handle many thousands concurrent users. While there may be other tools that are capable of doing more requests per second on a given hardware, the low overhead of each Locust user makes it very suitable for testing highly concurrent workloads.\n\n#### Web-based UI\n\nLocust has a user friendly web interface that shows the progress of your test in real-time. You can even change the load while the test is running. It can also be run without the UI, making it easy to use for CI/CD testing.\n\n\n\n\n\"Locust\n\n\n\n\n\"Locust\n\n\n\n\n\"Locust\n\n\n\n\n\"Locust\n\n\n#### Can test any system\n\nEven though Locust primarily works with web sites/services, it can be used to test almost any system or protocol. Just [write a client](https://docs.locust.io/en/latest/testing-other-systems.html#testing-other-systems) for what you want to test, or [explore some created by the community](https://github.com/SvenskaSpel/locust-plugins#users).\n\n## Hackable\n\nLocust's code base is intentionally kept small and doesn't solve everything out of the box. Instead, we try to make it easy to adapt to any situation you may come across, using regular Python code. There is nothing stopping you from: \n\n* [Send real time reporting data to TimescaleDB and visualize it in Grafana](https://github.com/SvenskaSpel/locust-plugins/blob/master/locust_plugins/dashboards/README.md)\n* [Wrap calls to handle the peculiarities of your REST API](https://github.com/SvenskaSpel/locust-plugins/blob/8af21862d8129a5c3b17559677fe92192e312d8f/examples/rest_ex.py#L87) \n* [Use a totally custom load shape/profile](https://docs.locust.io/en/latest/custom-load-shape.html#custom-load-shape)\n* [...](https://github.com/locustio/locust/wiki/Extensions)\n\n## Links\n\n* Documentation: [docs.locust.io](https://docs.locust.io)\n* Support/Questions: [StackOverflow](https://stackoverflow.com/questions/tagged/locust)\n* Github Discussions: [Github Discussions](https://github.com/orgs/locustio/discussions)\n* Chat/discussion: [Slack](https://locustio.slack.com) [(signup)](https://communityinviter.com/apps/locustio/locust)\n\n## Authors\n\n* Maintainer: [Lars Holmberg](https://github.com/cyberw)\n* UI: [Andrew Baldwin](https://github.com/andrewbaldwin44)\n* Original creator: [Jonatan Heyman](https://github.com/heyman)\n* Massive thanks to [all of our contributors](https://github.com/locustio/locust/graphs/contributors)\n\n## License\n\nOpen source licensed under the MIT license (see _LICENSE_ file for details).\n" }, { "path": "SECURITY.md", "content": "# Security Policy\n\n## Supported Versions\n\nOnly latest version is actively supported, but issues reported for earlier minor will be considered if they are serious.\n\n## Reporting a Vulnerability\n\nReported using regular GitHub issues. If there is some reason an issue cannot be made public before a fix has been made, contact @cyberw directly.\n\n## Use Locust safely\n\nLocust is not intended to be deployed on a public-facing server. By default the web UI is only exposed on localhost, so normally this is not a problem.\n\nDo not give someone access to the web UI unless you trust them with everything else that is on that machine.\n\n## Use Locust nicely\n\nDo not load test public web sites/services that you do not own.\n" }, { "path": "Vagrantfile", "content": "Vagrant.configure(\"2\") do |config|\n config.vm.box = \"ubuntu/xenial32\"\n config.vm.network :forwarded_port, guest: 8089, host: 8089\n config.vm.provision :shell, :path => \"examples/vagrant/vagrant.sh\"\nend\n" }, { "path": "benchmarks/dispatch.py", "content": "\"\"\"\nThis file contains a benchmark to validate the performance of Locust itself.\nMore precisely, the performance of the `UsersDispatcher` class which is responsible\nfor calculating the distribution of users on each worker. This benchmark is to be used\nby people working on Locust's development.\n\"\"\"\n\nfrom locust import User\nfrom locust.dispatch import UsersDispatcher\nfrom locust.runners import WorkerNode\n\nimport argparse\nimport gc\nimport itertools\nimport statistics\nimport time\n\nfrom prettytable import PrettyTable\n\nNUMBER_OF_USER_CLASSES: int = 1000\nUSER_CLASSES: list[type[User]] = []\nWEIGHTS = list(range(1, NUMBER_OF_USER_CLASSES + 1))\n\nfor i, x in enumerate(WEIGHTS):\n exec(f\"class User{i}(User): weight = {x}\")\n\n# Equivalent to:\n#\n# class User0(User):\n# weight = 5\n#\n# class User1(User):\n# weight = 55\n# .\n# .\n# .\n\nexec(\"USER_CLASSES = [\" + \",\".join(f\"User{i}\" for i in range(len(WEIGHTS))) + \"]\")\n# Equivalent to:\n#\n# USER_CLASSES = [\n# User0,\n# User1,\n# .\n# .\n# .\n# ]\n\n\nif __name__ == \"__main__\":\n parser = argparse.ArgumentParser()\n parser.add_argument(\"-f\", \"--full-benchmark\", action=\"store_true\", help=\"run benchmark on full test matrix\")\n parser.add_argument(\n \"-i\",\n \"--include-fixed-users\",\n action=\"store_true\",\n help=\"add test cases when 50 percent of users use User.fixed_count instead of User.weight\",\n )\n parser.add_argument(\"-r\", \"--repeat\", default=1, type=int, help=\"number of test cases with the same parameters\")\n parser.add_argument(\"-s\", \"--save-output\", action=\"store_true\", help=\"save test results to files\")\n args = parser.parse_args()\n\n now = time.time()\n\n worker_count_cases = [10, 100, 1000]\n user_count_cases = [10_000, 100_000, 1_000_000]\n number_of_user_classes_cases = [1, 30, 1000]\n spawn_rate_cases = [100, 10_000]\n fixed_count_cases = [False, True] if args.include_fixed_users else [False]\n # [0% fixed_count users, 50% fixed_count users] if args.mixed_user_types else [0% fixed_count users]\n repeat_cases = list(range(1, args.repeat + 1))\n\n if not args.full_benchmark:\n worker_count_cases = [max(worker_count_cases)]\n user_count_cases = [max(user_count_cases)]\n number_of_user_classes_cases = [max(number_of_user_classes_cases)]\n spawn_rate_cases = [max(spawn_rate_cases)]\n\n case_count = (\n len(worker_count_cases)\n * len(user_count_cases)\n * len(number_of_user_classes_cases)\n * len(spawn_rate_cases)\n * len(fixed_count_cases)\n * len(repeat_cases)\n )\n\n results = {}\n\n try:\n for case_index, (\n worker_count,\n user_count,\n number_of_user_classes,\n spawn_rate,\n fixed_users,\n iteration,\n ) in enumerate(\n itertools.product(\n worker_count_cases,\n user_count_cases,\n number_of_user_classes_cases,\n spawn_rate_cases,\n fixed_count_cases,\n repeat_cases,\n )\n ):\n workers = [WorkerNode(str(i)) for i in range(worker_count)]\n if fixed_users:\n sum_fixed_weight = 0\n for j in range(0, number_of_user_classes, 2):\n sum_fixed_weight += USER_CLASSES[j].weight\n\n for j in range(0, number_of_user_classes, 2): # set fixed_weights for 50% of users\n USER_CLASSES[j].fixed_count = max(1, USER_CLASSES[j].weight // sum_fixed_weight) # type: ignore # assigned .weight is int\n\n ts = time.process_time()\n users_dispatcher = UsersDispatcher(\n worker_nodes=workers,\n user_classes=USER_CLASSES[:number_of_user_classes],\n )\n instantiate_duration = time.process_time() - ts\n\n # Ramp-up\n gc.disable()\n ts = time.process_time()\n users_dispatcher.new_dispatch(target_user_count=user_count, spawn_rate=spawn_rate)\n new_dispatch_ramp_up_duration = time.process_time() - ts\n gc.enable()\n\n assert len(users_dispatcher.dispatch_iteration_durations) == 0\n users_dispatcher._wait_between_dispatch = 0\n all_dispatched_users_ramp_up = list(users_dispatcher)\n dispatch_iteration_durations_ramp_up = users_dispatcher.dispatch_iteration_durations[:]\n\n # Ramp-down\n gc.disable()\n ts = time.process_time()\n users_dispatcher.new_dispatch(target_user_count=0, spawn_rate=spawn_rate)\n new_dispatch_ramp_down_duration = time.process_time() - ts\n gc.enable()\n\n assert len(users_dispatcher.dispatch_iteration_durations) == 0\n users_dispatcher._wait_between_dispatch = 0\n all_dispatched_users_ramp_down = list(users_dispatcher)\n dispatch_iteration_durations_ramp_down = users_dispatcher.dispatch_iteration_durations[:]\n\n if fixed_users:\n for j in range(0, number_of_user_classes, 2):\n USER_CLASSES[j].fixed_count = None\n\n cpu_ramp_up = \"{:3.3f}/{:3.3f}/{:3.3f}\".format( # noqa: UP032\n 1000 * statistics.mean(dispatch_iteration_durations_ramp_up),\n 1000 * min(dispatch_iteration_durations_ramp_up),\n 1000 * max(dispatch_iteration_durations_ramp_up),\n ) # noqa: UP032\n cpu_ramp_down = \"{:3.3f}/{:3.3f}/{:3.3f}\".format( # noqa: UP032\n 1000 * statistics.mean(dispatch_iteration_durations_ramp_down),\n 1000 * min(dispatch_iteration_durations_ramp_down),\n 1000 * max(dispatch_iteration_durations_ramp_down),\n )\n\n print(\n \"{:04.0f}/{:04.0f} - {:,} workers - {:,} users - {} user classes - {:,} users/s - instantiate: {:.3f}ms - new_dispatch (ramp-up/ramp-down): {:.3f}ms/{:.3f}ms - cpu_ramp_up: {}ms - cpu_ramp_down: {}ms\".format( # noqa: UP032\n case_index + 1,\n case_count,\n worker_count,\n user_count,\n number_of_user_classes,\n spawn_rate,\n instantiate_duration * 1000,\n new_dispatch_ramp_up_duration * 1000,\n new_dispatch_ramp_down_duration * 1000,\n cpu_ramp_up,\n cpu_ramp_down,\n )\n )\n\n results[(worker_count, user_count, number_of_user_classes, spawn_rate, fixed_users, iteration)] = (\n cpu_ramp_up,\n cpu_ramp_down,\n )\n\n finally:\n table = PrettyTable()\n table.field_names = [\n \"Workers\",\n \"Users\",\n \"User Classes\",\n \"Spawn Rate\",\n \"Fixed Users\",\n \"Iteration\",\n \"Ramp-Up (avg/min/max) (ms)\",\n \"Ramp-Down (avg/min/max) (ms)\",\n ]\n table.align[\"Workers\"] = \"l\"\n table.align[\"Users\"] = \"l\"\n table.align[\"User Classes\"] = \"l\"\n table.align[\"Spawn Rate\"] = \"l\"\n table.align[\"Fixed Users\"] = \"l\"\n table.align[\"Iteration\"] = \"c\"\n table.align[\"Ramp-Up (avg/min/max) (ms)\"] = \"c\"\n table.align[\"Ramp-Down (avg/min/max) (ms)\"] = \"c\"\n table.add_rows(\n [\n [\n f\"{worker_count:,}\",\n f\"{user_count:,}\",\n number_of_user_classes,\n f\"{spawn_rate:,}\",\n \"50%\" if fixed_users else \"0%\",\n iteration,\n cpu_ramp_up,\n cpu_ramp_down,\n ]\n for (worker_count, user_count, number_of_user_classes, spawn_rate, fixed_users, iteration), (\n cpu_ramp_up,\n cpu_ramp_down,\n ) in results.items()\n ]\n )\n print()\n print(table)\n\n if args.save_output:\n with open(f\"results-dispatch-benchmarks-{int(now)}.txt\", \"w\") as file:\n file.write(table.get_string())\n\n with open(f\"results-dispatch-benchmarks-{int(now)}.json\", \"w\") as file:\n file.write(table.get_json_string())\n" }, { "path": "docs/_static/theme-overrides.css", "content": "/* Make it possible to have multiline table cells by removing white-space:nowrap */\n.wy-table-responsive table td, .wy-table-responsive table th {\n white-space: normal;\n}\n.wy-table-responsive {\n margin-bottom: 24px;\n max-width: 100%;\n overflow: visible;\n}\n" }, { "path": "docs/_templates/footer.html", "content": "{% extends \"!footer.html\" %}\n{% block extrafooter %}\n {{ super }}\n \n{% endblock %}\n" }, { "path": "docs/api.rst", "content": "###\nAPI\n###\n\n\nUser class\n============\n\n.. autoclass:: locust.User\n :members: wait_time, tasks, weight, fixed_count, abstract, on_start, on_stop, wait, context, environment\n\nHttpUser class\n================\n\n.. autoclass:: locust.HttpUser\n :members: wait_time, tasks, client, abstract\n\nHttpSession class\n=================\n\n.. autoclass:: locust.clients.HttpSession\n :members: __init__, request, get, post, delete, put, head, options, patch\n\nFastHttpUser class\n==================\n\n.. autoclass:: locust.contrib.fasthttp.FastHttpUser\n :members: wait_time, tasks, client, abstract, rest\n :noindex:\n\nMqttUser class\n==================\n.. autoclass:: locust.contrib.mqtt.MqttUser\n :members: __init__, host, port, transport, ws_path, tls_context, client_cls, client_id, username, password, protocol \n\n.. _socketio:\n\nSocketIOUser class\n==================\n\n.. autoclass:: locust.contrib.socketio.SocketIOUser\n :members: connect, call, emit, send, on_message, client, options\n :noindex:\n\nFastHttpSession class\n=====================\n\n.. autoclass:: locust.contrib.fasthttp.FastHttpSession\n :members: __init__, request, get, post, delete, put, head, options, patch, iter_lines\n\nPostgresUser class\n==================\n\n.. autoclass:: locust.contrib.postgres.PostgresUser\n :members: wait_time, tasks, client, abstract\n :noindex:\n\nMongoDBUser class\n=================\n\n.. autoclass:: locust.contrib.mongodb.MongoDBUser\n :members: wait_time, tasks, client, abstract\n :noindex:\n\nMilvusUser class\n================\n\n.. autoclass:: locust.contrib.milvus.MilvusUser\n :members: wait_time, tasks, client, abstract\n :noindex:\n\nQdrantUser class\n================\n\n.. autoclass:: locust.contrib.qdrant.QdrantUser\n :members: wait_time, tasks, client, abstract\n :noindex:\n\nDNSUser class\n==========\n\n.. autoclass:: locust.contrib.dns.DNSUser\n :members: client\n :noindex:\n\nTaskSet class\n=============\n\n.. autoclass:: locust.TaskSet\n :members: user, parent, wait_time, client, tasks, interrupt, schedule_task, on_start, on_stop, wait\n\ntask decorator\n==============\n\n.. autofunction:: locust.task\n\ntag decorator\n==============\n\n.. autofunction:: locust.tag\n\nSequentialTaskSet class\n=======================\n\n.. autoclass:: locust.SequentialTaskSet\n :members: user, parent, wait_time, client, tasks, interrupt, schedule_task, on_start, on_stop\n\n\n.. _wait_time_functions:\n\nBuilt in wait_time functions\n============================\n\n.. automodule:: locust.wait_time\n :members: between, constant, constant_pacing, constant_throughput\n\nResponse class\n==============\n\nThis class actually resides in the `requests `_ library, \nsince that's what Locust is using to make HTTP requests, but it's included in the API docs \nfor locust since it's so central when writing locust load tests. You can also look at the \n:py:class:`Response ` class at the \n`requests documentation `_.\n\n.. autoclass:: requests.Response\n :inherited-members:\n :noindex:\n\nResponseContextManager class\n============================\n\n.. autoclass:: locust.clients.ResponseContextManager\n :members: success, failure\n\n\n.. _exceptions:\n\nExceptions\n==========\n\n.. autoexception:: locust.exception.InterruptTaskSet\n\n\n.. autoexception:: locust.exception.RescheduleTask\n\n\n.. autoexception:: locust.exception.RescheduleTaskImmediately\n\n\nEnvironment class\n=================\n.. autoclass:: locust.env.Environment\n :members:\n\n\n.. _events:\n\nEvent hooks\n===========\n\nLocust provides event hooks that can be used to extend Locust in various ways.\n\nThe following event hooks are available under :py:attr:`Environment.events `, \nand there's also a reference to these events under ``locust.events`` that can be used at the module level \nof locust scripts (since the Environment instance hasn't been created when the locustfile is imported).\n\n.. autoclass:: locust.event.Events\n :members:\n\n\n.. note::\n\n It's highly recommended that you add a wildcard keyword argument in your event listeners\n to prevent your code from breaking if new arguments are added in a future version.\n\nEventHook class\n---------------\n\nThe event hooks are instances of the **locust.events.EventHook** class:\n\n.. autoclass:: locust.event.EventHook\n :members:\n\nRunner classes\n=====================\n\n.. autoclass:: locust.runners.Runner\n :members: start, stop, quit, user_count\n\n.. autoclass:: locust.runners.LocalRunner\n\n.. autoclass:: locust.runners.MasterRunner\n :members: register_message, send_message\n\n.. autoclass:: locust.runners.WorkerRunner\n :members: register_message, send_message, client_id, worker_index\n\nWeb UI class\n============\n\n.. autoclass:: locust.web.WebUI\n :members:\n\nOther\n=====\n\n.. autoclass:: locust.shape.LoadTestShape\n :members:\n\n.. autoclass:: locust.stats.RequestStats\n :members: get\n\n.. autoclass:: locust.stats.StatsEntry\n\n.. autofunction:: locust.debug.run_single_user\n" }, { "path": "docs/changelog.rst", "content": "####################\nChangelog Highlights\n####################\n\nFor full details of changes, please see https://github.com/locustio/locust/releases or https://github.com/locustio/locust/blob/master/CHANGELOG.md\n\n2.43.3\n======\n* Update dependencies and some documentation, no functional changes\n\n2.43.2\n======\n* Upgrade various dependencies, no functional changes https://github.com/locustio/locust/pull/3339, https://github.com/locustio/locust/pull/3343, https://github.com/locustio/locust/pull/3342, https://github.com/locustio/locust/pull/3341, https://github.com/locustio/locust/pull/3340\n\n2.43.1\n======\n* Upgrade various Web UI dependencies, no other changes\n\n2.43.0\n======\n* Capture stacktrace on KeyboardInterrupt on greenlets https://github.com/locustio/locust/pull/3306\n* Solving iter_lines problem https://github.com/locustio/locust/pull/3311\n* Allow users to stop test run by raising StopTest, use it on missing host https://github.com/locustio/locust/pull/3313\n* Remove references to locust.cloud now that it is shutting down https://github.com/locustio/locust/pull/3314\n* Support requests>=2.32.5, reimplement the fix previously there for only loading ssl certificates once https://github.com/locustio/locust/pull/3316\n\n2.42.6\n======\n* GH Actions: Bump actions/checkout from 5 to 6 https://github.com/locustio/locust/pull/3287\n* Fix Toml Parser Being Called on .conf Files https://github.com/locustio/locust/pull/3293\n* Log duplicate client_ready messages as debug instead of info level https://github.com/locustio/locust/pull/3296\n* Various minor code modernization https://github.com/locustio/locust/pull/3299, https://github.com/locustio/locust/pull/3301\n* Don't import pytest unless it is really needed, to speed up startup https://github.com/locustio/locust/pull/3296\n\n2.42.5\n======\n* Log when otel is enabled https://github.com/locustio/locust/pull/3284\n\n2.42.4\n======\n* Update pytest dependency range https://github.com/locustio/locust/pull/3263\n* Allow multiple dropdown in Web UI https://github.com/locustio/locust/pull/3261\n* Add OpenTelemetry support https://github.com/locustio/locust/pull/3275, https://github.com/locustio/locust/pull/3276, https://github.com/locustio/locust/pull/3278, https://github.com/locustio/locust/pull/3279\n\n2.42.3\n======\n* Fix single line .conf files incorrectly being treated as toml https://github.com/locustio/locust/pull/3257\n* Update various GitHub actions used in the build https://github.com/locustio/locust/pull/3266, https://github.com/locustio/locust/pull/3259\n\n2.42.2\n======\n* Remove setuptools from dependencies https://github.com/locustio/locust/pull/3253\n* Fix an issue with .conf-files https://github.com/locustio/locust/pull/3256\n\n2.42.1\n======\n\n* Add VS Code Extension and k8s Operator to documentation https://github.com/locustio/locust/pull/3251\n\n2.42.0\n======\n* Introduce DNSUser https://github.com/locustio/locust/pull/3243\n* Dependencies: allow gevent >25.8.1, avoid python-requests >2.32.5\n\n2.41.6\n======\n* Officially support Python 3.14 https://github.com/locustio/locust/pull/3235\n\n2.41.5\n======\n* Fix FastHttpUser handling of 308 response code\n* Fix Unsafe Template Arg https://github.com/locustio/locust/pull/3232\n\n2.41.4\n======\n(skipped because of failed publishing)\n\n2.41.3\n======\n* Make workers correctly ignore the --run-time flag https://github.com/locustio/locust/pull/3230\n\n2.41.2\n======\n* Fix Alignment of View Column Selector https://github.com/locustio/locust/pull/3226\n* Pytest plugin: Workaround issue with potential duplicate --host argument definition https://github.com/locustio/locust/pull/3228\n\n2.41.1\n======\n* Fix incorrect url for feedback form\n\n2.41.0\n======\n* Suggest possibly misspelled command line arguments (Did you mean ...) https://github.com/locustio/locust/pull/3224\n* Add Feedback Form https://github.com/locustio/locust/pull/3223\n* Add MqttUser https://github.com/locustio/locust/pull/3216\n\n2.40.5\n======\n* Avoid wrapping FastResponse in response context manager when not needed https://github.com/locustio/locust/pull/3222\n\n2.40.4\n======\n* Avoid pytest style locustfiles capturing keyboard input https://github.com/locustio/locust/pull/3219\n\n2.40.3\n======\n* Make ResponseContextManager.raise_for_status() consider calls to failure() and success() https://github.com/locustio/locust/pull/3217\n\n2.40.2\n======\n* Refactor clients.ResponseContextManager and fix GC issue https://github.com/locustio/locust/pull/3210\n* Refactor SocketIOUser to create separate SocketIOClient class https://github.com/locustio/locust/pull/3211\n\n2.40.1\n======\n* Pytest plugin: Delay imports to avoid monkey patching until someone actually uses the fixtures https://github.com/locustio/locust/pull/3204 https://github.com/locustio/locust/pull/3205\n\n2.40.0\n======\n* Add support for pytests as locustfiles https://github.com/locustio/locust/pull/3200\n* Refactor FastHttpSession slightly https://github.com/locustio/locust/pull/3198\n* Update Dockerfile base to Python 3.13 https://github.com/locustio/locust/pull/3193\n\n2.39.1\n======\n* Avoid broken gevent version for now by @cyberw in https://github.com/locustio/locust/pull/3196\n\n2.39.0\n======\n* Add MilvusUser https://github.com/locustio/locust/pull/3168\n* Add SocketIOUser https://github.com/locustio/locust/pull/3189\n\n2.38.1\n======\n* FastHttpUser: Dont send zstd in Accept-Encoding header https://github.com/locustio/locust/pull/3188\n\n2.38.0\n======\n* Add MarkovTaskSet https://github.com/locustio/locust/pull/3176\n* Support for list based custom arguments https://github.com/locustio/locust/pull/3181\n* Webui fixes https://github.com/locustio/locust/pull/3177 & https://github.com/locustio/locust/pull/3185\n\n2.37.14\n=======\n* Web UI: Fix Chart Zoom Slider https://github.com/locustio/locust/pull/3174\n\n2.37.13\n=======\n* Web UI: Shrink Bundle Size by https://github.com/locustio/locust/pull/3169\n* Remove safe_name from /stats/requests response https://github.com/locustio/locust/pull/3171\n\n2.37.12\n=======\n* Attempt to increase open file limit (RLIMIT_NOFILE) even on master https://github.com/locustio/locust/pull/3162\n\n2.37.11\n=======\n* Web UI: Always Warn of Invalid Host https://github.com/locustio/locust/pull/3155\n* locust-cloud: bump minimum version and support multiple locustfiles https://github.com/locustio/locust/pull/3157 / https://github.com/locustcloud/locust-cloud/pull/38\n\n2.37.10\n=======\n* Revert accidental removal of --json-file option https://github.com/locustio/locust/pull/3154\n\n2.37.9\n======\n* Web UI: Fix host field name missing if host is not required https://github.com/locustio/locust/pull/3152\n\n2.37.8\n======\n* Allow 25.x versions of gevent https://github.com/locustio/locust/pull/3151\n\n2.37.7\n======\n* Web Ui: Add host field validation https://github.com/locustio/locust/pull/3149\n\n2.37.6\n======\n* Doc updates, including a fix for config options https://github.com/locustio/locust/pull/3145\n* Bumped minimum ConfigArgParse dependency to 1.7.1\n\n2.37.5\n======\n* Locust Cloud: Stop requiring a locustfile when doing --login or --delete https://github.com/locustio/locust/pull/3141\n\n2.37.4\n======\n* Bump minimum version of locust-cloud\n\n2.37.3\n======\n* Webui: Warn on Missing Host https://github.com/locustio/locust/pull/3140\n\n2.37.2\n======\n* Improve the performance of the `/stats/requests` endpoint when there are >500 unique request names https://github.com/locustio/locust/pull/3136\n* Webui: Block starting test in distributed mode until workers have connected https://github.com/locustio/locust/pull/3138\n\n2.37.1\n======\n* Fix --json-file https://github.com/locustio/locust/pull/3131\n\n2.37.0\n======\n* Update uv to 0.7.2\n* Add --json-file by https://github.com/locustio/locust/pull/3124\n* Minor fixes\n\n2.36.3\n======\n* Bump minimum locust-cloud version + some minor fixes\n\n2.36.2\n======\n* Remove circular dependency between locust and locust-cloud https://github.com/locustio/locust/pull/3119\n\n2.36.1\n======\n* Ensure correct version of gevent on Python 3.12\n\n2.36.0\n======\n* Add locust-cloud as a dependency, so you can now run it using ``locust --cloud`` https://github.com/locustio/locust/pull/3097\n* Various minor UI fixes & changes to build process https://github.com/locustio/locust/pull/3104, https://github.com/locustio/locust/pull/3107, https://github.com/locustio/locust/pull/3116\n* Refactorings in main() https://github.com/locustio/locust/pull/3101, https://github.com/locustio/locust/pull/3102\n* Narrow gevent version requirements to avoid incompatible new version for now https://github.com/locustio/locust/pull/3112\n\n2.35.0\n======\n* Add profile argument and display in html report https://github.com/locustio/locust/pull/3093\n* Various UI fixes and dependency updates\n\n2.34.1\n======\n* Drop support for Python 3.9 https://github.com/locustio/locust/pull/3090\n\n2.34.0\n======\n* Add experimental OpenAIUser and example https://github.com/locustio/locust/pull/3081\n* Make the Locust UI Responsive and work for smaller screens https://github.com/locustio/locust/pull/3083, https://github.com/locustio/locust/pull/3086\n* Tiny fixes & version bumps\n\n2.33.2\n======\n* Optimize docker startup time https://github.com/locustio/locust/pull/3073\n* Various dependency updates\n\n2.33.1\n======\n* Fix html report file naming crash https://github.com/locustio/locust/pull/3072\n\n2.33.0\n======\n* Press enter to automatically open web UI in browser https://github.com/locustio/locust/pull/3057\n* Enable HTML Report Filename Parsing https://github.com/locustio/locust/pull/3049\n* Various minor fixes and dependency updates\n\n2.32.10\n=======\n* Use uv/hatch instead of Poetry https://github.com/locustio/locust/pull/3039\n\n2.32.9\n======\n* Fix issue where empty WebUI property is not parsed correctly https://github.com/locustio/locust/pull/3012\n* Add iter_lines method to FastHttpSession https://github.com/locustio/locust/pull/3024\n\n2.32.8\n======\n* Fix a single broken link in the UI\n\n2.32.7\n======\n* Fix readme image ref links by @changchaishi in https://github.com/locustio/locust/pull/3031\n* Add tab showing `Locust Cloud `_ features https://github.com/locustio/locust/pull/3032\n* Minor UI enhancements https://github.com/locustio/locust/pull/3035, https://github.com/locustio/locust/pull/3036, https://github.com/locustio/locust/pull/3037\n* Code quality: Fix unused imports and switch on related ruff check https://github.com/locustio/locust/pull/3034\n\n2.32.6\n======\n* Update Dockerfile to use Python 3.12 https://github.com/locustio/locust/pull/3029\n* Remove deprecated --hatch-rate parameter https://github.com/locustio/locust/pull/3026\n\n2.32.5\n======\n* Treat exceptions in init event handler as fatal https://github.com/locustio/locust/pull/3009\n* FastHttpUser: Fix SSL certificate loading performance issue https://github.com/locustio/locust/pull/3013\n* Delay CPU usage checks to make it less likely to generate false positives during process startup https://github.com/locustio/locust/pull/3014\n\n2.32.4\n======\n* Minor doc updates https://github.com/locustio/locust/pull/2990, https://github.com/locustio/locust/pull/2989, https://github.com/locustio/locust/pull/2993\n* UI fixes and dependency updates https://github.com/locustio/locust/pull/2992 https://github.com/locustio/locust/pull/2997, https://github.com/locustio/locust/pull/3002, https://github.com/locustio/locust/pull/2999\n* Fix missing last requests in web UI https://github.com/locustio/locust/pull/3001\n\n2.32.3\n======\n* Add option for Extra Options to be Required https://github.com/locustio/locust/pull/2981\n* Use debug log level for first 5s of waiting for workers to be ready https://github.com/locustio/locust/pull/2982\n* Ensure we never use old version of setuptools https://github.com/locustio/locust/pull/2988\n\n2.32.2\n======\n* Better html report file names https://github.com/locustio/locust/pull/2947\n* Fix Incorrectly Updating Stat History https://github.com/locustio/locust/pull/2972\n* Various WebUI fixes (most only relevant for https://locust.cloud)\n\n2.32.1\n======\n* Various WebUI fixes (most only relevant for https://locust.cloud)\n* LocustBadStatusCode without url param in fasthttp https://github.com/locustio/locust/pull/2944\n\n2.32.0\n======\n* Explicitly support Python 3.13 https://github.com/locustio/locust/pull/2939\n* Log deprecation warning for Python 3.9 https://github.com/locustio/locust/pull/2940\n* Decide if ipv6 can work (especially relevant for EKS) https://github.com/locustio/locust/pull/2923\n* Various minor fixes\n\n2.31.8\n======\n* Minor fixes, nothing worth mentioning.\n\n2.31.7\n======\n* Log locust version earlier https://github.com/locustio/locust/pull/2904\n* Improve Web UI Logging https://github.com/locustio/locust/pull/2911\n\n2.31.6\n======\n* Various documentation and type hint fixes.\n* Fix issue when using --config-users to set weight to 0 https://github.com/locustio/locust/pull/2891\n* Add worker_count = 1 to LocalRunner for parity with MasterRunner https://github.com/locustio/locust/pull/2900/files\n* Tiny WebUI fixes https://github.com/locustio/locust/pull/2901, https://github.com/locustio/locust/pull/2902\n\n2.31.5\n======\n* WebUI: Correct types for form select https://github.com/locustio/locust/pull/2872\n* Web UI Remove Scroll to Zoom https://github.com/locustio/locust/pull/2876\n* Webui Remove chart initial data fetch https://github.com/locustio/locust/pull/2878\n* Improved Build Pipeline https://github.com/locustio/locust/pull/2873, https://github.com/locustio/locust/pull/2879, https://github.com/locustio/locust/pull/2880\n\n2.31.4\n======\n* Publish UI NPM package to simplify use from custom UIs (https://locust.cloud)\n* Some tiny UI fixes\n\n2.31.3\n======\n* Use new logo in web UI + some minor improvements https://github.com/locustio/locust/pull/2844, https://github.com/locustio/locust/pull/2840, https://github.com/locustio/locust/pull/2846, https://github.com/locustio/locust/pull/2850, https://github.com/locustio/locust/pull/2847, https://github.com/locustio/locust/pull/2855\n* Update GitHub action versions https://github.com/locustio/locust/pull/2853\n\n2.31.2\n======\n* Prebuild UI in PyPi publish steps so that even source distributions contain web UI code https://github.com/locustio/locust/pull/2839\n\n2.31.1\n======\n* Fix issue with downloading HTML report https://github.com/locustio/locust/pull/2834\n\n2.31.0\n======\n* Fix HTML Report Stats Table https://github.com/locustio/locust/pull/2817\n* URL Directory, and Multi-File Support for Locustfile Distribution https://github.com/locustio/locust/pull/2766\n* Various UI improvements https://github.com/locustio/locust/pull/2815, https://github.com/locustio/locust/pull/2804, https://github.com/locustio/locust/pull/2824, https://github.com/locustio/locust/pull/2825, https://github.com/locustio/locust/pull/2826, https://github.com/locustio/locust/pull/2828\n* Fix docker image build https://github.com/locustio/locust/pull/2830\n\n2.30.0\n======\n* FastHttpSession: Enable passing json as a positional argument for post() and stop converting response times to int https://github.com/locustio/locust/pull/2772\n* New events for heartbeat and usage monitor https://github.com/locustio/locust/pull/2777\n* SequentialTaskSet: Allow weighted tasks and dict in .tasks (experimental) https://github.com/locustio/locust/pull/2742\n* Implement Poetry build system (mainly so we don't have to commit the built frontend resources to git) https://github.com/locustio/locust/pull/2725\n* UI: Replace total avg response time with 50 percentile (avg was broken) https://github.com/locustio/locust/pull/2806\n* Avoid deadlock in gevent/urllib3 connection pool (fixes occasional worker heartbeat timeouts) https://github.com/locustio/locust/pull/2813\n* This release got no docker image due to a build error\n\n2.29.1\n======\n* Add option to Skip Monkey Patching with LOCUST_SKIP_MONKEY_PATCH https://github.com/locustio/locust/pull/2765\n* HttpSession requests typing https://github.com/locustio/locust/pull/2699\n* Add proxy support for FastHttpUser https://github.com/locustio/locust/pull/2758\n\n2.29.0\n======\n* Ensure spawning_complete only happens once on workers https://github.com/locustio/locust/pull/2728\n* Correct time in the downloaded HTML report https://github.com/locustio/locust/pull/2729\n* Add date and zoom to charts in web UI https://github.com/locustio/locust/pull/2731\n* Send logs from workers to master and improve log viewer tab in the Web UI https://github.com/locustio/locust/pull/2750\n* Docs: Upgrade Sphinx and theme, Fix API TOC, import wiki to docs, and mention installing Locust in Building the Docs\n\n2.28.0\n======\n* Remove legacy UI https://github.com/locustio/locust/pull/2703\n* Stop HTML escaping errors for /stats/requests endpoint https://github.com/locustio/locust/pull/2710\n* Various minor UI & logging improvements\n\n2.27.0\n======\n* Simplify how locustfiles are found (using -f). Don’t automatically append .py https://github.com/locustio/locust/pull/2655\n* Use more efficient algorithm to calculate user distribution, and allow float weights https://github.com/locustio/locust/pull/2686\n* Various minor fixes\n\n2.26.0\n======\n* Drop support for Python 3.8\n* Update geventhttpclient and adjust FastHttpUser max_retries / max_redirects (https://github.com/locustio/locust/pull/2676)\n* Pin gevenhttpclient version (https://github.com/locustio/locust/pull/2682)\n\n2.25.0\n======\n* Add functionality to run listener functions for `custom_messages` concurrently (https://github.com/locustio/locust/pull/2650)\n* Update User Classes in Distributed Mode (https://github.com/locustio/locust/pull/2666)\n* Log deprecation warning for --legacy-ui (https://github.com/locustio/locust/pull/2670)\n* Fix UserClasses weight distribution with gcd (https://github.com/locustio/locust/pull/2663)\n\n2.24.1\n======\n* Some documentation updates & minor fixes to UI\n* Fixes to FastHttpUser content streaming (https://github.com/locustio/locust/pull/2642, https://github.com/locustio/locust/pull/2643)\n\n2.24.0\n======\n* Pluggable dispatcher logic https://github.com/locustio/locust/pull/2606\n* pyproject.toml support for Locust configuration file https://github.com/locustio/locust/pull/2612\n* Minor fixes\n\n2.23.1\n======\n* Fixes for locustfile download https://github.com/locustio/locust/pull/2599\n* UI fixes https://github.com/locustio/locust/pull/2600 https://github.com/locustio/locust/pull/2601\n\n2.23.0\n======\n* UI updates (https://github.com/locustio/locust/pull/2589, https://github.com/locustio/locust/pull/2590, https://github.com/locustio/locust/pull/2596)\n* Locustfile distribution from master to worker https://github.com/locustio/locust/pull/2583\n* Allow getting locust files from http urls https://github.com/locustio/locust/pull/2595\n* Use exec_module() when loading locustfile instead of the deprecated load_module() https://github.com/locustio/locust/pull/2576\n\n2.22.0\n======\n* Use Modern UI by default, remove --modern-ui and add --legacy-ui parameters https://github.com/locustio/locust/pull/2569\n\n2.21.0\n======\n* Switch from flake8 + black to ruff for linting and formatting of code\n* Update shape class' runner when Web UI picker is used by https://github.com/locustio/locust/pull/2534\n* Web UI Modern Auth https://github.com/locustio/locust/pull/2538\n* Customization Feature for Percentile Display on Statistics Page https://github.com/locustio/locust/pull/2550\n* Allow User weight adjustment (and task selection) in UI when running with --class-picker, or on command line with --config-users argument https://github.com/locustio/locust/pull/2559\n* Optimize memory usage when using --processes https://github.com/locustio/locust/pull/2564\n\n2.20.1\n======\n* run_single_user improvements https://github.com/locustio/locust/pull/2519\n* Support IPv6 for zmq connection between master and worker https://github.com/locustio/locust/pull/2521\n* Modern UI: Update Vite to 4.5.1 https://github.com/locustio/locust/pull/2530\n* Other tiny fixes\n\n2.20.0\n======\n* Add event.measure context manager for simpler firing of request event (experimental) https://github.com/locustio/locust/pull/2511\n* Various improvements to modern UI https://github.com/locustio/locust/pull/2491\n* Various tiny fixes\n\n2.19.1\n======\n* Create any directories as part of the CSV Prefix https://github.com/locustio/locust/pull/2481\n* Dont suppress StopUser or GreenletExit in on_stop https://github.com/locustio/locust/pull/2486\n* FastHttpUser: Detect response text encoding when no information is present in headers https://github.com/locustio/locust/pull/2485\n\n2.19.0\n======\n* Add --processes parameter to automatically fork subprocesses for workers https://github.com/locustio/locust/pull/2472\n* Automatically shut down workers if master goes missing for too long https://github.com/locustio/locust/pull/2474\n* Update minimum version of various dependencies https://github.com/locustio/locust/pull/2476\n\n2.18.4\n======\n* Various fixes to Modern UI\n* Ensure to wait a second before next call to LoadTestShape's tick() https://github.com/locustio/locust/pull/2465\n\n2.18.3\n======\n* Modern UI: Add sorting to columns on statistics page and downloaded report https://github.com/locustio/locust/pull/2453\n\n2.18.2\n======\n* FastHttpUser: encoding return str when response is empty https://github.com/locustio/locust/pull/2451\n\n2.18.1\n======\n* Add Log Viewer to Modern UI https://github.com/locustio/locust/pull/2440\n\n2.18.0\n======\n* Add a modern web UI based on React, MaterialUI and Vite (activated using --modern-ui) https://github.com/locustio/locust/pull/2405\n* Stop supporting Python 3.7 https://github.com/locustio/locust/pull/2421\n* Fix too long first wait time for constant_pacing (and constant_throughput) https://github.com/locustio/locust/pull/2428\n\n2.17.0\n======\n* Support user abstract load shape base classes https://github.com/locustio/locust/pull/2393\n* Allow LoadShapes to reuse run-time, spawn-rate and users parameters https://github.com/locustio/locust/pull/2395\n* Improve performance for statistics handling https://github.com/locustio/locust/pull/2410\n* Test and explicitly support Python 3.12 https://github.com/locustio/locust/pull/2411\n\n2.16.1\n======\n* Deprecate LOCUST_PLAYWRIGHT env var https://github.com/locustio/locust/pull/2378\n* Import locust_plugins if available to give access to its custom command line arguments https://github.com/locustio/locust/pull/2379\n\n2.16.0\n======\n* Add worker_connect event https://github.com/locustio/locust/pull/2344\n* Allow selecting user classes using LOCUST_USER_CLASSES env var https://github.com/locustio/locust/pull/2355\n* Web UI dropdown for custom args with choices https://github.com/locustio/locust/pull/2372\n* Various minor fixes\n\n2.15.1\n======\n* Add PERCENTILES_TO_CHART param in stats.py to make the Response Time Chart configurable https://github.com/locustio/locust/pull/2313\n\n2.15.0\n======\n* Add is_secret option for custom args to be shown in the web UI masked https://github.com/locustio/locust/pull/2284\n* Breaking change: Remove deprecated request_success and request_failure event handlers (unified request handler was introduced in 1.5) https://github.com/locustio/locust/pull/2306\n\n2.14.2\n======\n* Re-add py.typed marker file to package (it was missing in 2.14.1) https://github.com/locustio/locust/pull/2282\n\n2.14.1\n======\n* Add --json to send stats to stdout as json by @AndersSpringborg in https://github.com/locustio/locust/pull/2269\n\n2.14.0\n======\n* Add rest method to FastHttpUser to facilitate easy REST/JSON API testing https://github.com/locustio/locust/pull/2274\n\n2.13.2\n======\n* Fix: Ask worker to reconnect if master gets a broken RPC message by @marcinh in https://github.com/locustio/locust/pull/2271\n\n2.13.1\n======\n* Document har2locust (auto generation of locustfiles from browser recordings) https://github.com/locustio/locust/pull/2259\n* Dont reset connection to worker if master receives a corrupted zmq message by @marcinh in https://github.com/locustio/locust/pull/2266\n* Other minor fixes\n\n2.13.0\n======\n* Add the ability to set default_headers on FastHttpUser https://github.com/locustio/locust/pull/2231\n* Web UI: URL link on the host name for easy navigation by @JonanOribe in https://github.com/locustio/locust/pull/2228\n* Add support for time strings for --stop timeout (e.g. \"5m30s\") @cyberw in https://github.com/locustio/locust/pull/2239\n\n2.12.1\n======\n* Allow setting run time from the web UI & http api by @ajt89 in https://github.com/locustio/locust/pull/2202\n* Various fixes\n\n2.12.0\n======\n* LoadTestShapes with custom user classes https://github.com/locustio/locust/pull/2181\n* Minor fixes and bumped some dependencies\n\n2.11.1\n======\n* Fix issue when editing user count while running a test using --class-picker https://github.com/locustio/locust/pull/2171\n* Various minor logging fixes\n\n2.11.0\n======\n* Allow passing multiple Locustfiles, allow selecting User and Shape class from the WebUI https://github.com/locustio/locust/pull/2137\n* Add 'worker_index' to WorkerRunner https://github.com/locustio/locust/pull/2155\n* Fix: Ensure new test starts with specified number of users after previous test has been stopped https://github.com/locustio/locust/pull/2152\n\n2.10.2\n======\n* Fix for Flask 2.2.0 breaking changes https://github.com/locustio/locust/pull/2148\n\n2.10.1\n======\n* Increase CONNECT_RETRY_COUNT to avoid workers giving up too soon if master is not up yet by https://github.com/locustio/locust/pull/2125\n\n2.10.0\n======\n* Add ack for worker connection https://github.com/locustio/locust/pull/2077 (note that 2.10 workers will not work with a 2.9 master)\n* add support for custom SSLContext when using FastHttpUser https://github.com/locustio/locust/pull/2113\n* More robust handling of ZMQ/RPC errors https://github.com/locustio/locust/pull/2120 / https://github.com/locustio/locust/pull/2096\n* Full Changelog https://github.com/locustio/locust/compare/2.9.0...2.10.0\n\n2.9.0\n=====\n\n* FastHttpUser improvements (including a rename of parameter \"url\" to \"path\") https://github.com/locustio/locust/pull/2083\n* Modernized build https://github.com/locustio/locust/pull/2070\n* Drop support for Python 3.6 https://github.com/locustio/locust/pull/2080\n* Add table linkage in UI https://github.com/locustio/locust/pull/2082\n* Uniform style of stats/report ascii tables https://github.com/locustio/locust/pull/2084\n* Remove explicit version requirement for jinja2 https://github.com/locustio/locust/pull/2090\n* Rebalance users even when using fixed_count https://github.com/locustio/locust/pull/2093\n* Avoid using incompatible pyzmq 23 https://github.com/locustio/locust/pull/2100\n\n2.8.6\n=====\n\n* Support sharing connection pools between users https://github.com/locustio/locust/pull/2059\n* Add cpu_warning event, so listeners can do some action when CPU usage is too high https://github.com/locustio/locust/pull/2067\n\n2.8.5\n=====\n\n* Fix dependency: Dont use latest Jinja2 because it has breaking changes\n\n2.8.4\n=====\n\n* New event: `test_stopping`, triggered just before stopping the test https://github.com/locustio/locust/pull/2033\n* New event: `quit`, to enable getting the locust process exit code https://github.com/locustio/locust/pull/2049\n* Fix users sometimes not being stopped correctly https://github.com/locustio/locust/pull/2041\n\n2.8.3\n=====\n\n* Ensure users are distributed evently across hosts during ramp up https://github.com/locustio/locust/pull/2025 \n\n2.8.2\n=====\n\n* Fix issue with permissions in docker image\n\n2.8.1\n=====\n\n* Further optimize docker image (60MB compressed)\n\n2.8.0\n=====\n\n* Shrink docker image significantly (95MB compressed size for x64 instead of 358MB) by basing the image on python3-slim instead of python3 \n* Fix empty tasks section in UI and static report bug (really) https://github.com/locustio/locust/pull/2001\n\n2.7.3\n=====\n\n* Fix 'Tasks' section remains empty in web ui https://github.com/locustio/locust/pull/1997\n\n2.7.2\n=====\n\n* Fix an issue introduced in 2.7.1 that caused Locust to shut down when the UI stop was clicked https://github.com/locustio/locust/pull/1996\n\n2.7.1\n=====\n* fix --html report in web mode https://github.com/locustio/locust/pull/1992\n\n2.7.0\n=====\n\n* Add run_single_user and documentation on how to debug Users/locustfiles https://github.com/locustio/locust/pull/1985\n* Fix \"socket operation on non-socket\" at shutdown, by reverting #1935 https://github.com/locustio/locust/pull/1991\n* Fixing issue with incorrect \"All users spawned\" log messages https://github.com/locustio/locust/pull/1977\n\n2.6.1\n=====\n\n* Documentation fixes only.\n\n2.6.0\n=====\n* Pass --tags and --exclude-tags to workers. (https://github.com/locustio/locust/pull/1976)\n* Clean up some logging messages (https://github.com/locustio/locust/pull/1973)\n* Ensure heartbeat\\_worker doesn't try to re-establish connection to workers when quit has been called (https://github.com/locustio/locust/pull/1972)\n* fixed\\_count: ability to spawn a specific number of users \\(as opposed to just using weights\\) (https://github.com/locustio/locust/pull/1964)\n\n2.5.1\n=====\n\n* Ignore empty host field in web ui (Fix running the web UI with class defined hosts) (https://github.com/locustio/locust/pull/1956)\n* Throw exception when calling response.success()/.failure() if with-block has not been entered (https://github.com/locustio/locust/pull/1955)\n* Stop declaring \"fake\" class level variables in Environment, User and StatsEntry (https://github.com/locustio/locust/pull/1948)\n\n2.5.0\n=====\n\n* Change request event 'url' parameter to contain full URL (technically a breaking change, but very few users will have had time to start using this) (https://github.com/locustio/locust/issues/1927)\n* Suppress warnings for patch version mismatch between master and worker (https://github.com/locustio/locust/issues/1926)\n\n2.4.3\n=====\n\n* Fix crash on windows (https://github.com/locustio/locust/issues/1924)\n\n2.4.2\n=====\n\n* Add --expect-workers-max-wait parameter (https://github.com/locustio/locust/pull/1922)\n* Track worker memory usage (https://github.com/locustio/locust/pull/1917)\n* Other small fixes\n\n2.4.1\n=====\n\n* Fix stat printing when using shapes (https://github.com/locustio/locust/pull/1907)\n\n2.4.0\n=====\n\n* Add start_time and url parameters to request event. (https://github.com/locustio/locust/pull/1900)\n* Support (and test) Python 3.10 (https://github.com/locustio/locust/pull/1901)\n* Make User.run/TaskSet.run final and raise an exception if someone marks it as a task (https://github.com/locustio/locust/pull/1895)\n* Release docker image for arm64. (https://github.com/locustio/locust/pull/1889)\n* Automated change log generation is broken. Will fix this later, but until then you can look here: https://github.com/locustio/locust/compare/2.2.3...2.4.0\n\n2.3.0\n=====\n\n* Accidentally increased version to 2.4 directly so there is no 2.3...\n\n2.2.3\n=====\n\n* Fix issue with custom arguments in config file (when not running headless) (https://github.com/locustio/locust/pull/1888)\n* Automated change log generation is broken. Will fix this later, but until then you can look here: https://github.com/locustio/locust/compare/2.2.2...2.2.3\n\n2.2.2\n=====\n\n* Fix version in Docker builds\n* Automated change log generation is broken. Will fix this later, but until then you can look here: https://github.com/locustio/locust/compare/2.2.1...2.2.2\n\n2.2.1\n=====\n\n* Automated change log generation is broken. Will fix this later, but until then you can look here: https://github.com/locustio/locust/compare/2.2.0...2.2.1\n\n2.2.0\n=====\n\n* Display locustfile and tasks ratio information on index.html\n* Add --autostart and --autoquit parameters (https://github.com/locustio/locust/pull/1864)\n* Add constant\\_throughput wait time \\(the inverse of constant\\_pacing\\)\n* Alternative way to rename requests (particularly useful when using an SDK that wraps `requests`) (https://github.com/locustio/locust/pull/1858)\n* Add --equal-weights flag (https://github.com/locustio/locust/pull/1842)\n* HttpUser: Unpack known exceptions\n* Various charting fixes\n* Add FastHttpUser directly under locust package\n* Auto-generate Locust's version number using setuptools\\_scm and git tags \n* Show custom arguments in web ui and forward them to worker (https://github.com/locustio/locust/pull/1841)\n\n2.1.0\n=====\n\n* Fix docker builds (2.0 never got pushed to Docker Hub)\n* Bump dependency on pyzmq to fix out of memory issue on Windows\n* Use 1 as default for user count and spawn rate in web UI start form\n* Various documentation updates\n\n2.0.0\n=====\n\nUser ramp up/down and User type selection is now controlled by the master instead of autonomously by the workers \n----------------------------------------------------------------------------------------------------------------\nThis has allowed us to fix some issues with incorrect/skewed User type selection and undesired stepping of ramp up. The issues were especially visible when running many workers and/or using LoadShape:s. This change also allows redistribution of Users if a worker disconnects during a test. This is a major change internally in Locust so please let us know if you encounter any problems (particularly regarding ramp up pace, User distribution, CPU usage on master, etc)\n\nOther potentially breaking API changes\n--------------------------------------\n* Change the default User weight to 1 instead of 10 (the old default made no sense)\n* Fire test_start and test_stop events on workers too (previously they were only fired on master/standalone instances)\n* Workers now send their version number to master. Master will warn about version differences, and pre 2.0-versions will not be allowed to connect at all (because they would not work anyway)\n* Update Flask dependency to 2.0\n\nSignificant merged PR:s (and prerelease version they were introduced in)\n------------------------------------------------------------------------\n* Allow workers to bypass version check by sending -1 as version (2.0.0) https://github.com/locustio/locust/pull/1830\n* Improve logging messages and clean up code after dispatch refactoring (2.0.0b4) https://github.com/locustio/locust/pull/1826\n* Remove `user_classes_count` from heartbeat payload (2.0.0b4) https://github.com/locustio/locust/pull/1825\n* Add option to set concurrency of FastHttpUser/Session (2.0.0b3) https://github.com/locustio/locust/pull/1812/\n* Fire test_start and test_stop events on worker nodes (2.0.0b3) https://github.com/locustio/locust/pull/1777/\n* Auto shrink request stats table to fit terminal (2.0.0b2) https://github.com/locustio/locust/pull/1811\n* Refactoring of the dispatch logic to improve performance (2.0.0b2) https://github.com/locustio/locust/pull/1809 \n* Check version of workers when they connect. Warn if there is a mismatch, refuse 1.x workers to connect (2.0.0b1) https://github.com/locustio/locust/pull/1805 \n* Change the default User weight to 1 instead of 10 (2.0.0b1) https://github.com/locustio/locust/pull/1803\n* Upgrade to Flask 2 (2.0.0b1) https://github.com/locustio/locust/pull/1764\n* Move User selection responsibility from worker to master in order to fix unbalanced distribution of users and uneven ramp-up (2.0.0b0) https://github.com/locustio/locust/pull/1621\n\nSome of these are not really that significant and may be removed from this list at a later time, once 2.0 has stabilised.\n\n1.6.0\n=====\n\n* Allow cross process communication using custom messages https://github.com/locustio/locust/pull/1782\n* Fix: status \"stopped\" instead of \"spawning\", tick\\(\\) method of LoadShape called only once https://github.com/locustio/locust/pull/1769\n\n1.5.3\n=====\n\n* Fix an issue with custom Users calling request_success/_failure.fire() not being added to statistics https://github.com/locustio/locust/pull/1761\n\n1.5.2\n=====\n\n* Pin version of flask to 1.1.2, fixing https://github.com/locustio/locust/issues/1759\n* Fix issue with GRPC compatibility and add GRPC example to documentation https://github.com/locustio/locust/pull/1755\n* Use time.perf_counter() to calculate elapsed times everywhere, should only matter for Windows https://github.com/locustio/locust/pull/1758\n\n1.5.1\n=====\n\n* Fixed an issue with 1.5.0 where an extra parameter (start_time) was passed to request event https://github.com/locustio/locust/pull/1754\n\n1.5.0\n=====\n\n* Unify request_success/request_failure into a single event called request (the old ones are deprecated but still work) https://github.com/locustio/locust/issues/1724\n* Add the response object and context as parameters to the request event. context is used to forward information to the request event handler (can be used for things like username, tags etc)\n\n1.4.4\n=====\n\n* Ensure runner.quit finishes even when users are broken https://github.com/locustio/locust/pull/1728\n* Make runner / user count available to LoadTestShape https://github.com/locustio/locust/pull/1719\n* Other small fixes\n\n1.4.3\n=====\n\n* Fix bug that broke the tooltips for charts in the Web UI \n\n1.4.2\n=====\n\n* Multiple improvements for charting including tooltips etc\n* Added --html option to save HTML report https://github.com/locustio/locust/pull/1637\n* Lots of other small fixes\n\n1.4.1\n=====\n\n* Fix 100% cpu usage when running in docker/non-tty terminal https://github.com/locustio/locust/issues/1629\n\n1.4.0\n=====\n\n* You can now control user count from terminal while the test is running https://github.com/locustio/locust/pull/1612\n* Infinite run time is now the default for command line runs https://github.com/locustio/locust/pull/1625\n* wait_time now defaults to zero https://github.com/locustio/locust/pull/1626\n\n1.3.2\n=====\n\n* List Python 3.9 as supported in the package/on PyPi\n* Fix XSS vulnerability in the web UI (sounds important but really isn't, as Locust UI is not meant to be exposed to outside users)\n\n1.3.1\n=====\n\n* Bump minimum required gevent version to 20.9.0 (latest), as the previous ones had sneaky binary incompatibilities with the latest version of greenlet (\"RuntimeWarning: greenlet.greenlet size changed, may indicate binary incompatibility. Expected 144 from C header, got 152 from PyObject\")\n\n1.3.0\n=====\n\n* Breaking change: Remove step-load feature (now that we have LoadTestShape it is no longer needed)\n* More type hints to enable better code completion and linting of locustfiles\n\nBug fixes: \n\n* LoadTestShape.get\\_run\\_time is not relative to start of test https://github.com/locustio/locust/issues/1557\n* Refactor and fix delayed user stopping in combination with on\\_stop https://github.com/locustio/locust/pull/1560\n* runner.quit gets blocked by slow on stop https://github.com/locustio/locust/issues/1552\n* Remove legacy code that was only needed for py2\n* Lots more\n\n1.2.3\n=====\n\n* Bug fix (TypeError: code() takes at least 14 arguments (13 given) (Werkzeug version issue) https://github.com/locustio/locust/issues/1545)\n* Bug fix (Locust stuck in \"Shape worker starting\" when restarting a test from the webUI https://github.com/locustio/locust/issues/1540)\n* Various linting fixes that *should* have no functional impact\n\n1.2.2\n=====\n\n* Bug fix (LoadTestShape in headless mode https://github.com/locustio/locust/pull/1539)\n\n1.2.1\n=====\n\n* Bug fix (StatsEntry.use_response_times_cache must be set to True, https://github.com/locustio/locust/issues/1531)\n\n1.2\n===\n\n* Rename hatch rate to spawn rate (the --hatch-rate parameter is only deprecated, but the hatch_complete event has been renamed spawning_complete)\n* Ability to generate any custom load shape with LoadTestShape class\n* Allow ramping down of users\n* Ability to use save custom percentiles\n* Improve command line stats output\n* Bug fixes (excessive precision of metrics in losust csv stats, negative response time when system clock has changed, issue with non-string failure messages, some typos etc)\n* Documentation improvements\n\n1.1.1\n=====\n\n* --run-time flag is not respected if there is an exception in a test_stop listener\n* FastHttpUser: Handle stream ended at an unexpected time and UnicodeDecodeError. Show bad/error status codes on failures page.\n* Improve logging when locust master port is busy\n\n1.1\n===\n\n* The official Docker image is now based on the ``python:3.8`` image instead of ``python:3.8-alpine``. This should \n make it easier to install other python packages when extending the locust docker image.\n* Allow Users to stop the runner by calling self.environment.runner.quit() (without deadlocking sometimes)\n* Cut to only 5% free space on the top of the graphs\n* Use csv module to generate csv data (solves issues with sample names that need escaping in csv)\n* Various documentation improvements\n\n1.0.3\n=====\n\n* Ability to control the exit code of the Locust process by setting :py:attr:`Environment.process_exit_code `\n* FastHttpLocust: Change dependency to use original geventhttpclient (now that releases can be made there) instead of geventhttpclient-wheels\n* Fix search on readthedocs\n\n1.0.2\n=====\n\n* Check for low open files limit (ulimit) and try to automatically increase it from within the locust process.\n* Other various bug fixes as improvements\n\n\n.. _changelog-1-0:\n\n1.0, 1.0.1\n==========\n\nThis version contains some breaking changes.\n\nLocust class renamed to User\n----------------------------\n\nWe've renamed the ``Locust`` and ``HttpLocust`` classes to ``User`` and ``HttpUser``. The ``locust`` attribute on \n:py:class:`TaskSet ` instances has been renamed to :py:attr:`user `.\n\nThe parameter for setting number of users has also been changed, from ``-c`` / ``--clients`` to ``-u`` / ``--users``.\n\nAbility to declare @task directly under the ``User`` class\n----------------------------------------------------------\n\nIt's now possible to declare tasks directly under a User class like this:\n\n.. code-block:: python\n\n class WebUser(User):\n @task\n def some_task(self):\n pass\n\nIn tasks declared under a User class (e.g. ``some_task`` in the example above), ``self`` refers to the User \ninstance, as one would expect. For tasks defined under a :py:class:`TaskSet ` class, ``self`` \nwould refer to the ``TaskSet`` instance.\n\nThe ``task_set`` attribute on the ``User`` class (previously ``Locust`` class) has been removed. To declare a \n``User`` class with a single ``TaskSet`` one would now use the :py:attr:`tasks `\nattribute instead:\n\n.. code-block:: python\n\n class MyTaskSet(TaskSet):\n ...\n \n class WebUser(User):\n tasks = [MyTaskSet]\n\n\nTask tagging\n------------\n\nA new :ref:`tag feature ` has been added that makes it possible to include/exclude tasks during \na test run.\n\nTasks can be tagged using the :py:func:`@tag ` decorator:\n\n.. code-block:: python\n\n class WebUser(User):\n @task\n @tag(\"tag1\", \"tag2\")\n def my_task(self):\n ...\n\nAnd tasks can then be specified/excluded using the ``--tags``/``-T`` and ``--exclude-tags``/``-E`` command line arguments. \n\n\nEnvironment variables changed\n-----------------------------\n\nThe following changes has been made to the configuration environment variables\n\n* ``LOCUST_MASTER`` has been renamed to ``LOCUST_MODE_MASTER`` (in order to make it less likely to get variable name collisions \n when running Locust in Kubernetes/K8s which automatically adds environment variables depending on service/pod names).\n* ``LOCUST_SLAVE`` has been renamed to ``LOCUST_MODE_WORKER``.\n* ``LOCUST_MASTER_PORT`` has been renamed to ``LOCUST_MASTER_NODE_PORT``.\n* ``LOCUST_MASTER_HOST`` has been renamed to ``LOCUST_MASTER_NODE_HOST``.\n* ``CSVFILEBASE`` has been renamed to ``LOCUST_CSV``.\n\nSee the :ref:`configuration` documentation for a full list of available :ref:`environment variables `.\n\n\nOther breaking changes\n----------------------\n\n* The master/slave terminology has been changed to master/worker. Therefore the command line arguments ``--slave`` and\n ``--expect-slaves`` has been renamed to ``--worker`` and ``--expect-workers``.\n* The option for running Locust without the Web UI has been renamed from ``--no-web`` to ``--headless``.\n* Removed ``Locust.setup``, ``Locust.teardown``, ``TaskSet.setup`` and ``TaskSet.teardown`` hooks. If you want to \n run code at the start or end of a test, you should instead use the :py:attr:`test_start `\n and :py:attr:`test_stop ` events:\n \n .. code-block:: python\n \n from locust import events\n \n @events.test_start.add_listener\n def on_test_start(**kw):\n print(\"test is starting\")\n \n @events.test_stop.add_listener\n def on_test_start(**kw):\n print(\"test is stopping\")\n* ``TaskSequence`` and ``@seq_task`` has been replaced with :ref:`SequentialTaskSet `.\n* A ``User count`` column has been added to the history stats CSV file. The column order and column names has been changed.\n* The official docker image no longer uses a shell script with a bunch of special environment variables to configure how \n how locust is started. Instead, the ``locust`` command is now set as ``ENTRYPOINT`` of the docker image. See\n :ref:`running-in-docker` for more info.\n* Command line option ``--csv-base-name`` has been removed, since it was just an alias for ``--csv``.\n* The way Locust handles logging has been changed. We no longer wrap stdout (and stderr) to automatically make print \n statements go into the log. ``print()`` statements now only goes to stdout. To add custom entries to the log, one \n should now use the Python logging module:\n \n .. code-block:: python\n \n import logging\n logging.info(\"custom logging message)\n \n For more info see :ref:`logging`\n\n\nWeb UI improvements\n-------------------\n\n* It's now possible to protect the Web UI with Basic Auth using the ``--web-auth`` command line argument.\n* The Web UI can now be served over HTTPS by specifying a TLS certificate and key with the ``--tls-cert`` \n and ``--tls-key`` command line arguments.\n* If the number of users and hatch rate are specified on command line, it's now used to pre-populate the input fields in \n the Web UI.\n\n\n\nOther fixes and improvements\n----------------------------\n\n* Added ``--config`` command line option for specifying a :ref:`configuration file ` path\n* The code base has been refactored to make it possible to run :ref:`Locust as a python lib `. \n* It's now possible to call ``response.failure()`` or ``response.success()`` multiple times when using \n the ``catch_response=True`` in the HTTP clients. Only the last call to ``success``/``failure`` will count.\n* The ``--help`` output has been improved by grouping related options together.\n\n\n\n0.14.6\n======\n\n* Fix bug when running with latest Gevent version, and pinned the latest version\n\n\n0.14.0\n======\n\n* Drop Python 2 and Python 3.5 support!\n* Continuously measure CPU usage and emit a warning if we get a five second average above 90%\n* Show CPU usage of slave nodes in the Web UI\n* Fixed issue when running Locust distributed and new slave nodes connected during the hatching/ramp-up \n phase (https://github.com/locustio/locust/issues/1168)\n\n\n0.13.5\n======\n\nVarious minor fixes, mainly regarding FastHttpLocust.\n\n0.13.4\n======\n\nIdentical to previous version, but now built & deployed to Pypi using Travis.\n\n0.13.3\n======\n\n* Unable to properly connect multiple slaves - https://github.com/locustio/locust/issues/1176\n* Zero exit code on exception - https://github.com/locustio/locust/issues/1172\n* `--stop-timeout` is not respected when changing number of running Users in distributed mode - https://github.com/locustio/locust/issues/1162\n\n0.13.2\n======\n\n* Fixed bug that broke the Web UI's response time graph\n\n0.13.1\n======\n\n* Fixed crash bug on Python 3.8.0\n* Various other bug fixes and improvements.\n\n\n0.13.0\n======\n\n* New API for specifying wait time - https://github.com/locustio/locust/pull/1118\n\n Example of the new API::\n\n from locust import HttpLocust, between\n class User(HttpLocust):\n # wait between 5 and 30 seconds\n wait_time = between(5, 30)\n\n There are three built in :ref:`wait time functions `: :py:func:`between `,\n :py:func:`constant ` and :py:func:`constant_pacing `.\n\n* FastHttpLocust: Accept self signed SSL certificates, ignore host checks. Improved response code handling\n* Add current working dir to sys.path - https://github.com/locustio/locust/pull/484\n* Web UI improvements: Added 90th percentile to table, failure per seconds as a series in the chart\n* Ability to specify host in web ui\n* Added response_length to request_failure event - https://github.com/locustio/locust/pull/1144\n* Added p99.9 and p99.99 to request stats distribution csv - https://github.com/locustio/locust/pull/1125\n* Various other bug fixes and improvements.\n\n0.12.2\n======\n\n* Added `--skip-log-setup` to disable Locust's default logging setup.\n* Added `--stop-timeout` to allow tasks to finish running their iteration before stopping\n* Added 99.9 and 99.99 percentile response times to csv output\n* Allow custom clients to set request response time to None. Those requests will be excluded\n when calculating median, average, min, max and percentile response times.\n* Renamed the last row in statistics table from \"Total\" to \"Aggregated\" (since the values aren't\n a sum of the individual table rows).\n* Some visual improvements to the web UI.\n* Fixed issue with simulating fewer number of locust users than the number of slave/worker nodes.\n* Fixed bugs in the web UI related to the fact that the stats table is truncated at 500 entries.\n* Various other bug fixes and improvements.\n\n\n0.12.1\n======\n\n* Added new :code:`FastHttpLocust` class that uses a faster HTTP client, which should be 5-6 times faster\n than the normal :code:`HttpLocust` class. For more info see the documentation on :ref:`increasing performance `.\n* Added ability to set the exit code of the locust process when exceptions has occurred within the user code,\n using the :code:`--exit-code-on-error` parameter.\n* Added TCP keep alive to master/slave communication sockets to avoid broken connections in some environments.\n* Dropped support for Python 3.4\n* Numerous other bug fixes and improvements.\n\n\n0.10.0\n======\n\n* Python 3.7 support\n* Added a status page to the web UI when running Locust distributed showing the status of slave nodes\n and detect down slaves using heartbeats\n* Numerous bugfixes/documentation updates (see detailed changelog)\n\n\n0.9.0\n=====\n\n* Added detailed changelog (https://github.com/locustio/locust/blob/master/CHANGELOG.md)\n* Numerous bugfixes (see detailed changelog)\n* Added sequential task support - https://github.com/locustio/locust/pull/827\n* Added support for user-defined wait_function - https://github.com/locustio/locust/pull/785\n* By default, Locust no longer resets the statistics when the hatching is complete.\n Therefore :code:`--no-reset-stats` has been deprecated (since it's now the default behavior),\n and instead a new :code:`--reset-stats` option has been added.\n* Dropped support for Python 3.3\n* Updated documentation\n\n0.8.1\n=====\n\n* Updated pyzmq version, and changed so that we don't pin a specific version.\n This makes it easier to install Locust on Windows.\n\n\n0.8\n===\n\n* Python 3 support\n* Dropped support for Python 2.6\n* Added :code:`--no-reset-stats` option for controlling if the statistics should be reset once\n the hatching is complete\n* Added charts to the web UI for requests per second, average response time, and number of\n simulated users.\n* Updated the design of the web UI.\n* Added ability to write a CSV file for results via command line flag\n* Added the URL of the host that is currently being tested to the web UI.\n* We now also apply gevent's monkey patching of threads. This fixes an issue when\n using Locust to test Cassandra (https://github.com/locustio/locust/issues/569).\n* Various bug fixes and improvements\n\n\n0.7.5\n=====\n\n* Use version 1.1.1 of gevent. Fixes an install issue on certain versions of python.\n\n\n0.7.4\n=====\n\n* Use a newer version of requests, which fixed an issue for users with older versions of\n requests getting ConnectionErrors (https://github.com/locustio/locust/issues/273).\n* Various fixes to documentation.\n\n\n0.7.3\n=====\n\n* Fixed bug where POST requests (and other methods as well) got incorrectly reported as\n GET requests, if the request resulted in a redirect.\n* Added ability to download exceptions in CSV format. Download links has also been moved\n to its own tab in the web UI.\n\n\n0.7.2\n=====\n\n* Locust now returns an exit code of 1 when any failed requests were reported.\n* When making an HTTP request to an endpoint that responds with a redirect, the original\n URL that was requested is now used as the name for that entry in the statistics (unless\n an explicit override is specified through the *name* argument). Previously, the last\n URL in the redirect chain was used to label the request(s) in the statistics.\n* Fixed bug which caused only the time of the last request in a redirect chain to be\n included in the reported time.\n* Fixed bug which caused the download time of the request body not to be included in the\n reported response time.\n* Fixed bug that occurred on some linux dists that were tampering with the python-requests\n system package (removing dependencies which requests is bundling). This bug only occurred\n when installing Locust in the python system packages, and not when using virtualenv.\n* Various minor fixes and improvements.\n\n\n0.7.1\n=====\n\n* Exceptions that occurs within TaskSets are now caught by default.\n* Fixed bug which caused Min response time to always be 0 after all locusts had been hatched\n and the statistics had been reset.\n* Minor UI improvements in the web interface.\n* Handle messages from \"zombie\" slaves by ignoring the message and making a log entry\n in the master process.\n\n\n\n0.7\n===\n\nHTTP client functionality moved to HttpLocust\n---------------------------------------------\n\nPreviously, the Locust class instantiated a :py:class:`HttpSession `\nunder the client attribute that was used to make HTTP requests. This functionality has\nnow been moved into the :py:class:`HttpLocust ` class, in an\neffort to make it more obvious how one can use Locust to\n:doc:`load test non-HTTP systems `.\n\nTo make existing locust scripts compatible with the new version you should make your\nlocust classes inherit from HttpLocust instead of the base Locust class.\n\n\nmsgpack for serializing master/slave data\n-----------------------------------------\n\nLocust now uses `msgpack `_ for serializing data that is sent between\na master node and its slaves. This addresses a possible attack that can be used to execute\ncode remote, if one has access to the internal locust ports that are used for master-slave\ncommunication. The reason for this exploit was due to the fact that pickle was used.\n\n.. warning::\n\n Anyone who uses an older version should make sure that their Locust machines are not publicly\n accessible on port 5557 and 5558. Also, one should never run Locust as root.\n\nAnyone who uses the :py:class:`report_to_master ` and\n:py:class:`slave_report ` events, needs to make sure that\nany data that is attached to the slave reports is serializable by msgpack.\n\nrequests updated to version 2.2\n-------------------------------\n\nLocust updated `requests `_ to the latest major release.\n\n.. note::\n\n Requests 1.0 introduced some major API changes (and 2.0 just a few). Please check if you\n are using any internal features and check the documentation:\n `Migrating to 1.x `_ and\n `Migrationg to 2.x `_\n\ngevent updated to version 1.0\n-------------------------------\n\ngevent 1.0 has now been released and Locust has been updated accordingly.\n\nBig refactoring of request statistics code\n------------------------------------------\n\nRefactored :py:class:`RequestStats`.\n\n* Created :py:class:`StatsEntry` which represents a single stats entry (URL).\n\nPreviously the :py:class:`RequestStats` was actually doing two different things:\n\n* It was holding track of the aggregated stats from all requests\n* It was holding the stats for single stats entries.\n\nNow RequestStats should be instantiated and holds the global stats, as well as a dict of StatsEntry instances which holds the stats for single stats entries (URLs)\n\nRemoved support for avg_wait\n----------------------------\n\nPreviously one could specify avg_wait to :py:class:`TaskSet` and :py:class:`Locust` that Locust would try to strive to. However this can be sufficiently accomplished by using min_wait and max_wait for most use-cases. Therefore we've decided to remove the avg_wait as its use-case is not clear or just too narrow to be in the Locust core.\n\nRemoved support for ramping\n----------------------------\n\nPreviously one could tell Locust, using the --ramp option, to try to find a stable client count that the target host could handle, but it's been broken and undocumented for quite a while so we've decided to remove it from the locust core and perhaps have it reappear as a plugin in the future.\n\n\nLocust Event hooks now takes keyword argument\n---------------------------------------------\n\nWhen :doc:`extending-locust` by listening to :ref:`events`, the listener functions should now expect\nthe arguments to be passed in as keyword arguments. It's also highly recommended to add an extra\nwildcard keyword arguments to listener functions, since they're then less likely to break if extra\narguments are added to that event in some future version. For example::\n\n from locust import events\n\n def on_request(request_type, name, response_time, response_length, **kw):\n print \"Got request!\"\n\n locust.events.request_success += on_request\n\nThe *method* and *path* arguments to :py:obj:`request_success ` and\n:py:obj:`request_failure ` are now called *request_type* and *name*,\nsince it's less HTTP specific.\n\n\nOther changes\n-------------\n\n* You can now specify the port on which to run the web host\n* Various code cleanups\n* Updated gevent/zmq libraries\n* Switched to unittest2 discovery\n* Added option --only-summary to only output the summary to the console, thus disabling the periodic stats output.\n* Locust will now make sure to spawn all the specified locusts in distributed mode, not just a multiple of the number of slaves.\n* Fixed the broken Vagrant example.\n* Fixed the broken events example (events.py).\n* Fixed issue where the request column was not sortable in the web-ui.\n* Minor styling of the statistics table in the web-ui.\n* Added options to specify host and ports in distributed mode using --master-host, --master-port for the slaves, --master-bind-host, --master-bind-port for the master.\n* Removed previously deprecated and obsolete classes WebLocust and SubLocust.\n* Fixed so that also failed requests count, when specifying a maximum number of requests on the command line\n\n\n0.6.2\n=====\n\n* Made Locust compatible with gevent 1.0rc2. This allows user to step around a problem\n with running Locust under some versions of CentOS, that can be fixed by upgrading\n gevent to 1.0.\n* Added :py:attr:`parent ` attribute to TaskSet class that\n refers to the parent TaskSet, or Locust, instance. Contributed by Aaron Daubman.\n\n\n0.6.1\n=====\n\n* Fixed bug that was causing problems when setting a maximum number of requests using the\n **-n** or **--num-request** command line parameter.\n\n\n0.6\n===\n\n.. warning::\n\n This version comes with non backward compatible changes to the API.\n Anyone who is currently using existing locust scripts and want to upgrade to 0.6\n should read through these changes.\n\n:py:class:`SubLocust ` replaced by :py:class:`TaskSet ` and :py:class:`Locust ` class behavior changed\n-----------------------------------------------------------------------------------------------------------------------------------------------------------------------\n\n:py:class:`Locust ` classes does no longer control task scheduling and execution.\nTherefore, you no longer define tasks within Locust classes, instead the Locust class has a\n:py:attr:`task_set ` attribute which should point to a\n:py:class:`TaskSet ` class. Tasks should now be defined in TaskSet\nclasses, in the same way that was previously done in Locust and SubLocust classes. TaskSets can be\nnested just like SubLocust classes could.\n\nSo the following code for 0.5.1::\n\n class User(Locust):\n min_wait = 10000\n max_wait = 120000\n\n @task(10)\n def index(self):\n self.client.get(\"/\")\n\n @task(2)\n class AboutPage(SubLocust):\n min_wait = 10000\n max_wait = 120000\n\n def on_init(self):\n self.client.get(\"/about/\")\n\n @task\n def team_page(self):\n self.client.get(\"/about/team/\")\n\n @task\n def press_page(self):\n self.client.get(\"/about/press/\")\n\n @task\n def stop(self):\n self.interrupt()\n\nShould now be written like::\n\n class BrowsePage(TaskSet):\n @task(10)\n def index(self):\n self.client.get(\"/\")\n\n @task(2)\n class AboutPage(TaskSet):\n def on_init(self):\n self.client.get(\"/about/\")\n\n @task\n def team_page(self):\n self.client.get(\"/about/team/\")\n\n @task\n def press_page(self):\n self.client.get(\"/about/press/\")\n\n @task\n def stop(self):\n self.interrupt()\n\n class User(Locust):\n min_wait = 10000\n max_wait = 120000\n task_set = BrowsePage\n\nEach TaskSet instance gets a :py:attr:`locust ` attribute, which refers to the\nLocust class.\n\nLocust now uses Requests\n------------------------\n\nLocust's own HttpBrowser class (which was typically accessed through *self.client* from within a locust class)\nhas been replaced by a thin wrapper around the requests library (http://python-requests.org). This comes with\na number of advantages. Users can now take advantage of a well documented, well written, fully fledged\nlibrary for making HTTP requests. However, it also comes with some small API changes which will require users\nto update their existing load testing scripts.\n\nGzip encoding turned on by default\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nThe HTTP client now sends headers for accepting gzip encoding by default. The **--gzip** command line argument\nhas been removed and if someone want to disable the *Accept-Encoding* that the HTTP client uses, or any\nother HTTP headers you can do::\n\n class MyWebUser(Locust):\n def on_start(self):\n self.client.headers = {\"Accept-Encoding\":\"\"}\n\n\nImproved HTTP client\n^^^^^^^^^^^^^^^^^^^^\n\nBecause of the switch to using python-requests in the HTTP client, the API for the client has also\ngotten a few changes.\n\n* Additionally to the :py:meth:`get `, :py:meth:`post `,\n :py:meth:`put `, :py:meth:`delete ` and\n :py:meth:`head ` methods, the :py:class:`HttpSession ` class\n now also has :py:meth:`patch ` and :py:meth:`options ` methods.\n\n* All arguments to the HTTP request methods, except for **url** and **data** should now be specified as keyword arguments.\n For example, previously one could specify headers using::\n\n client.get(\"/path\", {\"User-Agent\":\"locust\"}) # this will no longer work\n\n And should now be specified like::\n\n client.get(\"/path\", headers={\"User-Agent\":\"locust\"})\n\n* In general the whole HTTP client is now more powerful since it leverages on python-requests. Features that we're\n now able to use in Locust includes file upload, SSL, connection keep-alive, and more.\n See the `python-requests documentation `_ for more details.\n\n* The new :py:class:`HttpSession ` class' methods now return python-request\n :py:class:`Response ` objects. This means that accessing the content of the response\n is no longer made using the **data** attribute, but instead the **content** attribute. The HTTP response\n code is now accessed through the **status_code** attribute, instead of the **code** attribute.\n\n\nHttpSession methods' catch_response argument improved and allow_http_error argument removed\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n* When doing HTTP requests using the **catch_response** argument, the context manager that is returned now\n provides two functions, :py:meth:`success ` and\n :py:meth:`failure ` that can be used to manually control\n what the request should be reported as in Locust's statistics.\n\n .. autoclass:: locust.clients.ResponseContextManager\n :members: success, failure\n :noindex:\n\n* The **allow_http_error** argument of the HTTP client's methods has been removed. Instead one can use the\n **catch_response** argument to get a context manager, which can be used together with a with statement.\n\n The following code in the previous Locust version::\n\n client.get(\"/does/not/exist\", allow_http_error=True)\n\n Can instead now be written like::\n\n with client.get(\"/does/not/exist\", catch_response=True) as response:\n response.success()\n\n\nOther improvements and bug fixes\n--------------------------------\n\n* Scheduled task callables can now take keyword arguments and not only normal function arguments.\n* SubLocust classes that are scheduled using :func:`locust.core.Locust.schedule_task` can now take\n arguments and keyword arguments (available in *self.args* and *self.kwargs*).\n* Fixed bug where the average content size would be zero when doing requests against a server that\n didn't set the content-length header (i.e. server that uses *Transfer-Encoding: chunked*)\n\n\n\nSmaller API Changes\n-------------------\n\n* The *require_once* decorator has been removed. It was an old legacy function that no longer fit into\n the current way of writing Locust tests, where tasks are either methods under a Locust class or SubLocust\n classes containing task methods.\n* Changed signature of :func:`locust.core.Locust.schedule_task`. Previously all extra arguments that\n was given to the method was passed on to the task when it was called. It no longer accepts extra arguments.\n Instead, it takes an *args* argument (list) and a *kwargs* argument (dict) which are be passed to the task when\n it's called.\n* Arguments for :py:class:`request_success ` event hook has been changed.\n Previously it took an HTTP Response instance as argument, but this has been changed to take the\n content-length of the response instead. This makes it easier to write custom clients for Locust.\n\n\n0.5.1\n=====\n\n* Fixed bug which caused --logfile and --loglevel command line parameters to not be respected when running\n locust without zeromq.\n\n0.5\n===\n\nAPI changes\n-----------\n\n* Web interface is now turned on by default. The **--web** command line option has been replaced by --no-web.\n* :func:`locust.events.request_success` and :func:`locust.events.request_failure` now gets the HTTP method as the first argument.\n\nImprovements and bug fixes\n--------------------------\n\n* Removed **--show-task-ratio-confluence** and added a **--show-task-ratio-json** option instead. The\n **--show-task-ratio-json** will output JSON data containing the task execution ratio for the locust\n \"brain\".\n* The HTTP method used when a client requests a URL is now displayed in the web UI\n* Some fixes and improvements in the stats exporting:\n\n * A file name is now set (using content-disposition header) when downloading stats.\n * The order of the column headers for request stats was wrong.\n * Thanks Benjamin W. Smith, Jussi Kuosa and Samuele Pedroni!\n\n0.4\n===\n\nAPI changes\n-----------\n\n* WebLocust class has been deprecated and is now called just Locust. The class that was previously\n called Locust is now called LocustBase.\n* The *catch_http_error* argument to HttpClient.get() and HttpClient.post() has been renamed to\n *allow_http_error*.\n\nImprovements and bug fixes\n--------------------------\n\n* Locust now uses python's logging module for all logging\n* Added the ability to change the number of spawned users when a test is running, without having\n to restart the test.\n* Experimental support for automatically ramping up and down the number of locust to find a maximum\n number of concurrent users (based on some parameters like response times and acceptable failure\n rate).\n* Added support for failing requests based on the response data, even if the HTTP response was OK.\n* Improved master node performance in order to not get bottlenecked when using enough slaves (>100)\n* Minor improvements in web interface.\n* Fixed missing template dir in MANIFEST file causing locust installed with \"setup.py install\" not to work.\n" }, { "path": "docs/conf.py", "content": "#\n# This file is execfile()d with the current directory set to its containing dir.\n#\n# The contents of this file are pickled, so don't put values in the namespace\n# that aren't pickleable (module imports are okay, they're removed automatically).\n#\n# All configuration values have a default value; values that are commented out\n# serve to show the default value.\n\nfrom locust.argument_parser import get_parser\n\nimport os\nimport subprocess\n\n# Add fixes for RTD deprecation\n# https://about.readthedocs.com/blog/2024/07/addons-by-default/\n\n# Define the canonical URL if you are using a custom domain on Read the Docs\nhtml_baseurl = os.environ.get(\"READTHEDOCS_CANONICAL_URL\", \"\")\n\n# Tell Jinja2 templates the build is running on Read the Docs\nif os.environ.get(\"READTHEDOCS\", \"\") == \"True\":\n if \"html_context\" not in globals():\n html_context = {}\n html_context[\"READTHEDOCS\"] = True\n\n\n# Run command `locust --help` and store output in cli-help-output.txt which is included in the docs\ndef save_locust_help_output():\n cli_help_output_file = os.path.join(os.path.abspath(os.path.dirname(__file__)), \"cli-help-output.txt\")\n print(f\"Running `locust --help` command and storing output in {cli_help_output_file}\")\n help_output = subprocess.check_output([\"locust\", \"--help\"], text=True)\n with open(cli_help_output_file, \"w\") as f:\n f.write(help_output)\n\n\nsave_locust_help_output()\n\n\n# Generate RST table with help/descriptions for all available environment variables\n\n\ndef save_locust_env_variables():\n env_options_output_file = os.path.join(os.path.abspath(os.path.dirname(__file__)), \"config-options.rst\")\n print(f\"Generating RST table for Locust environment variables and storing in {env_options_output_file}\")\n parser = get_parser()\n table_data = []\n for action in parser._actions:\n if action.env_var and action.help != \"==SUPPRESS==\":\n table_data.append(\n (\n \", \".join([f\"``{c}``\" for c in action.option_strings]),\n f\"``{action.env_var}``\",\n \", \".join([f\"``{c}``\" for c in parser.get_possible_config_keys(action) if not c.startswith(\"--\")]),\n action.help.replace(\"\\n\", \" \"),\n )\n )\n colsizes = [max(len(r[i]) for r in table_data) for i in range(len(table_data[0]))]\n formatter = \" \".join(\"{:<%d}\" % c for c in colsizes)\n rows = [formatter.format(*row) for row in table_data]\n edge = formatter.format(*[\"=\" * c for c in colsizes])\n divider = formatter.format(*[\"-\" * c for c in colsizes])\n headline = formatter.format(*[\"Command line\", \"Environment\", \"Config file\", \"Description\"])\n output = \"\\n\".join(\n [\n edge,\n headline,\n divider,\n \"\\n\".join(rows),\n edge,\n ]\n )\n with open(env_options_output_file, \"w\") as f:\n f.write(output)\n\n\nsave_locust_env_variables()\n\n\n# The default replacements for |version| and |release|, also used in various\n# other places throughout the built documents.\n#\n# The short X.Y version.\nfrom locust import __version__\n\n# General configuration\n# ---------------------\n\n# Add any Sphinx extension module names here, as strings. They can be extensions\n# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.\nextensions = [\n \"sphinx-prompt\",\n \"sphinx_substitution_extensions\",\n \"sphinx.ext.autodoc\",\n \"sphinx.ext.intersphinx\",\n \"sphinx.ext.viewcode\",\n \"sphinx_search.extension\",\n \"sphinx_rtd_theme\",\n \"sphinxcontrib.googleanalytics\",\n \"sphinx.ext.extlinks\",\n]\n\nextlinks = {\n \"gh\": (\"https://github.com/locustio/locust/blob/master/%s\", \"%s\"),\n}\n\n\n# autoclass options\n# autoclass_content = \"both\"\n\nautodoc_typehints = \"none\" # I would have liked to use 'description' but unfortunately it too is very verbose\n\n# Add any paths that contain templates here, relative to this directory.\ntemplates_path = [\"_templates\"]\n\n# The suffix of source filenames.\nsource_suffix = {\".rst\": \"restructuredtext\"}\n\n# The master toctree document.\nmaster_doc = \"index\"\n\n# General substitutions.\nproject = \"Locust\"\ncopyright = \"2009-2025, Carl Byström, Jonatan Heyman, Lars Holmberg\"\n\n# Intersphinx config\nintersphinx_mapping = {\n \"requests\": (\"https://requests.readthedocs.io/en/latest/\", None),\n \"socketio\": (\"https://python-socketio.readthedocs.io/en/stable/\", None),\n \"dnspython\": (\"https://dnspython.readthedocs.io/en/stable/\", None),\n}\n\n\n# The full version, including alpha/beta/rc tags.\nrelease = __version__\n\n# There are two options for replacing |today|: either, you set today to some\n# non-false value, then it is used:\n# today = ''\n# Else, today_fmt is used as the format for a strftime call.\ntoday_fmt = \"%B %d, %Y\"\n\n# List of documents that shouldn't be included in the build.\n# unused_docs = []\n\n# If true, '()' will be appended to :func: etc. cross-reference text.\nadd_function_parentheses = True\n\n# If true, the current module name will be prepended to all description\n# unit titles (such as .. function::).\nadd_module_names = False\n\n# If true, sectionauthor and moduleauthor directives will be shown in the\n# output. They are ignored by default.\nshow_authors = False\n\n# Sphinx will recurse into subversion configuration folders and try to read\n# any document file within. These should be ignored.\n# Note: exclude_dirnames is new in Sphinx 0.5\nexclude_dirnames = []\n\n# Options for HTML output\n# -----------------------\n\nhtml_show_sourcelink = False\nhtml_file_suffix = \".html\"\nhtml_theme = \"sphinx_rtd_theme\"\n\n# Custom CSS overrides\nhtml_static_path = [\"_static\"]\nhtml_css_files = [\"_static/theme-overrides.css\", \"_static/css/rtd_sphinx_search.min.css\"]\n\n# Google Analytics ID\ngoogleanalytics_id = \"G-MCG99XYF9M\"\ngoogleanalytics_enabled = True\n\n# HTML theme\n# html_theme = \"default\"\n# html_theme_options = {\n# \"rightsidebar\": \"true\",\n# \"codebgcolor\": \"#fafcfa\",\n# \"bodyfont\": \"Arial\",\n# }\n\n# The name of the Pygments (syntax highlighting) style to use.\n# pygments_style = 'trac'\n\nrst_prolog = f\"\"\"\n.. |version| replace:: {__version__}\n\"\"\"\n" }, { "path": "docs/configuration.rst", "content": ".. _configuration:\n\n=============\nConfiguration\n=============\n\n\nCommand Line Options\n====================\n\nLocust is configured mainly through command line arguments.\n\n.. code-block:: console\n\n $ locust --help\n\n.. literalinclude:: cli-help-output.txt\n :language: console\n\n\n\n.. _environment-variables:\n\nEnvironment Variables\n=====================\n\nOptions can also be set through environment variables. They are typically the same as the command line argument\nbut capitalized and prefixed with ``LOCUST_``:\n\nOn Linux/macOS:\n\n.. code-block::\n\n $ LOCUST_LOCUSTFILE=custom_locustfile.py locust\n\nOn Windows:\n\n.. code-block::\n\n > set LOCUST_LOCUSTFILE=custom_locustfile.py\n > locust\n\n.. _configuration-file:\n\nConfiguration File\n==================\n\nOptions can also be set in a configuration file in the\n`config or TOML file format `_.\n\nLocust will look for ``~/.locust.conf``, ``./locust.conf`` and ``./pyproject.toml`` by default.\nYou can specify an additional file using the ``--config`` flag.\n\n.. code-block:: console\n\n $ locust --config custom_config.conf\n\nHere's an example:\n\nlocust.conf\n--------------\n\n.. code-block:: ini\n\n locustfile = locust_files/my_locust_file.py\n headless = true\n master = true\n expect-workers = 5\n host = https://target-system\n users = 100\n spawn-rate = 10\n run-time = 10m\n tags = [Critical, Normal]\n\nHave a look later in this page for `All available configuration options`_\n\npyproject.toml\n--------------\n\nWhen using a TOML file, configuration options should be defined within the ``[tool.locust]`` section.\n\n.. code-block:: toml\n\n [tool.locust]\n locustfile = \"locust_files/my_locust_file.py\"\n headless = true\n master = true\n expect-workers = 5\n host = \"https://target-system\"\n users = 100\n spawn-rate = 10\n run-time = \"10m\"\n tags = [\"Critical\", \"Normal\"]\n\n.. note::\n\n Configuration values are read (and overridden) in the following order:\n\n .. code-block:: console\n\n ./pyproject.toml -> ./locust.conf -> (file specified using --config) -> env vars -> cmd args\n\n\nAll available configuration options\n===================================\n\nHere's a table of all the available configuration options, and their corresponding Environment and config file keys:\n\n.. include:: config-options.rst\n\nRunning without the web UI\n==========================\n\nSee :ref:`running-without-web-ui`\n\nUsing multiple Locustfiles at once\n==================================\n\n``-f/--locustfile`` accepts multiple, comma-separated locustfiles.\n\nExample:\n\nWith the following file structure:\n\n.. code-block::\n\n ├── locustfiles/\n │ ├── locustfile1.py\n │ ├── locustfile2.py\n │ └── more_files/\n │ ├── locustfile3.py\n │ ├── _ignoreme.py\n\n.. code-block:: console\n\n $ locust -f locustfiles/locustfile1.py,locustfiles/locustfile2.py,locustfiles/more_files/locustfile3.py\n\nLocust will use ``locustfile1.py``, ``locustfile2.py`` & ``more_files/locustfile3.py``\n\nAdditionally, ``-f/--locustfile`` accepts directories as an option. Locust will recursively\nsearch specified directories for ``*.py`` files, ignoring files that start with \"_\".\n\nExample:\n\n.. code-block:: console\n\n $ locust -f locustfiles\n\nLocust will use ``locustfile1.py``, ``locustfile2.py`` & ``more_files/locustfile3.py``\n\n\n\nYou can also use ``-f/--locustfile`` for web urls. This will download the file and use it as any normal locustfile.\n\nExample:\n\n.. code-block:: console\n\n $ locust -f https://raw.githubusercontent.com/locustio/locust/master/examples/basic.py\n\n\n.. _class-picker:\n\nPick User classes, Shapes and tasks from the UI\n===============================================\n\nYou can select which Shape class and which User classes to run in the WebUI when running locust with the ``--class-picker`` flag.\nNo selection uses all the available User classes.\n\nFor example, with a file structure like this:\n\n.. code-block::\n\n ├── src/\n │ ├── some_file.py\n ├── locustfiles/\n │ ├── locustfile1.py\n │ ├── locustfile2.py\n │ └── more_files/\n │ ├── locustfile3.py\n │ ├── _ignoreme.py\n │ └── shape_classes/\n │ ├── DoubleWaveShape.py\n │ ├── StagesShape.py\n\n\n.. code-block:: console\n\n $ locust -f locustfiles --class-picker\n\nThe Web UI will display:\n\n.. image:: images/userclass_picker_example.png\n\nThe class picker additionally allows for disabling individual User tasks, changing the weight or fixed count, and configuring the host.\n\nIt is even possible to add custom attributes that you wish to be configurable for each User. Simply add a ``json`` classmethod\nto your user:\n\n.. code-block:: python\n\n class Example(HttpUser):\n @task\n def example_task(self):\n self.client.get(f\"/example/{self.some_custom_arg}\")\n\n @classmethod\n def json(self):\n return {\n \"host\": self.host,\n \"some_custom_arg\": \"example\"\n }\n\nConfigure Users from command line\n=================================\n\nYou can update User class attributes from the command line too, using the ``--config-users`` argument:\n\n.. code-block:: console\n\n $ locust --config-users '{\"user_class_name\": \"Example\", \"fixed_count\": 1, \"some_custom_attribute\": false}'\n\nTo configure multiple users you pass multiple arguments to ``--config-users``, or use a JSON Array. You can also pass a path to a JSON file.\n\n.. code-block:: console\n\n $ locust --config-users '{\"user_class_name\": \"Example\", \"fixed_count\": 1}' '{\"user_class_name\": \"ExampleTwo\", \"fixed_count\": 2}'\n $ locust --config-users '[{\"user_class_name\": \"Example\", \"fixed_count\": 1}, {\"user_class_name\": \"ExampleTwo\", \"fixed_count\": 2}]'\n $ locust --config-users my_user_config.json\n\nWhen using this way to configure your users, you can set any attribute.\n\n.. note::\n\n ``--config-users`` is a somewhat experimental feature and the json format may change even between minor Locust revisions.\n\nConfiguring Profiles\n====================\n\nProfiles are an advanced feature that allow for grouping and filtering testruns. A profile may be set using the ``--profile`` argument\nor by inputting a value in the advanced options from the web ui.\n\nIt may be useful to see a list of existing profiles as options in the form. If you have such a list, you may set it in your locustfile:\n\n.. code-block:: python\n\n from locust import events\n\n @events.init.add_listener\n def on_locust_init(environment, **kwargs):\n environment.web_ui.template_args[\"all_profiles\"] = [\"one\", \"two\", \"three\"]\n\n\nCustom arguments\n================\n\nSee :ref:`custom-arguments`\n\nCustomization of statistics settings\n====================================\n\nDefault configuration for Locust statistics is set in constants of stats.py file.\nIt can be tuned to specific requirements by overriding these values.\nTo do this, import locust.stats module and override required settings:\n\n.. code-block:: python\n\n import locust.stats\n locust.stats.CONSOLE_STATS_INTERVAL_SEC = 15\n\nIt can be done directly in Locust file or extracted to separate file for common usage by all Locust files.\n\nThe list of statistics parameters that can be modified is:\n\n+-----------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------------------------+\n| Parameter name | Purpose | Default value |\n+-----------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------------------------+\n| STATS_NAME_WIDTH | Width of column for request name in console output | terminal size or 80 |\n+-----------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------------------------+\n| STATS_TYPE_WIDTH | Width of column for request type in console output | 8 |\n+-----------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------------------------+\n| CSV_STATS_INTERVAL_SEC | Interval for how frequently the CSV file is written if this option is configured | 1 |\n+-----------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------------------------+\n| CONSOLE_STATS_INTERVAL_SEC | Interval for how frequently results are written to console / chart UI | 2 |\n+-----------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------------------------+\n| HISTORY_STATS_INTERVAL_SEC | Interval for how frequently results are written to history | 5 |\n+-----------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------------------------+\n| CURRENT_RESPONSE_TIME_PERCENTILE_WINDOW | Window size/resolution - in seconds - when calculating the current response | 10 |\n| | time percentile | |\n+-----------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------------------------+\n| PERCENTILES_TO_REPORT | List of response time percentiles to be calculated & reported | [0.50, 0.66, 0.75, 0.80, 0.90, 0.95, 0.98, 0.99, 0.999, 0.9999, 1.0] |\n+-----------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------------------------+\n| PERCENTILES_TO_STATISTICS | List of response time percentiles in the screen of statistics for UI | [0.95, 0.99] |\n+-----------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------------------------+\n| PERCENTILES_TO_CHART | List of response time percentiles in the screen of chart for UI | [0.5, 0.95] |\n+-----------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------------------------+\n\n.. _customizing-response-time-bucketing:\n\nCustomizing response time bucketing\n====================================\n\nResponse times are grouped into histogram buckets before being stored in the\n``response_times`` dict. By default, Locust rounds to approximately 2 significant\ndigits (e.g. 147 becomes 150, 3432 becomes 3400). This keeps the dict small,\nwhich matters in distributed mode where the dict is serialized from workers to master.\n\nYou can replace the bucketing function to change this behaviour:\n\n.. code-block:: python\n\n import locust.stats\n from math import floor, log10\n\n def my_bucket_function(response_time: int | float) -> int:\n \"\"\"Example: bucket to 3 significant figures.\"\"\"\n if response_time == 0:\n return 0\n return int(round(response_time, -int(floor(log10(abs(response_time)))) + 2))\n\n locust.stats.bucket_response_time = my_bucket_function\n\nThe replacement function receives a single numeric argument (the response time in\nmilliseconds) and must return a numeric value to use as the dict key. Keep in mind\nthat more unique keys means more data transferred in distributed mode.\n\nCustomization of additional static variables\n============================================\n\nThis table lists the constants that are set within locust and may be overridden.\n\n+-------------------------------------------+--------------------------------------------------------------------------------------+\n| Parameter name | Purpose |\n+-------------------------------------------+--------------------------------------------------------------------------------------+\n| locust.runners.WORKER_LOG_REPORT_INTERVAL | Interval for how frequently worker logs are reported to master. Can be disabled |\n| | by setting to a negative number |\n+-------------------------------------------+--------------------------------------------------------------------------------------+\n| locust.web.HOST_IS_REQUIRED | Makes the host field for the webui required |\n+-------------------------------------------+--------------------------------------------------------------------------------------+\n" }, { "path": "docs/custom-load-shape.rst", "content": ".. _custom-load-shape:\n\n==================\nCustom load shapes\n==================\n\nSometimes a completely custom shaped load test is required that cannot be achieved by simply setting or changing the user count and spawn rate. For example, you might want to generate a load spike or ramp up and down at custom times. By using a `LoadTestShape` class you have full control over the user count and spawn rate at all times.\n\nDefine a class inheriting the LoadTestShape class in your locust file. If this type of class is found then it will be automatically used by Locust.\n\nIn this class you define a `tick()` method that returns a tuple with the desired user count and spawn rate (or `None` to stop the test). Locust will call the `tick()` method approximately once per second.\n\nIn the class you also have access to the `get_run_time()` method, for checking how long the test has run for.\n\nExample\n-------\n\nThis shape class will increase user count in blocks of 100 and then stop the load test after 10 minutes:\n\n.. code-block:: python\n\n class MyCustomShape(LoadTestShape):\n time_limit = 600\n spawn_rate = 20\n \n def tick(self):\n run_time = self.get_run_time()\n\n if run_time < self.time_limit:\n # User count rounded to nearest hundred.\n user_count = round(run_time, -2)\n return (user_count, self.spawn_rate)\n\n return None\n\nThis functionality is further demonstrated in the `examples on github `_ including:\n\n- Generating a double wave shape\n- Time based stages like K6\n- Step load pattern like Visual Studio\n\nOne further method may be helpful for your custom load shapes: `get_current_user_count()`, which returns the total number of active users. This method can be used to prevent advancing to subsequent steps until the desired number of users has been reached. This is especially useful if the initialization process for each user is slow or erratic in how long it takes. If this sounds like your use case, see the `example on github `_.\n\nNote that if you want to defined your own custom base shape, you need to define the `abstract` attribute to `True` to avoid it being picked as Shape when imported:\n\n.. code-block:: python\n\n class MyBaseShape(LoadTestShape):\n abstract = True\n \n def tick(self):\n # Something reusable but needing inheritance\n return None\n\n\nCombining Users with different load profiles\n--------------------------------------------\n\nIf you use the Web UI, you can add the :ref:`---class-picker ` parameter to select which shape to use. But it often more flexible to have your User definitions in one file and your LoadTestShape in a separate one. For example, if you a high/low load Shape class defined in low_load.py and high_load.py respectively:\n\n.. code-block:: console\n\n $ locust -f locustfile.py,low_load.py\n\n $ locust -f locustfile.py,high_load.py\n\nRestricting which user types to spawn in each tick\n--------------------------------------------------\n\nAdding the element ``user_classes`` to the return value gives you more detailed control:\n\n.. code-block:: python\n\n class StagesShapeWithCustomUsers(LoadTestShape):\n\n stages = [\n {\"duration\": 10, \"users\": 10, \"spawn_rate\": 10, \"user_classes\": [UserA]},\n {\"duration\": 30, \"users\": 50, \"spawn_rate\": 10, \"user_classes\": [UserA, UserB]},\n {\"duration\": 60, \"users\": 100, \"spawn_rate\": 10, \"user_classes\": [UserB]},\n {\"duration\": 120, \"users\": 100, \"spawn_rate\": 10, \"user_classes\": [UserA,UserB]},\n ]\n\n def tick(self):\n run_time = self.get_run_time()\n\n for stage in self.stages:\n if run_time < stage[\"duration\"]:\n try:\n tick_data = (stage[\"users\"], stage[\"spawn_rate\"], stage[\"user_classes\"])\n except:\n tick_data = (stage[\"users\"], stage[\"spawn_rate\"])\n return tick_data\n\n return None\n\nThis shape would create create in the first 10 seconds 10 User of ``UserA``. In the next twenty seconds 40 of type ``UserA / UserB`` and this continues until the stages end.\n\n\n.. _use-common-options:\n\nReusing common options in custom shapes\n---------------------------------------\n\nWhen using shapes, the the *Users*, *Spawn Rate* and *Run Time* options will be hidden from the UI, and if you specify them on command line Locust will log a warning. This is because those options dont directly apply to shapes, and specifying them might be a mistake.\n\nIf you really want to combine a shape with these options, set the ``use_common_options`` attribute and access them from ``self.runner.environment.parsed_options``:\n\n.. code-block:: python\n\n class MyCustomShape(LoadTestShape):\n use_common_options = True\n \n def tick(self):\n run_time = self.get_run_time()\n if run_time < self.runner.environment.parsed_options.run_time:\n # User count rounded to nearest hundred, just like in previous example\n user_count = round(run_time, -2)\n return (user_count, self.runner.environment.parsed_options.spawn_rate)\n \n return None\n" }, { "path": "docs/developing-locust.rst", "content": ".. _developing-locust:\n\n=================================\nDeveloping and Documenting Locust\n=================================\n\nYou want to contribute to Locust? Great! Here is a list of `open bugs/feature requests `_.\n\nInstall Locust for development\n==============================\n\nFork Locust on `GitHub `_ and then\n\n.. code-block:: sh\n\n # clone the repo:\n $ git clone git://github.com//locust.git\n\n # install the `uv` build system, https://docs.astral.sh/uv/getting-started/installation/\n\n # [optional] create a virtual environment and activate it\n $ uv venv\n $ . .venv/bin/activate\n\n # perform an editable install of the \"locust\" package along with the dev and test packages:\n $ uv sync\n\nNow the ``uv --directory locust run locust`` command will run *your* code (with no need for reinstalling after making changes). If you have installed the project to a virtual environment, you can simply call `locust`.\n\nTo contribute your changes, push to a branch in your repo and then `open a PR on github `_. \n\nIf you install `pre-commit `_, linting and format checks/fixes will be automatically performed before each commit.\n\nBefore you open a pull request, make sure all the tests work. And if you are adding a feature, make sure it is documented (in ``docs/*.rst``).\n\nIf you're in a hurry or don't have access to a development environment, you can simply use `Codespaces `_, the github cloud development environment. On your fork page, just click on *Code* then on *Create codespace on *, and voila, your ready to code and test.\n\nTesting your changes\n====================\n\nWe use `hatch `_ to automate tests across multiple Python versions.\n\nAll tests:\n\n.. code-block:: console\n\n $ hatch test\n ...\n py39: commands[1]> pytest locust/test\n ...\n\nYou can also run these tests against a specific Python version\n\n.. code-block:: console\n\n $ hatch test -py=3.10\n ...\n py39: commands[1]> pytest locust/test\n ...\n\nTo only run a specific suite or specific test you can call `pytest `_ directly.\n\nAll tests:\n\n.. code-block:: console\n\n $ pytest locust/test\n\nIndividual test:\n\n.. code-block:: console\n\n $ pytest locust/test/test_main.py::DistributedIntegrationTests::test_distributed_tags\n\nDebugging\n=========\n\nSee: :ref:`running-in-debugger`.\n\nFormatting and linting\n======================\n\nLocust uses `ruff `_ for formatting and linting. The build will fail if code does not adhere to it. If you run vscode it will automatically run every time you save a file, but if your editor doesn't support it you can run it manually:\n\n.. code-block:: console\n\n $ ruff --fix \n $ ruff format \n\nYou can validate the whole project using hatch:\n\n.. code-block:: console\n\n $ hatch run lint:format\n ruff: commands[0]> ruff check .\n ruff: commands[1]> ruff format --check\n 104 files already formatted\n ruff: OK (1.41=setup[1.39]+cmd[0.01,0.01] seconds)\n congratulations :) (1.47 seconds)\n\nBuild documentation\n===================\n\nThe documentation source is in the `docs/ `_ directory. To build the documentation you'll need to `Install Locust for development`_ then\n\n#. Install the documentation requirements:\n\n .. code-block:: console\n\n $ uv sync --all-groups\n\n#. Build the documentation locally:\n\n .. code-block:: console\n\n $ make build_docs\n \nView your generated documentation by opening ``docs/_build/index.html`` or running `make serve_docs`\n\n\nMaking changes to Locust's Web UI\n=================================\n\nThe Web UI is built using React and Typescript\n\nSetup\n-----\n\nNode\n````\n\nInstall node using nvm to easily switch between node version\n\n- Copy and run the install line from `nvm `_ (starts with curl/wget ...)\n\n- Verify nvm was installed correctly\n\n.. code-block:: console\n\n $ nvm --version\n\n- Install the proper Node version according to engines in the ``locust/webui/package.json``\n\n.. code-block:: console\n\n $ nvm install {version}\n $ nvm alias default {version}\n\nYarn\n````\n\n- Install Yarn from their official website (avoid installing through Node if possible)\n- Verify yarn was installed correctly\n\n.. code-block:: console\n\n $ yarn --version\n\n- Next, install all dependencies\n\n.. code-block:: console\n\n $ cd locust/webui\n $ yarn\n\n\nDeveloping\n----------\n\nTo develop while running a locust instance, run ``yarn watch``. This will output the static files to the ``dist`` directory. Vite will automatically detect any changed files and re-build as needed. Simply refresh the page to view the changes\n\nIn certain situations (usually when styling), you may want to develop the frontend without running a locust instance. Running ``yarn dev`` will start the Vite dev server and allow for viewing your changes.\n\nTo compile the webui, run ``yarn build``\n\nThe frontend can additionally be built using make:\n\n.. code-block:: console\n\n $ make frontend_build\n\n\nLinting\n-------\n\nRun ``yarn lint`` to detect lint failures in the frontend project. Running ``yarn lint --fix`` will resolve any issues that are automatically resolvable. Your IDE can additionally be configured with ESLint to resolve these issues on save.\n\nFormatting\n----------\n\nRun ``yarn format`` to fix any formatting issues in the frontend project. Once again your IDE can be configured to automatically format on save.\n\nTypechecking\n------------\n\nWe use Typescript in the frontend project. Run ``yarn type-check`` to find any issues.\n" }, { "path": "docs/extending-locust.rst", "content": ".. _extending_locust:\n\n===========\nEvent hooks\n===========\n\nLocust comes with a number of event hooks that can be used to extend Locust in different ways.\n\nFor example, here's how to set up an event listener that will trigger after a request is completed::\n\n from locust import events\n\n @events.request.add_listener\n def my_request_handler(request_type, name, response_time, response_length, response,\n context, exception, start_time, url, **kwargs):\n if exception:\n print(f\"Request to {name} failed with exception {exception}\")\n else:\n print(f\"Successfully made a request to: {name}\")\n print(f\"The response was {response.text}\")\n\n.. note::\n\n In the above example the wildcard keyword argument (\\**kwargs) will be empty, because we're handling all arguments, but it prevents the code from breaking if new arguments are added in some future version of Locust.\n\n Also, it is entirely possible to implement a client that does not supply all parameters for this event.\n For example, non-HTTP protocols might not even have the a concept of `url` or `response` object.\n Remove any such missing field from your listener function definition or use default arguments.\n\nWhen running locust in distributed mode, it may be useful to do some setup on worker nodes before running your tests.\nYou can check to ensure you aren't running on the master node by checking the type of the node's :py:attr:`runner `::\n\n from locust import events\n from locust.runners import MasterRunner\n\n @events.test_start.add_listener\n def on_test_start(environment, **kwargs):\n if not isinstance(environment.runner, MasterRunner):\n print(\"Beginning test setup\")\n else:\n print(\"Started test from Master node\")\n\n @events.test_stop.add_listener\n def on_test_stop(environment, **kwargs):\n if not isinstance(environment.runner, MasterRunner):\n print(\"Cleaning up test data\")\n else:\n print(\"Stopped test from Master node\")\n\nYou can also use events `to add custom command line arguments `_.\n\nTo see a full list of available events see :ref:`events`.\n\n.. _request_context:\n\n\nRequest context\n===============\n\nThe :py:attr:`request event ` has a context parameter that enable you to pass data `about` the request (things like username, tags etc). It can be set directly in the call to the request method or at the User level, by overriding the User.context() method.\n\nContext from request method::\n\n class MyUser(HttpUser):\n @task\n def t(self):\n self.client.post(\"/login\", json={\"username\": \"foo\"})\n self.client.get(\"/other_request\", context={\"username\": \"foo\"})\n\n @events.request.add_listener\n def on_request(context, **kwargs):\n if context:\n print(context[\"username\"])\n\nContext from User instance::\n\n class MyUser(HttpUser):\n def context(self):\n return {\"username\": self.username}\n\n @task\n def t(self):\n self.username = \"foo\"\n self.client.post(\"/login\", json={\"username\": self.username})\n\n @events.request.add_listener\n def on_request(context, **kwargs):\n print(context[\"username\"])\n\n\nContext from a value in the response, using :ref:`catch_response `::\n\n with self.client.get(\"/\", catch_response=True) as resp:\n resp.request_meta[\"context\"][\"requestId\"] = resp.json()[\"requestId\"]\n\n.. note::\n\n Request context doesn't change how Locust's regular statistics are calculated.\n\nAdding Web Routes\n==================\n\nLocust uses Flask to serve the web UI and therefore it is easy to add web end-points to the web UI.\nBy listening to the :py:attr:`init ` event, we can retrieve a reference\nto the Flask app instance and use that to set up a new route::\n\n from locust import events\n\n @events.init.add_listener\n def on_locust_init(environment, **kw):\n @environment.web_ui.app.route(\"/added_page\")\n def my_added_page():\n return \"Another page\"\n\nYou should now be able to start locust and browse to http://127.0.0.1:8089/added_page. Note that it doesn't get automatically added as a new tab - you'll need to enter the URL directly.\n\nExtending Web UI\n================\n\nAs an alternative to adding simple web routes, you can use `Flask Blueprints\n`_ and `templates\n`_ to not only add routes but also extend\nthe web UI to allow you to show custom data along side the built-in Locust stats. This is more advanced but can\ngreatly enhance the utility and customizability of the web UI.\n\nWorking examples of extending the web UI can be found\nin the `examples directory `_ of the Locust\nsource code.\n\n* ``extend_modern_web_ui.py``: Display a table with content-length for each call.\n\n* ``web_ui_cache_stats.py``: Display Varnish Hit/Miss stats for each call. This could easily be extended to other CDN or cache proxies and gather other cache statistics such as cache age, control, ...\n\n .. image:: images/extend_modern_web_ui_cache_stats.png\n\n\nAdding Authentication to the Web UI\n===================================\n\nLocust uses `Flask-Login `_ to handle authentication when the ``--web-login`` flag is present.\nThe ``login_manager`` is exposed on ``environment.web_ui.app``, allowing the flexibility for you to implement any kind of auth that\nyou would like!\n\nTo use username / password authentication, simply provide a ``username_password_callback`` to the ``environment.web_ui.auth_args``.\nYou are responsible for defining the route for the callback and implementing the authentication.\n\nAuthentication providers can additionally be configured to allow authentication from 3rd parties such as GitHub or an SSO provider.\nSimply provide a list of desired ``auth_providers``. You may specify the ``label`` and ``icon`` for display on the button.\nThe ``callback_url`` will be the url that the button directs to. You will be responsible for defining the callback route as\nwell as the authentication with the 3rd party.\n\nWhether you are using username / password authentication, an auth provider, or both, a ``user_loader`` needs to be proivded\nto the ``login_manager``. The ``user_loader`` should return ``None`` to deny authentication or return a User object when\nauthentication to the app should be granted.\n\nTo display errors on the login page, such as an incorrect username / password combination, you may store the ``auth_error``\non the session object: ``session[\"auth_error\"] = \"Incorrect username or password\"``. If you have non-erroneous information\nyou would like to display to the user, you can opt instead to set ``auth_info`` on the session object:\n``session[\"auth_info\"] = \"Successfully created new user!\"``\n\nA full example can be seen `in the auth example `_.\n\nIn certain situations you may wish to further extend the fields present in the auth form. To achieve this, pass a ``custom_form`` dict\nto the ``environment.web_ui.auth_args``. In this case, the fields will be represented by a list of ``inputs``, the callback url is\nconfigured by the ``custom_form.callback_url``, and the submit button may optionally be configured using the ``custom_form.submit_button_text``.\nThe fields in the auth form may be a text, select, checkbox, or secret password field. You may additionally override the HTML input type for\nspecific field validation (e.g. type=email).\n\nFor a full example see `configuring the custom_form in the auth example `_.\n\n\nRun a background greenlet\n=========================\n\nBecause a locust file is \"just code\", there is nothing preventing you from spawning your own greenlet to\nrun in parallel with your actual load/Users.\n\nFor example, you can monitor the fail ratio of your test and stop the run if it goes above some threshold:\n\n.. code-block:: python\n\n import gevent\n from locust import events\n from locust.runners import STATE_STOPPING, STATE_STOPPED, STATE_CLEANUP, MasterRunner, LocalRunner\n\n def checker(environment):\n while not environment.runner.state in [STATE_STOPPING, STATE_STOPPED, STATE_CLEANUP]:\n time.sleep(1)\n if environment.runner.stats.total.fail_ratio > 0.2:\n print(f\"fail ratio was {environment.runner.stats.total.fail_ratio}, quitting\")\n environment.runner.quit()\n return\n\n\n @events.init.add_listener\n def on_locust_init(environment, **_kwargs):\n # dont run this on workers, we only care about the aggregated numbers\n if isinstance(environment.runner, MasterRunner) or isinstance(environment.runner, LocalRunner):\n gevent.spawn(checker, environment)\n\n.. _parametrizing-locustfiles:\n\n\nParametrizing locustfiles\n=========================\n\nThere are two main ways to parametrize your locustfile.\n\nBasic environment variables\n---------------------------\n\nLike with any program, you can use environment variables:\n\nOn linux/mac:\n\n.. code-block:: bash\n\n MY_FUNKY_VAR=42 locust ...\n\nOn windows:\n\n.. code-block:: bash\n\n SET MY_FUNKY_VAR=42\n locust ...\n\n... and then access them in your locustfile.\n\n.. code-block:: python\n\n import os\n print(os.environ['MY_FUNKY_VAR'])\n\n.. _custom-arguments:\n\nCustom arguments\n----------------\n\nYou can add your own command line arguments to Locust, using the :py:attr:`init_command_line_parser ` Event. Custom arguments are also presented and editable in the web UI. \nIf `choices` are specified for the argument, they will be presented as a dropdown in the web UI.\nIf `is_multiple` is set to True together with `choices`, the argument will be presented as a multi-select dropdown in the web UI.\n\n.. literalinclude:: ../examples/add_command_line_argument.py\n :language: python\n\nWhen running Locust :ref:`distributed `, custom arguments are automatically forwarded to workers when the run is started (but not before then, so you cannot rely on forwarded arguments *before* the test has actually started).\n\n\nTest data management\n====================\n\nThere are a number of ways to get test data into your tests (after all, your test is just a Python program and it can do whatever Python can). Locust's events give you fine-grained control over *when* to fetch/release test data. You can find a `detailed example here `_.\n\n\nMore examples\n=============\n\nSee `locust-plugins `_\n" }, { "path": "docs/extensions.rst", "content": ".. _extensions:\n\n======================\nThird party extensions\n======================\n\nSupport for load testing other protocols, reporting etc\n-------------------------------------------------------\n\n- `locust-plugins `__\n\n - request logging & graphing\n - new protocols like selenium/webdriver, http users that\n load html page resources\n - readers (ways to get test data into your tests)\n - wait time (custom wait time functions)\n - checks (adds command line parameters to set locust exit code based\n on requests/s, error percentage and average response times)\n\nAutomatically translate a browser recording (HAR-file) to a locustfile\n----------------------------------------------------------------------\n\n- `har2locust `__\n\nWorkers written in other languages than Python\n----------------------------------------------\n\nA Locust master and a Locust worker communicate by exchanging\n`msgpack `__ messages, which is supported by many\nlanguages. So, you can write your User tasks in any languages you like.\nFor convenience, some libraries do the job as a worker runner. They run\nyour User tasks, and report to master regularly.\n\n- `Boomer `__ - Go\n- `Locust4j `__ - Java\n" }, { "path": "docs/faq.rst", "content": ".. _faq:\n\n===\nFAQ\n===\n\nHow do I…\n\nResolve errors that occur during load (error 5xx, Connection aborted, Connection reset by peer, etc)\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n Check your server logs. If it works at low load then it is almost\n certainly not a Locust issue, but an issue with the system you are\n testing.\n\nClear cookies, to make the next task iteration seem like a new user to my system under test\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n Call ``self.client.cookies.clear()`` at the end of your task.\n\nControl headers or other things about my HTTP requests\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n Locust’s client in ``HttpUser`` inherits from\n `requests `__ and the\n vast majority of parameters and methods for requests should just work\n with Locust. Check out the docs and Stack Overflow answers for\n requests first and then ask on Stack Overflow for additional Locust\n specific help if necessary.\n\n\nBasic auth (Authorization header) does not work after redirection\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n `requests `__ has a security mecanism that\n drops the authorization header on domain change. It could occure when testing a SSO,\n which is typically on a different domain and use mulitple redirections (30x).\n\n Since ``allow_redirects=True`` is the default ``request`` behavior you'll have to turn it off,\n handle manually the redirections and inject again the authorization header, ex:\n\n\n.. code-block:: python\n\n response = self.client.post(\n allow_redirects=False,\n url=...)\n\n while \"location\" in response.headers:\n response = self.client.get(\n allow_redirects=False,\n url=response.headers['location'],\n headers={\n 'Authorization': 'XXX'\n }\n )\n\n\nCreate a Locust file based on a recorded browser session\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n Try using `har2locust `__\n\nHow to run a Docker container of Locust in Windows Subsystem for Linux (Windows 10 users)?\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n If you use WSL on a Windows computer, then you need one extra step\n than the `“docker run …”\n command `__:\n copy your locusttest1.py to a folder in a Windows path on your WSL\n and mount that folder instead of your normal WSL folder:\n\n::\n\n $ mkdir /c/Users/[YOUR_Windows_USER]/Documents/Locust/\n $ cp ~/path/to/locusttest1.py /c/Users/[YOUR_Windows_USER]/Documents/Locust/\n $ docker run -p 8089:8089 -v /c/Users/[YOUR_Windows_USER]/Documents/Locust/:/mnt/locust locustio/locust:1.3.1 -f /mnt/locust/locusttest1.py\n\nHow to run locust on custom endpoint\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n Prefix the the endpoint to all ``@app.route`` definitions in\n ``locust/web.py`` file & also change as follows (where ``/locust`` is\n new endpoint)\n\n``app = Flask(__name__, static_url_path='/locust')``\n\n Change the entries of static content location in file\n ``locust/templates/index.html``.\n\nEg:\n````\n\nLocust web UI doesn’t show my tasks running, says 0 RPS\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nLocust only knows what you’re doing when you tell it. There are `Event\nHooks `__ that you use\nto tell Locust what’s going on in your code. If you use Locust’s\n``HttpUser`` and then use ``self.client`` to make http calls, the proper\nevents are normally fired for you automatically, making less work for\nyou unless you want to override the default events.\n\nIf you use the plain ``User`` or use ``HttpUser`` and you’re not using\n``self.client`` to make http calls, Locust will not fire events for you.\nYou will have to fire events yourself. See `the Locust\ndocs `__\nfor examples.\n\nHTML Report is filled up with failed requests for long running tests\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nhttps://github.com/locustio/locust/issues/2328\n\nOther questions and issues\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n`Check the list of issues (a lot of questions/misunderstandings are\nfiled as\nissues) `__\n\nAdd things that you ran into and solved here! Anyone with a GitHub\naccount can contribute!\n\nIf you have questions about Locust that are not answered here, please\ncheck\n`StackOverflow `__,\nor post your question there. This wiki is not for asking questions but\nfor answering them :)\n" }, { "path": "docs/further-reading.rst", "content": "===============================\nFurther reading / knowledgebase\n===============================\n\n- :ref:`extensions`.\n\n- An list of Locust `articles, blog posts, reviews, and walkthroughs `_.\n\n- :ref:`Common questions and answers about Locust `.\n\nYou'll also find a lot of answers on `stackoverflow `_, for example:\n\n- `BadStatusLine Errors `_\n\n- `Passing HTTP Headers `_\n\n- `POST file upload `_\n\n- `How often does Locust perform dns queries? `_\n\nIn other words, just google whatever problem or error message you're getting and you are likely to find good answers out there.\n\nIf you think Locust is missing some obvious feature (like stopping after a certain number of iterations/requests, setting goals/thresholds for when to fail a test run, support for additional User types like Kafka, Selenium/WebDriver etc), chances are it is implemented in `locust-plugins `_.\n" }, { "path": "docs/history.rst", "content": ":orphan:\n.. _history:\n\n===============================\nThe history of Locust\n===============================\n\nLocust was created because we were fed up with existing solutions. None of them are solving the \nright problem and to me, they are missing the point. We've tried both Apache JMeter and Tsung. \nBoth tools are quite OK to use; we've used the former many times benchmarking stuff at work.\nJMeter comes with a UI, which you might think for a second is a good thing. But you soon realize it's\na PITA to \"code\" your testing scenarios through some point-and-click interface. Secondly, JMeter \nis thread-bound. This means for every user you want to simulate, you need a separate thread. \nNeedless to say, benchmarking thousands of users on a single machine just isn't feasible.\n\nTsung, on the other hand, does not have these thread issues as it's written in Erlang. It can make \nuse of the light-weight processes offered by BEAM itself and happily scale up. But when it comes to \ndefining the test scenarios, Tsung is as limited as JMeter. It offers an XML-based DSL to define how \na user should behave when testing. I guess you can imagine the horror of \"coding\" this. Displaying \nany sorts of graphs or reports when completed requires you to post-process the log files generated from\nthe test. Only then can you get an understanding of how the test went.\n\nAnyway, we've tried to address these issues when creating Locust. Hopefully none of the above \npain points should exist.\n\nI guess you could say we're really just trying to scratch our own itch here. We hope others will \nfind it as useful as we do.\n\n- `Jonatan Heyman `_ (`@jonatanheyman `_ on Twitter)\n" }, { "path": "docs/increase-performance.rst", "content": ".. _increase-performance:\n\n==============================================================\nIncrease performance with a more efficient HTTP client\n==============================================================\n\nLocust's default HTTP client uses `python-requests `_.\nIt provides a nice API that many python developers are familiar with, and is very well-maintained. But if you're planning to run tests with very high throughput and have limited hardware for running Locust, it is sometimes not efficient enough.\n\nBecause of this, Locust also comes with :py:class:`FastHttpUser ` which\nuses `geventhttpclient `_ instead.\nIt provides a very similar API and uses significantly less CPU time, sometimes increasing the maximum number of requests per second on a given hardware by as much as 5x-6x.\n\nIt is impossible to say how many requests Locust can do on your particular hardware, using your particular test plan, so you'll need to test it out. Check Locust's console output, it will log a warning if it is limited by CPU.\n\nIn a *best case* scenario (doing small requests inside a ``while True``-loop) a single Locust process (limited to one CPU core) can do around **16000 requests per second using FastHttpUser, and 4000 using HttpUser** (tested on a 2021 M1 MacBook Pro and Python 3.11)\n\nThe relative improvement may be even bigger with bigger request payloads, but it may also be smaller if your test is doing CPU intensive things not related to requests.\n\nOf course, in reality, you should run :ref:`one locust process per CPU core `.\n\n.. note::\n\n As long as your load generator CPU is not overloaded, FastHttpUser's response times should be almost identical to those of HttpUser. It does not make individual requests faster.\n\nHow to use FastHttpUser\n===========================\n\nJust subclass FastHttpUser instead of HttpUser::\n\n from locust import task, FastHttpUser\n \n class MyUser(FastHttpUser):\n @task\n def index(self):\n response = self.client.get(\"/\")\n\nConcurrency\n===========\n\nA single FastHttpUser/geventhttpclient session can run concurrent requests, you just have to launch greenlets for each request::\n\n @task\n def t(self):\n def concurrent_request(url):\n self.client.get(url)\n\n pool = gevent.pool.Pool()\n urls = [\"/url1\", \"/url2\", \"/url3\"]\n for url in urls:\n pool.spawn(concurrent_request, url)\n pool.join()\n\n\n.. note::\n\n FastHttpUser/geventhttpclient is very similar to HttpUser/python-requests, but sometimes there are subtle differences. This is particularly true if you work with the client library's internals, e.g. when manually managing cookies.\n\n.. _rest:\n\nREST\n====\n\nFastHttpUser provides a ``rest`` method for testing REST/JSON HTTP interfaces. It is a wrapper for ``self.client.request`` that:\n \n* Parses the JSON response to a dict called ``js`` in the response object. Marks the request as failed if the response was not valid JSON.\n* Defaults ``Content-Type`` and ``Accept`` headers to ``application/json``\n* Sets ``catch_response=True`` (so always use a :ref:`with-block `)\n* Catches any unhandled exceptions thrown inside your with-block, marking the sample as failed (instead of exiting the task immediately without even firing the request event)\n\n.. code-block:: python\n\n from locust import task, FastHttpUser\n\n class MyUser(FastHttpUser):\n @task\n def t(self):\n with self.rest(\"POST\", \"/\", json={\"foo\": 1}) as resp:\n if resp.js is None:\n pass # no need to do anything, already marked as failed\n elif \"bar\" not in resp.js:\n resp.failure(f\"'bar' missing from response {resp.text}\")\n elif resp.js[\"bar\"] != 42:\n resp.failure(f\"'bar' had an unexpected value: {resp.js['bar']}\")\n\nFor a complete example, see `rest.py `_. That also shows how you can use inheritance to provide behaviors specific to your REST API that are common to multiple requests/testplans.\n\n.. note::\n\n This feature is new and details of its interface/implementation may change in new versions of Locust.\n\n\nConnection Handling\n===================\n\nBy default, a User will reuse the same TCP/HTTP connection (unless it breaks somehow). To more realistically simulate new browsers connecting to your application this connection can be manually closed.\n\n.. code-block:: python\n\n @task\n def t(self):\n self.client.client.clientpool.close() # self.client.client is not a typo\n self.client.get(\"/\") # Here a new connection will be created\n\n\nAPI\n===\n\n\nFastHttpUser class\n--------------------\n\n.. autoclass:: locust.contrib.fasthttp.FastHttpUser\n :members: network_timeout, connection_timeout, max_redirects, max_retries, insecure, proxy_host, proxy_port, concurrency, client_pool, rest, rest_\n\n\nFastHttpSession class\n---------------------\n\n.. autoclass:: locust.contrib.fasthttp.FastHttpSession\n :members: request, get, post, delete, put, head, options, patch\n\n.. autoclass:: locust.contrib.fasthttp.FastResponse\n :members: content, text, json, headers\n" }, { "path": "docs/increasing-request-rate.rst", "content": ".. _increaserr:\n\n===========================\nIncreasing the request rate\n===========================\n\nIf you're not getting the desired/expected throughput there are a number of things you can do.\n\nConcurrency\n-----------\n\nIncrease the number of Users. To fully utilize your target system you may need a lot of concurrent requests. Note that spawn rate/ramp up does not change peak load, it only changes how fast you get there. High `wait times `_ and sleeps *do* impact throughput, so that may make it necessary to launch even more Users. You can find a whole blog post on this topic `here `__.\n\nLoad generation performance\n---------------------------\n\nIf Locust prints a warning about high CPU usage (``WARNING/root: CPU usage above 90%! ...``) try the following:\n\n - Run Locust `distributed `__ to utilize multiple cores & multiple machines\n - Try switching to `FastHttpUser `__ to reduce CPU usage\n - Check to see that there are no strange/infinite loops in your code\n\nAlso, if you are using a custom client (not HttpUser or FastHttpUser), make sure any client library you are using is `gevent-friendly `__ otherwise it will block the entire Python process (essentially limiting you to one user per worker)\n\nIf you're doing really high throughput or using a lot of bandwidth, you may also want to check out your network utilization and other OS level metrics.\n\n\nActual issues with the system under test\n----------------------------------------\n\nIf response times are high and/or increasing as the number of users go up, then you have probably saturated the system you are testing. This is not a Locust problem, but here are some things you may want to check:\n\n - resource utilization (e.g. CPU, memory & network)\n - configuration (e.g. max threads for your web server)\n - back end response times (e.g. DB)\n\nThere are a few common pitfalls specific to load testing too:\n\n - load balancing (make sure locust isn't hitting only a few of your instances)\n - flood protection (sometimes a load test with the high amount of load from only a few machines will trigger this)\n" }, { "path": "docs/index.rst", "content": "=====================\nLocust Documentation\n=====================\n\n\n\nGetting started\n---------------\n\n.. toctree ::\n :maxdepth: 2\n\n what-is-locust\n installation\n quickstart\n\n\nWriting Locust tests\n--------------------\n\n.. toctree ::\n :maxdepth: 2\n\n writing-a-locustfile\n\n\nRunning your Locust tests\n-------------------------\n\n.. toctree ::\n :maxdepth: 1\n\n configuration\n increasing-request-rate\n running-distributed\n running-in-debugger\n running-in-docker\n running-without-web-ui\n\n\nOther functionalities\n---------------------\n\n.. toctree ::\n :maxdepth: 2\n\n custom-load-shape\n retrieving-stats\n testing-other-systems\n increase-performance\n extending-locust\n logging\n use-as-lib\n telemetry\n extensions\n kubernetes-operator\n vscode-extension\n\n\nFurther reading / knowledgebase\n-------------------------------\n\n.. toctree ::\n :maxdepth: 1\n\n developing-locust\n further-reading\n faq\n\n\nAPI\n---\n\n.. toctree ::\n :maxdepth: 2\n\n api\n\n\nChangelog\n---------\n\n.. toctree ::\n :maxdepth: 2\n\n changelog\n" }, { "path": "docs/installation.rst", "content": ".. _installation:\n\nInstallation\n============\n\n.. note::\n\n Check `Troubleshooting Installation`_ if you encounter issues.\n\n0. `Install Python `_ (if you dont already have it)\n\n1. Install Locust\n\n.. code-block:: console\n\n $ pip install locust\n\n2. Validate your installation\n\n.. code-block:: console\n :substitutions:\n\n $ locust -V\n locust |version| from /usr/local/lib/python3.12/site-packages/locust (Python 3.12.5)\n\n\nUsing uvx (alternative)\n-----------------------\n\n0. `Install uv `_\n\n1. Install and run locust in an ephemeral environment\n\n.. code-block:: console\n :substitutions:\n\n $ uvx locust -V\n locust |version| from /.../uv/.../locust (Python 3.12.5)\n\nDone!\n-----\n\nNow you can :ref:`create and run your first test `\n\n-----------------\n\n\nPre-release builds\n------------------\n\nIf you need the latest and greatest version of Locust and cannot wait for the next release, you can install a dev build like this:\n\n.. code-block:: console\n\n $ pip3 install -U --pre locust\n\nPre-release builds are published every time a branch/PR is merged into master.\n\nInstall for development\n-----------------------\n\nIf you want to modify Locust, or contribute to the project, see :ref:`developing-locust`.\n\nTroubleshooting installation\n----------------------------\n\n\n.. contents:: Some solutions for common installation issues\n :depth: 1\n :local:\n :backlinks: none\n\n\npsutil/\\_psutil_common.c:9:10: fatal error: Python.h: No such file or directory\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n`Answered in Stackoverflow thread 63440765 `_\n\nERROR: Failed building wheel for xxx\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nWhile Locust itself is a pure Python package, it has some dependencies\n(e.g. gevent and geventhttpclient) that are compiled from C code. Pretty\nmuch all common platforms have binary packages on PyPi, but sometimes\nthere is a new release that doesn't, or you are running on some exotic\nplatform. You have two options:\n\n- (on macos) Install xcode: ``xcode-select --install``\n- Use ``pip install --prefer-binary locust`` to select a pre-compiled\n version of packages even if there is a more recent version available\n as source.\n- Try googling the error message for the specific package that failed\n (not Locust), ensure you have the appropriate build tools installed\n etc.\n\nWindows\n~~~~~~~\n\n`Answered in Stackoverflow thread 61592069 `_\n\nInstallation works, but the ``locust`` command is not found\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nWhen running pip, did you get a warning saying ``The script locust is installed in '...' which is not on PATH``?\n\nAdd that directory to your PATH environment variable.\n\nIncreasing Maximum Number of Open Files Limit\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nEvery User/HTTP connection from Locust opens a new file (technically\na file descriptor). Many operating systems by default set a low limit\nfor the maximum number of files that can be open at the same time.\nLocust will try to adjust this automatically for you, but in a lot of\ncases your operating system will not allow it (in which case you will\nget a warning in the log). Instead you will have to do it manually.\n\nHow to do this depends on your operating system, but you might find\nsome useful information here:\nhttps://www.tecmint.com/increase-set-open-file-limits-in-linux/ and\npractical examples\nhttps://www.ibm.com/support/knowledgecenter/SS8NLW_11.0.2/com.ibm.discovery.es.in.doc/iiysiulimits.html\n\nFor systemd-based systems (e.g. Debian/Ubuntu) different limits are\nused for graphical login sessions. See\nhttps://unix.stackexchange.com/a/443467 for additional settings.\n" }, { "path": "docs/kubernetes-operator.rst", "content": ".. _kubernetes-operator:\n\nKubernetes Operator\n===================\n\nThe Locust Operator for Kubernetes is an operator that manages the lifecyle of :ref:`running-distributed` inside a Kubernetes cluster.\n\nIt is a Custom Resource Definition (CRD) and a Controller that run on your Kubernetes cluster and allow you to create and manage your Locust tests as Kubernetes resources.\nAutomatically creates master/worker jobs, mounts locustfiles, exposes the web UI, collects metrics, and handles restarts when the spec changes.\n\n\nInstallation\n------------\n\nHelm Charts\n~~~~~~~~~~~\n\n`Helm `_ is a package manager for Kubernetes that installs and manages Kubernetes applications.\n\n1. Add the Helm repository\n\n.. code-block:: bash\n\n $ helm repo add locust-operator https://locustio.github.io/k8s-operator\n \"locust-operator\" has been added to your repositories\n\n $ helm repo update\n Hang tight while we grab the latest from your chart repositories...\n ...Successfully got an update from the \"locust-operator\" chart repository\n Update Complete. ⎈Happy Helming!⎈\n\n2. Install Locust Operator for Kubernetes\n\n.. code-block:: bash\n\n $ helm install locust-operator locust-operator/locust-operator \\\n --namespace locust-operator --create-namespace\n\n3. Check that the operator is running and the CRD is installed\n\n.. code-block:: bash\n\n $ kubectl get pods -A -l app.kubernetes.io/name=locust-operator \n NAMESPACE NAME READY STATUS RESTARTS AGE\n locust-operator locust-operator-xxxxxxxxx-xxxxx 1/1 Running 0 18s\n\n $ kubectl get crd [none 🚀]\n NAME CREATED AT\n locusttests.locust.io ...\n\nManifest Files\n~~~~~~~~~~~~~~\n\nLocust Operator for Kubernetes can be installed using raw manifest files with `kubectl `_.\nTo generate the raw resources, you can use the Helm chart and output the manifests without installing them.\n\n.. code-block:: bash\n\n $ helm repo add locust-operator https://locustio.github.io/k8s-operator\n $ helm repo update\n $ helm template locust-operator locust-operator/locust-operator \\\n --namespace locust-operator > locust-operator.yaml\n\nThen apply the generated manifest file:\n\n.. code-block:: bash\n\n $ kubectl apply -f locust-operator.yaml\n\n\nQuickstart\n----------\n\n1. Create a YAML file defining a ``LocustTest`` resource.\n\n.. code-block:: yaml\n\n apiVersion: locust.io/v1\n kind: LocustTest\n metadata:\n name: load-test\n spec:\n workers: 2\n locustfile:\n content: |\n from locust import HttpUser, task\n class TestUser(HttpUser):\n @task\n def index(self):\n self.client.get(\"/\")\n\n2. Apply it using ``kubectl apply -f .yaml``.\n\n3. You can verify the created resource using ``kubectl get locusttests`` and ``kubectl get pods`` to see the master and worker pods.\n\n.. code-block:: bash\n\n $ kubectl apply -f locust-test.yaml\n locusttest.locust.io/load-test created\n\n $ kubectl get locusttests\n NAME STATE WORKERS FAIL_RATIO RPS USERS AGE\n load-test READY 2/2 0% 0 0 30s\n\n $ kubectl get pods -l locust.io/test-run=load-test\n NAME READY STATUS RESTARTS AGE\n load-test-master-xxxxx 1/1 Running 0 35s\n load-test-worker-xxxxx 1/1 Running 0 35s\n load-test-worker-xxxxx 1/1 Running 0 35s\n\n4. Access the Locust web UI by port-forwarding the service to your local machine. Then open your browser and navigate to `http://localhost:8089`.\n\n.. code-block:: bash\n\n $ kubectl port-forward svc/load-test-webui 8089:8089\n Forwarding from 127.0.0.1:8089 -> 8089\n Forwarding from [::1]:8089 -> 8089\n\n5. You can see the master logs by running:\n\n.. code-block:: bash\n\n # Tailing the master pod logs directly\n $ kubectl logs -f pod/load-test-master-xxxxx\n\n # Using a selector to follow the master pod by labels\n $ kubectl logs -f -l locust.io/test-run=load-test,locust.io/component=master\n\n6. Cleanup by deleting the ``LocustTest`` resource (this will also delete all managed resources):\n\n.. code-block:: bash\n\n $ kubectl delete loadtest load-test\n\n\nLocustTest CRD Configuration\n----------------------------\n\nGeneral\n~~~~~~~\n\n``spec.image`` (string, required, default: ``locustio/locust:latest``)\n\n Container image for master and workers pods.\n\n``spec.workers`` (integer, required, default: ``1``)\n\n Number of worker pods to run.\n\n``spec.args`` (string, optional)\n\n Additional CLI flags, e.g. ``--run-time=5m --users=200 --spawn-rate=20``.\n\n``spec.env`` (array, optional)\n\n List of environment variables to set in the container.\n\nLocustfile source\n~~~~~~~~~~~~~~~~~\n\n``spec.locustfile`` (object, optional; choose **one**)\n\n* ``content`` (string): inline locustfile.py\n\n* ``configMap``: reference an existing ConfigMap\n\n * ``name`` (string, required)\n * ``key`` (string, default: ``locustfile.py``)\n\n* Built into image\n\n The image contains a locustfile.\n If the filename isn't ``locustfile.py`` (default locustfile name), pass ``-f `` via ``spec.args``.\n\n\nMetadata\n~~~~~~~~\n\n``spec.labels`` / ``spec.annotations`` (object, optional)\n\n User-provided labels/annotations merged onto all managed resources.\n\nPer-role overrides\n~~~~~~~~~~~~~~~~~~\n\nThis allows customizing **master** and **worker** pods separately.\n\n``spec.master`` / ``spec.worker`` (object, optional)\n\n* ``labels`` / ``annotations`` (object, optional)\n* ``resources`` (object, optional).\n\nExample:\n .. code-block:: yaml\n\n master:\n labels:\n my.custom.label/is-locust-master: \"true\"\n resources:\n requests:\n cpu: \"500m\"\n memory: \"256Mi\"\n limits:\n cpu: \"1\"\n memory: \"512Mi\"\n\nExtended\n~~~~~~~~\n\n``spec.imagePullPolicy`` (string, optional)\n\n The `image pull policy `_ for master/worker pods.\n\n``spec.imagePullSecrets`` (array, optional)\n\n The `image pull secrets `_ for master/worker pods.\n e.g. ``[{ name: my-regcred }]`` for private registries.\n\n\nExamples\n--------\n\nInline locustfile\n~~~~~~~~~~~~~~~~~\n\n.. code-block:: yaml\n\n apiVersion: locust.io/v1\n kind: LocustTest\n metadata:\n name: load-test-v1\n spec:\n image: locustio/locust:latest\n workers: 5\n args:\n --host http://my.site.com/api/v1\n --run-time=10m\n --users=500\n --spawn-rate=50\n env:\n - name: LOCUST_LOGLEVEL\n value: INFO\n locustfile:\n content: |\n from locust import HttpUser, task\n class TestUser(HttpUser):\n @task\n def index(self):\n self.client.get(\"/\")\n\nExternal ConfigMap locustfile\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n.. code-block:: yaml\n\n apiVersion: v1\n kind: ConfigMap\n metadata:\n name: v2-locustfile\n data:\n mytest.py: |\n from locust import HttpUser, task\n class PingUser(HttpUser):\n @task\n def ping(self):\n self.client.get(\"/ping\")\n ---\n apiVersion: locust.io/v1\n kind: LocustTest\n metadata:\n name: load-test-v2\n spec:\n workers: 5\n args:\n -f mytest.py\n --host http://my.site.com/api/v2\n --run-time=10m\n --users=500\n --spawn-rate=50\n locustfile:\n configMap:\n name: v2-locustfile\n\nCustom Master/Worker pod configuration\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n.. code-block:: yaml\n\n apiVersion: locust.io/v1\n kind: LocustTest\n metadata:\n name: locust-test\n spec:\n labels:\n # Merged into all managed resources labels\n my.custom.label/group: group1\n image: my-private-registry/custom-image:1.0.0\n imagePullSecrets:\n - name: regcred\n workers: 5\n master:\n annotations:\n # Merged into master pod annotations\n my.custom.annotations/version: \"1.0.0\"\n labels:\n # Merged into master pod labels\n my.custom.label/is-locust-master: \"true\"\n resources:\n requests:\n cpu: \"500m\"\n memory: \"512Mi\"\n limits:\n cpu: \"1\"\n memory: \"1Gi\"\n worker:\n annotations:\n # Merged into worker pod annotations\n my.custom.annotations/version: \"1.0.0\"\n labels:\n # Merged into worker pod labels\n my.custom.label/is-locust-master: \"false\"\n resources:\n requests:\n cpu: \"500m\"\n memory: \"512Mi\"\n limits:\n cpu: \"1\"\n memory: \"1Gi\"\n\nHeadless run\n~~~~~~~~~~~~\n\n.. code-block:: yaml\n\n apiVersion: locust.io/v1\n kind: LocustTest\n metadata:\n name: headless-test\n spec:\n workers: 2\n args:\n --host http://locust.io/\n --headless\n --run-time=5m\n --users=300\n --spawn-rate=30\n locustfile:\n content: |\n from locust import HttpUser, task\n class TestUser(HttpUser):\n @task\n def index(self):\n self.client.get(\"/\")\n\nUpgrade\n-------\n\nHelm\n~~~~\n\n.. code-block:: bash\n\n $ helm repo update\n $ helm upgrade locust-operator locust-operator/locust-operator \\\n --namespace locust-operator \\\n --reuse-values\n\nHelm `does not support updating or deleting CRDs `_.\nYou may need to update the CRD manually when upgrading the operator.\n\n.. code-block:: bash\n\n $ kubectl apply -f https://raw.githubusercontent.com/locustio/k8s-operator/refs/tags/helm-chart-/charts/locust-operator/crds/locusttest.yaml\n\nUninstall\n---------\n\n1. Delete all ``LocustTest`` resources (optional but recommended)\n\n.. code-block:: bash\n\n $ kubectl get locusttests --all-namespaces\n $ kubectl delete locusttests --all --all-namespaces\n\nHelm\n~~~~\n\n.. code-block:: bash\n\n # Uninstall the Helm release\n $ helm uninstall locust-operator --namespace locust-operator\n # Remove the LocustTest CRD\n $ kubectl delete crd locusttests.locust.io\n\nManifest Files\n~~~~~~~~~~~~~~\n\n.. code-block:: bash\n\n $ kubectl delete -f locust-operator.yaml" }, { "path": "docs/logging.rst", "content": ".. _logging:\n\n=======\nLogging\n=======\n\nLocust uses Python's `built in logging framework `_ for \nhandling logging.\n\nThe default logging configuration that Locust applies, writes log messages directly to stderr. ``--loglevel`` \nand ``--logfile`` can be used to change the verbosity and/or make the log go to a file instead. \n\nThe default logging configuration installs handlers for the ``root`` logger as well as the ``locust.*`` loggers, \nso using the root logger in your own test scripts will put the message into the log file if ``--logfile`` is used:\n\n.. code-block:: python\n \n import logging\n logging.info(\"this log message will go wherever the other locust log messages go\")\n\nIt's also possible to control the whole logging configuration in your own test scripts by using the \n``--skip-log-setup`` option. You will then have to \n`configure the logging `_ yourself.\n\n\nOptions\n=======\n\n``--skip-log-setup``\n--------------------\n\nDisable Locust's logging setup. Instead, the configuration is provided by the Locust test or Python defaults.\n\n\n``--loglevel``\n--------------\n\nChoose between DEBUG/INFO/WARNING/ERROR/CRITICAL. Default is INFO. The short-hand version is ``-L``.\n\n\n``--logfile``\n-------------\n\nPath to log file. If not set, log will go to stdout/stderr.\n\n\nLocust loggers\n==============\n\nHere's a table of the loggers used within Locust (for reference when configuring logging settings manually):\n\n+------------------------+--------------------------------------------------------------------------------------+\n| Logger name | Purpose |\n+------------------------+--------------------------------------------------------------------------------------+\n| locust | The locust namespace is used for all loggers such as ``locust.main``, |\n| | ``locust.runners``, etc. |\n+------------------------+--------------------------------------------------------------------------------------+\n| locust.stats_logger | This logger is used to periodically print the current stats to the console. The |\n| | stats does *not* go into the log file when ``--logfile`` is used by default. |\n+------------------------+--------------------------------------------------------------------------------------+\n" }, { "path": "docs/quickstart.rst", "content": ".. _quickstart:\n\n===============\nYour first test\n===============\n\nA Locust test is essentially just a Python program making requests to the system you want to test. This makes it very flexible and particularly good at implementing complex user flows. But it can do simple tests as well, so let's start with that:\n\n.. code-block:: python\n\n from locust import HttpUser, task\n\n class HelloWorldUser(HttpUser):\n @task\n def hello_world(self):\n self.client.get(\"/hello\")\n self.client.get(\"/world\")\n\nThis user will make an HTTP request to ``/hello``, then to ``/world``, and then repeat. For a full explanation and a more realistic example see :ref:`writing-a-locustfile`.\n\nChange ``/hello`` and ``/world`` to some actual paths on the website/service you want to test, put the code in a file named ``locustfile.py`` in your current directory and then run ``locust``:\n\n.. code-block:: console\n :substitutions:\n\n $ locust\n [2021-07-24 09:58:46,215] .../INFO/locust.main: Starting web interface at http://0.0.0.0:8089\n [2021-07-24 09:58:46,285] .../INFO/locust.main: Starting Locust |version|\n\nLocust's web interface\n======================\n\nOpen http://localhost:8089\n\n.. image:: images/webui-splash-light.png\n\n| Provide the host name of your server and try it out!\n\nThe following screenshots show what it might look like when running this test using 50 concurrent users, with a ramp up rate of 1 user/s\n\n.. image:: images/webui-running-statistics-light.png\n\n| Under the *Charts* tab you'll find things like requests per second (RPS), response times and number of running users:\n\n.. image:: images/bottlenecked-server-light.png\n\n.. note::\n\n Interpreting performance test results is quite complex (and mostly out of scope for this manual), but if your graphs start looking like this, the target service/system cannot handle the load and you have found a bottleneck.\n\n When we get to around 20 users, response times start increasing so fast that even though Locust is still spawning more users, the number of requests per second is no longer increasing. The target service is \"overloaded\" or \"saturated\".\n\n If your response times are *not* increasing then add even more users until you find the service's breaking point, or celebrate that your service is already performant enough for your expected load.\n\n If you're having trouble generating enough load to saturate your system, take a look at :ref:`increaserr`.\n\nDirect command line usage / headless\n====================================\n\nUsing the Locust web UI is entirely optional. You can supply the load parameters on the command line and get reports on the results in text form:\n\n.. code-block:: console\n :substitutions:\n\n $ locust --headless --users 10 --spawn-rate 1 -H http://your-server.com\n [2021-07-24 10:41:10,947] .../INFO/locust.main: No run time limit set, use CTRL+C to interrupt.\n [2021-07-24 10:41:10,947] .../INFO/locust.main: Starting Locust |version|\n [2021-07-24 10:41:10,949] .../INFO/locust.runners: Ramping to 10 users using a 1.00 spawn rate\n Name # reqs # fails | Avg Min Max Median | req/s failures/s\n ----------------------------------------------------------------------------------------------\n GET /hello 1 0(0.00%) | 115 115 115 115 | 0.00 0.00\n GET /world 1 0(0.00%) | 119 119 119 119 | 0.00 0.00\n ----------------------------------------------------------------------------------------------\n Aggregated 2 0(0.00%) | 117 115 119 117 | 0.00 0.00\n (...)\n [2021-07-24 10:44:42,484] .../INFO/locust.runners: All users spawned: {\"HelloWorldUser\": 10} (10 total users)\n (...)\n\nSee :ref:`running-without-web-ui` for more details.\n\nMore options\n============\n\nTo run Locust distributed across multiple Python processes or machines, you start a single Locust master process\nwith the ``--master`` command line parameter, and then any number of Locust worker processes using the ``--worker``\ncommand line parameter. See :ref:`running-distributed` for more info.\n\nTo see all available options type: ``locust --help`` or check :ref:`configuration`.\n\nNext steps\n==========\n\nNow, let's have a more in-depth look at locustfiles and what they can do: :ref:`writing-a-locustfile`.\n" }, { "path": "docs/retrieving-stats.rst", "content": "======================================\nRetrieve test statistics in CSV format\n======================================\n\nYou may wish to consume your Locust results via a CSV file. In this case, there are two ways to do this.\n\nFirst, when running Locust with the web UI, you can retrieve CSV files under the Download Data tab. \n\nSecondly, you can run Locust with a flag which will periodically save four CSV files. This is particularly useful\nif you plan on running Locust in an automated way with the ``--headless`` flag:\n\n.. code-block:: console\n\n $ locust -f examples/basic.py --csv example --headless -t10m\n\nThe files will be named ``example_stats.csv``, ``example_failures.csv``, ``example_exceptions.csv`` and ``example_stats_history.csv``\n(when using ``--csv example``). The first two files will contain the stats and failures for the whole \ntest run, with a row for every stats entry (URL endpoint) and an aggregated row. The ``example_stats_history.csv`` \nwill get new rows with the *current* (10 seconds sliding window) stats appended during the whole test run. \nBy default only the Aggregate row is appended regularly to the history stats, but if Locust is started with \nthe ``--csv-full-history`` flag, a row for each stats entry (and the Aggregate) is appended every time \nthe stats are written (once every 2 seconds by default).\n\nYou can also customize how frequently this is written:\n\n.. code-block:: python\n\n import locust.stats\n locust.stats.CSV_STATS_INTERVAL_SEC = 5 # default is 1 second\n" }, { "path": "docs/running-distributed.rst", "content": ".. _running-distributed:\n\n===========================\nDistributed load generation\n===========================\n\nA single process running Locust can simulate a reasonably high throughput. For a simple test plan and small payloads it can make more than a thousand requests per second, possibly over ten thousand if you use :ref:`FastHttpUser `.\n\nBut if your test plan is complex or you want to run even more load, you'll need to scale out to multiple processes, maybe even multiple machines. Fortunately, Locust supports distributed runs out of the box.\n\nTo do this, you start one instance of Locust with the ``--master`` flag and one or more using the ``--worker`` flag. The master instance runs Locust's web interface, and tells the workers when to spawn/stop Users. The worker instances run your Users and send statistics back to the master. The master instance doesn't run any Users itself.\n\nTo simplify startup, you can use the ``--processes`` flag. It will launch a master process and the specified number of worker processes. It can also be used in combination with ``--worker``, then it will only launch workers. This feature relies on `fork() `_ so it doesn't work on Windows.\n\n.. note::\n Because Python cannot fully utilize more than one core per process (see `GIL `_), you need to run one worker instance per processor core in order to have access to all your computing power.\n\n.. note::\n There is almost no limit to how many Users you can run per worker. Locust/gevent can run thousands or even tens of thousands of Users per process just fine, as long as their total request rate (RPS) is not too high.\n\n If Locust *is* getting close to running out of CPU resources, it will log a warning. If there is no warning but you are still unable to generate the expected load, then the problem must be :ref:`increaserr`.\n\nSingle machine\n==============\n\nIt is really simple to launch a master and 4 worker processes::\n\n locust --processes 4\n\nYou can even auto-detect the number of logical cores in your machine and launch one worker for each of them::\n\n locust --processes -1\n\nMultiple machines\n=================\n\nStart locust in master mode on one machine::\n\n locust -f my_locustfile.py --master\n\nAnd then on each worker machine:\n\n.. code-block:: bash\n\n locust -f - --worker --master-host --processes 4\n\n.. note::\n The ``-f -`` argument tells Locust to get the locustfile from master instead of from its local filesystem. This only works for single locustfiles.\n\nMultiple machines, using locust-swarm\n=====================================\n\n.. note::\n locust-swarm is no longer actively maintained.\n\nWhen you make changes to the locustfile you'll need to restart all Locust processes. `locust-swarm `_ automates this for you. It also solves the issue of firewall/network access from workers to master using SSH tunnels (this is often a problem if the master is running on your workstation and workers are running in some datacenter).\n\n.. code-block:: bash\n\n pip install locust-swarm\n\n swarm -f my_locustfile.py --loadgen-list worker-server1,worker-server2 \n\n\nOptions for distributed load generation\n=======================================\n\n``--master-host ``\n----------------------------------\n\nOptionally used together with ``--worker`` to set the hostname/IP of the master node (defaults\nto localhost)\n\n``--master-port ``\n-------------------------------\n\nOptionally used together with ``--worker`` to set the port number of the master node (defaults to 5557).\n\n``--master-bind-host ``\n---------------------------\n\nOptionally used together with ``--master``. Determines which network interface the master node\nwill bind to. Defaults to * (all available interfaces).\n\n``--master-bind-port ``\n------------------------------------\n\nOptionally used together with ``--master``. Determines what network ports that the master node will\nlisten to. Defaults to 5557.\n\n``--expect-workers ``\n----------------------------------------\n\nUsed when starting the master node with ``--headless``. The master node will then wait until X worker\nnodes has connected before the test is started.\n\nCommunicating across nodes\n=============================================\n\nWhen running Locust in distributed mode, you may want to communicate between master and worker nodes in \norder to coordinate the test. This can be easily accomplished with custom messages using the built in messaging hooks:\n\n.. code-block:: python\n\n from locust import events\n from locust.runners import MasterRunner, WorkerRunner\n\n # Fired when the worker receives a message of type 'test_users'\n def setup_test_users(environment, msg, **kwargs):\n for user in msg.data:\n print(f\"User {user['name']} received\")\n environment.runner.send_message('acknowledge_users', f\"Thanks for the {len(msg.data)} users!\")\n\n # Fired when the master receives a message of type 'acknowledge_users'\n def on_acknowledge(msg, **kwargs):\n print(msg.data)\n\n @events.init.add_listener\n def on_locust_init(environment, **_kwargs):\n if not isinstance(environment.runner, MasterRunner):\n environment.runner.register_message('test_users', setup_test_users)\n if not isinstance(environment.runner, WorkerRunner):\n environment.runner.register_message('acknowledge_users', on_acknowledge)\n\n @events.test_start.add_listener\n def on_test_start(environment, **_kwargs):\n if not isinstance(environment.runner, WorkerRunner):\n users = [\n {\"name\": \"User1\"},\n {\"name\": \"User2\"},\n {\"name\": \"User3\"},\n ]\n environment.runner.send_message('test_users', users) \n\nNote that when running locally (i.e. non-distributed), this functionality will be preserved; \nthe messages will simply be handled by the runner that sends them.\n\n.. note::\n Using the default options while registering a message handler will run the listener function\n in a **blocking** way, resulting in the heartbeat and other messages being delayed for the amount\n of the execution.\n If you think that your message handler will need to run for more than a second then you can register it\n as **concurrent**. Locust will then make it run in its own greenlet. Note that these greenlets will never \n be join():ed.\n\n .. code-block::\n\n environment.runner.register_message('test_users', setup_test_users, concurrent=True)\n\nFor more details, see the `complete example `_.\n\n\nRunning distributed with Docker\n=============================================\n\nSee :ref:`running-in-docker`\n\n\nRunning Locust distributed without the web UI\n=============================================\n\nSee :ref:`running-distributed-without-web-ui`\n\n\nIncrease Locust's performance\n=============================\n\nIf you're planning to run large-scale load tests, you might be interested to use the alternative\nHTTP client that's shipped with Locust. You can read more about it here: :ref:`increase-performance`.\n" }, { "path": "docs/running-in-debugger.rst", "content": ".. _running-in-debugger:\n\n===========================\nRunning tests in a debugger\n===========================\n\nRunning Locust in a debugger is extremely useful when developing your tests. Among other things, you can examine a particular response or check some User instance variable.\n\nBut debuggers sometimes have issues with complex gevent-applications like Locust, and there is a lot going on in the framework itself that you probably aren't interested in. To simplify this, Locust provides a method called :py:func:`run_single_user `:\n\n.. literalinclude:: ../examples/debugging.py\n :language: python\n\nIt implicitly registers an event handler for the :ref:`request ` event to print some stats about every request made:\n\n.. code-block:: console\n\n type name resp_ms exception\n GET /hello 38 ConnectionRefusedError(61, 'Connection refused')\n GET /hello 4 ConnectionRefusedError(61, 'Connection refused')\n\nYou can configure exactly what is printed by specifying parameters to :py:func:`run_single_user `.\n\nMake sure you have enabled gevent in your debugger settings. \n\nDebugging Locust is quite easy with Vscode:\n\n- Place breakpoints\n- Select a python file or a scenario (ex: ```examples/basic.py``)\n- Check that the desired virtualenv is correctly detected (bottom right)\n- Open the action *Debug using launch.json*. You will have the choice between debugging the python file, the scenario with WebUI or in headless mode\n- It could be rerun with the F5 shortkey\n\nVS Code's ``launch.json`` looks like this:\n\n.. literalinclude:: ../.vscode/launch.json\n :language: json\n\nIf you want to the whole Locust runtime (with ramp up, command line parsing etc), you can do that too:\n\n.. literalinclude:: ../.vscode/launch_locust.json\n :language: json\n\nThere is a similar setting in `PyCharm `_.\n\n.. note::\n\n | VS Code/pydev may give you warnings about:\n | ``sys.settrace() should not be used when the debugger is being used``\n | It can safely be ignored (and if you know how to get rid of it, please let us know)\n\nYou can execute run_single_user multiple times, as shown in `debugging_advanced.py `_.\n\n\nPrint HTTP communication\n========================\n\nSometimes it can be hard to understand why an HTTP request fails in Locust when it works from a regular browser/other application. Here's how to examine the communication in detail:\n\nFor ``HttpUser`` (`python-requests `_):\n\n.. code-block:: python\n\n # put this at the top of your locustfile (or just before the request you want to trace)\n import logging\n from http.client import HTTPConnection\n\n HTTPConnection.debuglevel = 1\n logging.basicConfig()\n logging.getLogger().setLevel(logging.DEBUG)\n requests_log = logging.getLogger(\"requests.packages.urllib3\")\n requests_log.setLevel(logging.DEBUG)\n requests_log.propagate = True\n\nFor ``FastHttpUser`` (`geventhttpclient `_):\n\n.. code-block:: python\n\n import sys\n ...\n\n class MyUser(FastHttpUser):\n @task\n def t(self):\n self.client.get(\"http://example.com/\", debug_stream=sys.stderr)\n\nExample output (for FastHttpUser):\n\n.. code-block:: console\n\n REQUEST: http://example.com/\n GET / HTTP/1.1\n user-agent: python/gevent-http-client-1.5.3\n accept-encoding: gzip, deflate, br, zstd\n host: example.com\n\n RESPONSE: HTTP/1.1 200\n Content-Encoding: gzip\n Accept-Ranges: bytes\n Age: 460461\n Cache-Control: max-age=604800\n Content-Type: text/html; charset=UTF-8\n Date: Fri, 12 Aug 2022 09:20:07 GMT\n Etag: \"3147526947+ident\"\n Expires: Fri, 19 Aug 2022 09:20:07 GMT\n Last-Modified: Thu, 17 Oct 2019 07:18:26 GMT\n Server: ECS (nyb/1D20)\n Vary: Accept-Encoding\n X-Cache: HIT\n Content-Length: 648\n\n \n \n \n ...\n\nThese approaches can of course be used when doing a full load test, but you might get a lot of output :)" }, { "path": "docs/running-in-docker.rst", "content": ".. _running-in-docker:\n\n=================\nRunning in Docker\n=================\n\nThe official Docker image is at `locustio/locust `_.\n\nUse it like this (assuming that the ``locustfile.py`` exists in the current working directory)::\n\n docker run -p 8089:8089 -v $PWD:/mnt/locust locustio/locust -f /mnt/locust/locustfile.py\n\nOn Windows, this command will sometimes cause errors. Windows users should try using this instead::\n\n docker run -p 8089:8089 --mount type=bind,source=$pwd,target=/mnt/locust locustio/locust -f /mnt/locust/locustfile.py\n\nDocker Compose\n==============\n\nHere's an example Docker Compose file that could be used to start both a master node, and worker nodes:\n\n.. literalinclude:: ../examples/docker-compose/docker-compose.yml\n :language: yaml\n\nThe above compose configuration could be used to start a master node and 4 workers using the following command::\n\n docker-compose up --scale worker=4\n\nUse docker image as a base image\n================================\n\nIt's very common to have test scripts that rely on third party python packages. In those cases you can use the\nofficial Locust docker image as a base image::\n\n FROM locustio/locust\n RUN pip install some-package # some dependency you need\n RUN pip install locust[otel] # for OpenTelemetry support\n" }, { "path": "docs/running-without-web-ui.rst", "content": ".. _running-without-web-ui:\n\n=================================\nRunning without the web UI\n=================================\n\nYou can run locust without the web UI by using the ``--headless`` flag together with ``-u/--users`` and ``-r/--spawn-rate``:\n\n.. code-block:: console\n :substitutions:\n\n $ locust -f locust_files/my_locust_file.py --headless -u 100 -r 5\n [2021-07-24 10:41:10,947] .../INFO/locust.main: No run time limit set, use CTRL+C to interrupt.\n [2021-07-24 10:41:10,947] .../INFO/locust.main: Starting Locust |version|\n [2021-07-24 10:41:10,949] .../INFO/locust.runners: Ramping to 100 users using a 5.00 spawn rate\n Name # reqs # fails | Avg Min Max Median | req/s failures/s\n ----------------------------------------------------------------------------------------------\n GET /hello 1 0(0.00%) | 115 115 115 115 | 0.00 0.00\n GET /world 1 0(0.00%) | 119 119 119 119 | 0.00 0.00\n ----------------------------------------------------------------------------------------------\n Aggregated 2 0(0.00%) | 117 115 119 117 | 0.00 0.00\n (...)\n [2021-07-24 10:44:42,484] .../INFO/locust.runners: All users spawned: {\"HelloWorldUser\": 100} (100 total users)\n (...)\n\nEven in headless mode you can change the user count while the test is running. Press ``w`` to add 1 user or ``W`` to add 10. Press ``s`` to remove 1 or ``S`` to remove 10.\n\nSetting a time limit for the test\n---------------------------------\n\nTo specify the run time for a test, use ``-t/--run-time``:\n\n.. code-block:: console\n\n $ locust --headless -u 100 --run-time 1h30m\n $ locust --headless -u 100 --run-time 60 # default unit is seconds\n\nLocust will shut down once the time is up. Time is calculated from the start of the test (not from when ramp up has finished).\n\n\nAllow tasks to finish their iteration on shutdown\n-------------------------------------------------\n\nBy default, Locust will stop your tasks immediately (without even waiting for requests to finish). \nTo give running tasks some time to finish their iteration, use ``-s/--stop-timeout``:\n\n.. code-block:: console\n\n $ locust --headless --run-time 1h30m --stop-timeout 10s\n\n.. _running-distributed-without-web-ui:\n\n\nRunning Locust distributed without the web UI\n---------------------------------------------\n\nIf you want to :ref:`run Locust distributed ` without the web UI, \nyou should specify the ``--expect-workers`` option when starting the master node, to specify\nthe number of worker nodes that are expected to connect. It will then wait until that many worker\nnodes have connected before starting the test.\n\n\nControlling the exit code of the Locust process\n-----------------------------------------------\n\nBy default the locust process will give an exit code of 1 if there were any failed samples \n(use the ``--exit-code-on-error`` to change that behaviour).\n\nYou can also manually control the exit code in your test scripts by setting the :py:attr:`process_exit_code ` of the \n:py:class:`Environment ` instance. This is particularly useful when running Locust as an automated/scheduled test, for example as part of a CI pipeline.\n\nBelow is an example that'll set the exit code to non zero if any of the following conditions are met:\n\n* More than 1% of the requests failed\n* The average response time is longer than 200 ms\n* The 95th percentile for response time is larger than 800 ms\n\n.. code-block:: python\n\n import logging\n from locust import events\n \n @events.quitting.add_listener\n def _(environment, **kw):\n if environment.stats.total.fail_ratio > 0.01:\n logging.error(\"Test failed due to failure ratio > 1%\")\n environment.process_exit_code = 1\n elif environment.stats.total.avg_response_time > 200:\n logging.error(\"Test failed due to average response time ratio > 200 ms\")\n environment.process_exit_code = 1\n elif environment.stats.total.get_response_time_percentile(0.95) > 800:\n logging.error(\"Test failed due to 95th percentile response time > 800 ms\")\n environment.process_exit_code = 1\n else:\n environment.process_exit_code = 0\n\nNote that this code could go into the locustfile.py or in any other file that is imported in the locustfile.\n\n\nRunning in CI/CD\n----------------\n\nYou can easily run a single instance of Locust in headless mode as part of a CI/CD pipeline.\n\nHere's an example using GitHub Actions. Use it in combination with the above snippet to fail the run based on metrics.\n\n.. code-block:: yaml\n\n env:\n PYTHONUNBUFFERED: 1 # ensure we see output right away\n\n jobs:\n loadtest:\n runs-on: ubuntu-latest\n timeout-minutes: 15 # just in case something goes wrong\n steps:\n - uses: actions/checkout@v6\n - uses: actions/setup-python@v6\n with:\n python-version: '3.11' \n - run: pip install locust\n - run: locust --headless --run-time 5m" }, { "path": "docs/tasksets.rst", "content": ":orphan:\n.. _tasksets:\n\nTaskSet class\n=============\n\nIf you are performance testing a website that is structured in a hierarchical way, with \nsections and sub-sections, it may be useful to structure your load test the same way. \nFor this purpose, Locust provides the TaskSet class. It is a collection of tasks that will \nbe executed much like the ones declared directly on a User class. \n\n.. note::\n\n TaskSets are an advanced feature and only rarely useful. Most of the time, you're better off\n using regular Python loops and control statements to achieve the same thing. There are a few \n gotchas as well, the most frequent one being forgetting to call self.interrupt()\n\n.. code-block:: python\n\n from locust import User, TaskSet, constant\n \n class ForumSection(TaskSet):\n wait_time = constant(1)\n\n @task(10)\n def view_thread(self):\n pass\n \n @task\n def create_thread(self):\n pass\n \n @task\n def stop(self):\n self.interrupt()\n \n class LoggedInUser(User):\n wait_time = constant(5)\n tasks = {ForumSection:2}\n \n @task\n def my_task(self):\n pass\n\nA TaskSet can also be inlined directly under a User/TaskSet class using the @task decorator:\n\n.. code-block:: python\n\n class MyUser(User):\n @task\n class MyTaskSet(TaskSet):\n ...\n\nThe tasks of a TaskSet class can be other TaskSet classes, allowing them to be nested any number \nof levels. This allows us to define a behaviour that simulates users in a more realistic way. \n\nFor example we could define TaskSets with the following structure::\n\n - Main user behaviour\n - Index page\n - Forum page\n - Read thread\n - Reply\n - New thread\n - View next page\n - Browse categories\n - Watch movie\n - Filter movies\n - About page\n\nWhen a running User thread picks a TaskSet class for execution an instance of this class will\nbe created and execution will then go into this TaskSet. What happens then is that one of the \nTaskSet's tasks will be picked and executed, and then the thread will sleep for a duration specified \nby the User's wait_time function (unless a ``wait_time`` function has been declared directly on\nthe TaskSet class, in which case it'll use that function instead), then pick a new task from the \nTaskSet's tasks, wait again, and so on.\n\nThe TaskSet instance contains a reference to the User - ``self.user``. It also has a shortcut to its \nUser's client attribute. So you can make a request using ``self.client.request()``,\njust like if your task was defined directly on an HttpUser.\n\n\nInterrupting a TaskSet\n----------------------\n\nOne important thing to know about TaskSets is that they will never stop executing their tasks, and \nhand over execution back to their parent User/TaskSet, by themselves. This has to be done by the\ndeveloper by calling the :py:meth:`TaskSet.interrupt() ` method. \n\n.. autofunction:: locust.TaskSet.interrupt\n :noindex:\n\nIn the following example, if we didn't have the stop task that calls ``self.interrupt()``, the \nsimulated user would never stop running tasks from the Forum taskset once it has went into it:\n\n.. code-block:: python\n\n class RegisteredUser(User):\n @task\n class Forum(TaskSet):\n @task(5)\n def view_thread(self):\n pass\n \n @task(1)\n def stop(self):\n self.interrupt()\n \n @task\n def frontpage(self):\n pass\n\nUsing the interrupt function, we can - together with task weighting - define how likely it \nis that a simulated user leaves the forum.\n\n\nDifferences between tasks in TaskSet and User classes\n-------------------------------------------------------\n\nOne difference for tasks residing under a TaskSet, compared to tasks residing directly under a User,\nis that the argument that they are passed when executed (``self`` for tasks declared as methods with \nthe :py:func:`@task ` decorator) is a reference to the TaskSet instance, instead of \nthe User instance. The User instance can be accessed from within a TaskSet instance through the\n:py:attr:`TaskSet.user `. TaskSets also contains a convenience \n:py:attr:`client ` attribute that refers to the client attribute on the \nUser instance.\n\n\nReferencing the User instance, or the parent TaskSet instance\n---------------------------------------------------------------\n\nA TaskSet instance will have the attribute :py:attr:`user ` point to\nits User instance, and the attribute :py:attr:`parent ` point to its\nparent TaskSet instance.\n\n\nTags and TaskSets\n------------------\nYou can tag TaskSets using the :py:func:`@tag ` decorator in a similar way to normal tasks,\nbut there are some nuances worth mentioning. Tagging a TaskSet will automatically apply the tag(s) to \nall of the TaskSet's tasks. Furthermore, if you tag a task within a nested TaskSet, Locust will execute \nthat task even if the TaskSet isn't tagged.\n\n\n.. _sequential-taskset:\n\nSequentialTaskSet class\n=======================\n\n:py:class:`SequentialTaskSet ` is a TaskSet whose tasks will be executed \nin the order that they are declared. If the ** dictionary is used, each task will be repeated by the amount\ngiven by the integer at the point of declaration. It is possible to nest SequentialTaskSets\nwithin a TaskSet and vice versa.\n\nFor example, the following code will request URLs /1-/4 in order, and then repeat.\n\n.. code-block:: python\n \n def function_task(taskset):\n taskset.client.get(\"/3\")\n \n class SequenceOfTasks(SequentialTaskSet):\n @task\n def first_task(self):\n self.client.get(\"/1\")\n self.client.get(\"/2\")\n \n # you can still use the tasks attribute to specify a list or dict of tasks\n tasks = [function_task]\n # tasks = {function_task: 1}\n \n @task\n def last_task(self):\n self.client.get(\"/4\")\n\nNote that you dont need SequentialTaskSets to just do some requests in order. It is often easier to \njust do a whole user flow in a single task.\n\n.. _markov-taskset:\n\nMarkovTaskSet class\n===================\n\n:py:class:`MarkovTaskSet ` is a TaskSet that defines a probabilistic sequence of tasks \nusing a Markov chain. Unlike regular TaskSets where tasks are chosen randomly based on weight, MarkovTaskSets \nallow you to define specific transitions between tasks with associated probabilities.\n\nThis is useful for modeling user behavior where the next action depends on the current state, creating more \nrealistic user flows. For example, after viewing a product, a user might be more likely to add it to cart than \nto log out.\n\n.. note::\n\n MarkovTaskSets require at least one task with transitions defined. All tasks must eventually be reachable from the\n first task, and tags are not supported with MarkovTaskSets as they could make the Markov chain invalid.\n\n.. code-block:: python\n\n from locust import User, constant\n from locust.user.markov_taskset import MarkovTaskSet, transition, transitions\n\n class ShoppingBehavior(MarkovTaskSet):\n wait_time = constant(1)\n \n @transition(\"view_product\")\n def browse_catalog(self):\n self.client.get(\"/catalog\")\n \n @transitions({\n \"add_to_cart\": 3, # Higher probability\n \"browse_catalog\": 1,\n \"checkout\": 1\n })\n def view_product(self):\n self.client.get(\"/product/1\")\n \n @transitions([\"view_product\", \"checkout\"])\n def add_to_cart(self):\n self.client.post(\"/cart/add\", json={\"product_id\": 1})\n \n @transition(\"browse_catalog\")\n def checkout(self):\n self.client.post(\"/checkout\")\n \n class ShopperUser(HttpUser):\n host = \"http://localhost\"\n tasks = {ShoppingBehavior: 1}\n\nIn this example, after browsing the catalog, the user will always view a product. After viewing a product, \nthe user has a 60% chance (3/5) of adding it to cart, a 20% chance (1/5) of returning to browsing, and a \n20% chance (1/5) of going directly to checkout.\n\nDefining Transitions\n--------------------\n\nMarkovTaskSet provides two decorators for defining transitions between tasks:\n\n1. ``@transition(task_name, weight=1)``: Defines a single transition to another task.\n\n .. code-block:: python\n \n @transition(\"next_task\")\n def current_task(self):\n pass\n\n2. ``@transitions(weights)``: Defines multiple transitions at once. The ``weights`` parameter can be:\n \n - A dictionary mapping task names to weights:\n \n .. code-block:: python\n \n @transitions({\n \"task_a\": 3,\n \"task_b\": 1\n })\n def current_task(self):\n pass\n \n - A list of task names or (task_name, weight) tuples:\n \n .. code-block:: python\n \n @transitions([\"task_a\", (\"task_b\", 2)])\n def current_task(self):\n pass\n \n" }, { "path": "docs/telemetry.rst", "content": ".. _telemetry:\n\n=========================\nOpenTelemetry Integration\n=========================\n\nLocust now optionally integrates with OpenTelemetry (OTel), enabling you to automatically export traces\nand metrics from your load tests to any OTel-compatible backend (OTLP, Prometheus, Jaeger, Tempo, etc.).\nThis makes it easy to correlate load-test activity with application and infrastructure telemetry in your observability stack.\n\nThe configuration is done via environment variables. See the `OpenTelemetry documentation `_\nfor details on how to configure exporters, resource attributes, sampling, etc.\n\nSetup\n-----\n\nTo enable OpenTelemetry, you need to download ``locust`` with the OpenTelemetry dependencies:\n\n.. code-block:: console\n\n $ pip install locust[otel]\n\nThen, pass the command line argument ``--otel`` to enable OpenTelemetry:\n\n.. code-block:: console\n\n $ locust --otel\n ...\n\nIf you're using the official locust Docker image, you need to install it in a custom Dockerfile, see :ref:`running-in-docker`.\n\nExporters\n---------\n\nLocust supports the following OpenTelemetry exporters, for both traces and metrics, out of the box:\n\n- OTLP (gRPC and HTTP) - this is the default exporter using gRPC protocol\n- Console (useful for debugging)\n\nFor traces, ``BatchSpanProcessor`` is used and can be configured with these `variables `_.\n\nFor metrics, ``PeriodicExportingMetricReader`` is used and is configurable with the corresponding `variables `_.\n\n\nAuto Instrumentation\n--------------------\n\n.. note::\n\n Currently, only the ``requests`` library is auto-instrumented. This mean that only ``HttpUser`` will have it's HTTP requests made during your load tests automatically generate spans,\n and metrics with no additional configuration needed.\n\n We plan to add auto-instrumentation for more libraries in future releases.\n\n\nSupported Users\n~~~~~~~~~~~~~~~\n+--------------+-----------------------+\n| User Class | Instrumented Library |\n+--------------+-----------------------+\n| ``HttpUser`` | ``requests`` |\n+--------------+-----------------------+\n\nIf you need instrumentation for other libraries (e.g., database clients, messaging libraries), you can manually set up additional instrumentation\nusing the OpenTelemetry Python SDK as per the `OpenTelemetry Python documentation `_.\n\n\nExample\n-------\n\n.. code-block:: console\n\n $ export OTEL_TRACES_EXPORTER=otlp\n $ export OTEL_EXPORTER_OTLP_ENDPOINT=https://...\n $ export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf\n $ locust --otel\n [2025-11-28 16:27:01,916] locust/INFO/locust.main: Starting Locust, OpenTelemetry enabled\n [2025-11-28 16:27:01,916] locust/INFO/locust.main: Starting web interface at http://0.0.0.0:8089, press enter to open your default browser.\n ...\n" }, { "path": "docs/testing-other-systems.rst", "content": ".. _testing-other-systems:\n\n===============================\nTesting other systems/protocols\n===============================\n\nLocust only comes with built-in support for HTTP/HTTPS but it can be extended to test almost any system. This is normally done by wrapping the protocol library and triggering a :py:attr:`request ` event after each call has completed, to let Locust know what happened.\n\n.. note::\n\n It is important that the protocol libraries you use can be `monkey-patched `_ by gevent. \n \n Almost any libraries that are pure Python (using the Python ``socket`` module or some other standard library function like ``subprocess``) should work fine out of the box - but if they do their I/O calls from compiled code C, gevent will be unable to patch it. This will block the whole Locust/Python process (in practice limiting you to running a single User per worker process).\n\n Some C libraries allow for other workarounds. For example, if you want to use psycopg2 to performance test PostgreSQL, you can use `psycogreen `_. If you are willing to get your hands dirty, you may be able to patch a library yourself, but that is beyond the scope of this documentation.\n\nXML-RPC\n=======\n\nLets assume we have an XML-RPC server that we want to load test.\n\n.. literalinclude:: ../examples/custom_xmlrpc_client/server.py\n\nWe can build a generic XML-RPC client, by wrapping :py:class:`xmlrpc.client.ServerProxy`.\n\n.. literalinclude:: ../examples/custom_xmlrpc_client/xmlrpc_locustfile.py\n\ngRPC\n====\n\nLets assume we have a `gRPC `_ server that we want to load test:\n\n.. literalinclude:: ../examples/grpc/hello_server.py\n\nThe generic GrpcUser base class sends events to Locust using an `interceptor `_:\n\n.. literalinclude:: ../examples/grpc/grpc_user.py\n\nAnd a locustfile using the above would look like this:\n\n.. literalinclude:: ../examples/grpc/locustfile.py\n\n.. _testing-request-sdks:\n\nrequests-based libraries/SDKs\n=============================\n\nIf you want to use a library that uses a `requests.Session `_ object under the hood you will most likely be able to skip all the above complexity.\n\nSome libraries allow you to pass a Session explicitly, like for example the SOAP client provided by `Zeep `_. In that case, just pass it your ``HttpUser``'s :py:attr:`client `, and any requests made using the library will be logged in Locust.\n\nEven if your library doesn't expose that in its interface, you may be able to get it working by overwriting some internally used Session. Here's an example of how to do that for the `Archivist `_ client.\n\n.. literalinclude:: ../examples/sdk_session_patching/session_patch_locustfile.py\n\nREST\n====\n\nSee :ref:`FastHttpUser `\n\nSocketIO\n========\n\nSee :ref:`SocketIOUser `\n\n.. note::\n\n SocketIO support is experimental and may change without notice.\n\npytest\n======\n\nLocust allows you to use `pytest `_ syntax to define Locust Users using pytest fixtures (currently :py:class:`HttpSession ` and :py:class:`FastHttpSession `). It has multiple benefits:\n\n* Simpler syntax than regular Locustfiles\n* Run or debug easily from any editor that supports pytest\n* Reliably reuse functional test cases for load testing\n\n.. literalinclude:: ../examples/test_pytest.py\n\nExample usage:\n\n.. code-block:: sh\n\n $ locust -f test_pytest.py\n $ pytest test_pytest.py\n # if you have issues with gevent patching (RecursionError: maximum recursion depth exceeded)\n $ python -m gevent.monkey -m pytest test_pytest.py\n\nLimitations:\n\n* Each test case becomes a Locust User under the hood. We don't (yet) support weighting users.\n* Locust will only look for pytest-style tests if there are no regular User classes defined.\n* Adding other pytest fixtures or pytest plugins may cause issues (do let us know though)\n* For a more complex example, see ``_\n\n.. note::\n\n pytest support is experimental and may change without a new major release version.\n\nOpenAI\n======\n\nPerformance/load testing AI services is a little different. While you could call the OpenAI API using HttpUser or FastHttpUser, it is often convenient to use `the SDK `_.\n\n.. literalinclude:: ../examples/openai_ex.py\n\n.. note::\n\n OpenAIUser is experimental and may change without notice.\n\nMQTT\n====\n\nLocust uses to `paho-mqtt `_ to provide Mqtt connection capabilities.\n\n.. literalinclude:: ../examples/mqtt/locustfile.py\n\nAlternatively, if you need more control over the Mqtt client you can use a custom implementation.\n\n.. literalinclude:: ../examples/mqtt/locustfile_custom_mqtt_client.py\n\n.. note::\n\n MqttUser is experimental and may change without notice.\n\n\nOther examples\n==============\n\nSee `locust-plugins `_ it has users for Kafka, Selenium/WebDriver, Playwright and more.\n" }, { "path": "docs/use-as-lib.rst", "content": ".. _use-as-lib:\n\n==========================\nUsing Locust as a library\n==========================\n\nIt is possible to start a load test from your own Python code, instead of running Locust using the ``locust`` command.\n\nStart by creating an :py:class:`Environment ` instance:\n\n.. code-block:: python\n\n from locust.env import Environment\n \n env = Environment(user_classes=[MyTestUser])\n\nThe :py:class:`Environment ` instance's \n:py:meth:`create_local_runner `, \n:py:meth:`create_master_runner ` can then be used to start a \n:py:class:`Runner ` instance, which can be used to start a load test:\n\n.. code-block:: python\n\n env.create_local_runner()\n env.runner.start(5000, spawn_rate=20)\n env.runner.greenlet.join()\n\nIt is also possible to bypass the dispatch and distribution logic, and manually control the spawned users:\n\n.. code-block:: python\n\n new_users = env.runner.spawn_users({MyUserClass.__name__: 2})\n new_users[1].my_custom_token = \"custom-token-2\"\n new_users[0].my_custom_token = \"custom-token-1\"\n\nThe above example only works on standalone/local runner mode and is an experimental feature. A more common/better approach would be to use ``init`` or ``test_start`` :ref:`events` to get/create a list of tokens and use :ref:`on-start-on-stop` to read from that list and set them on your individual User instances.\n\n.. note::\n\n While it is possible to create locust workers this way (using :py:meth:`create_worker_runner `), that almost never makes sense. Every worker needs to be in a separate Python process and interacting directly with the worker runner might break things. Just launch workers using the regular ``locust --worker ...`` command.\n\nWe could also use the :py:class:`Environment ` instance's \n:py:meth:`create_web_ui ` method to start a Web UI that can be used \nto view the stats, and to control the runner (e.g. start and stop load tests):\n\n.. code-block:: python\n\n env.create_local_runner()\n env.create_web_ui()\n env.web_ui.greenlet.join()\n\nSkipping monkey patching\n========================\n\nSome packages such as boto3 may have incompatibility when using Locust as a library, where monkey patching is already applied. In this case monkey patching may be disabled by setting ``LOCUST_SKIP_MONKEY_PATCH=1`` as env variable.\n\nFull example\n============\n\n.. literalinclude:: ../examples/use_as_lib.py\n :language: python\n" }, { "path": "docs/vscode-extension.rst", "content": ".. _vscode-extension:\n\nVS Code Extension\n=================\n\nLocust has an official extension for Visual Studio Code that helps you set up your Python environment, create and run tests and even use Copilot to generate/adjust Locust test code.\n\nCheck it out at:\n\n* `VS Code Marketplace `__\n* `Open VSX Registry `__ \n* `Git Repo `__\n" }, { "path": "docs/what-is-locust.rst", "content": "===============================\nWhat is Locust?\n===============================\n\nLocust is an open source performance/load testing tool for HTTP and other protocols. Its developer-friendly approach lets you define your tests in regular Python code.\n\nLocust tests can be run from command line or using its web-based UI. Throughput, response times and errors can be viewed in real time and/or exported for later analysis.\n\nYou can import regular Python libraries into your tests, and with Locust's pluggable architecture it is infinitely expandable. Unlike when using most other tools, your test design will never be limited by a GUI or domain-specific language.\n\nTo start using Locust, go to :ref:`installation`\n\nFeatures\n========\n\n.. raw:: html\n\n
\n \n

\n \n* **Write test scenarios in plain old Python**\n\n If you want your users to loop, perform some conditional behavior or do some calculations, you just use the regular programming constructs provided by Python.\n Locust runs every user inside its own greenlet (a lightweight process/coroutine). This enables you to write your tests like normal (blocking) Python code instead of having to use callbacks or some other mechanism.\n Because your scenarios are \"just python\" you can use your regular IDE, and version control your tests as regular code (as opposed to some other tools that use XML or binary formats)\n\n* **Distributed and scalable - supports hundreds of thousands of concurrent users**\n\n Locust makes it easy to run load tests distributed over multiple machines.\n It is event-based (using `gevent `_), which makes it possible for a single process to handle many thousands concurrent users.\n While there may be other tools that are capable of doing more requests per second on a given hardware, the low overhead of each Locust user makes it very suitable for testing highly concurrent workloads.\n \n* **Web-based UI**\n\n Locust has a user friendly web interface that shows the progress of your test in real-time. You can even change the load while the test is running. It can also be run without the UI, making it easy to use for CI/CD testing.\n\n* **Can test any system**\n\n Even though Locust primarily works with websites/services, it can be used to test almost any system or protocol. Just :ref:`write a client ` \n for what you want to test, or `explore some created by the community `_.\n\n* **Hackable**\n\n Locust is small and very flexible and we intend to keep it that way. If you want to `send reporting data to that database & graphing system you like `_, wrap calls to a REST API to handle the particulars of your system or run a :ref:`totally custom load pattern `, there is nothing stopping you!\n\nName & background\n=================\n\nLocust was born out of a frustration with existing solutions. No existing load testing tool was well-equipped to generate realistic \nload against a dynamic website where most pages had different content for different users. Existing tools used clunky interfaces or \nverbose configuration files to declare the tests. In Locust we took a different approach. Instead of configuration formats or UIs \nyou'd get a python framework that would let you define the behavior of your users using Python code. \n\nLocust takes its name from the `grasshopper species `_, known for their swarming behavior. \n\n:ref:`history`\n\nAuthors\n=======\n\n- Jonatan Heyman (`@heyman `_)\n- Lars Holmberg (`@cyberw `_)\n- Andrew Baldwin (`@andrewbaldwin44 `_)\n\nMany thanks to our other great `contributors `_!\n\n\nLicense\n=======\n\nOpen source licensed under the MIT license (see LICENSE file for details).\n" }, { "path": "docs/writing-a-locustfile.rst", "content": ".. _writing-a-locustfile:\n\n======================\nWriting a locustfile\n======================\n\nNow, lets look at a more complete/realistic example of what your tests might look like:\n\n.. code-block:: python\n\n import time\n from locust import HttpUser, task, between\n\n class QuickstartUser(HttpUser):\n wait_time = between(1, 5)\n\n @task\n def hello_world(self):\n self.client.get(\"/hello\")\n self.client.get(\"/world\")\n\n @task(3)\n def view_items(self):\n for item_id in range(10):\n self.client.get(f\"/item?id={item_id}\", name=\"/item\")\n time.sleep(1)\n\n def on_start(self):\n self.client.post(\"/login\", json={\"username\":\"foo\", \"password\":\"bar\"})\n\n\n.. rubric:: Let's break it down\n\n.. code-block:: python\n\n import time\n from locust import HttpUser, task, between\n\nA locust file is just a normal Python module, it can import code from other files or packages.\n\n.. code-block:: python\n\n class QuickstartUser(HttpUser):\n\nHere we define a class for the users that we will be simulating. It inherits from\n:py:class:`HttpUser ` which gives each user a ``client`` attribute,\nwhich is an instance of :py:class:`HttpSession `, that\ncan be used to make HTTP requests to the target system that we want to load test. When a test starts,\nlocust will create an instance of this class for every user that it simulates, and each of these\nusers will start running within their own green gevent thread.\n\nFor a file to be a valid locustfile it must contain at least one class inheriting from :py:class:`User `.\n\n.. code-block:: python\n\n wait_time = between(1, 5)\n\nOur class defines a ``wait_time`` that will make the simulated users wait between 1 and 5 seconds after each task (see below)\nis executed. For more info see :ref:`wait-time`.\n\n.. code-block:: python\n\n @task\n def hello_world(self):\n self.client.get(\"/hello\")\n self.client.get(\"/world\")\n\nMethods decorated with ``@task`` are the core of your locust file. For every running User,\nLocust creates a `greenlet `_ (a coroutine or \"micro-thread\"), that will call those methods. \nCode within a task is executed sequentially (it is just regular Python code),\nso ``/world`` won't be called until the response from ``/hello`` has been received.\n\n.. code-block:: python\n\n @task\n def hello_world(self):\n ...\n \n @task(3)\n def view_items(self):\n ...\n\nWe've declared two tasks by decorating two methods with ``@task``, one of which has been given a higher weight (3).\nWhen our ``QuickstartUser`` runs it'll pick one of the declared tasks - in this case either ``hello_world`` or\n``view_items`` - and execute it. Tasks are picked at random, but you can give them different weighting. The above\nconfiguration will make Locust three times more likely to pick ``view_items`` than ``hello_world``. When a task has\nfinished executing, the User will then sleep for its specified wait time (in this case between 1 and 5 seconds).\nThen it will pick a new task.\n\nNote that only methods decorated with ``@task`` will be picked, so you can define your own internal helper methods any way you like.\n\n.. code-block:: python\n\n self.client.get(\"/hello\")\n\nThe ``self.client`` attribute makes it possible to make HTTP calls that will be logged by Locust. For information on how\nto make other kinds of requests, validate the response, etc, see\n`Using the HTTP Client `_.\n\n.. note::\n\n HttpUser is not a real browser, and thus will not parse an HTML response to load resources or render the page. It will keep track of cookies though.\n\n.. code-block:: python\n\n @task(3)\n def view_items(self):\n for item_id in range(10):\n self.client.get(f\"/item?id={item_id}\", name=\"/item\")\n time.sleep(1)\n\nIn the ``view_items`` task we load 10 different URLs by using a variable query parameter.\nIn order to not get 10 separate entries in Locust's statistics - since the stats is grouped on the URL - we use\nthe :ref:`name parameter ` to group all those requests under an entry named ``\"/item\"`` instead.\n\n.. code-block:: python\n\n def on_start(self):\n self.client.post(\"/login\", json={\"username\":\"foo\", \"password\":\"bar\"})\n\nAdditionally we've declared an `on_start` method. A method with this name will be called for each simulated\nuser when they start. For more info see :ref:`on-start-on-stop`.\n\nAuto-generating a locustfile\n============================\n\nYou can use `har2locust `_ to generate locustfiles based on a browser recording (HAR-file).\n\nIt is particularly useful for beginners that are not used to writing their own locustfile, but also highly customizable for more advanced use cases.\n\n.. note::\n\n har2locust is still in beta. It may not always generate correct locustfiles, and its interface may change between versions.\n\nUser class\n==========\n\nA user class represents one type of user/scenario for your system. When you do a test run you specify the number of concurrent \nusers you want to simulate and Locust will create an instance per user. You can add any attributes you like to these \nclasses/instances, but there are some that have special meaning to Locust:\n\n.. _wait-time:\n\nwait_time attribute\n-------------------\n\nA User's :py:attr:`wait_time ` method makes it easy to introduce delays after\neach task execution. If no `wait_time` is specified, the next task will be executed as soon as one finishes.\n\n* :py:attr:`constant ` for a fixed amount of time\n\n* :py:attr:`between ` for a random time between a min and max value\n\nFor example, to make each user wait between 0.5 and 10 seconds between every task execution:\n\n.. code-block:: python\n\n from locust import User, task, between\n\n class MyUser(User):\n @task\n def my_task(self):\n print(\"executing my_task\")\n\n wait_time = between(0.5, 10)\n\n* :py:attr:`constant_throughput ` for an adaptive time that ensures the task runs (at most) X times per second.\n\n* :py:attr:`constant_pacing ` for an adaptive time that ensures the task runs (at most) once every X seconds (it is the mathematical inverse of `constant_throughput`).\n\n.. note::\n\n For example, if you want Locust to run 500 task iterations per second at peak load, you could use `wait_time = constant_throughput(0.1)` and a user count of 5000.\n\n Wait time can only constrain the throughput, not launch new Users to reach the target. So, in our example, the throughput will be less than 500 if the time for the task iteration exceeds 10 seconds.\n\n Wait time is applied *after* task execution, so if you have a high spawn rate/ramp up you may end up exceeding your target during ramp-up.\n\n Wait times apply to *tasks*, not requests. For example, if you specify `wait_time = constant_throughput(2)` and do two requests in your tasks, your request rate/RPS will be 4 per User.\n\nIt's also possible to declare your own wait_time method directly on your class.\nFor example, the following User class would sleep for one second, then two, then three, etc.\n\n.. code-block:: python\n\n class MyUser(User):\n last_wait_time = 0\n\n def wait_time(self):\n self.last_wait_time += 1\n return self.last_wait_time\n\n ...\n\n\nweight and fixed_count attributes\n---------------------------------\n\nIf more than one user class exists in the file, and no user classes are specified on the command line,\nLocust will spawn an equal number of each of the user classes. You can also specify which of the\nuser classes to use from the same locustfile by passing them as command line arguments:\n\n.. code-block:: console\n\n $ locust -f locust_file.py WebUser MobileUser\n\nIf you wish to simulate more users of a certain type than another you can set a weight attribute on those\nclasses. The code below will make Locust spawn 3 times as many WebUsers as MobileUsers:\n\n.. code-block:: python\n\n class WebUser(User):\n weight = 3\n ...\n\n class MobileUser(User):\n weight = 1\n ...\n\nAlso, you can set the :py:attr:`fixed_count ` attribute.\nIn this case, the weight attribute will be ignored and only that exact number users will be spawned.\nThese users are spawned before any regular, weighted ones. In the example below, only one instance of AdminUser\nwill be spawned, to make some specific work with more accurate control\nof request count independently of total user count.\n\n.. code-block:: python\n\n class AdminUser(User):\n wait_time = constant(600)\n fixed_count = 1\n \n @task\n def restart_app(self):\n ...\n\n class WebUser(User):\n ...\n\n\nhost attribute\n--------------\n\nThe host attribute is a URL prefix (e.g. ``https://google.com``) to the host you want to test. It is automatically added to requests, so you can do ``self.client.get(\"/\")`` for example.\n\nYou can overwrite this value in Locust's web UI or on the command line, using the\n:code:`--host` option.\n\ntasks attribute\n---------------\n\nA User class can have tasks declared as methods under it using the :py:func:`@task ` decorator, but one can also\nspecify tasks using the *tasks* attribute, which is described in more details :ref:`below `.\n\nenvironment attribute\n---------------------\n\nA reference to the :py:attr:`environment ` in which the user is running. Use this to interact with\nthe environment, or the :py:attr:`runner ` which it contains. E.g. to stop the runner from a task method:\n\n.. code-block:: python\n\n self.environment.runner.quit()\n\nIf run on a standalone locust instance, this will stop the entire run. If run on worker node, it will stop that particular node.\n\n.. _on-start-on-stop:\n\non_start and on_stop methods\n----------------------------\n\nUsers (and :ref:`TaskSets `) can declare an :py:meth:`on_start ` method and/or\n:py:meth:`on_stop ` method. A User will call its\n:py:meth:`on_start ` method when it starts running, and its\n:py:meth:`on_stop ` method when it stops running. For a TaskSet, the\n:py:meth:`on_start ` method is called when a simulated user starts executing\nthat TaskSet, and :py:meth:`on_stop ` is called when the simulated user stops\nexecuting that TaskSet (when :py:meth:`interrupt() ` is called, or the\nuser is killed).\n\nTasks\n=====\n\nWhen a load test is started, an instance of a User class will be created for each simulated user\nand they will start running within their own greenlet. When these users run they pick tasks that\nthey execute, sleep for awhile, and then pick a new task and so on.\n\n@task decorator\n---------------\n\nThe easiest way to add a task for a User is by using the :py:meth:`task ` decorator.\n\n.. code-block:: python\n\n from locust import User, task, constant\n\n class MyUser(User):\n wait_time = constant(1)\n\n @task\n def my_task(self):\n print(\"User instance (%r) executing my_task\" % self)\n\n**@task** takes an optional weight argument that can be used to specify the task's execution ratio. In\nthe following example, *task2* will be twice as likely to be selected as *task1*:\n\n.. code-block:: python\n\n from locust import User, task, between\n\n class MyUser(User):\n wait_time = between(5, 15)\n\n @task(3)\n def task1(self):\n pass\n\n @task(6)\n def task2(self):\n pass\n\n\n.. _tasks-attribute:\n\ntasks attribute\n---------------\n\nAnother way to define the tasks of a User is by setting the :py:attr:`tasks ` attribute.\n\nThe *tasks* attribute is either a list of Tasks, or a ** dict, where Task is either a\npython callable or a :ref:`TaskSet ` class. If the task is a normal python function they\nreceive a single argument which is the User instance that is executing the task.\n\nHere is an example of a User task declared as a normal python function:\n\n.. code-block:: python\n\n from locust import User, constant\n\n def my_task(user):\n pass\n\n class MyUser(User):\n tasks = [my_task]\n wait_time = constant(1)\n\n\nIf the tasks attribute is specified as a list, each time a task is to be performed, it will be randomly\nchosen from the *tasks* attribute. If however, *tasks* is a dict - with callables as keys and ints\nas values - the task that is to be executed will be chosen at random but with the int as ratio. So\nwith a task that looks like this::\n\n {my_task: 3, another_task: 1}\n\n*my_task* would be 3 times as likely to be executed as *another_task*.\n\nInternally the above dict will actually be expanded into a list (and the ``tasks`` attribute is updated)\nthat looks like this::\n\n [my_task, my_task, my_task, another_task]\n\nand then Python's ``random.choice()`` is used to pick tasks from the list.\n\n\n.. _tagging-tasks:\n\n@tag decorator\n--------------\n\nBy tagging tasks using the :py:func:`@tag ` decorator, you can be picky about what tasks are\nexecuted during the test using the :code:`--tags` and :code:`--exclude-tags` arguments. Consider\nthe following example:\n\n.. code-block:: python\n\n from locust import User, constant, task, tag\n\n class MyUser(User):\n wait_time = constant(1)\n\n @tag('tag1')\n @task\n def task1(self):\n pass\n\n @tag('tag1', 'tag2')\n @task\n def task2(self):\n pass\n\n @tag('tag3')\n @task\n def task3(self):\n pass\n\n @task\n def task4(self):\n pass\n\nIf you started this test with :code:`--tags tag1`, only *task1* and *task2* would be executed\nduring the test. If you started it with :code:`--tags tag2 tag3`, only *task2* and *task3* would be\nexecuted.\n\n:code:`--exclude-tags` will behave in the exact opposite way. So, if you start the test with\n:code:`--exclude-tags tag3`, only *task1*, *task2*, and *task4* will be executed. Exclusion always\nwins over inclusion, so if a task has a tag you've included and a tag you've excluded, it will not\nbe executed.\n\nEvents\n======\n\nIf you want to run some setup code as part of your test, it is often enough to put it at the module\nlevel of your locustfile, but sometimes you need to do things at particular times in the run. For\nthis need, Locust provides event hooks.\n\ntest_start and test_stop\n------------------------\n\nIf you need to run some code at the start or stop of a load test, you should use the\n:py:attr:`test_start ` and :py:attr:`test_stop `\nevents. You can set up listeners for these events at the module level of your locustfile:\n\n.. code-block:: python\n\n from locust import events\n\n @events.test_start.add_listener\n def on_test_start(environment, **kwargs):\n print(\"A new test is starting\")\n\n @events.test_stop.add_listener\n def on_test_stop(environment, **kwargs):\n print(\"A new test is ending\")\n\ninit\n----\n\nThe ``init`` event is triggered at the beginning of each Locust process. This is especially useful in distributed mode\nwhere each worker process (not each user) needs a chance to do some initialization. For example, let's say you have some\nglobal state that all users spawned from this process will need:\n\n.. code-block:: python\n\n from locust import events\n from locust.runners import MasterRunner\n\n @events.init.add_listener\n def on_locust_init(environment, **kwargs):\n if isinstance(environment.runner, MasterRunner):\n print(\"I'm on master node\")\n else:\n print(\"I'm on a worker or standalone node\")\n\nOther events\n------------\n\nSee :ref:`extending locust using event hooks ` for other events and more examples of how to use them.\n\nHttpUser class\n==============\n\n:py:class:`HttpUser ` is the most commonly used :py:class:`User `. It adds a :py:attr:`client ` attribute which is used to make HTTP requests.\n\n.. code-block:: python\n\n from locust import HttpUser, task, between\n\n class MyUser(HttpUser):\n wait_time = between(5, 15)\n\n @task(4)\n def index(self):\n self.client.get(\"/\")\n\n @task(1)\n def about(self):\n self.client.get(\"/about/\")\n\n\nclient attribute / HttpSession\n------------------------------\n\n:py:attr:`client ` is an instance of :py:class:`HttpSession `. HttpSession is a subclass/wrapper for\n:py:class:`requests.Session`, so its features are well documented and should be familiar to many. What HttpSession adds is mainly reporting of the request results into Locust (success/fail, response time, response length, name).\n\n\nIt contains methods for all HTTP methods: :py:meth:`get `,\n:py:meth:`post `, :py:meth:`put `,\n...\n\n\nJust like :py:class:`requests.Session`, it preserves cookies between requests so it can easily be used to log in to websites.\n\n.. code-block:: python\n :caption: Make a POST request, look at the response and implicitly reuse any session cookie we got for a second request\n\n response = self.client.post(\"/login\", {\"username\":\"testuser\", \"password\":\"secret\"})\n print(\"Response status code:\", response.status_code)\n print(\"Response text:\", response.text)\n response = self.client.get(\"/my-profile\")\n\nHttpSession catches any :py:class:`requests.RequestException` thrown by Session (caused by connection errors, timeouts or similar), instead returning a dummy\nResponse object with *status_code* set to 0 and *content* set to None.\n\n\n.. _catch-response:\n\nValidating responses\n--------------------\n\nRequests are considered successful if the HTTP response code is OK (<400), but it is often useful to\ndo some additional validation of the response.\n\nYou can mark a request as failed by using the *catch_response* argument, a *with*-statement and\na call to *response.failure()*\n\n.. code-block:: python\n\n with self.client.get(\"/\", catch_response=True) as response:\n if response.text != \"Success\":\n response.failure(\"Got wrong response\")\n elif response.elapsed.total_seconds() > 0.5:\n response.failure(\"Request took too long\")\n\n\nYou can also mark a request as successful, even if the response code was bad:\n\n.. code-block:: python\n\n with self.client.get(\"/does_not_exist/\", catch_response=True) as response:\n if response.status_code == 404:\n response.success()\n\nYou can even avoid logging a request at all by throwing an exception and then catching it outside the with-block. Or you can throw a :ref:`locust exception `, like in the example below, and let Locust catch it.\n\n.. code-block:: python\n\n from locust.exception import RescheduleTask\n ...\n with self.client.get(\"/does_not_exist/\", catch_response=True) as response:\n if response.status_code == 404:\n raise RescheduleTask()\n\nREST/JSON APIs\n--------------\n\n:ref:`FastHttpUser ` provides a ready-made ``rest`` method, but you can also do it yourself:\n\n.. code-block:: python\n\n from json import JSONDecodeError\n ...\n with self.client.post(\"/\", json={\"foo\": 42, \"bar\": None}, catch_response=True) as response:\n try:\n if response.json()[\"greeting\"] != \"hello\":\n response.failure(\"Did not get expected value in greeting\")\n except JSONDecodeError:\n response.failure(\"Response could not be decoded as JSON\")\n except KeyError:\n response.failure(\"Response did not contain expected key 'greeting'\")\n\n.. _name-parameter:\n\nGrouping requests\n-----------------\n\nIt's very common for websites to have pages whose URLs contain some kind of dynamic parameter(s).\nOften it makes sense to group these URLs together in User's statistics. This can be done\nby passing a *name* argument to the :py:class:`HttpSession's `\ndifferent request methods.\n\nExample:\n\n.. code-block:: python\n\n # Statistics for these requests will be grouped under: /blog/?id=[id]\n for i in range(10):\n self.client.get(\"/blog?id=%i\" % i, name=\"/blog?id=[id]\")\n\nThere may be situations where passing in a parameter into request function is not possible, such as when interacting with libraries/SDK's that\nwrap a Requests session. An alternative way of grouping requests is provided by setting the ``client.request_name`` attribute.\n\n.. code-block:: python\n\n # Statistics for these requests will be grouped under: /blog/?id=[id]\n self.client.request_name=\"/blog?id=[id]\"\n for i in range(10):\n self.client.get(\"/blog?id=%i\" % i)\n self.client.request_name=None\n\nIf you want to chain multiple groupings with minimal boilerplate, you can use the ``client.rename_request()`` context manager.\n\n.. code-block:: python\n\n @task\n def multiple_groupings_example(self):\n # Statistics for these requests will be grouped under: /blog/?id=[id]\n with self.client.rename_request(\"/blog?id=[id]\"):\n for i in range(10):\n self.client.get(\"/blog?id=%i\" % i)\n\n # Statistics for these requests will be grouped under: /article/?id=[id]\n with self.client.rename_request(\"/article?id=[id]\"):\n for i in range(10):\n self.client.get(\"/article?id=%i\" % i)\n\nUsing :ref:`catch_response ` and accessing `request_meta `_ directly, you can even rename requests based on something in the response.\n\n.. code-block:: python\n\n with self.client.get(\"/\", catch_response=True) as resp:\n resp.request_meta[\"name\"] = resp.json()[\"name\"]\n\n\nHTTP Proxy settings\n-------------------\nTo improve performance, we configure requests to not look for HTTP proxy settings in the environment by setting\nrequests.Session's trust_env attribute to ``False``. If you don't want this, you can manually set\n``locust_instance.client.trust_env`` to ``True``. For further details, refer to the\n`documentation of requests `_.\n\nConnection reuse\n----------------\n\nBy default, connections are reused by an HttpUser, even across tasks runs. To avoid connection reuse you can do:\n\n.. code-block:: python\n \n self.client.get(\"/\", headers={\"Connection\": \"close\"})\n self.client.get(\"/new_connection_here\")\n\nOr you can close the entire requests.Session object (this also deletes cookies, closes the SSL session etc). This has some CPU overhead \n(and the response time of the next request will be higher due to SSL renegotiation etc), so dont use this unless you really need it.\n\n.. code-block:: python\n \n self.client.get(\"/\")\n self.client.close()\n self.client.get(\"/new_connection_here\")\n\n\nConnection pooling\n------------------\n\nAs every :py:class:`HttpUser ` creates new :py:class:`HttpSession `,\nevery user instance has its own connection pool. This is similar to how real users (browsers) would interact with a web server.\n\nIf you instead want to share connections, you can use a single pool manager. To do this, set :py:attr:`pool_manager ` \nclass attribute to an instance of :py:class:`urllib3.PoolManager`.\n\n.. code-block:: python\n\n from locust import HttpUser\n from urllib3 import PoolManager\n\n class MyUser(HttpUser):\n # All instances of this class will be limited to 10 concurrent connections at most.\n pool_manager = PoolManager(maxsize=10, block=True)\n\nFor more configuration options, refer to the\n`urllib3 documentation `_.\n\nTaskSets\n================================\nTaskSets is a way to structure tests of hierarchical websites/systems. You can :ref:`read more about it here `.\n\nExamples\n========\n\nThere are lots of locustfile examples `here `_\n\nHow to structure your test code\n================================\n\nIt's important to remember that the locustfile.py is just an ordinary Python module that is imported\nby Locust. From this module you're free to import other python code just as you normally would\nin any Python program. The current working directory is automatically added to python's ``sys.path``,\nso any python file/module/packages that resides in the working directory can be imported using the\npython ``import`` statement.\n\nFor small tests, keeping all the test code in a single ``locustfile.py`` should work fine, but for\nlarger test suites, you'll probably want to split the code into multiple files and directories.\n\nHow you structure the test source code is of course entirely up to you, but we recommend that you\nfollow Python best practices. Here's an example file structure of an imaginary Locust project:\n\n* Project root\n\n * ``common/``\n\n * ``__init__.py``\n * ``auth.py``\n * ``config.py``\n * ``locustfile.py``\n * ``requirements.txt`` (External Python dependencies is often kept in a requirements.txt)\n\nA project with multiple locustfiles could also keep them in a separate subdirectory:\n\n* Project root\n\n * ``common/``\n\n * ``__init__.py``\n * ``auth.py``\n * ``config.py``\n * ``my_locustfiles/``\n\n * ``api.py``\n * ``website.py``\n * ``requirements.txt``\n\n\nWith any of the above project structure, your locustfile can import common libraries using:\n\n.. code-block:: python\n\n import common.auth\n" }, { "path": "examples/add_command_line_argument.py", "content": "from locust import HttpUser, events, task\n\n\n@events.init_command_line_parser.add_listener\ndef _(parser):\n parser.add_argument(\"--my-argument\", type=str, env_var=\"LOCUST_MY_ARGUMENT\", default=\"\", help=\"It's working\")\n # Choices will validate command line input and show a dropdown in the web UI\n parser.add_argument(\"--env\", choices=[\"dev\", \"staging\", \"prod\"], default=\"dev\", help=\"Environment\")\n # In combination with choices, is_multiple makes the dropdown in the web UI allow multiple selections\n parser.add_argument(\"--endpoints\", choices=[\"a\", \"b\", \"c\"], is_multiple=True, default=[\"a\"], help=\"Endpoints\")\n # Set `include_in_web_ui` to False if you want to hide from the web UI\n parser.add_argument(\"--my-ui-invisible-argument\", include_in_web_ui=False, default=\"I am invisible\")\n # Set `is_secret` to True if you want the text input to be password masked in the web UI\n parser.add_argument(\"--my-ui-password-argument\", is_secret=True, default=\"I am a secret\")\n # Use a boolean default value if you want the input to be a checkmark\n parser.add_argument(\"--my-ui-boolean-argument\", default=True)\n # Set `is_required` to mark a form field as required\n parser.add_argument(\"--my-ui-required-argument\", is_required=True, default=\"I am required\")\n\n\n@events.test_start.add_listener\ndef _(environment, **kw):\n print(f\"Custom argument supplied: {environment.parsed_options.my_argument}\")\n\n\nclass WebsiteUser(HttpUser):\n @task\n def my_task(self):\n print(f\"my_argument={self.environment.parsed_options.my_argument}\")\n print(f\"my_ui_invisible_argument={self.environment.parsed_options.my_ui_invisible_argument}\")\n" }, { "path": "examples/basic.py", "content": "from locust import HttpUser, TaskSet, between, task\n\n\ndef index(l):\n l.client.get(\"/\")\n\n\ndef stats(l):\n l.client.get(\"/stats/requests\")\n\n\nclass UserTasks(TaskSet):\n # one can specify tasks like this\n tasks = [index, stats]\n\n # but it might be convenient to use the @task decorator\n @task\n def page404(self):\n self.client.get(\"/does_not_exist\")\n\n\nclass WebsiteUser(HttpUser):\n \"\"\"\n User class that does requests to the locust web server running on localhost\n \"\"\"\n\n host = \"http://127.0.0.1:8089\"\n wait_time = between(2, 5)\n tasks = [UserTasks]\n" }, { "path": "examples/bottlenecked_server.py", "content": "\"\"\"\nThis example uses extensions in Locust's own WebUI to simulate a bottlenecked server and runs a test against itself.\n\nThe purpose of this is mainly to generate nice graphs in the UI to teach new users how to interpret load test results.\n\nSee https://docs.locust.io/en/stable/quickstart.html#locust-s-web-interface\n\"\"\"\n\nfrom locust import HttpUser, events, run_single_user, task\n\nimport time\nfrom threading import Semaphore\n\n# Only allow up to 10 concurrent requests. Similar to how a server with 10 threads might behave.\nsema = Semaphore(10)\n\n\nclass WebsiteUser(HttpUser):\n host = \"http://127.0.0.1:8089\"\n\n @task\n def index(l):\n l.client.get(\"/slow\")\n\n\n@events.init.add_listener\ndef locust_init(environment, **kwargs):\n assert environment.web_ui, \"you can't run this headless\"\n\n @environment.web_ui.app.route(\"/slow\")\n def my_added_page():\n with sema: # only 10 requests can hold this lock at the same time\n time.sleep(1) # pretend each request takes 1 second to execute\n return \"Another page\"\n\n\nif __name__ == \"__main__\":\n run_single_user(WebsiteUser)\n" }, { "path": "examples/browse_docs_sequence_test.py", "content": "# This locust test script example will simulate a user\n# browsing the Locust documentation on https://docs.locust.io/\n\nfrom locust import HttpUser, SequentialTaskSet, between, task\n\nimport random\n\nfrom pyquery import PyQuery\n\n\nclass BrowseDocumentationSequence(SequentialTaskSet):\n def on_start(self):\n self.urls_on_current_page = self.toc_urls = None\n\n # assume all users arrive at the index page\n @task\n def index_page(self):\n r = self.client.get(\"/\")\n pq = PyQuery(r.content)\n link_elements = pq(\".toctree-wrapper a.internal\")\n self.toc_urls = [l.attrib[\"href\"] for l in link_elements]\n # it is fine to do multiple requests in a single task, you dont need SequentialTaskSet for that\n self.client.get(\"/favicon.ico\")\n\n @task\n def load_page(self, url=None):\n url = random.choice(self.toc_urls)\n r = self.client.get(url)\n pq = PyQuery(r.content)\n link_elements = pq(\"a.internal\")\n self.urls_on_current_page = [l.attrib[\"href\"] for l in link_elements]\n\n @task\n def load_sub_page(self):\n url = random.choice(self.urls_on_current_page)\n r = self.client.get(url)\n\n\nclass AwesomeUser(HttpUser):\n tasks = [BrowseDocumentationSequence]\n host = \"https://docs.locust.io/en/latest/\"\n\n # we assume someone who is browsing the Locust docs,\n # generally has a quite long waiting time (between\n # 20 and 600 seconds), since there's a bunch of text\n # on each page\n wait_time = between(20, 600)\n" }, { "path": "examples/browse_docs_test.py", "content": "# This locust test script example will simulate a user\n# browsing the Locust documentation on https://docs.locust.io/\n\nfrom locust import HttpUser, TaskSet, between, task\n\nimport random\n\nfrom pyquery import PyQuery\n\n\nclass BrowseDocumentation(TaskSet):\n def on_start(self):\n # assume all users arrive at the index page\n self.index_page()\n self.urls_on_current_page = self.toc_urls\n\n @task(10)\n def index_page(self):\n r = self.client.get(\"/\")\n pq = PyQuery(r.content)\n link_elements = pq(\".toctree-wrapper a.internal\")\n self.toc_urls = [l.attrib[\"href\"] for l in link_elements]\n\n @task(50)\n def load_page(self, url=None):\n url = random.choice(self.toc_urls)\n r = self.client.get(url)\n pq = PyQuery(r.content)\n link_elements = pq(\"a.internal\")\n self.urls_on_current_page = [l.attrib[\"href\"] for l in link_elements]\n\n @task(30)\n def load_sub_page(self):\n url = random.choice(self.urls_on_current_page)\n r = self.client.get(url)\n\n\nclass AwesomeUser(HttpUser):\n tasks = [BrowseDocumentation]\n host = \"https://docs.locust.io/en/latest/\"\n\n # we assume someone who is browsing the Locust docs,\n # generally has a quite long waiting time (between\n # 20 and 600 seconds), since there's a bunch of text\n # on each page\n wait_time = between(20, 600)\n" }, { "path": "examples/csrf_form_authentication.py", "content": "from locust import HttpUser, between, task\n\nimport re\n\n\nclass WebsiteUser(HttpUser):\n host = \"http://127.0.0.1:8089\"\n wait_time = between(2, 5)\n\n @task\n def authenticate(self):\n with self.client.get(\"/sign-in\", catch_response=True) as response:\n match = re.search(\n r']*value=\"([^\"]*)\"',\n response.text,\n )\n token = match.group(1)\n\n with self.client.post(\n \"/sign-in\",\n {\n \"user[email]\": \"username\",\n \"user[password]\": \"password\",\n \"authenticity_token\": token,\n },\n catch_response=True,\n ) as response:\n if \"welcome\" not in response.url:\n response.failure(\"Login failed\")\n" }, { "path": "examples/custom_messages.py", "content": "from locust import HttpUser, between, events, task\nfrom locust.runners import LocalRunner, MasterRunner, WorkerRunner\n\nimport gevent\n\nusernames = []\n\n\ndef setup_test_users(environment, msg, **kwargs):\n # Fired when the worker receives a message of type 'test_users'\n usernames.extend(map(lambda u: u[\"name\"], msg.data))\n environment.runner.send_message(\"acknowledge_users\", f\"Thanks for the {len(msg.data)} users!\")\n environment.runner.send_message(\"concurrent_message\", \"Message to concurrent handler\")\n\n\ndef on_acknowledge(msg, **kwargs):\n # Fired when the master receives a message of type 'acknowledge_users'\n print(msg.data)\n\n\ndef on_concurrent_message(msg, **kwargs):\n print(f\"concurrent_message received with data: '{msg.data}'\")\n gevent.sleep(10) # if this handler was run with concurrent=False it would halt the message handling loop in locust\n print(\"finished processing concurrent_message\")\n\n\n@events.init.add_listener\ndef on_locust_init(environment, **_kwargs):\n if not isinstance(environment.runner, MasterRunner):\n environment.runner.register_message(\"test_users\", setup_test_users)\n if not isinstance(environment.runner, WorkerRunner):\n environment.runner.register_message(\"acknowledge_users\", on_acknowledge)\n environment.runner.register_message(\"concurrent_message\", on_concurrent_message, concurrent=True)\n\n\n@events.test_start.add_listener\ndef on_test_start(environment, **_kwargs):\n # When the test is started, evenly divides list between\n # worker nodes to ensure unique data across threads\n if not isinstance(environment.runner, WorkerRunner):\n users = []\n for i in range(environment.runner.target_user_count):\n users.append({\"name\": f\"User{i}\"})\n\n worker_count = environment.runner.worker_count\n chunk_size = int(len(users) / worker_count)\n if isinstance(environment.runner, LocalRunner):\n workers = [environment.runner]\n else:\n workers = environment.runner.clients\n\n for i, worker in enumerate(workers):\n start_index = i * chunk_size\n\n if i + 1 < worker_count:\n end_index = start_index + chunk_size\n else:\n end_index = len(users)\n\n data = users[start_index:end_index]\n environment.runner.send_message(\"test_users\", data, worker)\n\n\nclass WebsiteUser(HttpUser):\n host = \"http://127.0.0.1:8089\"\n wait_time = between(2, 5)\n\n def __init__(self, parent):\n self.username = usernames.pop()\n super().__init__(parent)\n\n @task\n def task(self):\n print(self.username)\n" }, { "path": "examples/custom_shape/double_wave.py", "content": "from locust import HttpUser, LoadTestShape, TaskSet, constant, task\n\nimport math\n\n\nclass UserTasks(TaskSet):\n @task\n def get_root(self):\n self.client.get(\"/\")\n\n\nclass WebsiteUser(HttpUser):\n wait_time = constant(0.5)\n tasks = [UserTasks]\n\n\nclass DoubleWave(LoadTestShape):\n \"\"\"\n A shape to imitate some specific user behaviour. In this example, midday\n and evening meal times. First peak of users appear at time_limit/3 and\n second peak appears at 2*time_limit/3\n\n Settings:\n min_users -- minimum users\n peak_one_users -- users in first peak\n peak_two_users -- users in second peak\n time_limit -- total length of test\n \"\"\"\n\n min_users = 20\n peak_one_users = 60\n peak_two_users = 40\n time_limit = 600\n\n def tick(self):\n run_time = round(self.get_run_time())\n\n if run_time < self.time_limit:\n user_count = (\n (self.peak_one_users - self.min_users)\n * math.e ** -(((run_time / (self.time_limit / 10 * 2 / 3)) - 5) ** 2)\n + (self.peak_two_users - self.min_users)\n * math.e ** -(((run_time / (self.time_limit / 10 * 2 / 3)) - 10) ** 2)\n + self.min_users\n )\n return (round(user_count), round(user_count))\n else:\n return None\n" }, { "path": "examples/custom_shape/stages.py", "content": "from locust import HttpUser, LoadTestShape, TaskSet, constant, task\n\n\nclass UserTasks(TaskSet):\n @task\n def get_root(self):\n self.client.get(\"/\")\n\n\nclass WebsiteUser(HttpUser):\n wait_time = constant(0.5)\n tasks = [UserTasks]\n\n\nclass StagesShape(LoadTestShape):\n \"\"\"\n A simply load test shape class that has different user and spawn_rate at\n different stages.\n\n Keyword arguments:\n\n stages -- A list of dicts, each representing a stage with the following keys:\n duration -- When this many seconds pass the test is advanced to the next stage\n users -- Total user count\n spawn_rate -- Number of users to start/stop per second\n stop -- A boolean that can stop that test at a specific stage\n\n stop_at_end -- Can be set to stop once all stages have run.\n \"\"\"\n\n stages = [\n {\"duration\": 60, \"users\": 10, \"spawn_rate\": 10},\n {\"duration\": 100, \"users\": 50, \"spawn_rate\": 10},\n {\"duration\": 180, \"users\": 100, \"spawn_rate\": 10},\n {\"duration\": 220, \"users\": 30, \"spawn_rate\": 10},\n {\"duration\": 230, \"users\": 10, \"spawn_rate\": 10},\n {\"duration\": 240, \"users\": 1, \"spawn_rate\": 1},\n ]\n\n def tick(self):\n run_time = self.get_run_time()\n\n for stage in self.stages:\n if run_time < stage[\"duration\"]:\n tick_data = (stage[\"users\"], stage[\"spawn_rate\"])\n return tick_data\n\n return None\n" }, { "path": "examples/custom_shape/staging_user_classes.py", "content": "from locust import HttpUser, LoadTestShape, TaskSet, constant, task\n\n\nclass UserTasks(TaskSet):\n @task\n def get_root(self):\n self.client.get(\"/\")\n\n\nclass WebsiteUserA(HttpUser):\n wait_time = constant(0.5)\n tasks = [UserTasks]\n\n\nclass WebsiteUserB(HttpUser):\n wait_time = constant(0.5)\n tasks = [UserTasks]\n\n\nclass StagesShapeWithCustomUsers(LoadTestShape):\n \"\"\"\n A simply load test shape class that has different user and spawn_rate at\n different stages.\n\n Keyword arguments:\n\n stages -- A list of dicts, each representing a stage with the following keys:\n duration -- When this many seconds pass the test is advanced to the next stage\n users -- Total user count\n spawn_rate -- Number of users to start/stop per second\n stop -- A boolean that can stop that test at a specific stage\n\n stop_at_end -- Can be set to stop once all stages have run.\n \"\"\"\n\n stages = [\n {\"duration\": 60, \"users\": 10, \"spawn_rate\": 10, \"user_classes\": [WebsiteUserA]},\n {\"duration\": 100, \"users\": 50, \"spawn_rate\": 10, \"user_classes\": [WebsiteUserB]},\n {\"duration\": 180, \"users\": 100, \"spawn_rate\": 10, \"user_classes\": [WebsiteUserA]},\n {\"duration\": 220, \"users\": 30, \"spawn_rate\": 10},\n {\"duration\": 230, \"users\": 10, \"spawn_rate\": 10},\n {\"duration\": 240, \"users\": 1, \"spawn_rate\": 1},\n ]\n\n def tick(self):\n run_time = self.get_run_time()\n\n for stage in self.stages:\n if run_time < stage[\"duration\"]:\n # Not the smartest solution, TODO: find something better\n try:\n tick_data = (stage[\"users\"], stage[\"spawn_rate\"], stage[\"user_classes\"])\n except KeyError:\n tick_data = (stage[\"users\"], stage[\"spawn_rate\"])\n return tick_data\n\n return None\n" }, { "path": "examples/custom_shape/step_load.py", "content": "from locust import HttpUser, LoadTestShape, TaskSet, constant, task\n\nimport math\n\n\nclass UserTasks(TaskSet):\n @task\n def get_root(self):\n self.client.get(\"/\")\n\n\nclass WebsiteUser(HttpUser):\n wait_time = constant(0.5)\n tasks = [UserTasks]\n\n\nclass StepLoadShape(LoadTestShape):\n \"\"\"\n A step load shape\n\n\n Keyword arguments:\n\n step_time -- Time between steps\n step_load -- User increase amount at each step\n spawn_rate -- Users to stop/start per second at every step\n time_limit -- Time limit in seconds\n\n \"\"\"\n\n step_time = 30\n step_load = 10\n spawn_rate = 10\n time_limit = 600\n\n def tick(self):\n run_time = self.get_run_time()\n\n if run_time > self.time_limit:\n return None\n\n current_step = math.floor(run_time / self.step_time) + 1\n return (current_step * self.step_load, self.spawn_rate)\n" }, { "path": "examples/custom_shape/wait_user_count.py", "content": "from locust import HttpUser, LoadTestShape, TaskSet, constant, task\n\nimport random\nimport time\nfrom collections import namedtuple\n\n\nclass UserTasks(TaskSet):\n @task\n def get_root(self):\n self.client.get(\"/\")\n\n\nclass WebsiteUser(HttpUser):\n wait_time = constant(0.5)\n tasks = [UserTasks]\n\n def __init__(self, *args, **kwargs):\n # we arbitrarily make the users very slow to create, and also\n # unpredictably slow. One way this might happen in real use cases is if\n # the User has a slow initialization for gathering data to randomly\n # select.\n time.sleep(random.randint(0, 5))\n super().__init__(*args, **kwargs)\n\n\nStep = namedtuple(\"Step\", [\"users\", \"dwell\"])\n\n\nclass StepLoadShape(LoadTestShape):\n \"\"\"\n A step load shape that waits until the target user count has\n been reached before waiting on a per-step timer.\n\n The purpose here is to ensure that a target number of users is always reached,\n regardless of how slow the user spawn rate is. The dwell time is there to\n observe the steady state at that number of users.\n\n Keyword arguments:\n\n targets_with_times -- iterable of 2-tuples, with the desired user count first,\n and the dwell (hold) time with that user count second\n\n \"\"\"\n\n targets_with_times = (Step(10, 10), Step(20, 15), Step(10, 10))\n\n def __init__(self, *args, **kwargs):\n self.step = 0\n self.time_active = False\n super().__init__(*args, **kwargs)\n\n def tick(self):\n if self.step >= len(self.targets_with_times):\n return None\n\n target = self.targets_with_times[self.step]\n users = self.get_current_user_count()\n\n if target.users == users:\n if not self.time_active:\n self.reset_time()\n self.time_active = True\n run_time = self.get_run_time()\n if run_time > target.dwell:\n self.step += 1\n self.time_active = False\n\n # Spawn rate is the second value here. It is not relevant because we are\n # rate-limited by the User init rate. We set it arbitrarily high, which\n # means \"spawn as fast as you can\"\n return (target.users, 100)\n" }, { "path": "examples/custom_wait_function.py", "content": "from locust import HttpUser, TaskSet, task\n\nimport random\n\n\ndef index(l):\n l.client.get(\"/\")\n\n\ndef stats(l):\n l.client.get(\"/stats/requests\")\n\n\nclass UserTasks(TaskSet):\n # one can specify tasks like this\n tasks = [index, stats]\n\n # but it might be convenient to use the @task decorator\n @task\n def page404(self):\n self.client.get(\"/does_not_exist\")\n\n\nclass WebsiteUser(HttpUser):\n \"\"\"\n User class that does requests to the locust web server running on localhost\n \"\"\"\n\n host = \"http://127.0.0.1:8089\"\n # Most task inter-arrival times approximate to exponential distributions\n # We will model this wait time as exponentially distributed with a mean of 1 second\n wait_time = lambda self: random.expovariate(1)\n tasks = [UserTasks]\n\n\ndef strictExp(min_wait, max_wait, mu=1):\n \"\"\"\n Returns an exponentially distributed time strictly between two bounds.\n \"\"\"\n while True:\n x = random.expovariate(mu)\n increment = (max_wait - min_wait) / (mu * 6.0)\n result = min_wait + (x * increment)\n if result < max_wait:\n break\n return result\n\n\nclass StrictWebsiteUser(HttpUser):\n \"\"\"\n User class that makes exponential requests but strictly between two bounds.\n \"\"\"\n\n host = \"http://127.0.0.1:8089\"\n wait_time = lambda self: strictExp(3, 7)\n tasks = [UserTasks]\n" }, { "path": "examples/custom_xmlrpc_client/server.py", "content": "import random\nimport time\nfrom xmlrpc.server import SimpleXMLRPCServer\n\n\ndef get_time():\n time.sleep(random.random())\n return time.time()\n\n\ndef get_random_number(low, high):\n time.sleep(random.random())\n return random.randint(low, high)\n\n\nserver = SimpleXMLRPCServer((\"localhost\", 8877))\nprint(\"Listening on port 8877...\")\nserver.register_function(get_time, \"get_time\")\nserver.register_function(get_random_number, \"get_random_number\")\nserver.serve_forever()\n" }, { "path": "examples/custom_xmlrpc_client/xmlrpc_locustfile.py", "content": "from locust import User, task\n\nimport time\nfrom xmlrpc.client import Fault, ServerProxy\n\n\nclass XmlRpcClient(ServerProxy):\n \"\"\"\n XmlRpcClient is a wrapper around the standard library's ServerProxy.\n It proxies any function calls and fires the *request* event when they finish,\n so that the calls get recorded in Locust.\n \"\"\"\n\n def __init__(self, host, request_event):\n super().__init__(host)\n self._request_event = request_event\n\n def __getattr__(self, name):\n func = ServerProxy.__getattr__(self, name)\n\n def wrapper(*args, **kwargs):\n request_meta = {\n \"request_type\": \"xmlrpc\",\n \"name\": name,\n \"start_time\": time.time(),\n \"response_length\": 0, # calculating this for an xmlrpc.client response would be too hard\n \"response\": None,\n \"context\": {}, # see HttpUser if you actually want to implement contexts\n \"exception\": None,\n }\n start_perf_counter = time.perf_counter()\n try:\n request_meta[\"response\"] = func(*args, **kwargs)\n except Fault as e:\n request_meta[\"exception\"] = e\n request_meta[\"response_time\"] = (time.perf_counter() - start_perf_counter) * 1000\n self._request_event.fire(**request_meta) # This is what makes the request actually get logged in Locust\n return request_meta[\"response\"]\n\n return wrapper\n\n\nclass XmlRpcUser(User):\n \"\"\"\n A minimal Locust user class that provides an XmlRpcClient to its subclasses\n \"\"\"\n\n abstract = True # dont instantiate this as an actual user when running Locust\n\n def __init__(self, environment):\n super().__init__(environment)\n self.client = XmlRpcClient(self.host, request_event=environment.events.request)\n\n\n# The real user class that will be instantiated and run by Locust\n# This is the only thing that is actually specific to the service that we are testing.\nclass MyUser(XmlRpcUser):\n host = \"http://127.0.0.1:8877/\"\n\n @task\n def get_time(self):\n self.client.get_time()\n\n @task\n def get_random_number(self):\n self.client.get_random_number(0, 100)\n" }, { "path": "examples/debugging.py", "content": "from locust import HttpUser, run_single_user, task\n\n\nclass QuickstartUser(HttpUser):\n host = \"http://localhost\"\n\n @task\n def hello_world(self):\n with self.client.get(\"/hello\", catch_response=True) as resp:\n pass # maybe set a breakpoint here to analyze the resp object?\n\n\n# if launched directly, e.g. \"python3 debugging.py\", not \"locust -f debugging.py\"\nif __name__ == \"__main__\":\n run_single_user(QuickstartUser)\n" }, { "path": "examples/debugging_advanced.py", "content": "from locust import HttpUser, run_single_user, task\nfrom locust.exception import StopUser\n\n\nclass User1(HttpUser):\n host = \"http://localhost\"\n\n @task\n def hello_world(self):\n with self.client.get(\"/hello1\", catch_response=True) as resp:\n pass\n raise StopUser()\n\n\nclass User2(HttpUser):\n host = \"http://localhost\"\n\n @task\n def hello_world(self):\n with self.client.get(\"/hello2\", catch_response=True) as resp:\n pass\n raise StopUser()\n\n\nif __name__ == \"__main__\":\n print(\"running User1\")\n run_single_user(User1)\n print(\"running User2\")\n run_single_user(User2)\n print(\"done!\")\n" }, { "path": "examples/dispatch_test_scripts/locustfile.py", "content": "from locust import HttpUser, LoadTestShape, constant, task\n\n\nclass UserA(HttpUser):\n wait_time = constant(600)\n\n # host = \"https://example.com\"\n\n @task\n def get_root(self):\n self.client.get(\"/\", name=\"UserA\")\n\n\nclass UserB(HttpUser):\n wait_time = constant(600)\n\n # host = \"https://example.com\"\n\n @task\n def get_root(self):\n self.client.get(\"/\", name=\"UserB\")\n\n\nclass UserC(HttpUser):\n wait_time = constant(600)\n\n # host = \"https://example.com\"\n\n @task\n def get_root(self):\n self.client.get(\"/\", name=\"UserC\")\n\n\n# class StepLoadShape(LoadTestShape):\n# step_time = 30\n# step_load = 10\n# spawn_rate = 1\n# time_limit = 300\n#\n# def tick(self):\n# run_time = self.get_run_time()\n#\n# if run_time > self.time_limit:\n# return None\n#\n# current_step = math.floor(run_time / self.step_time) + 1\n# return current_step * self.step_load, self.spawn_rate\n\n\nclass RampUpThenDownLoadShape(LoadTestShape):\n stages = [\n {\"duration\": 5, \"users\": 1, \"spawn_rate\": 1},\n {\"duration\": 35, \"users\": 30, \"spawn_rate\": 1},\n {\"duration\": 35, \"users\": 1, \"spawn_rate\": 1},\n {\"duration\": 35, \"users\": 73, \"spawn_rate\": 6},\n {\"duration\": 35, \"users\": 1, \"spawn_rate\": 6},\n {\"duration\": 35, \"users\": 153, \"spawn_rate\": 17},\n {\"duration\": 10, \"users\": 145, \"spawn_rate\": 1},\n {\"duration\": 60, \"users\": 130, \"spawn_rate\": 0.25},\n {\"duration\": 15, \"users\": 50, \"spawn_rate\": 25},\n {\"duration\": 20, \"users\": 1, \"spawn_rate\": 5},\n ]\n\n for previous_stage, stage in zip(stages[:-1], stages[1:]):\n stage[\"duration\"] += previous_stage[\"duration\"]\n\n for previous_stage, stage in zip(stages[:-1], stages[1:]):\n assert stage[\"duration\"] > previous_stage[\"duration\"]\n\n def tick(self):\n run_time = self.get_run_time()\n\n for stage in self.stages:\n if run_time < stage[\"duration\"]:\n tick_data = (stage[\"users\"], stage[\"spawn_rate\"])\n return tick_data\n\n return None\n" }, { "path": "examples/dispatch_test_scripts/run-disributed-headless.sh", "content": "#!/usr/bin/env bash\n\nset -o errexit\nset -o pipefail\nset -o nounset\n\nscript_dir=\"$(realpath \"$( cd \"$( dirname \"${BASH_SOURCE[0]}\" )\" >/dev/null 2>&1 && pwd )\")\"\nroot_dir=\"$(realpath \"${script_dir}/..\")\"\n\npushd \"${root_dir}\"\n\"${VIRTUAL_ENV}/bin/pip\" install --editable .\npopd\n\npushd \"${script_dir}\"\n\npids=()\n\nfunction cleanup(){\n for pid in ${pids}\n do\n echo \"Killing worker with pid ${pid}\"\n kill -9 \"${pid}\" || echo \"Failed killing worker with pid ${pid}\"\n done\n}\n\ntrap cleanup EXIT\n\nexport LOCUST_WORKER_ADDITIONAL_WAIT_BEFORE_READY_AFTER_STOP=5\n\nn_workers=4\n\nfor n in $(seq 1 ${n_workers})\ndo\n tmp_file=\"$(mktemp /tmp/locust-worker-${n}.log.XXXXXX)\"\n echo \"Starting worker ${n} (logs in ${tmp_file})\"\n \"${VIRTUAL_ENV}/bin/python\" -m locust \\\n --locustfile \"${script_dir}/locustfile.py\" \\\n --host \"https://example.com\" \\\n --worker \\\n --master-host \"0.0.0.0\" \\\n --master-port \"5557\" \\\n --logfile \"${tmp_file}\" \\\n --loglevel \"DEBUG\" &\n pids+=($!)\ndone\n\necho \"Starting master\"\n\"${VIRTUAL_ENV}/bin/python\" -m locust \\\n --locustfile \"${script_dir}/locustfile.py\" \\\n --host \"https://example.com\" \\\n --headless \\\n --master \\\n --master-bind-host \"0.0.0.0\" \\\n --master-bind-port \"5557\" \\\n --expect-workers ${n_workers} \\\n --loglevel \"DEBUG\"\n\npopd\n" }, { "path": "examples/dispatch_test_scripts/run-disributed-web.sh", "content": "#!/usr/bin/env bash\n\nset -o errexit\nset -o pipefail\nset -o nounset\n\nscript_dir=\"$(realpath \"$( cd \"$( dirname \"${BASH_SOURCE[0]}\" )\" >/dev/null 2>&1 && pwd )\")\"\nroot_dir=\"$(realpath \"${script_dir}/..\")\"\n\npushd \"${root_dir}\"\n\"${VIRTUAL_ENV}/bin/pip\" install --editable .\npopd\n\npushd \"${script_dir}\"\n\npids=()\n\nfunction cleanup(){\n for pid in ${pids}\n do\n echo \"Killing worker with pid ${pid}\"\n kill -9 \"${pid}\" || echo \"Failed killing worker with pid ${pid}\"\n done\n}\n\ntrap cleanup EXIT\n\nexport LOCUST_WORKER_ADDITIONAL_WAIT_BEFORE_READY_AFTER_STOP=5\n\nn_workers=13\n\nfor n in $(seq 1 ${n_workers})\ndo\n tmp_file=\"$(mktemp /tmp/locust-worker-${n}.log.XXXXXX)\"\n echo \"Starting worker ${n} (logs in ${tmp_file})\"\n \"${VIRTUAL_ENV}/bin/python\" -m locust \\\n --locustfile \"${script_dir}/locustfile.py\" \\\n --host \"https://example.com\" \\\n --worker \\\n --master-host \"0.0.0.0\" \\\n --master-port \"5557\" \\\n --logfile \"${tmp_file}\" \\\n --loglevel \"DEBUG\" &\n pids+=($!)\ndone\n\necho \"Starting master\"\n\"${VIRTUAL_ENV}/bin/python\" -m locust \\\n --locustfile \"${script_dir}/locustfile.py\" \\\n --host \"https://example.com\" \\\n --master \\\n --master-bind-host \"0.0.0.0\" \\\n --master-bind-port \"5557\" \\\n --expect-workers ${n_workers} \\\n --loglevel \"DEBUG\"\n\npopd\n" }, { "path": "examples/dispatch_test_scripts/run-local-headless.sh", "content": "#!/usr/bin/env bash\n\nset -o errexit\nset -o pipefail\nset -o nounset\n\nscript_dir=\"$(realpath \"$( cd \"$( dirname \"${BASH_SOURCE[0]}\" )\" >/dev/null 2>&1 && pwd )\")\"\nroot_dir=\"$(realpath \"${script_dir}/..\")\"\n\npushd \"${root_dir}\"\n\"${VIRTUAL_ENV}/bin/pip\" install --editable .\npopd\n\npushd \"${script_dir}\"\n\"${VIRTUAL_ENV}/bin/python\" -m locust \\\n --locustfile \"${script_dir}/locustfile.py\" \\\n --headless \\\n --host \"https://example.com\" \\\n --loglevel \"INFO\"\npopd\n" }, { "path": "examples/dispatch_test_scripts/run-local-web.sh", "content": "#!/usr/bin/env bash\n\nset -o errexit\nset -o pipefail\nset -o nounset\n\nscript_dir=\"$(realpath \"$( cd \"$( dirname \"${BASH_SOURCE[0]}\" )\" >/dev/null 2>&1 && pwd )\")\"\nroot_dir=\"$(realpath \"${script_dir}/..\")\"\n\npushd \"${root_dir}\"\n\"${VIRTUAL_ENV}/bin/pip\" install --editable .\npopd\n\npushd \"${script_dir}\"\n\"${VIRTUAL_ENV}/bin/python\" -m locust \\\n --locustfile \"${script_dir}/locustfile.py\" \\\n --host \"https://example.com\" \\\n --loglevel \"DEBUG\"\npopd\n" }, { "path": "examples/dns_ex.py", "content": "from locust import run_single_user, task\nfrom locust.contrib.dns import DNSUser\n\nimport time\n\nimport dns.message\nimport dns.rdatatype\n\n\nclass MyDNSUser(DNSUser):\n @task\n def t(self):\n message = dns.message.make_query(\"example.com\", dns.rdatatype.A)\n # self.client wraps all dns.query methods https://dnspython.readthedocs.io/en/stable/query.html\n self.client.udp(message, \"8.8.8.8\")\n self.client.tcp(message, \"1.1.1.1\")\n self.client.udp(\n dns.message.make_query(\"doesnot-exist-1234234.com\", dns.rdatatype.A),\n \"1.1.1.1\",\n name=\"You can rename requests\",\n )\n # don't spam other people's DNS servers\n time.sleep(10)\n\n\nif __name__ == \"__main__\":\n run_single_user(MyDNSUser)\n" }, { "path": "examples/docker-compose/docker-compose.yml", "content": "version: '3'\n\nservices:\n master:\n image: locustio/locust\n ports:\n - \"8089:8089\"\n volumes:\n - ./:/mnt/locust\n command: -f /mnt/locust/locustfile.py --master -H http://master:8089\n \n worker:\n image: locustio/locust\n volumes:\n - ./:/mnt/locust\n command: -f /mnt/locust/locustfile.py --worker --master-host master\n" }, { "path": "examples/dynamic_user_credentials.py", "content": "# locustfile.py\n\nfrom locust import HttpUser, TaskSet, between, task\n\nUSER_CREDENTIALS = [\n (\"user1\", \"password\"),\n (\"user2\", \"password\"),\n (\"user3\", \"password\"),\n]\n\n\nclass UserBehaviour(TaskSet):\n def on_start(self):\n if len(USER_CREDENTIALS) > 0:\n user, passw = USER_CREDENTIALS.pop()\n self.client.post(\"/login\", {\"username\": user, \"password\": passw})\n\n @task\n def some_task(self):\n # user should be logged in here (unless the USER_CREDENTIALS ran out)\n self.client.get(\"/protected/resource\")\n\n\nclass User(HttpUser):\n tasks = [UserBehaviour]\n wait_time = between(5, 60)\n" }, { "path": "examples/events.py", "content": "\"\"\"\nThis is an example of a locustfile that uses Locust's built in event hooks to\ntrack the sum of the content-length header in all successful HTTP responses\n\"\"\"\n\nfrom locust import HttpUser, TaskSet, between, events, task\n\n\nclass MyTaskSet(TaskSet):\n @task(2)\n def index(l):\n l.client.get(\"/\")\n\n @task(1)\n def stats(l):\n l.client.get(\"/stats/requests\")\n\n\nclass WebsiteUser(HttpUser):\n host = \"http://127.0.0.1:8089\"\n wait_time = between(2, 5)\n tasks = [MyTaskSet]\n\n\nstats = {\"content-length\": 0}\n\n\n@events.init.add_listener\ndef locust_init(environment, **kwargs):\n \"\"\"\n We need somewhere to store the stats.\n\n On the master node stats will contain the aggregated sum of all content-lengths,\n while on the worker nodes this will be the sum of the content-lengths since the\n last stats report was sent to the master\n \"\"\"\n if environment.web_ui:\n # this code is only run on the master node (the web_ui instance doesn't exist on workers)\n @environment.web_ui.app.route(\"/content-length\")\n def total_content_length():\n \"\"\"\n Add a route to the Locust web app, where we can see the total content-length\n \"\"\"\n return \"Total content-length received: %i\" % stats[\"content-length\"]\n\n\n@events.request.add_listener\ndef on_request(request_type, name, response_time, response_length, exception, context, **kwargs):\n \"\"\"\n Event handler that get triggered on every request.\n \"\"\"\n stats[\"content-length\"] += response_length\n\n\n@events.report_to_master.add_listener\ndef on_report_to_master(client_id, data):\n \"\"\"\n This event is triggered on the worker instances every time a stats report is\n to be sent to the locust master. It will allow us to add our extra content-length\n data to the dict that is being sent, and then we clear the local stats in the worker.\n \"\"\"\n data[\"content-length\"] = stats[\"content-length\"]\n stats[\"content-length\"] = 0\n\n\n@events.worker_report.add_listener\ndef on_worker_report(client_id, data):\n \"\"\"\n This event is triggered on the master instance when a new stats report arrives\n from a worker. Here we just add the content-length to the master's aggregated\n stats dict.\n \"\"\"\n stats[\"content-length\"] += data[\"content-length\"]\n" }, { "path": "examples/extend_web_ui.py", "content": "\"\"\"\nThis is an example of a locustfile that uses Locust's built in event and web\nUI extension hooks to track the sum of the content-length header in all\nsuccessful HTTP responses and display them in the web UI.\n\"\"\"\n\nfrom locust import HttpUser, TaskSet, between, events, task\n\nimport json\nimport os\nfrom time import time\n\nfrom flask import Blueprint, make_response, render_template, request\n\n\nclass MyTaskSet(TaskSet):\n @task(2)\n def index(l):\n l.client.get(\"/\")\n\n @task(1)\n def stats(l):\n l.client.get(\"/stats/requests\")\n\n\nclass WebsiteUser(HttpUser):\n host = \"http://127.0.0.1:8089\"\n wait_time = between(2, 5)\n tasks = [MyTaskSet]\n\n\nstats = {}\npath = os.path.dirname(os.path.abspath(__file__))\nextend = Blueprint(\n \"extend\",\n \"extend_web_ui\",\n static_folder=f\"{path}/static/\",\n static_url_path=\"/extend/static/\",\n template_folder=f\"{path}/templates/\",\n)\n\n\n@events.init.add_listener\ndef locust_init(environment, **kwargs):\n \"\"\"\n We need somewhere to store the stats.\n\n On the master node stats will contain the aggregated sum of all content-lengths,\n while on the worker nodes this will be the sum of the content-lengths since the\n last stats report was sent to the master\n \"\"\"\n if environment.web_ui:\n\n def get_content_length_stats():\n \"\"\"\n This is used by the Content Length tab in the\n extended web UI to show the stats.\n \"\"\"\n if stats:\n stats_tmp = []\n\n for name, inner_stats in stats.items():\n content_length = inner_stats[\"content-length\"]\n\n stats_tmp.append({\"name\": name, \"content_length\": content_length})\n\n # Truncate the total number of stats and errors displayed since a large number of rows will cause the app\n # to render extremely slowly.\n return stats_tmp[:500]\n return stats\n\n @environment.web_ui.app.after_request\n def extend_stats_response(response):\n if request.path != \"/stats/requests\":\n return response\n\n response.set_data(\n json.dumps(\n {**response.json, \"extended_stats\": [{\"key\": \"content-length\", \"data\": get_content_length_stats()}]}\n )\n )\n\n return response\n\n @extend.route(\"/extend\")\n def extend_web_ui():\n \"\"\"\n Add route to access the extended web UI with our new tab.\n \"\"\"\n # ensure the template_args are up to date before using them\n environment.web_ui.update_template_args()\n\n return render_template(\n \"index.html\",\n template_args={\n **environment.web_ui.template_args,\n \"extended_tabs\": [{\"title\": \"Content Length\", \"key\": \"content-length\"}],\n \"extended_tables\": [\n {\n \"key\": \"content-length\",\n \"structure\": [\n {\"key\": \"name\", \"title\": \"Name\"},\n {\"key\": \"content_length\", \"title\": \"Total content length\"},\n ],\n }\n ],\n \"extended_csv_files\": [\n {\"href\": \"/content-length/csv\", \"title\": \"Download content length statistics CSV\"}\n ],\n },\n )\n\n @extend.route(\"/content-length/csv\")\n def request_content_length_csv():\n \"\"\"\n Add route to enable downloading of content-length stats as CSV\n \"\"\"\n response = make_response(content_length_csv())\n file_name = f\"content_length{time()}.csv\"\n disposition = f\"attachment;filename={file_name}\"\n response.headers[\"Content-type\"] = \"text/csv\"\n response.headers[\"Content-disposition\"] = disposition\n return response\n\n def content_length_csv():\n \"\"\"Returns the content-length stats as CSV.\"\"\"\n rows = [\n \",\".join(\n [\n '\"Name\"',\n '\"Total content-length\"',\n ]\n )\n ]\n\n if stats:\n for url, inner_stats in stats.items():\n rows.append(f'\"{url}\",{inner_stats[\"content-length\"]:.2f}')\n return \"\\n\".join(rows)\n\n # register our new routes and extended UI with the Locust web UI\n environment.web_ui.app.register_blueprint(extend)\n\n\n@events.request.add_listener\ndef on_request(request_type, name, response_time, response_length, exception, context, **kwargs):\n \"\"\"\n Event handler that get triggered on every request\n \"\"\"\n stats.setdefault(name, {\"content-length\": 0})\n stats[name][\"content-length\"] += response_length\n\n\n@events.reset_stats.add_listener\ndef on_reset_stats():\n \"\"\"\n Event handler that get triggered on click of web UI Reset Stats button\n \"\"\"\n global stats\n stats = {}\n" }, { "path": "examples/fast_http_locust.py", "content": "from locust import FastHttpUser, task\n\n\nclass WebsiteUser(FastHttpUser):\n \"\"\"\n User class that does requests to the locust web server running on localhost,\n using the fast HTTP client\n \"\"\"\n\n host = \"http://127.0.0.1:8089\"\n # some things you can configure on FastHttpUser\n # connection_timeout = 60.0\n # insecure = True\n # max_redirects = 5\n # max_retries = 1\n # network_timeout = 60.0\n # proxy_host = my-proxy.com\n # proxy_port = 8080\n\n @task\n def index(self):\n self.client.get(\"/\")\n\n @task\n def stats(self):\n self.client.get(\"/stats/requests\")\n" }, { "path": "examples/grpc/grpc_user.py", "content": "from locust import User\nfrom locust.exception import LocustError\n\nimport time\nfrom collections.abc import Callable\nfrom typing import Any\n\nimport grpc\nimport grpc.experimental.gevent as grpc_gevent\nfrom grpc_interceptor import ClientInterceptor\n\n# patch grpc so that it uses gevent instead of asyncio\ngrpc_gevent.init_gevent()\n\n\nclass LocustInterceptor(ClientInterceptor):\n def __init__(self, environment, *args, **kwargs):\n super().__init__(*args, **kwargs)\n\n self.env = environment\n\n def intercept(\n self,\n method: Callable,\n request_or_iterator: Any,\n call_details: grpc.ClientCallDetails,\n ):\n response = None\n exception = None\n start_perf_counter = time.perf_counter()\n response_length = 0\n try:\n response = method(request_or_iterator, call_details)\n response_length = response.result().ByteSize()\n except grpc.RpcError as e:\n exception = e\n\n self.env.events.request.fire(\n request_type=\"grpc\",\n name=call_details.method,\n response_time=(time.perf_counter() - start_perf_counter) * 1000,\n response_length=response_length,\n response=response,\n context=None,\n exception=exception,\n )\n return response\n\n\nclass GrpcUser(User):\n abstract = True\n stub_class = None\n\n def __init__(self, environment):\n super().__init__(environment)\n for attr_value, attr_name in ((self.host, \"host\"), (self.stub_class, \"stub_class\")):\n if attr_value is None:\n raise LocustError(f\"You must specify the {attr_name}.\")\n\n self._channel = grpc.insecure_channel(self.host)\n interceptor = LocustInterceptor(environment=environment)\n self._channel = grpc.intercept_channel(self._channel, interceptor)\n\n self.stub = self.stub_class(self._channel)\n" }, { "path": "examples/grpc/hello.proto", "content": "syntax = \"proto3\";\n\npackage locust.hello;\n\nservice HelloService {\n rpc SayHello (HelloRequest) returns (HelloResponse) {}\n}\n\nmessage HelloRequest {\n string name = 1;\n}\n\nmessage HelloResponse {\n string message = 1;\n}\n" }, { "path": "examples/grpc/hello_pb2.py", "content": "# Generated by the protocol buffer compiler. DO NOT EDIT!\n# source: hello.proto\n\"\"\"Generated protocol buffer code.\"\"\"\n\nfrom google.protobuf import descriptor as _descriptor\nfrom google.protobuf import message as _message\nfrom google.protobuf import reflection as _reflection\nfrom google.protobuf import symbol_database as _symbol_database\n\n# @@protoc_insertion_point(imports)\n\n_sym_db = _symbol_database.Default()\n\n\nDESCRIPTOR = _descriptor.FileDescriptor(\n name=\"hello.proto\",\n package=\"locust.hello\",\n syntax=\"proto3\",\n serialized_options=None,\n create_key=_descriptor._internal_create_key,\n serialized_pb=b'\\n\\x0bhello.proto\\x12\\x0clocust.hello\"\\x1c\\n\\x0cHelloRequest\\x12\\x0c\\n\\x04name\\x18\\x01 \\x01(\\t\" \\n\\rHelloResponse\\x12\\x0f\\n\\x07message\\x18\\x01 \\x01(\\t2U\\n\\x0cHelloService\\x12\\x45\\n\\x08SayHello\\x12\\x1a.locust.hello.HelloRequest\\x1a\\x1b.locust.hello.HelloResponse\"\\x00\\x62\\x06proto3',\n)\n\n\n_HELLOREQUEST = _descriptor.Descriptor(\n name=\"HelloRequest\",\n full_name=\"locust.hello.HelloRequest\",\n filename=None,\n file=DESCRIPTOR,\n containing_type=None,\n create_key=_descriptor._internal_create_key,\n fields=[\n _descriptor.FieldDescriptor(\n name=\"name\",\n full_name=\"locust.hello.HelloRequest.name\",\n index=0,\n number=1,\n type=9,\n cpp_type=9,\n label=1,\n has_default_value=False,\n default_value=b\"\".decode(\"utf-8\"),\n message_type=None,\n enum_type=None,\n containing_type=None,\n is_extension=False,\n extension_scope=None,\n serialized_options=None,\n file=DESCRIPTOR,\n create_key=_descriptor._internal_create_key,\n ),\n ],\n extensions=[],\n nested_types=[],\n enum_types=[],\n serialized_options=None,\n is_extendable=False,\n syntax=\"proto3\",\n extension_ranges=[],\n oneofs=[],\n serialized_start=29,\n serialized_end=57,\n)\n\n\n_HELLORESPONSE = _descriptor.Descriptor(\n name=\"HelloResponse\",\n full_name=\"locust.hello.HelloResponse\",\n filename=None,\n file=DESCRIPTOR,\n containing_type=None,\n create_key=_descriptor._internal_create_key,\n fields=[\n _descriptor.FieldDescriptor(\n name=\"message\",\n full_name=\"locust.hello.HelloResponse.message\",\n index=0,\n number=1,\n type=9,\n cpp_type=9,\n label=1,\n has_default_value=False,\n default_value=b\"\".decode(\"utf-8\"),\n message_type=None,\n enum_type=None,\n containing_type=None,\n is_extension=False,\n extension_scope=None,\n serialized_options=None,\n file=DESCRIPTOR,\n create_key=_descriptor._internal_create_key,\n ),\n ],\n extensions=[],\n nested_types=[],\n enum_types=[],\n serialized_options=None,\n is_extendable=False,\n syntax=\"proto3\",\n extension_ranges=[],\n oneofs=[],\n serialized_start=59,\n serialized_end=91,\n)\n\nDESCRIPTOR.message_types_by_name[\"HelloRequest\"] = _HELLOREQUEST\nDESCRIPTOR.message_types_by_name[\"HelloResponse\"] = _HELLORESPONSE\n_sym_db.RegisterFileDescriptor(DESCRIPTOR)\n\nHelloRequest = _reflection.GeneratedProtocolMessageType(\n \"HelloRequest\",\n (_message.Message,),\n {\n \"DESCRIPTOR\": _HELLOREQUEST,\n \"__module__\": \"hello_pb2\",\n # @@protoc_insertion_point(class_scope:locust.hello.HelloRequest)\n },\n)\n_sym_db.RegisterMessage(HelloRequest)\n\nHelloResponse = _reflection.GeneratedProtocolMessageType(\n \"HelloResponse\",\n (_message.Message,),\n {\n \"DESCRIPTOR\": _HELLORESPONSE,\n \"__module__\": \"hello_pb2\",\n # @@protoc_insertion_point(class_scope:locust.hello.HelloResponse)\n },\n)\n_sym_db.RegisterMessage(HelloResponse)\n\n\n_HELLOSERVICE = _descriptor.ServiceDescriptor(\n name=\"HelloService\",\n full_name=\"locust.hello.HelloService\",\n file=DESCRIPTOR,\n index=0,\n serialized_options=None,\n create_key=_descriptor._internal_create_key,\n serialized_start=93,\n serialized_end=178,\n methods=[\n _descriptor.MethodDescriptor(\n name=\"SayHello\",\n full_name=\"locust.hello.HelloService.SayHello\",\n index=0,\n containing_service=None,\n input_type=_HELLOREQUEST,\n output_type=_HELLORESPONSE,\n serialized_options=None,\n create_key=_descriptor._internal_create_key,\n ),\n ],\n)\n_sym_db.RegisterServiceDescriptor(_HELLOSERVICE)\n\nDESCRIPTOR.services_by_name[\"HelloService\"] = _HELLOSERVICE\n\n# @@protoc_insertion_point(module_scope)\n" }, { "path": "examples/grpc/hello_pb2_grpc.py", "content": "# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!\n\"\"\"Client and server classes corresponding to protobuf-defined services.\"\"\"\n\nimport grpc\nimport hello_pb2 as hello__pb2\n\n\nclass HelloServiceStub:\n \"\"\"Missing associated documentation comment in .proto file.\"\"\"\n\n def __init__(self, channel):\n \"\"\"Constructor.\n\n Args:\n channel: A grpc.Channel.\n \"\"\"\n self.SayHello = channel.unary_unary(\n \"/locust.hello.HelloService/SayHello\",\n request_serializer=hello__pb2.HelloRequest.SerializeToString,\n response_deserializer=hello__pb2.HelloResponse.FromString,\n )\n\n\nclass HelloServiceServicer:\n \"\"\"Missing associated documentation comment in .proto file.\"\"\"\n\n def SayHello(self, request, context):\n \"\"\"Missing associated documentation comment in .proto file.\"\"\"\n context.set_code(grpc.StatusCode.UNIMPLEMENTED)\n context.set_details(\"Method not implemented!\")\n raise NotImplementedError(\"Method not implemented!\")\n\n\ndef add_HelloServiceServicer_to_server(servicer, server):\n rpc_method_handlers = {\n \"SayHello\": grpc.unary_unary_rpc_method_handler(\n servicer.SayHello,\n request_deserializer=hello__pb2.HelloRequest.FromString,\n response_serializer=hello__pb2.HelloResponse.SerializeToString,\n ),\n }\n generic_handler = grpc.method_handlers_generic_handler(\"locust.hello.HelloService\", rpc_method_handlers)\n server.add_generic_rpc_handlers((generic_handler,))\n\n\n# This class is part of an EXPERIMENTAL API.\nclass HelloService:\n \"\"\"Missing associated documentation comment in .proto file.\"\"\"\n\n @staticmethod\n def SayHello(\n request,\n target,\n options=(),\n channel_credentials=None,\n call_credentials=None,\n insecure=False,\n compression=None,\n wait_for_ready=None,\n timeout=None,\n metadata=None,\n ):\n return grpc.experimental.unary_unary(\n request,\n target,\n \"/locust.hello.HelloService/SayHello\",\n hello__pb2.HelloRequest.SerializeToString,\n hello__pb2.HelloResponse.FromString,\n options,\n channel_credentials,\n insecure,\n call_credentials,\n compression,\n wait_for_ready,\n timeout,\n metadata,\n )\n" }, { "path": "examples/grpc/hello_server.py", "content": "import logging\nimport time\nfrom concurrent import futures\n\nimport grpc\nimport hello_pb2\nimport hello_pb2_grpc\n\nlogger = logging.getLogger(__name__)\n\n\nclass HelloServiceServicer(hello_pb2_grpc.HelloServiceServicer):\n def SayHello(self, request, context):\n name = request.name\n time.sleep(1)\n return hello_pb2.HelloResponse(message=f\"Hello from Locust, {name}!\")\n\n\ndef start_server():\n server = grpc.server(futures.ThreadPoolExecutor(max_workers=100))\n hello_pb2_grpc.add_HelloServiceServicer_to_server(HelloServiceServicer(), server)\n server.add_insecure_port(\"localhost:50051\")\n server.start()\n logger.info(\"gRPC server started\")\n server.wait_for_termination()\n\n\nif __name__ == \"__main__\":\n start_server()\n" }, { "path": "examples/grpc/locustfile.py", "content": "from locust import events, task\n\nimport gevent\nimport grpc_user\nimport hello_pb2\nimport hello_pb2_grpc\nfrom hello_server import start_server\n\n\n# Start the dummy server. This is not something you would do in a real test.\n@events.init.add_listener\ndef run_grpc_server(environment, **_kwargs):\n gevent.spawn(start_server)\n\n\nclass HelloGrpcUser(grpc_user.GrpcUser):\n host = \"localhost:50051\"\n stub_class = hello_pb2_grpc.HelloServiceStub\n\n @task\n def sayHello(self):\n self.stub.SayHello(hello_pb2.HelloRequest(name=\"Test\"))\n" }, { "path": "examples/locustfile.py", "content": "from locust import HttpUser, between, task\n\nimport time\n\n\nclass QuickstartUser(HttpUser):\n wait_time = between(1, 2)\n\n @task\n def hello_world(self):\n self.client.get(\"/hello\")\n self.client.get(\"/world\")\n\n @task(3)\n def view_item(self):\n for item_id in range(10):\n self.client.get(f\"/item?id={item_id}\", name=\"/item\")\n time.sleep(1)\n\n def on_start(self):\n self.client.post(\"/login\", json={\"username\": \"foo\", \"password\": \"bar\"})\n" }, { "path": "examples/manual_stats_reporting.py", "content": "\"\"\"\nExample of a manual_report() function that can be used either as a context manager\n(with statement), or a decorator, to manually add entries to Locust's statistics.\n\nUsage as a context manager:\n\n with manual_report(\"stats entry name\"):\n # Run time of this block will be reported under a stats entry called \"stats entry name\"\n # do stuff here, if an Exception is raised, it'll be reported as a failure\n\nUsage as a decorator:\n\n @task\n @manual_report\n def my_task(self):\n # The run time of this task will be reported under a stats entry called \"my task\" (type \"manual\").\n # If an Exception is raised, it'll be reported as a failure\n\"\"\"\n\nfrom locust import User, constant, events, task\n\nimport random\nfrom contextlib import contextmanager\nfrom time import sleep, time\n\n\n@contextmanager\ndef _manual_report(name):\n start_time = time()\n try:\n yield\n except Exception as e:\n events.request.fire(\n request_type=\"manual\",\n name=name,\n response_time=(time() - start_time) * 1000,\n response_length=0,\n exception=e,\n )\n raise\n else:\n events.request.fire(\n request_type=\"manual\",\n name=name,\n response_time=(time() - start_time) * 1000,\n response_length=0,\n exception=None,\n )\n\n\ndef manual_report(name_or_func):\n if callable(name_or_func):\n # used as decorator without name argument specified\n return _manual_report(name_or_func.__name__)(name_or_func)\n else:\n return _manual_report(name_or_func)\n\n\nclass MyUser(User):\n wait_time = constant(1)\n\n @task\n def successful_task(self):\n with manual_report(\"successful_task\"):\n sleep(random.random())\n\n @task\n @manual_report\n def decorator_test(self):\n if random.random() > 0.5:\n raise Exception(\"decorator_task failed\")\n sleep(random.random())\n\n @task\n def failing_task(self):\n with manual_report(\"failing_task\"):\n sleep(random.random())\n raise Exception(\"Oh nooes!\")\n" }, { "path": "examples/markov_taskset.py", "content": "from locust import MarkovTaskSet, User, constant, transition, transitions\n\n\"\"\"\nThis example demonstrates the different ways to specify transitions in a MarkovTaskSet.\n\nThe MarkovTaskSet class supports several ways to define transitions between tasks:\n1. Using @transition decorator for a single transition\n2. Stacking multiple @transition decorators\n3. Using @transitions with a dictionary of task names and weights\n4. Using @transitions with a list of task names (default weight 1)\n5. Using @transitions with a list of tuples (task_name, weight)\n6. Using @transitions with a mixed list of strings and tuples\n\"\"\"\n\n\nclass TransitionsExample(MarkovTaskSet):\n \"\"\"\n This MarkovTaskSet demonstrates all the different ways to specify transitions.\n \"\"\"\n\n @transition(\"method2\")\n def method1(self):\n print(\"Method 1: Using a single @transition decorator\")\n print(\" Next: Will transition to method2\")\n\n @transition(\"method3\", weight=2)\n @transition(\"method1\")\n def method2(self):\n print(\"Method 2: Using multiple stacked @transition decorators\")\n print(\" Next: Will transition to method3 (weight 2) or method1 (weight 1)\")\n\n @transitions({\"method4\": 3, \"method2\": 1, \"method1\": 1})\n def method3(self):\n print(\"Method 3: Using @transitions with a dictionary\")\n print(\" Next: Will transition to method4 (weight 3), method2 (weight 1), or method1 (weight 1)\")\n\n @transitions([\"method5\", \"method3\"])\n def method4(self):\n print(\"Method 4: Using @transitions with a list of task names\")\n print(\" Next: Will transition to method5 or method3 with equal probability (weight 1 each)\")\n\n @transitions([(\"method6\", 4), (\"method4\", 1)])\n def method5(self):\n print(\"Method 5: Using @transitions with a list of tuples\")\n print(\" Next: Will transition to method6 (weight 4) or method4 (weight 1)\")\n\n @transitions([(\"method1\", 2), \"method5\"])\n def method6(self):\n print(\"Method 6: Using @transitions with a mixed list\")\n print(\" Next: Will transition to method1 (weight 2) or method5 (weight 1)\")\n\n\nclass TransitionsUser(User):\n tasks = [TransitionsExample]\n wait_time = constant(1)\n\n\nif __name__ == \"__main__\":\n from locust import run_single_user\n\n run_single_user(TransitionsUser)\n" }, { "path": "examples/milvus/README.md", "content": "# Milvus Load Testing with Locust\n\nSimple example demonstrating load testing for Milvus vector database operations.\n\n## Prerequisites\n\nInstall Locust with Milvus support:\n\n```bash\n# Using pip\npip install locust[milvus]\n\n# Using uv\nuv add locust[milvus]\n# or\nuv sync --extra milvus\n```\n\nThis installs the required dependencies:\n- [`pymilvus`](https://github.com/milvus-io/pymilvus) - Official Milvus Python SDK (>=2.5.0)\n\n## Usage\n\n```bash\n# Run with web UI\nlocust -f locustfile.py --host=http://localhost:19530\n\n# Run headless\nlocust -f locustfile.py --host=http://localhost:19530 --headless --users=10 --spawn-rate=2 --run-time=60s\n```\n\n## Operations Tested\n\n- Insert vectors\n- Search vectors\n- Query by filter\n- Delete records\n\nFor more advanced usage, see the [Locust documentation](https://docs.locust.io/).\n\n\n\n" }, { "path": "examples/milvus/locustfile.py", "content": "\"\"\"\nMinimal example demonstrating Milvus load testing with Locust.\n\"\"\"\n\nfrom locust import between, task\nfrom locust.contrib.milvus import MilvusUser\n\nimport random\n\nfrom pymilvus import CollectionSchema, DataType, FieldSchema\nfrom pymilvus.milvus_client import IndexParams\n\n\nclass SimpleMilvusUser(MilvusUser):\n \"\"\"Minimal Milvus user for load testing.\"\"\"\n\n wait_time = between(1, 3)\n\n def on_start(self):\n \"\"\"Generate test vectors.\"\"\"\n self.dimension = 128\n self.test_vectors = [[random.random() for _ in range(self.dimension)] for _ in range(10)]\n\n def __init__(self, environment):\n # Define collection schema\n schema = CollectionSchema(\n fields=[\n FieldSchema(name=\"id\", dtype=DataType.INT64, is_primary=True),\n FieldSchema(name=\"vector\", dtype=DataType.FLOAT_VECTOR, dim=128),\n FieldSchema(name=\"name\", dtype=DataType.VARCHAR, max_length=50),\n ],\n description=\"Test collection\",\n )\n\n # Define index parameters\n index_params = IndexParams()\n index_params.add_index(\n field_name=\"vector\",\n index_type=\"IVF_FLAT\",\n metric_type=\"L2\",\n )\n\n super().__init__(\n environment,\n uri=environment.host,\n collection_name=\"load_test_collection\",\n schema=schema,\n index_params=index_params,\n enable_dynamic_field=True,\n num_shards=2,\n consistency_level=\"Eventually\",\n )\n\n @task(3)\n def insert_data(self):\n \"\"\"Insert data into Milvus.\"\"\"\n data = [\n {\n \"id\": random.randint(1, 10000),\n \"vector\": random.choice(self.test_vectors),\n \"name\": f\"item_{random.randint(1, 1000)}\",\n }\n ]\n self.insert(data)\n\n @task(5)\n def search_vectors(self):\n \"\"\"Search for similar vectors.\"\"\"\n search_vector = random.choice(self.test_vectors)\n self.search(data=[search_vector], anns_field=\"vector\", limit=5)\n\n @task(2)\n def query_data(self):\n \"\"\"Query data by ID.\"\"\"\n query_id = random.randint(1, 10000)\n self.query(filter=f\"id == {query_id}\")\n\n @task(1)\n def delete_data(self):\n \"\"\"Delete data.\"\"\"\n delete_id = random.randint(1, 10000)\n self.delete(filter=f\"id == {delete_id}\")\n" }, { "path": "examples/mongodb/README.md", "content": "# Overview\n\n### Prerequisites:\n\n- [`gevent`](https://www.gevent.org/install.html)\n - [For pymongo to use greenlets instead of standard threads](https://pymongo.readthedocs.io/en/stable/examples/gevent.html)\n- [`pymongo`](https://pymongo.readthedocs.io/en/stable/installation.html)\n\n### How to run the test:\n\n- Set your environment variables for:\n `MONGODB_URI`\n\n- Run locust as usual, see https://docs.locust.io/en/stable/quickstart.html\n\nNote:\n\n- It is recommended that you use the `--processes` parameter when running this test\n - see https://docs.locust.io/en/stable/running-distributed.html\n" }, { "path": "examples/mongodb/locustfile.py", "content": "from locust import task\nfrom locust.contrib.mongodb import MongoDBUser\n\nimport os\n\n\nclass MongoUser(MongoDBUser):\n conn_string = os.getenv(\"MONGODB_URI\", \"mongodb://localhost:27017/defaultdb\")\n db_name = \"test\" # change to your db name\n\n @task\n def db_query(self):\n self.client.execute_query(\"collection\", {\"field\": \"value\"}) # update to match your collection, field, and value\n" }, { "path": "examples/mqtt/README.md", "content": "# MQTT Load testing with Locust\n\n## Prerequisites\n\nHave access to a running mqtt broker.\n\n```bash\n# start mosquitto locally\n# the configuration file is required to start \n# WINDOWS\ndocker run -d -p 1883:1883 --name mqtt-broker -v .\\\\examples\\\\mqtt\\\\mosquitto_config\\\\mosquitto.conf:/mosquitto/config/mosquitto.conf eclipse-mosquitto:latest\n# UNIX\ndocker run -d -p 1883:1883 --name mqtt-broker -v ./examples/mqtt/mosquitto_config/mosquitto.conf:/mosquitto/config/mosquitto.conf eclipse-mosquitto:latest\n```\n\nInstall Locust with MQTT support:\n\n```bash\n# Using pip\npip install locust[mqtt]\n```\n\n## Usage\n\n```bash\n# Run simple example without web UI\nlocust -f examples/mqtt/locustfile.py --headless\n# Run simple custom client example without web UI\nlocust -f examples/mqtt/locustfile_custom_mqtt_client.py --headless\n```\n\n" }, { "path": "examples/mqtt/locustfile.py", "content": "from locust import task\nfrom locust.contrib.mqtt import MqttUser\nfrom locust.user.wait_time import between\n\nimport time\n\n\nclass MyUser(MqttUser):\n host = \"localhost\"\n port = 1883\n\n # We could uncomment below to use the WebSockets transport\n # transport = \"websockets\"\n\n # ws_path = \"/mqtt/custom/path\"\n\n # We'll probably want to throttle our publishing a bit: let's limit it to\n # 10-100 messages per second.\n wait_time = between(0.01, 0.1)\n\n # Uncomment below if you need to set MQTTv5\n # protocol = paho.mqtt.client.MQTTv5\n\n # Sleep for a while to allow the client time to connect.\n # This is probably not the most \"correct\" way to do this: a better method\n # might be to add a gevent.event.Event to the MqttClient's on_connect\n # callback and wait for that (with a timeout) here.\n # However, this works well enough for the sake of an example.\n def on_start(self):\n time.sleep(5)\n\n @task\n def say_hello(self):\n self.client.publish(\"hello/locust\", b\"hello world\")\n" }, { "path": "examples/mqtt/locustfile_custom_mqtt_client.py", "content": "from locust import task\nfrom locust.contrib.mqtt import MqttClient, MqttUser\nfrom locust.user.wait_time import between\n\nimport time\n\n\n# extend the MqttClient class with your own custom implementation\nclass MyMqttClient(MqttClient):\n # you can override the event name with your custom implementation\n def _generate_event_name(self, event_type: str, qos: int, topic: str):\n return f\"mqtt:{event_type}:{qos}\"\n\n\nclass MyUser(MqttUser):\n host = \"localhost\"\n port = 1883\n\n # We could uncomment below to use the WebSockets transport\n # transport = \"websockets\"\n\n # ws_path = \"/mqtt/custom/path\"\n\n # We'll probably want to throttle our publishing a bit: let's limit it to\n # 10-100 messages per second.\n wait_time = between(0.01, 0.1)\n\n # override the client_cls with your custom MqttClient implementation\n client_cls = MyMqttClient\n\n # Sleep for a while to allow the client time to connect.\n # This is probably not the most \"correct\" way to do this: a better method\n # might be to add a gevent.event.Event to the MqttClient's on_connect\n # callback and wait for that (with a timeout) here.\n # However, this works well enough for the sake of an example.\n def on_start(self):\n time.sleep(5)\n\n @task\n def say_hello(self):\n self.client.publish(\"hello/locust\", b\"hello world locust custom client\")\n" }, { "path": "examples/mqtt/mosquitto_config/mosquitto.conf", "content": "# mosquitto_config/mosquitto.conf\n\nlistener 1883\nallow_anonymous true" }, { "path": "examples/multiple_hosts.py", "content": "from locust import HttpUser, TaskSet, between, task\nfrom locust.clients import HttpSession\n\nimport os\n\n\nclass MultipleHostsUser(HttpUser):\n abstract = True\n\n def __init__(self, *args, **kwargs):\n super().__init__(*args, **kwargs)\n self.api_client = HttpSession(\n base_url=os.environ[\"API_HOST\"], request_event=self.client.request_event, user=self\n )\n\n\nclass UserTasks(TaskSet):\n # but it might be convenient to use the @task decorator\n @task\n def index(self):\n self.user.client.get(\"/\")\n\n @task\n def index_other_host(self):\n self.user.api_client.get(\"/stats/requests\")\n\n\nclass WebsiteUser(MultipleHostsUser):\n \"\"\"\n User class that does requests to the locust web server running on localhost\n \"\"\"\n\n host = \"http://127.0.0.1:8089\"\n wait_time = between(2, 5)\n tasks = [UserTasks]\n" }, { "path": "examples/nested_inline_tasksets.py", "content": "from locust import HttpUser, TaskSet, between, task\n\n\nclass WebsiteUser(HttpUser):\n \"\"\"\n Example of the ability of inline nested TaskSet classes\n \"\"\"\n\n host = \"http://127.0.0.1:8089\"\n wait_time = between(2, 5)\n\n @task\n class TopLevelTaskSet(TaskSet):\n @task\n class IndexTaskSet(TaskSet):\n @task(10)\n def index(self):\n self.client.get(\"/\")\n\n @task(1)\n def stop(self):\n self.interrupt()\n\n @task\n def stats(self):\n self.client.get(\"/stats/requests\")\n" }, { "path": "examples/open_closed_workload.py", "content": "from locust import HttpUser, constant, constant_pacing, task\n\n\nclass ClosedWorkload(HttpUser):\n wait_time = constant(10) # sleep 10s after each task, regardless of execution time\n\n @task\n def t(self):\n pass\n\n\nclass OpenWorkload(HttpUser):\n wait_time = constant_pacing(10) # sleep just enough so that we run one task iteration every 10s\n\n @task\n def t(self):\n pass\n\n\n# Note: A test using constant_pacing is still limited by the number of Users you spawn,\n# so if response times increase to the point where one task execution takes more than 10s,\n# you still wont reach your target throughput.\n" }, { "path": "examples/openai_ex.py", "content": "# You need to install the openai package and set OPENAI_API_KEY env var to run this\n\n# OpenAIUser tracks the number of output tokens in the response_length field,\n# because it is more useful than the actual payload size. This field is available to event handlers.\n\nfrom locust import run_single_user, task\nfrom locust.contrib.oai import OpenAIUser\n\n\nclass MyUser(OpenAIUser):\n @task\n def t(self):\n self.client.responses.create(\n model=\"gpt-4o\",\n instructions=\"You are a coding assistant that speaks like it were a Monty Python skit.\",\n input=\"How do I check if a Python object is an instance of a class?\",\n )\n # print(response.output_text)\n\n with self.client.rename_request(\"mini\"): # here's how to rename requests\n self.client.responses.create(\n model=\"gpt-4o-mini\",\n instructions=\"You are a coding assistant that speaks like it were a Monty Python skit.\",\n input=\"How do I check if a Python object is an instance of a class?\",\n )\n\n\nif __name__ == \"__main__\":\n run_single_user(MyUser)\n" }, { "path": "examples/postgres/README.md", "content": "# Overview\n\nRead the instruction below for your specific database\n\n## PostgreSQL\n\n### How to run the test\n\n- Prerequisites:\n\n - `psycopg3` - https://www.psycopg.org/psycopg3/docs/basic/install.html\n\n- Set your environment variables for:\n\n - PGHOST\n - PGPORT\n - PGDATABASE\n - PGUSER\n - PGPASSWORD\n\n- Run locust as usual, see https://docs.locust.io/en/stable/quickstart.html\n" }, { "path": "examples/postgres/locustfile.py", "content": "from locust import task\nfrom locust.contrib.postgres import PostgresUser\n\nimport os\nimport random\n\n\nclass MyUser(PostgresUser):\n @task\n def run_select_query(self):\n self.client.execute_query(\n \"SELECT * FROM loadtesting.invoice WHERE amount > 500\",\n )\n\n @task\n def run_update_query(self):\n random_amount = random.randint(1, 12)\n self.client.execute_query(\n f\"UPDATE loadtesting.invoice SET amount={random_amount} WHERE amount < 10\",\n )\n\n # Use environment variables or default values\n PGHOST = os.getenv(\"PGHOST\", \"localhost\")\n PGPORT = os.getenv(\"PGPORT\", \"5432\")\n PGDATABASE = os.getenv(\"PGDATABASE\", \"test_db\")\n PGUSER = os.getenv(\"PGUSER\", \"postgres\")\n PGPASSWORD = os.getenv(\"PGPASSWORD\", \"postgres\")\n\n conn_string = f\"postgresql://{PGUSER}:{PGPASSWORD}@{PGHOST}:{PGPORT}/{PGDATABASE}\"\n" }, { "path": "examples/qdrant/README.md", "content": "# Qdrant Load Testing with Locust\n\nSimple example demonstrating load testing for Qdrant vector database operations.\n\n## Prerequisites\n\nInstall Locust with Qdrant support:\n\n```bash\n# Using pip\npip install locust[qdrant]\n\n# Using uv\nuv add locust[qdrant]\n# or\nuv sync --extra qdrant\n```\n\nThis installs the required dependencies:\n\n- [`qdrant-client`](https://github.com/qdrant/qdrant-client) - Official Qdrant Python SDK\n\n## Usage\n\n```bash\n# Navigate to this directory\ncd examples/qdrant\n```\n\n```bash\n# Run Qdrant\ndocker run -p 6333:6333 -d qdrant/qdrant\n```\n\n```bash\n# Run headless\nlocust -f locustfile.py --host=http://localhost:6333 --headless --users=10 --spawn-rate=2 --run-time=60s\n\n# Run with web UI\nlocust -f locustfile.py --host=http://localhost:6333\n```\n\n## Operations Tested\n\n- Upsert points\n- Search points\n- Scroll points\n- Delete points\n\nFor more advanced usage, see the [Locust documentation](https://docs.locust.io/).\n" }, { "path": "examples/qdrant/locustfile.py", "content": "\"\"\"\nMinimal example demonstrating Qdrant load testing with Locust.\n\"\"\"\n\nfrom locust import between, task\nfrom locust.contrib.qdrant import QdrantUser\n\nimport random\n\nfrom qdrant_client.models import Distance, PointStruct, VectorParams\n\n\nclass SimpleQdrantUser(QdrantUser):\n \"\"\"Minimal Qdrant user for load testing.\"\"\"\n\n wait_time = between(1, 3)\n\n def on_start(self):\n self.dimension = 128\n self.test_vectors = [[random.random() for _ in range(self.dimension)] for _ in range(10)]\n\n collection_name = \"load_test_collection\"\n vectors_config = VectorParams(\n size=128,\n distance=Distance.COSINE,\n )\n\n def __init__(self, environment):\n self.url = environment.host\n super().__init__(environment)\n\n @task(3)\n def upsert_data(self):\n points = [\n PointStruct(\n id=random.randint(1, 10000),\n vector=[random.random() for _ in range(self.dimension)],\n payload={\"name\": f\"item_{random.randint(1, 1000)}\"},\n )\n ]\n self.upsert(points)\n\n @task(5)\n def search_vectors(self):\n search_vector = random.choice(self.test_vectors)\n self.search(query=search_vector, limit=5)\n\n @task(2)\n def scroll_data(self):\n self.scroll(limit=5)\n\n @task(1)\n def delete_data(self):\n delete_id = random.randint(1, 10000)\n self.delete(points_selector=[delete_id])\n" }, { "path": "examples/response_validations.py", "content": "\"\"\"\nThis shows some useful ways to validate responses and how to exit tasks early on failure.\n\"\"\"\n\nfrom locust import FastHttpUser, events, run_single_user, task\nfrom locust.exception import RescheduleTask\n\n\nclass BadUser(FastHttpUser):\n @task\n def t(self):\n self.client.request(\"POST\", \"/authenticate\", json={\"username\": \"foo\", \"password\": \"bar\"})\n # ...\n self.client.request(\"POST\", \"/checkout/confirm\", json={\"foo\": \"bar\"})\n\n\n# This User will behave identically to BadUser long as things go well,\n# but give earlier and more detailed information if things go wrong:\nclass GoodUser(FastHttpUser):\n @task\n def t(self):\n with self.rest(\"POST\", \"/authenticate\", json={\"username\": \"foo\", \"password\": \"bar\"}) as resp:\n # check if there was an error field in the response:\n if error := resp.js.get(\"error\"):\n resp.failure(error)\n # to be even more sure things went well, lets validate a success criteria:\n elif message := resp.js.get(\"message\"):\n if message != \"Welcome foo!\":\n resp.failure(f\"Wrong welcome message: {message}\")\n # ...\n # If you have long flows and can't be bothered to add validations\n # for each step then at least do it for the final step:\n with self.rest(\"POST\", \"/checkout/confirm\", json={\"foo\": \"bar\"}) as resp:\n if not resp.js.get(\"orderId\"):\n resp.failure(\"orderId missing\")\n\n\n# Break tasks early if there is a failed request\n@events.init.add_listener\ndef register_request_listener(environment, **kwargs):\n @events.request.add_listener\n def request(exception, **kwargs):\n if exception:\n raise RescheduleTask()\n\n\n# We'll now add endpoints to Locust's own WebUI to use as a target for the test.\n# This means so you can't use headless or run_single_user, unless you also start a \"headful\" Locust instance.\n#\n# It is not very relevant to what this example is explaining, so feel free to ignore it.\n\nFastHttpUser.host = \"http://127.0.0.1:8089\"\n\nfrom flask import request\n\n\n@events.init.add_listener\ndef locust_init(environment, **kwargs):\n if environment.web_ui:\n\n @environment.web_ui.app.route(\"/authenticate\", methods=[\"POST\"])\n def authenticate():\n username = request.get_json()[\"username\"]\n return {\"message\": f\"Welcome {username}!\"}\n\n @environment.web_ui.app.route(\"/checkout/confirm\", methods=[\"POST\"])\n def checkout_confirm():\n foo = request.get_json()[\"foo\"]\n return {\"orderId\": 42}\n\n\nif __name__ == \"__main__\":\n run_single_user(GoodUser)\n" }, { "path": "examples/rest.py", "content": "from locust import FastHttpUser, run_single_user, task\nfrom locust.contrib.fasthttp import RestResponseContextManager\nfrom locust.user.wait_time import constant\n\nfrom collections.abc import Generator\nfrom contextlib import contextmanager\n\n\nclass MyUser(FastHttpUser):\n host = \"https://postman-echo.com\"\n wait_time = constant(180) # be nice to postman-echo.com, and dont run this at scale.\n\n @task\n def t(self):\n # should work\n with self.rest(\"GET\", \"/get\", json={\"foo\": 1}) as resp:\n if resp.js[\"args\"][\"foo\"] != 1:\n resp.failure(f\"Unexpected value of foo in response {resp.text}\")\n\n # should work\n with self.rest(\"POST\", \"/post\", json={\"foo\": 1}) as resp:\n if resp.js[\"data\"][\"foo\"] != 1:\n resp.failure(f\"Unexpected value of foo in response {resp.text}\")\n # assertions are a nice short way to express your expectations about the response. The AssertionError thrown will be caught\n # and fail the request, including the message and the payload in the failure content.\n assert resp.js[\"data\"][\"foo\"] == 1, \"Unexpected value of foo in response\"\n\n # assertions are a nice short way to validate the response. The AssertionError they raise\n # will be caught by rest() and mark the request as failed\n\n with self.rest(\"POST\", \"/post\", json={\"foo\": 1}) as resp:\n # mark the request as failed with the message \"Assertion failed\"\n assert resp.js[\"data\"][\"foo\"] == 2\n\n with self.rest(\"POST\", \"/post\", json={\"foo\": 1}) as resp:\n # custom failure message\n assert resp.js[\"data\"][\"foo\"] == 2, \"my custom error message\"\n\n with self.rest(\"POST\", \"/post\", json={\"foo\": 1}) as resp:\n # use a trailing comma to append the response text to the custom message\n assert resp.js[\"data\"][\"foo\"] == 2, \"my custom error message with response text,\"\n\n with self.rest(\"\", \"/post\", json={\"foo\": 1}) as resp:\n # assign and assert in one line\n assert (foo := resp.js[\"foo\"])\n print(f\"the number {foo} is awesome\")\n\n # rest() catches most exceptions, so any programming mistakes you make automatically marks the request as a failure\n # and stores the callstack in the failure message\n with self.rest(\"POST\", \"/post\", json={\"foo\": 1}) as resp:\n 1 / 0 # pylint: disable=pointless-statement\n\n # response isn't even json, but RestUser will already have been marked it as a failure, so we dont have to do it again\n with self.rest(\"GET\", \"/\") as resp:\n pass\n\n with self.rest(\"GET\", \"/\") as resp:\n # If resp.js is None (which it will be when there is a connection failure, a non-json responses etc),\n # reading from resp.js will raise a TypeError (instead of an AssertionError), so lets avoid that:\n if resp.js:\n assert resp.js[\"foo\"] == 2\n # or, as a mildly confusing oneliner:\n assert not resp.js or resp.js[\"foo\"] == 2\n\n # 404\n with self.rest(\"GET\", \"http://example.com/\") as resp:\n pass\n\n # connection closed\n with self.rest(\"POST\", \"http://example.com:42/\", json={\"foo\": 1}) as resp:\n pass\n\n\n# An example of how you might write a common base class for an API that always requires\n# certain headers, or where you always want to check the response in a certain way\nclass RestUserThatLooksAtErrors(FastHttpUser):\n abstract = True\n\n @contextmanager\n def rest(self, method, url, **kwargs) -> Generator[RestResponseContextManager]:\n extra_headers = {\"my_header\": \"my_value\"}\n with super().rest(method, url, headers=extra_headers, **kwargs) as resp:\n if resp.js and \"error\" in resp.js and resp.js[\"error\"] is not None:\n resp.failure(resp.js[\"error\"])\n yield resp\n\n\nclass MyOtherRestUser(RestUserThatLooksAtErrors):\n host = \"https://postman-echo.com\"\n wait_time = constant(180) # be nice to postman-echo.com, and dont run this at scale.\n\n @task\n def t(self):\n with self.rest(\"GET\", \"/\") as _resp:\n pass\n\n\nif __name__ == \"__main__\":\n run_single_user(MyUser)\n" }, { "path": "examples/sdk_session_patching/session_patch_locustfile.py", "content": "import locust\nfrom locust.user import task\n\nfrom archivist.archivist import Archivist # Example library under test\n\n\nclass ArchivistUser(locust.HttpUser):\n def on_start(self):\n AUTH_TOKEN = None\n\n with open(\"auth.text\") as f:\n AUTH_TOKEN = f.read()\n\n # Start an instance of of the library-provided client\n self.arch: Archivist = Archivist(url=self.host, auth=AUTH_TOKEN)\n # overwrite the internal _session attribute with the locust session\n self.arch._session = self.client\n\n @task\n def Create_assets(self):\n \"\"\"User creates assets as fast as possible\"\"\"\n\n while True:\n self.arch.assets.create(behaviours=[\"Builtin\", \"RecordEvidence\", \"Attachments\"], attrs={\"foo\": \"bar\"})\n" }, { "path": "examples/semaphore_wait.py", "content": "from locust import HttpUser, events, task\n\nfrom gevent.lock import Semaphore\n\nall_users_spawned = Semaphore()\nall_users_spawned.acquire()\n\n\n@events.spawning_complete.add_listener\ndef on_spawning_complete(**kw):\n all_users_spawned.release()\n\n\nclass WebsiteUser(HttpUser):\n host = \"http://127.0.0.1:8089\"\n\n def on_start(self):\n all_users_spawned.wait()\n\n @task\n def index(self):\n self.client.get(\"/\")\n" }, { "path": "examples/socketio/echo_server.py", "content": "# Used by socketio_ex.py as a mock target. Requires installing gevent-websocket\nimport gevent.monkey\n\ngevent.monkey.patch_all()\nimport time\n\nimport socketio\nfrom flask import Flask\nfrom gevent import pywsgi\nfrom geventwebsocket.handler import WebSocketHandler\n\n# Create a Socket.IO server\nsio = socketio.Server(async_mode=\"gevent\")\napp = Flask(__name__)\napp.wsgi_app = socketio.WSGIApp(sio, app.wsgi_app)\n\nDELAY = 0.01\n\n\n# When a client connects\n@sio.event\ndef connect(sid, environ):\n time.sleep(DELAY)\n print(f\"Client connected: {sid}\")\n\n\n# Join a room\n@sio.event\ndef join_room(sid, data):\n time.sleep(DELAY)\n room = data.get(\"room\")\n sio.enter_room(sid, room)\n print(f\"Client {sid} joined room {room}\")\n # Optionally notify the room\n sio.emit(\"room_joined\", f\"{sid} joined {room}\", room=room)\n return f\"Joined room {room}\"\n\n\n# Leave a room\n@sio.event\ndef leave_room(sid, data):\n time.sleep(DELAY)\n room = data.get(\"room\")\n sio.leave_room(sid, room)\n print(f\"Client {sid} left room {room}\")\n\n\n# Broadcast message to a room\n@sio.event\ndef send_message(sid, data):\n time.sleep(DELAY)\n room = data.get(\"room\")\n msg = data.get(\"message\")\n print(f\"Sent message ({msg} to room {room}\")\n sio.emit(\"chat_message\", msg, room=room)\n\n\n# When a client disconnects\n@sio.event\ndef disconnect(sid):\n time.sleep(DELAY)\n print(f\"Client disconnected: {sid}\")\n\n\nserver = pywsgi.WSGIServer((\"0.0.0.0\", 5001), app, handler_class=WebSocketHandler)\nserver.serve_forever()\n" }, { "path": "examples/socketio/socketio_ex.py", "content": "from locust import HttpUser, task\nfrom locust.contrib.socketio import SocketIOUser\n\nfrom threading import Event\n\nimport gevent\nfrom socketio import Client\n\n\nclass MySIOHttpUser(SocketIOUser, HttpUser):\n options = {\n # \"logger\": True,\n # \"engineio_logger\": True,\n }\n event: Event\n\n def on_start(self) -> None:\n self.sio.connect(\"ws://localhost:5001\", wait_timeout=10)\n self.sio_greenlet = gevent.spawn(self.sio.wait)\n # If you need authorization, here's how to do it:\n # resp = self.client.post(\"/login\", json={\"username\": \"foo\", \"password\": \"bar\"})\n # token = resp.json()[\"access_token\"]\n # self.sio.connect(\n # \"ws://localhost:5001\",\n # # Option 1: using Authorization header:\n # headers={\"Authorization\": f\"Bearer {token}\"},\n # # Option 2: using auth:\n # # auth={\"token\": token},\n # )\n\n @task\n def my_task(self):\n self.event = Event()\n # Send message and wait for confirmation\n self.sio.call(\"join_room\", {\"room\": \"room1\"})\n # Register an event handler\n self.sio.on(\"chat_message\", self.on_chat_message)\n # Use socketio.Client to send a message that wont be logged as a request\n Client.call(self.sio, \"send_message\", {\"room\": \"room1\", \"message\": \"foo\"})\n # Emit doesnt wait for confirmation\n self.sio.emit(\"send_message\", {\"room\": \"room1\", \"message\": \"bar\"})\n self.event.wait() # wait for on_chat_message to set this event\n self.sio.call(\"leave_room\", {\"room\": \"room1\"})\n # We've used multiple inheritance to combine this with HttpUser, so we can also make normal HTTP requests\n self.client.get(\"/\")\n\n def on_chat_message(self, event: str, data: str) -> None:\n if data.startswith(\"bar\"):\n self.event.set()\n self.sio.on_message(event, data)\n\n def on_stop(self) -> None:\n self.sio.disconnect()\n" }, { "path": "examples/stop_on_threshold.py", "content": "# An example of how to stop locust if a threshold (in this case the fail ratio) is exceeded\nfrom locust import HttpUser, events, task\nfrom locust.runners import STATE_CLEANUP, STATE_STOPPED, STATE_STOPPING, WorkerRunner\n\nimport time\n\nimport gevent\n\n\nclass MyUser(HttpUser):\n host = \"http://www.google.com\"\n\n @task\n def my_task(self):\n for _ in range(10):\n self.client.get(\"/\")\n time.sleep(1)\n for _ in range(5):\n self.client.get(\"/error\")\n time.sleep(1)\n\n\ndef checker(environment):\n while not environment.runner.state in [STATE_STOPPING, STATE_STOPPED, STATE_CLEANUP]:\n time.sleep(1)\n if environment.runner.stats.total.fail_ratio > 0.2:\n print(f\"fail ratio was {environment.runner.stats.total.fail_ratio}, quitting\")\n environment.runner.quit()\n return\n\n\n@events.init.add_listener\ndef on_locust_init(environment, **_kwargs):\n if not isinstance(environment.runner, WorkerRunner):\n gevent.spawn(checker, environment)\n" }, { "path": "examples/terraform/aws/README.md", "content": "## This doesnt seem to work right now for some people. See https://github.com/locustio/locust/issues/2357\n\n## 1. AWS Authentication\n\n```bash\nexport AWS_ACCESS_KEY_ID=AIAXXXXXXXXXXXXXXXXX\nexport AWS_SECRET_ACCESS_KEY=T9HyXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n```\n\n## 2. Configure your provisioning\n\n- Don't forget to provide the correct subnet name in the variable file\n- Define location and file of your locust plan script\n- Define the number of nodes to create\n\n**variables.tf**\n\n```bash\nvariable \"node_size\" {\n description = \"Size of total nodes\"\n default = 2\n}\n\nvariable \"loadtest_dir_source\" {\n default = \"plan/\"\n}\n\nvariable \"locust_plan_filename\" {\n default = \"basic.py\"\n}\n\nvariable \"subnet_name\" {\n default = \"subnet-prd-a\"\n description = \"Subnet name\"\n}\n\n```\n\n\n\n---\n\n## 3. Execute Terraform\n\n```bash\ncd examples/terraform/aws\nterraform init\nterraform apply --auto-approve\n```\n\n---\n\n## 4. Access UI\n\nClick on the link below to access the UI:\n\nResult example:\n\n```bash\nApply complete! Resources: 14 added, 0 changed, 0 destroyed.\n\nOutputs:\n\ndashboard_url = \"http://3.237.255.123\"\nleader_private_ip = \"10.17.5.119\"\nleader_public_ip = \"3.237.255.123\"\nnodes_private_ip = [\n \"10.17.5.167\",\n \"10.17.5.39\",\n]\nnodes_public_ip = [\n \"3.235.45.218\",\n \"100.24.124.0\",\n]\n```\n\n![locust-home](https://github.com/marcosborges/terraform-aws-loadtest-distribuited/raw/v0.4.0/assets/locust-home.png)\n\n---\n\n## 5. Cleanup\n\n```bash\nterraform destroy --auto-approve\n```\n\n---\n\n## 6. More information\n\n- [Terraform aws-get-started >> install-terraform-on-linux](https://learn.hashicorp.com/tutorials/terraform/install-cli?in=terraform/aws-get-started#install-terraform-on-linux)\n\n- [Terraform module aws loadtest distribuited](https://registry.terraform.io/modules/marcosborges/loadtest-distribuited/aws/latest)\n\n" }, { "path": "examples/terraform/aws/data_subnet.tf", "content": "data \"aws_subnet\" \"current\" {\n filter {\n name = \"tag:Name\"\n values = [var.subnet_name]\n }\n}\n" }, { "path": "examples/terraform/aws/main.tf", "content": "module \"loadtest\" {\n \n # https://registry.terraform.io/modules/marcosborges/loadtest-distribuited/aws/latest\n source = \"marcosborges/loadtest-distribuited/aws\"\n\n name = \"provision-name\"\n nodes_size = var.node_size\n executor = \"locust\"\n loadtest_dir_source = var.loadtest_dir_source\n \n # LEADER ENTRYPOINT\n loadtest_entrypoint = <<-EOT\n nohup locust \\\n -f ${var.locust_plan_filename} \\\n --web-port=8080 \\\n --expect-workers=${var.node_size} \\\n --master > locust-leader.out 2>&1 &\n EOT\n \n # NODES ENTRYPOINT\n node_custom_entrypoint = <<-EOT\n nohup locust \\\n -f ${var.locust_plan_filename} \\\n --worker \\\n --master-host={LEADER_IP} > locust-worker.out 2>&1 &\n EOT\n\n subnet_id = data.aws_subnet.current.id\n locust_plan_filename = var.locust_plan_filename\n ssh_export_pem = var.ssh_export_pem\n\n}\n" }, { "path": "examples/terraform/aws/output.tf", "content": "output \"leader_public_ip\" {\n value = module.loadtest.leader_public_ip\n description = \"The public IP address of the leader server instance.\"\n}\n\noutput \"leader_private_ip\" {\n value = module.loadtest.leader_private_ip\n description = \"The private IP address of the leader server instance.\"\n}\n\noutput \"nodes_public_ip\" {\n value = module.loadtest.nodes_public_ip\n description = \"The public IP address of the nodes instances.\"\n}\n\noutput \"nodes_private_ip\" {\n value = module.loadtest.nodes_private_ip\n description = \"The private IP address of the nodes instances.\"\n}\n\noutput \"dashboard_url\" {\n value = \"http://${coalesce(module.loadtest.leader_public_ip, module.loadtest.leader_private_ip)}\"\n description = \"The URL of the Locust UI.\"\n}\n" }, { "path": "examples/terraform/aws/plan/basic.py", "content": "from locust import HttpUser, between, task\n\n\nclass Quickstart(HttpUser):\n wait_time = between(1, 5)\n\n @task\n def google(self):\n self.client.request_name = \"google\"\n self.client.get(\"https://google.com/\")\n\n @task\n def microsoft(self):\n self.client.request_name = \"microsoft\"\n self.client.get(\"https://microsoft.com/\")\n\n @task\n def facebook(self):\n self.client.request_name = \"facebook\"\n self.client.get(\"https://facebook.com/\")\n" }, { "path": "examples/terraform/aws/provisioner.tf", "content": "provider \"aws\" {\n region = var.aws_region\n}\n" }, { "path": "examples/terraform/aws/variables.tf", "content": "variable \"aws_region\" {\n type = string\n default = \"us-east-1\"\n description = \"AWS Region\"\n}\n\nvariable \"node_size\" {\n description = \"Size of total nodes\"\n default = 2\n}\n\nvariable \"loadtest_dir_source\" {\n default = \"plan/\"\n}\n\nvariable \"locust_plan_filename\" {\n default = \"basic.py\"\n}\n\nvariable \"subnet_name\" {\n default = \"subnet-prd-a\"\n description = \"Subnet name\"\n}\n\nvariable \"ssh_export_pem\" {\n description = \"Export private ssh key\"\n type = bool\n default = false\n}\n" }, { "path": "examples/test_data_management.py", "content": "# This example shows the various ways to run things before/outside of the normal task execution flow,\n# which is very useful for fetching test data.\n#\n# 1. Locustfile parse time\n# 2. Locust start (init)\n# 3. Test start\n# 4. User start\n# 5. Inside a task\n# M1. CPU & memory usage\n# M2. master sent heartbeat to worker 1-N\n# M3. worker 1-N received heartbeat from master\n# (M* are repeated as long as locust is running)\n# ...\n# 6. Test run stopping\n# 7. User stop\n# 8. Test run stop\n# (3-8 are repeated if you restart the test in the UI)\n# 9. Locust quitting\n# 10. Locust quit\n#\n# try it out by running:\n# locust -f test_data_management.py --headless -u 2 -t 5 --processes 2\nfrom __future__ import annotations\n\nfrom locust import HttpUser, events, task\nfrom locust.env import Environment\nfrom locust.runners import MasterRunner\nfrom locust.user.wait_time import constant\n\nimport datetime\nfrom typing import Any\n\nimport requests\n\n\ndef timestring() -> str:\n now = datetime.datetime.now()\n return datetime.datetime.strftime(now, \"%m:%S.%f\")[:-5]\n\n\nprint(\"1. Parsing locustfile, happens before anything else\")\n\n# If you want to get something over HTTP at this time you can use `requests` directly:\nglobal_test_data = requests.post(\n \"https://postman-echo.com/post\",\n data=\"global_test_data_\" + timestring(),\n).json()[\"data\"]\n\ntest_run_specific_data = None\n\n\n@events.init.add_listener\ndef init(environment: Environment, **_kwargs: Any) -> None:\n print(\"2. Initializing locust, happens after parsing the locustfile but before test start\")\n\n\n@events.quitting.add_listener\ndef quitting(environment: Environment, **_kwargs: Any) -> None:\n print(\"9. locust is about to shut down\")\n\n\n@events.test_start.add_listener\ndef test_start(environment: Environment, **_kwargs) -> None:\n # happens only once in headless runs, but can happen multiple times in web ui-runs\n global test_run_specific_data\n print(\"3. Starting test run\")\n # in a distributed run, the master does not typically need any test data\n if not isinstance(environment.runner, MasterRunner):\n test_run_specific_data = requests.post(\n \"https://postman-echo.com/post\",\n data=\"test-run-specific_\" + timestring(),\n ).json()[\"data\"]\n\n\n@events.heartbeat_sent.add_listener\ndef heartbeat_sent(client_id: str, timestamp: float) -> None:\n print(f\"M2. master sent heartbeat to worker {client_id} at {datetime.datetime.fromtimestamp(timestamp)}\")\n\n\n@events.heartbeat_received.add_listener\ndef heartbeat_received(client_id: str, timestamp: float) -> None:\n print(f\"M3. worker {client_id} received heartbeat from master at {datetime.datetime.fromtimestamp(timestamp)}\")\n\n\n@events.usage_monitor.add_listener\ndef usage_monitor(environment: Environment, cpu_usage: float, memory_usage: int) -> None:\n # convert from bytes to Mebibytes\n memory_usage = memory_usage / 1024 / 1024\n print(f\"M1. {environment.runner.__class__.__name__}: cpu={cpu_usage}%, memory={memory_usage}M\")\n\n\n@events.quit.add_listener\ndef quit(exit_code: int, **kwargs: Any) -> None:\n print(f\"10. Locust has shut down with code {exit_code}\")\n\n\n@events.test_stopping.add_listener\ndef test_stopping(environment: Environment, **_kwargs: Any) -> None:\n print(\"6. stopping test run\")\n\n\n@events.test_stop.add_listener\ndef test_stop(environment: Environment, **_kwargs: Any) -> None:\n print(\"8. test run stopped\")\n\n\nclass MyUser(HttpUser):\n host = \"https://postman-echo.com\"\n wait_time = constant(180) # be nice to postman-echo\n first_start = True\n\n def on_start(self) -> None:\n if MyUser.first_start:\n MyUser.first_start = False\n # This is useful for similar things as to test_start, but happens in the context of a User\n # In the case of a distributed run, this would be run once per worker.\n # It will not be re-run on repeated runs (unless you clear the first_start flag)\n print(\"X. Here's where you would put things you want to run the first time a User is started\")\n\n print(\"4. A user was started\")\n # This is a good place to fetch user-specific test data. It is executed once per User\n # If you do not want the request logged, you can replace self.client. with requests.\n self.user_specific_testdata = self.client.post(\n \"https://postman-echo.com/post\",\n data=\"user-specific_\" + timestring(),\n ).json()[\"data\"]\n\n @task\n def t(self) -> None:\n self.client.get(f\"/get?{global_test_data}\")\n self.client.get(f\"/get?{test_run_specific_data}\")\n self.client.get(f\"/get?{self.user_specific_testdata}\")\n\n print(\"5. Getting task-run-specific testdata\")\n # If every iteration is meant to use new test data this is the most common way to do it\n task_run_specific_testdata = self.client.post(\n \"https://postman-echo.com/post\",\n data=\"task_run_specific_testdata_\" + timestring(),\n ).json()[\"data\"]\n self.client.get(f\"/get?{task_run_specific_testdata}\")\n\n def on_stop(self) -> None:\n # this is a good place to clean up/release any user-specific test data\n print(\"7. a user was stopped\")\n" }, { "path": "examples/test_pytest.py", "content": "from locust.clients import HttpSession # this import is just for type hints\n\nimport time\n\n\n# pytest/locust will discover any functions prefixed with \"test_\" as test cases.\n# session and fastsession are pytest fixtures provided by Locust's pytest plugin.\ndef test_stuff(session):\n resp = session.get(\"https://www.locust.io/\")\n\n # Bad HTTP status codes in the response dont automatically raise an exception,\n # so if that is what you want, you need to call:\n resp.raise_for_status()\n # In Locust, request-related exceptions are caught (and the test case restarted),\n # in pytest any exceptions fail the test case\n\n # Just like with Locust, you can set a base URL using --host/-H when using pytest.\n # Or you can set a default:\n if not session.base_url:\n session.base_url = \"https://www.locust.io\"\n\n # catch_response works just like in regular locustfiles\n with session.get(\"/\", catch_response=True) as resp:\n if not resp.text or not \"Locust\" in resp.text:\n resp.failure(\"important text was missing in response\")\n\n # raise_for_status also respects calls to resp.failure()/.success()\n # so this will raise an exception and fail the test case if \"Load\" was missing\n resp.raise_for_status()\n\n # you can call helper functions as needed\n helper_function(session)\n\n # unlike regular Locust Users, there's no wait_time, so use time.sleep instead\n time.sleep(0.1)\n\n\n# this is not a test case and won't be detected by pytest/locust\ndef helper_function(session: HttpSession):\n session.get(\"/\")\n" }, { "path": "examples/testdata_from_csv.csv", "content": "myuser1@example.com,password1\nmyuser2@example.com,password2\n" }, { "path": "examples/testdata_from_csv.py", "content": "\"\"\"\nThis shows an easy way to get testdata from a csv file into locust and use it for requests\n\"\"\"\n\nfrom locust import FastHttpUser, events, run_single_user, task\n\nimport csv\nimport os\n\ncsvfile = open(os.path.join(os.path.dirname(__file__), \"testdata_from_csv.csv\"))\niter = csv.reader(csvfile)\n\n\nclass DemoUser(FastHttpUser):\n @task\n def t(self):\n try:\n username, password = next(iter)\n except StopIteration:\n # go back to start of the file once its been exhausted\n csvfile.seek(0, 0)\n username, password = next(iter)\n with self.rest(\"POST\", \"/authenticate\", json={\"username\": username, \"password\": password}) as resp:\n if message := resp.js and resp.js.get(\"message\"):\n if not \"Welcome\" in message:\n resp.failure(f\"bad response: {message}\")\n\n\n# We'll now add endpoints to Locust's own WebUI to use as a target for the test.\n# This means so you can't use headless or run_single_user, unless you also start a \"headful\" Locust instance.\n#\n# It is not very relevant to what this example is explaining, so feel free to ignore it.\n\nFastHttpUser.host = \"http://127.0.0.1:8089\"\n\nfrom flask import request\n\n\n@events.init.add_listener\ndef locust_init(environment, **kwargs):\n if environment.web_ui:\n\n @environment.web_ui.app.route(\"/authenticate\", methods=[\"POST\"])\n def authenticate():\n username = request.get_json()[\"username\"]\n return {\"message\": f\"Welcome {username}!\"}\n\n @environment.web_ui.app.route(\"/checkout/confirm\", methods=[\"POST\"])\n def checkout_confirm():\n foo = request.get_json()[\"foo\"]\n return {\"orderId\": 42}\n\n\nif __name__ == \"__main__\":\n run_single_user(DemoUser)\n" }, { "path": "examples/use_as_lib.py", "content": "#!/usr/bin/env python3\nfrom locust import HttpUser, events, task\nfrom locust.env import Environment\nfrom locust.log import setup_logging\nfrom locust.stats import stats_history, stats_printer\n\nimport gevent\n\nsetup_logging(\"INFO\")\n\n\nclass MyUser(HttpUser):\n host = \"https://docs.locust.io\"\n\n @task\n def t(self):\n self.client.get(\"/\")\n\n\n# setup Environment and Runner\nenv = Environment(user_classes=[MyUser], events=events)\nrunner = env.create_local_runner()\n\n# start a WebUI instance\nweb_ui = env.create_web_ui(\"127.0.0.1\", 8089)\n\n# execute init event handlers (only really needed if you have registered any)\nenv.events.init.fire(environment=env, runner=runner, web_ui=web_ui)\n\n# start a greenlet that periodically outputs the current stats\ngevent.spawn(stats_printer(env.stats))\n\n# start a greenlet that save current stats to history\ngevent.spawn(stats_history, env.runner)\n\n# start the test\nrunner.start(1, spawn_rate=10)\n\n# in 30 seconds stop the runner\ngevent.spawn_later(30, runner.quit)\n\n# wait for the greenlets\nrunner.greenlet.join()\n\n# stop the web server for good measures\nweb_ui.stop()\n" }, { "path": "examples/vagrant/README.md", "content": "" }, { "path": "examples/vagrant/supervisord.conf", "content": "[inet_http_server] ; inet (TCP) server disabled by default\nport=*:9001 ; (ip_address:port specifier, *:port for all iface)\n;username=user ; (default is no username (open server))\n;password=123 ; (default is no password (open server))\n\n[supervisord]\nlogfile=/tmp/supervisord.log ; (main log file;default $CWD/supervisord.log)\nlogfile_maxbytes=50MB ; (max main logfile bytes b4 rotation;default 50MB)\nlogfile_backups=10 ; (num of main logfile rotation backups;default 10)\nloglevel=info ; (log level;default info; others: debug,warn,trace)\npidfile=/tmp/supervisord.pid ; (supervisord pidfile;default supervisord.pid)\nnodaemon=false ; (start in foreground if true;default false)\nminfds=1024 ; (min. avail startup file descriptors;default 1024)\nminprocs=200 ; (min. avail process descriptors;default 200)\n\n[supervisorctl]\nserverurl=unix:///tmp/supervisor.sock ; use a unix:// URL for a unix socket\n\n[rpcinterface:supervisor]\nsupervisor.rpcinterface_factory = supervisor.rpcinterface:make_main_rpcinterface\n\n[program:locustmaster]\ncommand=locust --master -f examples/basic.py ; TODO host should perhaps be configurable through the web UI\nprocess_name=master\nautostart=true\ndirectory=/vagrant\npriority=1\n\n[program:locustworkers]\ncommand=locust --worker -f examples/basic.py ; TODO host should perhaps be configurable through the web UI\nprocess_name=worker_%(process_num)s\nnumprocs=2\nnumprocs_start=1\nautostart=true\npriority=2\ndirectory=/vagrant" }, { "path": "examples/web_ui_auth/basic.py", "content": "\"\"\"\nExample of implementing authentication for Locust when the --web-login flag is given\n\nThis is only to serve as a starting point, proper authentication should be implemented\naccording to your projects specifications.\n\nFor more information, see https://docs.locust.io/en/stable/extending-locust.html#authentication\n\"\"\"\n\nfrom locust import HttpUser, events, task\n\nimport os\n\nfrom flask import Blueprint, redirect, request, session, url_for\nfrom flask_login import UserMixin, login_user\n\n\nclass LocustHttpUser(HttpUser):\n @task\n def example(self):\n self.client.get(\"/\")\n\n\nclass AuthUser(UserMixin):\n def __init__(self, username):\n self.username = username\n\n def get_id(self):\n return self.username\n\n\ndef load_user(username):\n return AuthUser(username)\n\n\n@events.init.add_listener\ndef locust_init(environment, **_kwargs):\n if environment.web_ui:\n auth_blueprint = Blueprint(\"auth\", \"web_ui_auth\", url_prefix=environment.parsed_options.web_base_path)\n\n environment.web_ui.login_manager.user_loader(load_user)\n\n environment.web_ui.app.config[\"SECRET_KEY\"] = os.getenv(\"FLASK_SECRET_KEY\")\n\n environment.web_ui.auth_args = {\n \"username_password_callback\": f\"{environment.parsed_options.web_base_path}/login_submit\",\n \"auth_providers\": [\n {\n \"label\": \"Github\",\n \"callback_url\": \"/login/github\",\n \"icon_url\": \"https://static-00.iconduck.com/assets.00/github-icon-1024x994-4h5sdmko.png\",\n },\n ],\n }\n\n @auth_blueprint.route(\"/login/github\")\n def google_login():\n # Implement authentication with desired auth provider\n username = \"username\"\n session[\"username\"] = username\n login_user(AuthUser(\"username\"))\n\n return redirect(url_for(\"locust.index\"))\n\n @auth_blueprint.route(\"/login_submit\", methods=[\"POST\"])\n def login_submit():\n username = request.form.get(\"username\")\n password = request.form.get(\"password\")\n\n # Implement real password verification here\n if password:\n login_user(AuthUser(username))\n\n return redirect(url_for(\"locust.index\"))\n\n session[\"auth_error\"] = \"Invalid username or password\"\n\n return redirect(url_for(\"locust.login\"))\n\n environment.web_ui.app.register_blueprint(auth_blueprint)\n" }, { "path": "examples/web_ui_auth/custom_form.py", "content": "\"\"\"\nExample of implementing authentication with a custom form for Locust when the --web-login\nflag is given\n\nThis is only to serve as a starting point, proper authentication should be implemented\naccording to your projects specifications.\n\nFor more information, see https://docs.locust.io/en/stable/extending-locust.html#authentication\n\"\"\"\n\nfrom __future__ import annotations\n\nfrom locust import HttpUser, events, task\n\nimport os\n\nfrom flask import Blueprint, redirect, request, session, url_for\nfrom flask_login import UserMixin, login_user\n\n\nclass LocustHttpUser(HttpUser):\n @task\n def example(self):\n self.client.get(\"/\")\n\n\nclass AuthUser(UserMixin):\n def __init__(self, username):\n self.username = username\n self.is_admin = False\n self.user_group: str | None = None\n\n def get_id(self):\n return self.username\n\n\ndef load_user(user_id):\n return AuthUser(user_id)\n\n\n@events.init.add_listener\ndef locust_init(environment, **_kwargs):\n if environment.web_ui:\n auth_blueprint = Blueprint(\"auth\", \"web_ui_auth\", url_prefix=environment.parsed_options.web_base_path)\n\n environment.web_ui.login_manager.user_loader(load_user)\n\n environment.web_ui.app.config[\"SECRET_KEY\"] = os.getenv(\"FLASK_SECRET_KEY\")\n\n environment.web_ui.auth_args = {\n \"custom_form\": {\n \"inputs\": [\n {\n \"label\": \"Username\",\n \"name\": \"username\",\n # make field required\n \"is_required\": True,\n # override input type for HTML validation\n # applies if !is_secret and !choices, and default_value is string | None\n \"type\": \"email\",\n },\n # boolean checkmark field\n {\"label\": \"Admin\", \"name\": \"is_admin\", \"default_value\": False},\n # select field\n {\"label\": \"User Group\", \"name\": \"user_group\", \"choices\": [\"developer\", \"manager\"]},\n {\n \"label\": \"Password\",\n \"name\": \"password\",\n \"is_secret\": True,\n },\n {\n \"label\": \"Confirm Password\",\n \"name\": \"confirm_password\",\n \"is_secret\": True,\n },\n ],\n \"callback_url\": f\"{environment.parsed_options.web_base_path}/login_submit\",\n \"submit_button_text\": \"Submit\",\n },\n }\n\n @auth_blueprint.route(\"/login_submit\", methods=[\"POST\"])\n def login_submit():\n username = request.form.get(\"username\")\n password = request.form.get(\"password\")\n confirm_password = request.form.get(\"confirm_password\")\n is_admin = request.form.get(\"is_admin\") == \"on\"\n user_group = request.form.get(\"user_group\")\n\n if password != confirm_password:\n session[\"auth_error\"] = \"Passwords do not match!\"\n\n return redirect(url_for(\"locust.login\"))\n\n # Implement real password verification here\n if password:\n current_user = AuthUser(username)\n\n # do something with your custom variables\n current_user.is_admin = is_admin\n current_user.user_group = user_group\n\n login_user(AuthUser(username))\n\n return redirect(url_for(\"locust.index\"))\n\n session[\"auth_error\"] = \"Invalid username or password\"\n\n return redirect(url_for(\"locust.login\"))\n\n environment.web_ui.app.register_blueprint(auth_blueprint)\n" }, { "path": "examples/web_ui_cache_stats.py", "content": "\"\"\"\nThis is an example of a locustfile that uses Locust's built in event and web\nUI extension hooks to track the sum of Varnish cache hit/miss headers\nand display them in the web UI.\n\"\"\"\n\nfrom locust import HttpUser, TaskSet, between, events, task\n\nimport json\nimport os\nfrom time import time\n\nfrom flask import Blueprint, make_response, render_template, request\n\n\nclass MyTaskSet(TaskSet):\n @task(1)\n def miss(l):\n \"\"\"MISS X-Cache header\"\"\"\n l.client.get(\"/response-headers?X-Cache=MISS\")\n\n @task(2)\n def hit(l):\n \"\"\"HIT X-Cache header\"\"\"\n l.client.get(\"/response-headers?X-Cache=HIT\")\n\n @task(1)\n def noinfo(l):\n \"\"\"No X-Cache header (noinfo counter)\"\"\"\n l.client.get(\"/\")\n\n\nclass WebsiteUser(HttpUser):\n host = \"http://httpbin.org\"\n wait_time = between(2, 5)\n tasks = [MyTaskSet]\n\n\n# This example is based on the Varnish hit/miss headers (https://docs.varnish-software.com/tutorials/hit-miss-logging/).\n# It could easily be customised for matching other caching systems, CDN or custom headers.\nCACHE_HEADER = \"X-Cache\"\n\ncache_stats = {}\n\npage_stats = {\"hit\": 0, \"miss\": 0, \"noinfo\": 0}\n\npath = os.path.dirname(os.path.abspath(__file__))\nextend = Blueprint(\n \"extend\",\n \"extend_web_ui\",\n static_folder=f\"{path}/static/\",\n static_url_path=\"/extend/static/\",\n template_folder=f\"{path}/templates/\",\n)\n\n\n@events.init.add_listener\ndef locust_init(environment, **kwargs):\n \"\"\"\n Load data on locust init.\n :param environment:\n :param kwargs:\n :return:\n \"\"\"\n\n if environment.web_ui:\n # this code is only run on the master node (the web_ui instance doesn't exist on workers)\n\n def get_cache_stats():\n \"\"\"\n This is used by the Cache tab in the\n extended web UI to show the stats.\n \"\"\"\n if cache_stats:\n stats_tmp = []\n\n for name, inner_stats in cache_stats.items():\n stats_tmp.append(\n {\n \"name\": name,\n \"hit\": inner_stats[\"hit\"],\n \"miss\": inner_stats[\"miss\"],\n \"noinfo\": inner_stats[\"noinfo\"],\n }\n )\n\n # Truncate the total number of stats and errors displayed since a large number\n # of rows will cause the app to render extremely slowly.\n return stats_tmp[:500]\n return cache_stats\n\n @environment.web_ui.app.after_request\n def extend_stats_response(response):\n if request.path != \"/stats/requests\":\n return response\n\n # extended_stats contains the data where extended_tables looks for its data: \"cache-statistics\"\n response.set_data(\n json.dumps(\n {**response.json, \"extended_stats\": [{\"key\": \"cache-statistics\", \"data\": get_cache_stats()}]}\n )\n )\n\n return response\n\n @extend.route(\"/extend\")\n def extend_web_ui():\n \"\"\"\n Add route to access the extended web UI with our new tab.\n \"\"\"\n # ensure the template_args are up to date before using them\n environment.web_ui.update_template_args()\n\n return render_template(\n \"index.html\",\n template_args={\n **environment.web_ui.template_args,\n # extended_tabs and extended_tables keys must match.\n \"extended_tabs\": [{\"title\": \"Cache statistics\", \"key\": \"cache-statistics\"}],\n \"extended_tables\": [\n {\n \"key\": \"cache-statistics\",\n \"structure\": [\n {\"key\": \"name\", \"title\": \"Name\"},\n {\"key\": \"hit\", \"title\": \"Hit\"},\n {\"key\": \"miss\", \"title\": \"Miss\"},\n {\"key\": \"noinfo\", \"title\": \"No Info\"},\n ],\n }\n ],\n \"extended_csv_files\": [{\"href\": \"/cache/csv\", \"title\": \"Download Cache statistics CSV\"}],\n },\n )\n\n @extend.route(\"/cache/csv\")\n def request_cache_csv():\n \"\"\"\n Add route to enable downloading of cache stats as CSV\n \"\"\"\n response = make_response(cache_csv())\n file_name = f\"cache-{time()}.csv\"\n disposition = f\"attachment;filename={file_name}\"\n response.headers[\"Content-type\"] = \"text/csv\"\n response.headers[\"Content-disposition\"] = disposition\n return response\n\n def cache_csv():\n \"\"\"Returns the cache stats as CSV.\"\"\"\n rows = [\",\".join(['\"Name\"', '\"hit\"', '\"miss\"', '\"noinfo\"'])]\n\n if cache_stats:\n for name, stats in cache_stats.items():\n rows.append(f'\"{name}\",' + \",\".join(str(v) for v in stats.values()))\n return \"\\n\".join(rows)\n\n # register our new routes and extended UI with the Locust web UI\n environment.web_ui.app.register_blueprint(extend)\n\n\n@events.request.add_listener\ndef on_request(name, response, exception, **kwargs):\n \"\"\"\n Event handler that get triggered on every request\n \"\"\"\n\n cache_stats.setdefault(name, page_stats.copy())\n\n if CACHE_HEADER not in response.headers:\n cache_stats[name][\"noinfo\"] += 1\n elif response.headers[CACHE_HEADER] == \"HIT\":\n cache_stats[name][\"hit\"] += 1\n elif response.headers[CACHE_HEADER] == \"MISS\":\n cache_stats[name][\"miss\"] += 1\n\n\n@events.report_to_master.add_listener\ndef on_report_to_master(client_id, data):\n \"\"\"\n This event is triggered on the worker instances every time a stats report is\n to be sent to the locust master. It will allow us to add our extra cache\n data to the dict that is being sent, and then we clear the local stats in the worker.\n \"\"\"\n global cache_stats\n data[\"cache_stats\"] = cache_stats\n cache_stats = {}\n\n\n@events.worker_report.add_listener\ndef on_worker_report(client_id, data):\n \"\"\"\n This event is triggered on the master instance when a new stats report arrives\n from a worker. Here we just add the cache to the master's aggregated stats dict.\n \"\"\"\n for name in data[\"cache_stats\"]:\n cache_stats.setdefault(name, page_stats.copy())\n for stat_name, value in data[\"cache_stats\"][name].items():\n cache_stats[name][stat_name] += value\n\n\n@events.reset_stats.add_listener\ndef on_reset_stats():\n \"\"\"\n Event handler that get triggered on click of web UI Reset Stats button\n \"\"\"\n global cache_stats\n cache_stats = {}\n" }, { "path": "examples/worker_index.py", "content": "# How to use worker_index to read from a pre-partitioned CSV file (mythings_0.csv, mythings_1.csv, ...)\n# so that each worker uses their own file\nfrom locust import User, events, runners, task\n\nfrom locust_plugins import csvreader # install locust-plugins first\n\n\nclass DemoUser(User):\n reader: csvreader.CSVDictReader\n\n @task\n def t(self):\n thing = next(self.reader)\n print(thing)\n\n\n@events.init.add_listener\ndef on_locust_init(environment, **_kwargs):\n if not isinstance(environment.runner, runners.MasterRunner):\n DemoUser.reader = csvreader.CSVDictReader(f\"mythings_{environment.runner.worker_index}.csv\")\n" }, { "path": "examples/x-forwarded-for.py", "content": "from locust import HttpUser, run_single_user, task\n\nimport random\n\n\nclass ForwardedForUser(HttpUser):\n subnet = \"10.10.\"\n\n def __init__(self, environment):\n super().__init__(environment)\n self.fake_ip = self.subnet + str(random.randint(0, 254)) + \".\" + str(random.randint(0, 254))\n self.client.headers[\"X-Forwarded-For\"] = self.fake_ip\n\n\nclass WebsiteUser(ForwardedForUser):\n @task\n def index(self):\n with self.client.get(\"/\", catch_response=True) as resp:\n pass\n\n\nif __name__ == \"__main__\":\n run_single_user(WebsiteUser)\n" }, { "path": "generate_changelog.py", "content": "#!/usr/bin/env python3\n\nimport os\nimport subprocess\nimport sys\n\ngithub_api_token = (\n os.getenv(\"CHANGELOG_GITHUB_TOKEN\") if os.getenv(\"CHANGELOG_GITHUB_TOKEN\") else input(\"Enter Github API token: \")\n)\n\nif len(sys.argv) < 2:\n raise Exception(\"Provide a version number as parameter (--future-release argument)\")\n\nversion = sys.argv[1]\n\ncmd = [\n \"github_changelog_generator\",\n \"-t\",\n github_api_token,\n \"-u\",\n \"locustio\",\n \"-p\",\n \"locust\",\n \"--exclude-labels\",\n \"duplicate,question,invalid,wontfix,cantfix,stale,no-changelog\",\n \"--header-label\",\n \"# Detailed changelog\\nThe most important changes can also be found in [the documentation](https://docs.locust.io/en/latest/changelog.html).\",\n \"--since-tag\",\n \"2.27.0\",\n # \"--since-commit\", # these cause issues\n # \"2020-07-01 00:00:00\",\n \"--future-release\",\n version,\n]\n\nprint(f\"Running command: {' '.join(cmd)}\\n\")\nsubprocess.run(cmd)\n" }, { "path": "hatch_build.py", "content": "import os\nimport subprocess\nfrom typing import Any\n\nfrom hatchling.builders.hooks.plugin.interface import BuildHookInterface # type: ignore\n\n\nclass BuildFrontend(BuildHookInterface):\n def initialize(self, version: str, build_data: dict[str, Any]) -> None:\n # Only build the front end once, in the source dist, the wheel build just copies it from there\n if self.target_name == \"sdist\":\n if not os.environ.get(\"SKIP_PRE_BUILD\"):\n print(\"Building front end...\")\n try:\n subprocess.check_output(\"yarn install\", cwd=\"locust/webui\", shell=True, stderr=subprocess.STDOUT)\n subprocess.check_output(\"yarn build\", cwd=\"locust/webui\", shell=True, stderr=subprocess.STDOUT)\n except subprocess.CalledProcessError as e:\n raise RuntimeError(f\"'{e.cmd}' got exit code {e.returncode}: {e.output}\")\n\n return super().initialize(version, build_data)\n" }, { "path": "locust/__init__.py", "content": "import os\n\nif os.getenv(\"LOCUST_PLAYWRIGHT\", None):\n print(\"LOCUST_PLAYWRIGHT setting is no longer needed (because locust-plugins no longer installs trio)\")\n print(\"Uninstall trio package and remove the setting.\")\n try:\n # preserve backwards compatibility for now\n import trio # noqa: F401\n except ModuleNotFoundError:\n # dont show a massive callstack if trio is not installed\n os._exit(1)\n\nif not os.getenv(\"LOCUST_SKIP_MONKEY_PATCH\", None):\n from gevent import monkey, queue\n\n monkey.patch_all()\n\n if not os.getenv(\"LOCUST_SKIP_URLLIB3_PATCH\", None):\n import urllib3\n\n urllib3.connectionpool.ConnectionPool.QueueCls = queue.LifoQueue\n # https://github.com/locustio/locust/issues/2812\n\nfrom ._version import version as __version__\nfrom .contrib.fasthttp import FastHttpUser\nfrom .debug import run_single_user\nfrom .event import Events\nfrom .shape import LoadTestShape\nfrom .user import wait_time\nfrom .user.markov_taskset import MarkovTaskSet, transition, transitions\nfrom .user.sequential_taskset import SequentialTaskSet\nfrom .user.task import TaskSet, tag, task\nfrom .user.users import HttpUser, User\nfrom .user.wait_time import between, constant, constant_pacing, constant_throughput\n\nevents = Events()\n\n__all__ = (\n \"SequentialTaskSet\",\n \"MarkovTaskSet\",\n \"transition\",\n \"transitions\",\n \"wait_time\",\n \"task\",\n \"tag\",\n \"TaskSet\",\n \"HttpUser\",\n \"FastHttpUser\",\n \"User\",\n \"between\",\n \"constant\",\n \"constant_pacing\",\n \"constant_throughput\",\n \"events\",\n \"LoadTestShape\",\n \"run_single_user\",\n \"HttpLocust\",\n \"Locust\",\n \"__version__\",\n)\n\n# Used for raising a DeprecationWarning if old Locust/HttpLocust is used\nfrom .util.deprecation import DeprecatedHttpLocustClass as HttpLocust\nfrom .util.deprecation import DeprecatedLocustClass as Locust\n" }, { "path": "locust/__main__.py", "content": "from .main import main\n\nmain()\n" }, { "path": "locust/argument_parser.py", "content": "from __future__ import annotations\n\nimport locust\nfrom locust import runners\nfrom locust.rpc import Message, zmqrpc\n\nimport argparse\nimport ast\nimport atexit\nimport difflib\nimport json\nimport os\nimport platform\nimport socket\nimport sys\nimport tempfile\nimport textwrap\nfrom collections import OrderedDict\nfrom typing import Any, NamedTuple\nfrom urllib.parse import urlparse\nfrom uuid import uuid4\n\nif sys.version_info >= (3, 11):\n import tomllib\nelse:\n import tomli as tomllib\n\nimport configargparse\nimport gevent\nimport requests\n\nfrom .util.directory import get_abspaths_in\nfrom .util.timespan import parse_timespan\nfrom .util.url import is_url\n\nversion = locust.__version__\n\n\nDEFAULT_CONFIG_FILES = (\"~/.locust.conf\", \"locust.conf\", \"pyproject.toml\")\n\n\n# Clean up downloaded locustfile on exit\ndef exit_handler(filename) -> None:\n try:\n os.remove(filename)\n except FileNotFoundError:\n pass # when multiple workers are running on the same machine, another one may already have deleted it\n except PermissionError:\n pass # this happens occasionally on windows on GH, maybe for the same reason?\n\n\nclass LocustArgumentParser(configargparse.ArgumentParser):\n \"\"\"Drop-in replacement for `configargparse.ArgumentParser` that adds support for\n optionally exclude arguments from the UI.\n \"\"\"\n\n def error(self, message):\n if \"unrecognized arguments:\" in message:\n bad_arg = message.split(\"unrecognized arguments:\")[1].strip().split()[0]\n options = [opt for action in self._actions for opt in action.option_strings]\n suggestion = difflib.get_close_matches(bad_arg, options, n=1)\n if suggestion:\n message += f\"\\nDid you mean '{suggestion[0]}'?\"\n self.exit(2, f\"{self.prog}: error: {message}\\n\")\n\n def add_argument(self, *args, **kwargs) -> configargparse.Action:\n \"\"\"\n This method supports the same args as ArgumentParser.add_argument(..)\n as well as the additional args below.\n\n Arguments:\n include_in_web_ui: If True (default), the argument will show in the UI.\n is_secret: If True (default is False) and include_in_web_ui is True, the argument will show in the UI with a password masked text input.\n is_required: If True (default is False) and include_in_web_ui is True, the argument will show in the UI as a required form field.\n is_multiple: If True (default is False) and include_in_web_ui is True, the argument will show in the UI as a multiple select form field.\n\n Returns:\n argparse.Action: the new argparse action\n \"\"\"\n include_in_web_ui = kwargs.pop(\"include_in_web_ui\", True)\n is_secret = kwargs.pop(\"is_secret\", False)\n is_required = kwargs.pop(\"is_required\", False)\n is_multiple = kwargs.pop(\"is_multiple\", False)\n action = super().add_argument(*args, **kwargs)\n action.include_in_web_ui = include_in_web_ui\n action.is_secret = is_secret\n action.is_required = is_required\n action.is_multiple = is_multiple\n return action\n\n @property\n def args_included_in_web_ui(self) -> dict[str, configargparse.Action]:\n return {a.dest: a for a in self._actions if hasattr(a, \"include_in_web_ui\") and a.include_in_web_ui}\n\n @property\n def secret_args_included_in_web_ui(self) -> dict[str, configargparse.Action]:\n return {\n a.dest: a\n for a in self._actions\n if a.dest in self.args_included_in_web_ui and hasattr(a, \"is_secret\") and a.is_secret\n }\n\n @property\n def required_args_included_in_web_ui(self) -> dict[str, configargparse.Action]:\n return {\n a.dest: a\n for a in self._actions\n if a.dest in self.args_included_in_web_ui and hasattr(a, \"is_required\") and a.is_required\n }\n\n @property\n def multiple_args_included_in_web_ui(self) -> dict[str, configargparse.Action]:\n return {\n a.dest: a\n for a in self._actions\n if a.dest in self.args_included_in_web_ui and hasattr(a, \"is_multiple\") and a.is_multiple\n }\n\n\nclass LocustTomlConfigParser(configargparse.TomlConfigParser):\n def parse(self, stream):\n try:\n config = tomllib.loads(stream.read())\n except Exception as e:\n raise configargparse.ConfigFileParserException(f\"Couldn't parse TOML file: {e}\")\n\n # convert to dict and filter based on section names\n result = OrderedDict()\n\n for section in self.sections:\n if data := configargparse.get_toml_section(config, section):\n for key, value in data.items():\n if isinstance(value, list):\n result[key] = value\n elif value is None:\n pass\n else:\n result[key] = str(value)\n break\n else:\n if not stream.name.endswith(\"toml\"):\n raise configargparse.ConfigFileParserException(\"Not a toml file. Fall back to DefaultConfigFileParser.\")\n\n return result\n\n\nclass LocustConfigParser(configargparse.ConfigFileParser):\n def parse(self, stream):\n if stream.name.endswith(\".toml\"):\n return LocustTomlConfigParser([\"tool.locust\"]).parse(stream)\n\n return configargparse.DefaultConfigFileParser().parse(stream)\n\n\ndef parse_locustfile_paths(paths: list[str]) -> list[str]:\n \"\"\"\n Returns a list of relative file paths.\n\n Args:\n paths (list[str]): paths taken from the -f command\n\n Returns:\n list[str]: Parsed locust file paths\n \"\"\"\n # Parse each path and unpack the returned lists as a single list\n return [parsed for path in paths for parsed in _parse_locustfile_path(path)]\n\n\ndef _parse_locustfile_path(path: str) -> list[str]:\n parsed_paths = []\n if is_url(path):\n # Download the file and use the new path as locustfile\n parsed_paths.append(download_locustfile_from_url(path))\n elif os.path.isdir(path):\n # Find all .py files in directory tree\n parsed_paths.extend(get_abspaths_in(path, extension=\".py\"))\n if not parsed_paths:\n sys.stderr.write(f\"Could not find any locustfiles in directory '{path}'\")\n sys.exit(1)\n else:\n # If file exists add the abspath\n if os.path.exists(path) and path.endswith(\".py\"):\n parsed_paths.append(os.path.abspath(path))\n else:\n note_about_file_endings = \"Ensure your locustfile ends with '.py' or is a directory with locustfiles. \"\n sys.stderr.write(f\"Could not find '{path}'. {note_about_file_endings}See --help for available options.\\n\")\n sys.exit(1)\n\n return parsed_paths\n\n\ndef download_locustfile_from_url(url: str) -> str:\n \"\"\"\n Attempt to download and save locustfile from url.\n Returns path to downloaded file.\n \"\"\"\n try:\n response = requests.get(url)\n except requests.exceptions.RequestException as e:\n sys.stderr.write(f\"Failed to get locustfile from: {url}. Exception: {e}\")\n sys.exit(1)\n else:\n try:\n # Check if response is valid python code\n ast.parse(response.text)\n except SyntaxError:\n sys.stderr.write(\n f\"Failed to get locustfile from: {url}. Response was not valid python code: '{response.text[:100]}'\"\n )\n sys.exit(1)\n\n with open(os.path.join(tempfile.gettempdir(), urlparse(url).path.split(\"/\")[-1]), \"w\") as locustfile:\n locustfile.write(response.text)\n\n atexit.register(exit_handler, locustfile.name)\n return locustfile.name\n\n\ndef get_empty_argument_parser(add_help=True, default_config_files=DEFAULT_CONFIG_FILES) -> LocustArgumentParser:\n parser = LocustArgumentParser(\n default_config_files=default_config_files,\n config_file_parser_class=LocustConfigParser,\n add_env_var_help=False,\n add_config_file_help=False,\n add_help=add_help,\n formatter_class=configargparse.RawDescriptionHelpFormatter,\n usage=configargparse.SUPPRESS,\n description=textwrap.dedent(\n \"\"\"\nUsage: locust [options] [UserClass ...]\n \"\"\"\n ),\n epilog=\"\"\"Examples:\n\n locust -f my_test.py -H https://www.example.com\n\n locust --headless -u 100 -t 20m --processes 4 MyHttpUser AnotherUser\n\n locust --headless -u 100 -r 10 -t 50 --print-stats --html \"test_report_{u}_{r}_{t}.html\"\n (The above run would generate an html file with the name \"test_report_100_10_50.html\")\n\nSee documentation for more details, including how to set options using a file or environment variables: https://docs.locust.io/en/stable/configuration.html\"\"\",\n )\n parser.add_argument(\n \"-f\",\n \"--locustfile\",\n metavar=\"\",\n default=\"locustfile.py\",\n help=\"The Python file or module that contains your test, e.g. 'my_test.py'. Accepts multiple comma-separated .py files, a package name/directory or a url to a remote locustfile. Defaults to 'locustfile.py'.\",\n env_var=\"LOCUST_LOCUSTFILE\",\n )\n\n parser.add_argument(\n \"--config\",\n is_config_file_arg=True,\n help=\"File to read additional configuration from. See https://docs.locust.io/en/stable/configuration.html#configuration-file\",\n metavar=\"\",\n )\n\n return parser\n\n\ndef download_locustfile_from_master(master_host: str, master_port: int) -> str:\n client_id = socket.gethostname() + \"_download_locustfile_\" + uuid4().hex\n tempclient = zmqrpc.Client(master_host, master_port, client_id)\n got_reply = False\n\n def ask_for_locustfile():\n while not got_reply:\n tempclient.send(Message(\"locustfile\", {\"version\": version}, client_id))\n gevent.sleep(1)\n\n def log_warning():\n gevent.sleep(10)\n while not got_reply:\n sys.stderr.write(\"Waiting to connect to master to receive locustfile...\\n\")\n gevent.sleep(60)\n\n def wait_for_reply():\n return tempclient.recv()\n\n gevent.spawn(ask_for_locustfile)\n gevent.spawn(log_warning)\n\n try:\n # wait same time as for client_ready ack. not that it is really relevant...\n msg = gevent.spawn(wait_for_reply).get(timeout=runners.CONNECT_TIMEOUT * runners.CONNECT_RETRY_COUNT)\n got_reply = True\n except gevent.Timeout:\n sys.stderr.write(\n f\"Got no locustfile response from master, gave up after {runners.CONNECT_TIMEOUT * runners.CONNECT_RETRY_COUNT}s\\n\"\n )\n sys.exit(1)\n\n if msg.type != \"locustfile\":\n sys.stderr.write(f\"Got wrong message type from master {msg.type}\\n\")\n sys.exit(1)\n\n if \"error\" in msg.data:\n sys.stderr.write(f\"Got error from master: {msg.data['error']}\\n\")\n sys.exit(1)\n\n tempclient.close()\n return msg.data.get(\"locustfiles\", [])\n\n\ndef parse_locustfile_option(args=None) -> tuple[argparse.Namespace, list[str]]:\n \"\"\"\n Construct a command line parser that is only used to parse the -f argument so that we can\n import the test scripts in case any of them adds additional command line arguments to the\n parser\n\n Returns:\n parsed_paths (List): List of locustfile paths\n \"\"\"\n parser = get_empty_argument_parser(add_help=False)\n parser.add_argument(\n \"-h\",\n \"--help\",\n action=\"store_true\",\n default=False,\n )\n parser.add_argument(\n \"--version\",\n \"-V\",\n action=\"store_true\",\n default=False,\n )\n # the following arguments are only used for downloading the locustfile from master\n parser.add_argument(\n \"--worker\",\n action=\"store_true\",\n env_var=\"LOCUST_MODE_WORKER\",\n )\n parser.add_argument(\n \"--master\", # this is just here to prevent argparse from giving the dreaded \"ambiguous option: --master could match --master-host, --master-port\"\n action=\"store_true\",\n env_var=\"LOCUST_MODE_MASTER\",\n )\n parser.add_argument(\n \"--master-host\",\n default=\"127.0.0.1\",\n env_var=\"LOCUST_MASTER_NODE_HOST\",\n )\n parser.add_argument(\n \"--master-port\",\n type=int,\n default=5557,\n env_var=\"LOCUST_MASTER_NODE_PORT\",\n )\n\n options, _ = parser.parse_known_args(args=args)\n\n if options.help or options.version:\n # if --help or --version is specified we'll call parse_args which will print the help/version message\n get_parser().parse_args(args=args)\n\n return options\n\n\ndef get_locustfiles_locally(options):\n if options.locustfile == \"-\":\n locustfile_list = retrieve_locustfiles_from_master(options)\n else:\n locustfile_list = [f.strip() for f in options.locustfile.split(\",\")]\n\n return parse_locustfile_paths(locustfile_list)\n\n\ndef parse_locustfiles_from_master(locustfile_sources) -> list[str]:\n locustfiles = []\n\n for source in locustfile_sources:\n if \"contents\" in source:\n filename = source[\"filename\"]\n file_contents = source[\"contents\"]\n\n with open(os.path.join(tempfile.gettempdir(), filename), \"w\", encoding=\"utf-8\") as locustfile:\n locustfile.write(file_contents)\n\n locustfiles.append(locustfile.name)\n else:\n locustfiles.append(source)\n\n return locustfiles\n\n\ndef retrieve_locustfiles_from_master(options) -> list[str]:\n if not options.worker:\n sys.stderr.write(\n \"locustfile was set to '-' (meaning to download from master) but --worker was not specified.\\n\"\n )\n sys.exit(1)\n # having this in argument_parser module is a bit weird, but it needs to be done early\n locustfile_sources = download_locustfile_from_master(options.master_host, options.master_port)\n return parse_locustfiles_from_master(locustfile_sources)\n\n\n# A hack for setting up an action that raises ArgumentError with configurable error messages.\n# This is meant to be used to immediately block use of deprecated arguments with some helpful messaging.\n\n\ndef raise_argument_type_error(err_msg):\n class ErrorRaisingAction(configargparse.Action):\n def __call__(self, parser, namespace, values, option_string=None):\n raise configargparse.ArgumentError(self, err_msg)\n\n return ErrorRaisingAction\n\n\n# Definitions for some \"types\" to use with the arguments\n\n\ndef timespan(time_str) -> int:\n try:\n return parse_timespan(time_str)\n except ValueError as e:\n raise configargparse.ArgumentTypeError(str(e))\n\n\ndef positive_integer(string) -> int:\n try:\n value = int(string)\n except ValueError:\n raise configargparse.ArgumentTypeError(f\"invalid int value: '{string}'\")\n\n if value < 1:\n raise configargparse.ArgumentTypeError(\n f\"Invalid --expect-workers argument ({value}), must be a positive number\"\n )\n\n return value\n\n\ndef gt_zero(t):\n def checker(value):\n v = t(value)\n if v <= 0:\n raise argparse.ArgumentTypeError(\"must be > 0\")\n return v\n\n return checker\n\n\ndef json_user_config(string):\n try:\n if string.endswith(\".json\"):\n with open(string) as file:\n user_config = json.load(file)\n else:\n user_config = json.loads(string)\n\n if not isinstance(user_config, list):\n user_config = [user_config]\n\n for config in user_config:\n if \"user_class_name\" not in config:\n raise configargparse.ArgumentTypeError(\"The user config must specify a user_class_name\")\n\n return user_config\n\n except json.decoder.JSONDecodeError as e:\n raise configargparse.ArgumentTypeError(f\"The --config-users argument must be a valid JSON string or file: {e}\")\n\n except FileNotFoundError as e:\n raise configargparse.ArgumentTypeError(str(e))\n\n\ndef setup_parser_arguments(parser):\n \"\"\"\n Setup command-line options\n\n Takes a configargparse.ArgumentParser as argument and calls it's add_argument\n for each of the supported arguments\n \"\"\"\n parser._optionals.title = \"Common options\"\n parser.add_argument(\n \"-H\",\n \"--host\",\n metavar=\"\",\n help=\"Host to load test, in the following format: https://www.example.com\",\n env_var=\"LOCUST_HOST\",\n )\n parser.add_argument(\n \"-u\",\n \"--users\",\n type=int,\n metavar=\"\",\n dest=\"num_users\",\n help=\"Peak number of concurrent Locust users. Primarily used together with --headless or --autostart. Can be changed during a test by keyboard inputs w, W (spawn 1, 10 users) and s, S (stop 1, 10 users)\",\n env_var=\"LOCUST_USERS\",\n )\n parser.add_argument(\n \"-r\",\n \"--spawn-rate\",\n type=gt_zero(float),\n metavar=\"\",\n help=\"Rate to spawn users at (users per second). Primarily used together with --headless or --autostart\",\n env_var=\"LOCUST_SPAWN_RATE\",\n )\n parser.add_argument(\n \"-t\",\n \"--run-time\",\n metavar=\"