Skip to content

004-testing.md

Latest commit

 

History

History
102 lines (76 loc) · 2.66 KB

004-testing.md

File metadata and controls

102 lines (76 loc) · 2.66 KB
Raw

Testing

Install development dependencies:

python -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"

Run the local validation suite:

ruff check .
ruff format --check .
mypy
pytest
python -m build

Local deterministic tests

The default pytest suite does not require a real engine:

pytest tests/unit tests/integration tests/examples

It covers:

Suite Coverage
tests/unit Config resolution, protocol framing, streams, tunnel objects, API helpers, direct ASGI and WSGI helpers, webhook signatures.
tests/integration TLS fake engine, control-channel lifecycle, tunnel creation and close, stream handshakes, zero-RTT, proxy delivery, timeout and retry behavior.
tests/examples Syntax compilation for every example plus FastAPI, Flask, and Django receivers with valid and invalid webhook signatures.

Real-engine e2e

Real-engine tests are opt-in:

RSTREAM_PYTHON_E2E=1 pytest tests/e2e

The private-tunnel e2e matrix creates a tunnel, dials it by name and ID, runs zero-RTT both enabled and disabled, exercises concurrent dials, and validates a direct WSGI handler through a private tunnel.

Published HTTP tunnel checks are opt-in because they require the engine to serve published hosts. They cover both managed local forwarding and direct ASGI serving:

RSTREAM_PYTHON_E2E=1 \
RSTREAM_PYTHON_E2E_PUBLISHED=1 \
pytest tests/e2e

Published TCP checks have a separate opt-in because the project and engine must allow published TCP tunnels and the allocated port must be reachable:

RSTREAM_PYTHON_E2E=1 \
RSTREAM_PYTHON_E2E_PUBLISHED_TCP=1 \
pytest tests/e2e

Set RSTREAM_PYTHON_E2E_PUBLISHED_CONNECT_HOST when the hostname returned by a local engine is not directly resolvable from the test process.

When bypassing the shared rstream config file, pass explicit engine settings:

RSTREAM_PYTHON_E2E_ENGINE="c.localhost.rstream.io:9443" \
RSTREAM_PYTHON_E2E_TOKEN="$RSTREAM_AUTHENTICATION_TOKEN" \
RSTREAM_PYTHON_E2E_TLS_INSECURE=1 \
pytest tests/e2e

If the local engine uses a private CA, prefer RSTREAM_PYTHON_E2E_CA_FILE="/path/to/local-ca.pem" instead of RSTREAM_PYTHON_E2E_TLS_INSECURE=1. RSTREAM_PYTHON_E2E_SERVER_NAME is only needed when the certificate name intentionally differs from the engine host.

Local EE engine

The engine repository documents the full local setup in its Enterprise Edition runtime README:

cmd/rstream-engine-ee/README.md

Start the EE engine, select the test context, then run:

RSTREAM_CONTEXT=tests \
RSTREAM_PYTHON_E2E=1 \
RSTREAM_PYTHON_E2E_PUBLISHED=1 \
RSTREAM_PYTHON_E2E_PUBLISHED_TCP=1 \
pytest tests/e2e