Running Tests

Prerequisites

Install uv.

Test suites

Suite	Location	What it tests
Unit tests	`python_modules/proxy-hopper/tests/`	Core package — config, pool, handlers, auth, identity, CLI, hot-reload
Integration tests	`python_modules/proxy-hopper-testserver/tests/`	End-to-end — TargetManager + MockProxy + UpstreamServer
Contract tests	`python_modules/tests/`	`IPPoolStore` + `DynamicConfigStore` against both backends
Redis tests	`python_modules/proxy-hopper-redis/tests/`	Redis backend internals — requires a running Redis instance

# Core unit tests
cd python_modules/proxy-hopper
uv sync --all-extras
uv run pytest

# Integration tests (no external dependencies)
cd python_modules/proxy-hopper-testserver
uv sync
uv run pytest

# Cross-backend contract tests (memory + fakeredis, no external dependencies)
cd python_modules/tests
uv sync
uv run pytest

# Redis backend tests (requires Redis on localhost:6379)
cd python_modules/proxy-hopper-redis
uv sync --all-extras
uv run pytest

Running Redis locally

docker run -d -p 6379:6379 redis:7-alpine

Integration tests run against both the memory backend and a fakeredis backend by default. To run against a real Redis instance:

REDIS_URL=redis://localhost:6379/1 uv run pytest

Test options

# Verbose output
uv run pytest -v

# Short traceback (used in CI)
uv run pytest --tb=short -q

# Run a specific test file
uv run pytest tests/test_pool.py

# Run tests matching a keyword
uv run pytest -k "quarantine"

# Run a specific test class
uv run pytest tests/test_auth_integration.py::TestApiKeyAuth

Integration test utilities

The proxy-hopper-testserver package provides test doubles for integration tests:

UpstreamServer — a controllable aiohttp HTTP server. Set it to respond with 200, 429, 503, hang, or close connections on demand.
MockProxy — a TCP server that simulates an external proxy IP. Can forward, refuse, hang, or return error responses.
MockProxyPool — manages a set of MockProxy instances as a named IP pool.

See the proxy-hopper-testserver README for full usage.

CI

Tests run on every push via GitHub Actions. The workflow:

Runs the core unit tests
Runs the integration tests (fakeredis)
Runs the cross-backend contract tests (memory + fakeredis)
Runs the Redis backend tests against a real Redis service container
Builds the Docker image and validates it starts correctly

All four suites must pass before a PR can be merged.

Getting Started

Concepts

For Administrators

For Developers

For Contributors

Running Tests

Prerequisites

Test suites

Running tests

Running Redis locally

Test options

Integration test utilities

CI

​Prerequisites

​Test suites

​Running tests

​Running Redis locally

​Test options

​Integration test utilities

​CI

Prerequisites

Test suites

Running tests

Running Redis locally

Test options

Integration test utilities

CI