gunicorn/tests/docker/uwsgi/README.md

uWSGI Protocol Docker Integration Tests

This directory contains Docker-based integration tests that verify gunicorn's uWSGI binary protocol implementation works correctly with nginx's uwsgi_pass directive.

Architecture

[pytest] --HTTP--> [nginx:8080] --uwsgi_pass--> [gunicorn:8000]

The tests make HTTP requests to nginx, which proxies them to gunicorn using the uWSGI binary protocol. This validates the complete request/response cycle through the protocol.

Prerequisites

• Docker
• Docker Compose (v2)
• Python 3.8+
• pytest
• requests

Running Tests

From repository root:

# Run all uWSGI integration tests
pytest tests/docker/uwsgi/ -v

# Run specific test class
pytest tests/docker/uwsgi/ -v -k TestBasicRequests

# Skip Docker tests (for CI environments without Docker)
pytest tests/ -v -m "not docker"

Manual testing:

cd tests/docker/uwsgi

# Start services
docker compose up -d

# Wait for services to be healthy
docker compose ps

# Test endpoints
curl http://localhost:8080/
curl -X POST -d "test body" http://localhost:8080/echo
curl http://localhost:8080/headers
curl "http://localhost:8080/query?foo=bar"
curl http://localhost:8080/environ
curl http://localhost:8080/error/404
curl http://localhost:8080/large > /dev/null  # 1MB response

# View logs
docker compose logs gunicorn
docker compose logs nginx

# Stop services
docker compose down -v

Test Categories

Category	Description
TestBasicRequests	GET, POST, query strings, large bodies
TestHeaderPreservation	Custom headers, Host, Content-Type, User-Agent
TestKeepAlive	Multiple requests per connection
TestErrorResponses	HTTP error codes (400, 404, 500, etc.)
TestEnvironVariables	WSGI environ: REQUEST_METHOD, PATH_INFO, etc.
TestLargeResponses	1MB response body streaming
TestConcurrency	Parallel request handling
TestSpecialCases	Edge cases: binary data, unicode, long headers

Files

File	Purpose
docker-compose.yml	Orchestrates nginx + gunicorn containers
Dockerfile.gunicorn	Builds gunicorn image with test app
Dockerfile.nginx	Builds nginx with uwsgi config
nginx.conf	nginx configuration using uwsgi_pass
uwsgi_params	Standard uwsgi parameter mappings
app.py	Test WSGI application with multiple endpoints
conftest.py	pytest fixtures for Docker lifecycle
test_uwsgi_integration.py	Test cases

Test App Endpoints

Endpoint	Method	Description
/	GET	Basic hello response
/echo	POST	Echo request body
/headers	GET/POST	Return received headers as JSON
/environ	GET/POST	Return WSGI environ as JSON
/query	GET	Return query params as JSON
/json	POST	Parse and echo JSON body
/error/{code}	GET	Return specified HTTP error
/large	GET	Return 1MB response

Gunicorn Configuration

The gunicorn container runs with:

gunicorn \
  --protocol uwsgi \
  --uwsgi-allow-from "*" \
  --bind 0.0.0.0:8000 \
  --workers 2 \
  --log-level debug \
  app:application

Key settings:

• --protocol uwsgi: Enable uWSGI binary protocol
• --uwsgi-allow-from "*": Accept connections from Docker network IPs

Troubleshooting

Services won't start

Check Docker logs:

docker compose logs

Connection refused

Wait for health checks:

docker compose ps  # Check health status

Tests timing out

Increase STARTUP_TIMEOUT in conftest.py or check if ports are in use:

lsof -i :8080
lsof -i :8000

Rebuild after code changes

docker compose build --no-cache
docker compose up -d