Metadata-Version: 2.4
Name: adc-locust
Version: 0.2.0
Summary: A Textual TUI for load-testing Citrix ADC (NetScaler) load balancing and content switching with Locust
License-Expression: MIT
License-File: LICENSE
Keywords: citrix,netscaler,adc,load-testing,load-balancer,locust,textual,tui,nitro-api
Author: Michael MacKenna
Author-email: mmackenna@unitedfiregroup.com
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Testing :: Traffic Generation
Classifier: Topic :: System :: Networking
Classifier: Topic :: Terminals
Classifier: Typing :: Typed
Requires-Dist: locust (>=2.46.5,<3.0.0)
Requires-Dist: nitro-python (==13.1.53.24)
Requires-Dist: python-dotenv (>=1.0.1,<2.0.0)
Requires-Dist: textual (>=8.2.8,<9.0.0)
Project-URL: Changelog, https://github.com/mmackenna/adc-locust/releases
Project-URL: Documentation, https://mmackenna.github.io/adc-locust/
Project-URL: Homepage, https://mmackenna.github.io/adc-locust/
Project-URL: Issues, https://github.com/mmackenna/adc-locust/issues
Project-URL: Repository, https://github.com/mmackenna/adc-locust
Description-Content-Type: text/markdown

# adc-locust

[![PyPI](https://img.shields.io/pypi/v/adc-locust)](https://pypi.org/project/adc-locust/)
[![Python versions](https://img.shields.io/pypi/pyversions/adc-locust)](https://pypi.org/project/adc-locust/)
[![License](https://img.shields.io/pypi/l/adc-locust)](https://pypi.org/project/adc-locust/)

`adc-locust` is a [Textual](https://textual.textualize.io/) 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/>

```sh
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](#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)

```sh
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:

```env
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](docs/index.md) for details, including how content-switched
vservers and persistence-vs-fairness modes are handled.

## Development

```sh
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`.

