adc-locust

adc-locust is a Textual terminal UI for load-testing the load balancing and content switching behavior of Citrix ADC (NetScaler) appliances. It reads existing configuration read-only through the Citrix Nitro API SDK and drives traffic with Locust to confirm whether load is actually distributed the way the configuration implies.

Full documentation: https://mmackenna.github.io/adc-locust/

Installation

adc-locust is published on PyPI: https://pypi.org/project/adc-locust/

pip install adc-locust
adc-locust

Note: adc-locust depends on the Citrix Nitro API SDK (nitro-python), which Citrix does not publish to PyPI. See Vendored dependency below — installing from PyPI requires either the vendored wheel from this repository or your own copy of nitro-python installed separately.

Setup (from source)

poetry install
poetry run adc-locust

adc-locust needs Nitro API credentials and the NetScaler address to test, read from a .env file in the current directory:

NITRO_URL=netscaler.example.com
NITRO_USER=nitro-api-user
NITRO_PASS=change-me
NITRO_VERIFY_TLS=false

Copy .env.example to get started, or just run adc-locust — if no usable .env is found it walks you through creating one interactively before loading the vserver list. Use --env-file /path/to/.env or ADC_LOCUST_ENV_FILE to use a different path. Never commit a real .env file; it's already excluded in .gitignore.

What it does

1. Lists LB vservers on the NetScaler that balance traffic across more than one bound service (read-only Nitro queries).
2. Lets you pick one and configure a Locust load test against it — either fairness mode (clears cookies every request, reveals the raw LB algorithm) or persistence mode (keeps cookies, confirms stickiness). Vservers reachable only through Content Switching are automatically routed through their CS vserver.
3. Runs Locust headless and reports aggregate stats plus a per-service traffic delta (via Nitro service_stats), flagging services that received far less traffic than expected.

See the docs for details, including how content-switched vservers and persistence-vs-fairness modes are handled.

Development

poetry install
poetry run pytest
poetry run ruff check .
poetry run mypy src/adc_locust
poetry run mkdocs build --strict

Vendored dependency

The Nitro Python SDK (nitro-python) is not published on PyPI. Its wheel is vendored in vendor/ and referenced as a local path dependency in pyproject.toml, matching how the source Nitro scripts this project is built from vendor it for uv.