Introduce Python binding test suite and CI job

Author: HudsonGraeme

.github/workflows/ci.yml

@@ -125,6 +125,19 @@ jobs:
           files: lcov.info
           fail_ci_if_error: false
 
+  python-test:
+    name: Python tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7
+        with:
+          toolchain: stable
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
+      - uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
+      - run: uv venv && uv pip install maturin pytest pytest-timeout && uv run maturin develop --release && uv run pytest tests/ -v --timeout=30
+        working-directory: crates/btlightning-py
+
   subtensor:
     name: Subtensor integration
     runs-on: ubuntu-latest

.gitignore

@@ -209,6 +209,8 @@ benchmarks/uv.lock
 *.gif
 plots/
 
-# Test files
-test_*.py
-*_test.py
+# Ad-hoc test scripts (not in test suites)
+/test_*.py
+/*_test.py
+/benchmarks/test_*.py
+/benchmarks/*_test.py

crates/btlightning-py/pyproject.toml

@@ -17,6 +17,13 @@ classifiers = [
 ]
 dependencies = ["typing_extensions~=4.0"]
 
+[project.optional-dependencies]
+test = ["pytest>=8.0", "pytest-timeout>=2.0"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+timeout = 30
+
 [tool.maturin]
 python-source = "python"
 module-name = "btlightning._native"

crates/btlightning-py/tests/conftest.py

@@ -0,0 +1,43 @@
+import socket
+import threading
+import time
+
+import pytest
+
+from btlightning import Lightning, LightningServer
+
+MINER_SEED = bytes([1] * 32)
+VALIDATOR_SEED = bytes([2] * 32)
+MINER_HOTKEY = "5CcyqxXnJucaCnQQvvUg5EPzj1uoNAxACZvzArHw5aVDvgNH"
+VALIDATOR_HOTKEY = "5CfCr47V5Dte6bwxNBE8K9oNnQd9fiay6aDEEkgYtFv7w4Fq"
+
+
+@pytest.fixture()
+def free_port():
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+@pytest.fixture()
+def echo_server(free_port):
+    server = LightningServer(miner_hotkey=MINER_HOTKEY, host="127.0.0.1", port=free_port)
+    server.set_miner_keypair(MINER_SEED)
+    server.register_synapse_handler("echo", lambda data: data)
+    server.start()
+    t = threading.Thread(target=server.serve_forever, daemon=True)
+    t.start()
+    time.sleep(0.05)
+    yield server, free_port
+    server.stop()
+
+
+@pytest.fixture()
+def client_and_axon(echo_server):
+    _, port = echo_server
+    client = Lightning(wallet_hotkey=VALIDATOR_HOTKEY)
+    client.set_validator_keypair(VALIDATOR_SEED)
+    axon = {"hotkey": MINER_HOTKEY, "ip": "127.0.0.1", "port": port}
+    client.initialize_connections([axon])
+    yield client, axon
+    client.close()

crates/btlightning-py/tests/test_client.py

@@ -0,0 +1,45 @@
+from btlightning import Lightning
+
+from conftest import VALIDATOR_HOTKEY, VALIDATOR_SEED
+
+
+def test_constructor_defaults():
+    client = Lightning(wallet_hotkey=VALIDATOR_HOTKEY)
+    assert client.wallet_hotkey == VALIDATOR_HOTKEY
+    client.close()
+
+
+def test_constructor_custom_config():
+    client = Lightning(
+        wallet_hotkey=VALIDATOR_HOTKEY,
+        connect_timeout_secs=5,
+        idle_timeout_secs=30,
+        keep_alive_interval_secs=10,
+        reconnect_initial_backoff_secs=1,
+        reconnect_max_backoff_secs=60,
+        reconnect_max_retries=3,
+        max_frame_payload_bytes=65536,
+        max_stream_payload_bytes=1048576,
+    )
+    assert client.wallet_hotkey == VALIDATOR_HOTKEY
+    client.close()
+
+
+def test_set_validator_keypair():
+    client = Lightning(wallet_hotkey=VALIDATOR_HOTKEY)
+    client.set_validator_keypair(VALIDATOR_SEED)
+    client.close()
+
+
+def test_set_python_signer():
+    client = Lightning(wallet_hotkey=VALIDATOR_HOTKEY)
+    client.set_python_signer(lambda msg: b"\x00" * 64)
+    client.close()
+
+
+def test_get_connection_stats_empty():
+    client = Lightning(wallet_hotkey=VALIDATOR_HOTKEY)
+    stats = client.get_connection_stats()
+    assert "total_connections" in stats
+    assert "active_miners" in stats
+    client.close()

crates/btlightning-py/tests/test_errors.py

@@ -0,0 +1,43 @@
+import pytest
+
+from btlightning import Lightning
+
+from conftest import MINER_HOTKEY, VALIDATOR_HOTKEY
+
+
+def test_missing_synapse_type(client_and_axon):
+    client, axon = client_and_axon
+    with pytest.raises(KeyError, match="synapse_type"):
+        client.query_axon(axon, {"data": {"msg": "hello"}})
+
+
+def test_missing_hotkey(client_and_axon):
+    client, _ = client_and_axon
+    with pytest.raises(KeyError, match="hotkey"):
+        client.query_axon({"ip": "127.0.0.1", "port": 1234}, {"synapse_type": "echo", "data": {}})
+
+
+def test_missing_ip(client_and_axon):
+    client, _ = client_and_axon
+    with pytest.raises(KeyError, match="ip"):
+        client.query_axon({"hotkey": MINER_HOTKEY, "port": 1234}, {"synapse_type": "echo", "data": {}})
+
+
+def test_missing_port(client_and_axon):
+    client, _ = client_and_axon
+    with pytest.raises(KeyError, match="port"):
+        client.query_axon({"hotkey": MINER_HOTKEY, "ip": "127.0.0.1"}, {"synapse_type": "echo", "data": {}})
+
+
+def test_query_without_signer():
+    client = Lightning(wallet_hotkey=VALIDATOR_HOTKEY)
+    axon = {"hotkey": MINER_HOTKEY, "ip": "127.0.0.1", "port": 9999}
+    with pytest.raises(Exception):
+        client.query_axon(axon, {"synapse_type": "echo", "data": {}})
+    client.close()
+
+
+def test_invalid_timeout(client_and_axon):
+    client, axon = client_and_axon
+    with pytest.raises(Exception):
+        client.query_axon(axon, {"synapse_type": "echo", "data": {}}, timeout_secs=-1.0)

crates/btlightning-py/tests/test_multi_handler.py

@@ -0,0 +1,41 @@
+import socket
+import threading
+import time
+
+from btlightning import Lightning, LightningServer
+
+from conftest import MINER_HOTKEY, MINER_SEED, VALIDATOR_HOTKEY, VALIDATOR_SEED
+
+
+def test_two_handlers_on_same_server():
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        port = s.getsockname()[1]
+
+    def upper_handler(data):
+        return {"result": data["text"].upper()}
+
+    server = LightningServer(miner_hotkey=MINER_HOTKEY, host="127.0.0.1", port=port)
+    server.set_miner_keypair(MINER_SEED)
+    server.register_synapse_handler("echo", lambda data: data)
+    server.register_synapse_handler("upper", upper_handler)
+    server.start()
+    t = threading.Thread(target=server.serve_forever, daemon=True)
+    t.start()
+    time.sleep(0.05)
+
+    client = Lightning(wallet_hotkey=VALIDATOR_HOTKEY)
+    client.set_validator_keypair(VALIDATOR_SEED)
+    axon = {"hotkey": MINER_HOTKEY, "ip": "127.0.0.1", "port": port}
+    client.initialize_connections([axon])
+
+    echo_resp = client.query_axon(axon, {"synapse_type": "echo", "data": {"msg": "hi"}})
+    assert echo_resp["success"] is True
+    assert echo_resp["data"]["msg"] == "hi"
+
+    upper_resp = client.query_axon(axon, {"synapse_type": "upper", "data": {"text": "hello"}})
+    assert upper_resp["success"] is True
+    assert upper_resp["data"]["result"] == "HELLO"
+
+    client.close()
+    server.stop()

crates/btlightning-py/tests/test_roundtrip.py

@@ -0,0 +1,34 @@
+def test_echo_roundtrip(client_and_axon):
+    client, axon = client_and_axon
+    resp = client.query_axon(axon, {"synapse_type": "echo", "data": {"msg": "hello"}})
+    assert resp["success"] is True
+    assert resp["error"] is None
+    assert resp["data"]["msg"] == "hello"
+    assert resp["latency_ms"] >= 0
+
+
+def test_large_payload(client_and_axon):
+    client, axon = client_and_axon
+    payload = b"\x42" * 100_000
+    resp = client.query_axon(axon, {"synapse_type": "echo", "data": {"payload": payload}})
+    assert resp["success"] is True
+    assert resp["data"]["payload"] == payload
+
+
+def test_query_with_timeout(client_and_axon):
+    client, axon = client_and_axon
+    resp = client.query_axon(
+        axon,
+        {"synapse_type": "echo", "data": {"val": 42}},
+        timeout_secs=5.0,
+    )
+    assert resp["success"] is True
+    assert resp["data"]["val"] == 42
+
+
+def test_multiple_sequential_queries(client_and_axon):
+    client, axon = client_and_axon
+    for i in range(10):
+        resp = client.query_axon(axon, {"synapse_type": "echo", "data": {"i": i}})
+        assert resp["success"] is True
+        assert resp["data"]["i"] == i

crates/btlightning-py/tests/test_server.py

@@ -0,0 +1,63 @@
+import socket
+import threading
+import time
+
+from btlightning import LightningServer
+
+from conftest import MINER_HOTKEY, MINER_SEED
+
+
+def test_constructor_defaults():
+    server = LightningServer(miner_hotkey=MINER_HOTKEY, host="127.0.0.1", port=0)
+    server.stop()
+
+
+def test_constructor_custom_config():
+    server = LightningServer(
+        miner_hotkey=MINER_HOTKEY,
+        host="127.0.0.1",
+        port=0,
+        max_signature_age_secs=60,
+        idle_timeout_secs=30,
+        keep_alive_interval_secs=10,
+        nonce_cleanup_interval_secs=120,
+        max_nonce_entries=5000,
+        max_frame_payload_bytes=65536,
+    )
+    server.stop()
+
+
+def test_start_stop_lifecycle():
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        port = s.getsockname()[1]
+
+    server = LightningServer(miner_hotkey=MINER_HOTKEY, host="127.0.0.1", port=port)
+    server.set_miner_keypair(MINER_SEED)
+    server.register_synapse_handler("echo", lambda data: data)
+    server.start()
+    t = threading.Thread(target=server.serve_forever, daemon=True)
+    t.start()
+    time.sleep(0.05)
+
+    stats = server.get_connection_stats()
+    assert "total_connections" in stats
+    assert "verified_connections" in stats
+
+    server.stop()
+
+
+def test_get_connection_stats():
+    server = LightningServer(miner_hotkey=MINER_HOTKEY, host="127.0.0.1", port=0)
+    server.set_miner_keypair(MINER_SEED)
+    server.register_synapse_handler("echo", lambda data: data)
+    server.start()
+    t = threading.Thread(target=server.serve_forever, daemon=True)
+    t.start()
+    time.sleep(0.05)
+
+    stats = server.get_connection_stats()
+    assert stats["total_connections"] == "0"
+    assert stats["verified_connections"] == "0"
+
+    server.stop()

crates/btlightning-py/tests/test_streaming.py

@@ -0,0 +1,38 @@
+import socket
+import threading
+import time
+
+from btlightning import Lightning, LightningServer
+
+from conftest import MINER_HOTKEY, MINER_SEED, VALIDATOR_HOTKEY, VALIDATOR_SEED
+
+
+def test_streaming_handler():
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        port = s.getsockname()[1]
+
+    chunks = [b"chunk-1", b"chunk-2", b"chunk-3"]
+
+    def stream_handler(data):
+        return iter(chunks)
+
+    server = LightningServer(miner_hotkey=MINER_HOTKEY, host="127.0.0.1", port=port)
+    server.set_miner_keypair(MINER_SEED)
+    server.register_streaming_handler("stream", stream_handler)
+    server.start()
+    t = threading.Thread(target=server.serve_forever, daemon=True)
+    t.start()
+    time.sleep(0.05)
+
+    client = Lightning(wallet_hotkey=VALIDATOR_HOTKEY)
+    client.set_validator_keypair(VALIDATOR_SEED)
+    axon = {"hotkey": MINER_HOTKEY, "ip": "127.0.0.1", "port": port}
+    client.initialize_connections([axon])
+
+    stream = client.query_axon_stream(axon, {"synapse_type": "stream", "data": {}})
+    received = list(stream)
+    assert received == chunks
+
+    client.close()
+    server.stop()