Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""Persistent sd-server manager tests with faked Popen and httpx."""
from __future__ import annotations
import base64
import io
import threading
import pytest
from PIL import Image
from core.inference import sd_cpp_server as srv
from core.inference.sd_cpp_args import SdCppModelFiles
from core.inference.sd_cpp_engine import SdCppCancelled
from core.inference.sd_cpp_server import SdCppServer
_FILES = SdCppModelFiles(diffusion_model = "/m/z.gguf", vae = "/m/vae.sft", llm = "/m/llm.sft")
def _png_b64(shade: int) -> str:
buf = io.BytesIO()
Image.new("RGB", (1, 1), (shade, shade, shade)).save(buf, format = "PNG")
return base64.b64encode(buf.getvalue()).decode()
class _FakePopen:
"""Popen stand-in: stdout yields scripted lines, then blocks until exit so the drain thread lives."""
def __init__(
self,
lines = (),
exit_code = None,
):
self.pid = 4242
self._lines = list(lines)
self._exit = exit_code
self.returncode = exit_code
self.terminated = False
self.killed = False
self._done = threading.Event()
if exit_code is not None:
self._done.set()
@property
def stdout(self):
def _gen():
for ln in self._lines:
yield ln
self._done.wait()
return _gen()
def poll(self):
return self._exit
def terminate(self):
self.terminated = True
self._exit = 0
self.returncode = 0
self._done.set()
def wait(self, timeout = None):
self._done.wait(timeout)
if self._exit is None:
self._exit = 0
self.returncode = 0
return self.returncode
def kill(self):
self.killed = True
self._exit = -9
self.returncode = -9
self._done.set()
class _Resp:
def __init__(
self,
status_code,
payload = None,
text = "",
bad_json = False,
):
self.status_code = status_code
self._payload = payload if payload is not None else {}
self.text = text
self._bad_json = bad_json
def json(self):
if self._bad_json:
raise ValueError("not json")
return self._payload
class _FakeClient:
def __init__(
self,
*,
get = None,
post = None,
):
self._get = get or (lambda url: _Resp(200, {}))
self._post = post or (lambda url, json: _Resp(202, {"id": "job1"}))
self.get_urls = []
self.get_headers = []
self.post_calls = []
self.closed = False
def get(
self,
url,
headers = None,
timeout = None,
):
self.get_urls.append(url)
self.get_headers.append(headers)
return self._get(url)
def post(
self,
url,
json = None,
timeout = None,
):
self.post_calls.append((url, json))
return self._post(url, json)
def close(self):
self.closed = True
@pytest.fixture
def patched(monkeypatch):
"""Neutralise process-lifetime side effects for the manager under test."""
monkeypatch.setattr(srv, "adopt_pid", lambda pid: None)
monkeypatch.setattr(srv, "forget_pid", lambda pid: None)
monkeypatch.setattr(srv, "child_popen_kwargs", lambda: {})
monkeypatch.setattr(srv, "windows_hidden_subprocess_kwargs", lambda: {})
return monkeypatch
def _server_with(popen, client):
s = SdCppServer("/x/sd-server")
s._client = client
s._process = popen
s.port = 1234
return s
def test_start_becomes_ready_when_capabilities_200(patched, caplog):
patched.setattr(srv, "_verbose_native_logs", lambda: False)
caplog.set_level("INFO", logger = srv.__name__)
popen = _FakePopen(lines = ["loading model", "listening on: http://127.0.0.1:1"])
patched.setattr(srv.subprocess, "Popen", lambda *a, **k: popen)
client = _FakeClient(get = lambda url: _Resp(200, {"model": {"path": "/m/z.gguf"}}))
s = _server_with(popen, client)
s.start(_FILES, startup_timeout = 5.0)
assert s.is_alive() is True
# Readiness probes must not leave a pooled connection for generation to reuse.
assert client.get_headers and all(h == {"Connection": "close"} for h in client.get_headers)
assert s.port is not None
messages = [record.getMessage() for record in caplog.records if record.name == srv.__name__]
start = next(message for message in messages if message.startswith("starting sd-server:"))
assert start.startswith("starting sd-server: mode=server model=z.gguf port=")
assert "/m/z.gguf" not in start
def test_start_fails_fast_when_process_exits(patched):
popen = _FakePopen(lines = ["error: bad model"], exit_code = 1)
patched.setattr(srv.subprocess, "Popen", lambda *a, **k: popen)
s = _server_with(
popen, _FakeClient(get = lambda url: (_ for _ in ()).throw(srv.httpx.ConnectError("refused")))
)
with pytest.raises(RuntimeError, match = "failed to become ready"):
s.start(_FILES, startup_timeout = 2.0)
def _completed_job(images_b64):
return _Resp(
200,
{
"status": "completed",
"result": {"images": [{"index": i, "b64_json": b} for i, b in enumerate(images_b64)]},
},
)
def test_img_gen_returns_image_bytes_in_index_order(patched):
popen = _FakePopen()
s = _server_with(
popen,
_FakeClient(
post = lambda url, json: _Resp(202, {"id": "jobA"}),
get = lambda url: _Resp(
200,
{
"status": "completed",
"result": {
"images": [
{"index": 1, "b64_json": _png_b64(200)},
{"index": 0, "b64_json": _png_b64(50)},
]
},
},
),
),
)
blobs = s.img_gen({"prompt": "x", "batch_count": 2, "sample_params": {"sample_steps": 4}})
assert len(blobs) == 2
first = Image.open(io.BytesIO(blobs[0])).convert("RGB").getpixel((0, 0))
assert first == (50, 50, 50)
def test_img_gen_failed_job_raises(patched):
popen = _FakePopen()
s = _server_with(
popen,
_FakeClient(
post = lambda url, json: _Resp(202, {"id": "jobF"}),
get = lambda url: _Resp(
200, {"status": "failed", "error": {"code": "x", "message": "boom"}}
),
),
)
with pytest.raises(RuntimeError, match = "generation failed.*boom"):
s.img_gen({"prompt": "x"})
def _emit(server, line):
server._tail.append(line)
server._lines_seen += 1
def _failing_job(server, lines):
def post(url, json):
for line in lines:
_emit(server, line)
return _Resp(202, {"id": "jobF"})
return post
_JOB_FAILED = {
"status": "failed",
"error": {"code": "generation_failed", "message": "generate_image returned no results"},
}
_CUDA_OOM = (
"[E] ggml: ggml_backend_cuda_buffer_type_alloc_buffer: allocating 2304.00 MiB on device 0: "
"cudaMalloc failed: out of memory"
)
def test_img_gen_failure_carries_the_log_cause(patched):
client = _FakeClient(post = None, get = lambda url: _Resp(200, _JOB_FAILED))
s = _server_with(_FakePopen(), client)
client._post = _failing_job(s, ["[I] generating image: 1/1 - seed 42", _CUDA_OOM])
with pytest.raises(RuntimeError) as info:
s.img_gen({"prompt": "x"}, poll_interval = 0.0)
message = str(info.value)
assert message.startswith(
"sd-server generation failed: generation_failed: generate_image returned no results"
)
assert "Last output:" in message
assert "out of memory" in message
def test_img_gen_failure_carries_only_its_own_output(patched):
client = _FakeClient(post = None, get = lambda url: _Resp(200, _JOB_FAILED))
s = _server_with(_FakePopen(), client)
client._post = _failing_job(s, [_CUDA_OOM])
with pytest.raises(RuntimeError):
s.img_gen({"prompt": "x"}, poll_interval = 0.0)
client._post = _failing_job(s, ["[E] failed to encode prompt --- image.cpp:450"])
with pytest.raises(RuntimeError) as info:
s.img_gen({"prompt": "x"}, poll_interval = 0.0)
message = str(info.value)
assert "failed to encode prompt" in message
assert "out of memory" not in message
def test_img_gen_failure_without_output_keeps_the_job_error(patched):
s = _server_with(
_FakePopen(),
_FakeClient(
post = lambda url, json: _Resp(202, {"id": "jobF"}),
get = lambda url: _Resp(
200, {"status": "failed", "error": {"code": "x", "message": "boom"}}
),
),
)
with pytest.raises(RuntimeError) as info:
s.img_gen({"prompt": "x"}, poll_interval = 0.0)
assert str(info.value) == "sd-server generation failed: x: boom"
def test_img_gen_queue_full_raises(patched):
popen = _FakePopen()
s = _server_with(popen, _FakeClient(post = lambda url, json: _Resp(429, text = "busy")))
with pytest.raises(RuntimeError, match = "queue is full"):
s.img_gen({"prompt": "x"})
def test_img_gen_cancel_posts_cancel_and_raises(patched):
popen = _FakePopen()
cancel = threading.Event()
cancel.set()
client = _FakeClient(
post = lambda url, json: _Resp(202, {"id": "jobC"}),
get = lambda url: _Resp(
200, {"status": "cancelled", "error": {"code": "cancelled", "message": "c"}}
),
)
s = _server_with(popen, client)
with pytest.raises(SdCppCancelled):
s.img_gen({"prompt": "x"}, cancel_event = cancel)
assert any(url.endswith("/cancel") for url, _ in client.post_calls)
def test_img_gen_detects_server_death(patched):
popen = _FakePopen()
def _die_get(url):
popen._exit = 137
return _Resp(200, {"status": "generating"})
s = _server_with(
popen, _FakeClient(post = lambda url, json: _Resp(202, {"id": "jobD"}), get = _die_get)
)
with pytest.raises(RuntimeError, match = "connection lost|process exited"):
s.img_gen({"prompt": "x"})
def test_drain_routes_lines_to_step_listener_and_tail(patched):
s = SdCppServer("/x/sd-server")
seen = []
s._step_listener = seen.append
s._drain_stdout(_FakePopen(lines = ["sampling 1/8", "", "sampling 8/8", "done"], exit_code = 0))
assert "sampling 1/8" in seen and "sampling 8/8" in seen
assert "" not in seen
assert s._tail[-1] == "done"
def test_stop_is_idempotent_and_terminates(patched):
popen = _FakePopen()
patched.setattr(srv.subprocess, "Popen", lambda *a, **k: popen)
client = _FakeClient(get = lambda url: _Resp(200, {}))
s = _server_with(popen, client)
s.start(_FILES, startup_timeout = 5.0)
s.stop()
assert popen.terminated is True
assert s.is_alive() is False
assert client.closed is True
s.stop()
def test_img_gen_submit_error_raises(patched):
popen = _FakePopen()
s = _server_with(popen, _FakeClient(post = lambda url, json: _Resp(400, text = "bad params")))
with pytest.raises(RuntimeError, match = "submit -> 400"):
s.img_gen({"prompt": "x"})
def test_img_gen_malformed_submit_json_raises(patched):
popen = _FakePopen()
s = _server_with(popen, _FakeClient(post = lambda url, json: _Resp(202, bad_json = True)))
with pytest.raises(RuntimeError, match = "non-JSON submit"):
s.img_gen({"prompt": "x"})
def test_img_gen_empty_result_raises(patched):
popen = _FakePopen()
s = _server_with(
popen,
_FakeClient(
post = lambda url, json: _Resp(202, {"id": "jobE"}),
get = lambda url: _Resp(200, {"status": "completed", "result": {"images": []}}),
),
)
with pytest.raises(RuntimeError, match = "no images"):
s.img_gen({"prompt": "x"})
def test_img_gen_rejected_after_stop(patched):
popen = _FakePopen()
patched.setattr(srv.subprocess, "Popen", lambda *a, **k: popen)
s = _server_with(popen, _FakeClient(get = lambda url: _Resp(200, {})))
s.start(_FILES, startup_timeout = 5.0)
s.stop()
with pytest.raises(RuntimeError, match = "not running"):
s.img_gen({"prompt": "x"})
def test_img_gen_cancelled_before_submit_reports_cancellation(patched):
popen = _FakePopen()
patched.setattr(srv.subprocess, "Popen", lambda *a, **k: popen)
s = _server_with(popen, _FakeClient(get = lambda url: _Resp(200, {})))
s.start(_FILES, startup_timeout = 5.0)
s.stop()
cancel = threading.Event()
cancel.set()
with pytest.raises(SdCppCancelled):
s.img_gen({"prompt": "x"}, cancel_event = cancel)
def test_img_gen_abandons_when_cancel_not_honored(patched):
patched.setattr(srv, "_CANCEL_GRACE_S", 0.0)
popen = _FakePopen()
cancel = threading.Event()
cancel.set()
client = _FakeClient(
post = lambda url, json: _Resp(202, {"id": "jobG"}),
get = lambda url: _Resp(200, {"status": "generating"}),
)
s = _server_with(popen, client)
with pytest.raises(SdCppCancelled):
s.img_gen({"prompt": "x"}, cancel_event = cancel, poll_interval = 0.01)
# sd-server does not interrupt an in-flight job, so an ignored cancel must stop the process.
assert not s.is_alive()
def test_img_gen_non_dict_submit_json_raises(patched):
popen = _FakePopen()
s = _server_with(popen, _FakeClient(post = lambda url, json: _Resp(202, ["not", "a", "dict"])))
with pytest.raises(RuntimeError, match = "unexpected submit response"):
s.img_gen({"prompt": "x"})
def test_img_gen_non_dict_status_json_raises(patched):
popen = _FakePopen()
s = _server_with(
popen,
_FakeClient(
post = lambda url, json: _Resp(202, {"id": "jobH"}),
get = lambda url: _Resp(200, ["unexpected"]),
),
)
with pytest.raises(RuntimeError, match = "unexpected response type"):
s.img_gen({"prompt": "x"}, poll_interval = 0.01)
def test_decode_images_tolerates_unexpected_shapes():
for job in ({"result": ["x"]}, {"result": {"images": "nope"}}, {"result": {"images": [1, 2]}}):
with pytest.raises(RuntimeError, match = "no images"):
SdCppServer._decode_images(job)
def test_start_aborted_by_concurrent_stop(patched):
popen = _FakePopen(lines = ["loading model"])
patched.setattr(srv.subprocess, "Popen", lambda *a, **k: popen)
def _never_ready(url):
raise srv.httpx.ConnectError("refused")
s = _server_with(popen, _FakeClient(get = _never_ready))
def _stop_soon():
import time as _t
_t.sleep(0.2)
s.stop()
threading.Thread(target = _stop_soon, daemon = True).start()
with pytest.raises(SdCppCancelled):
s.start(_FILES, startup_timeout = 30.0)
def test_diagnostic_tail_keeps_the_reason_not_just_the_backtrace():
"""What a Metal host produces: the abort prints its cause, then ggml_print_backtrace fills the
buffer with stack frames. Taking the last N lines reported addresses and no cause, so the
failure was undiagnosable from the message alone."""
lines = [
"loading model from flux-2-klein-4b-Q2_K.gguf",
"ggml_metal_op_encode: error: unsupported op 'SOME_OP'",
"/tmp/ggml/src/ggml-metal.m:1234: fatal error",
*[f"{i} sd-server 0x000000010311{i:04x} ggml_print_backtrace + {i}" for i in range(24)],
]
tail = srv._diagnostic_tail(lines)
assert "unsupported op 'SOME_OP'" in tail
assert "fatal error" in tail
assert "ggml_print_backtrace" in tail
def test_diagnostic_tail_falls_back_to_the_last_lines():
lines = [f"step {i}" for i in range(50)]
tail = srv._diagnostic_tail(lines)
assert "step 49" in tail
assert "step 0" not in tail
def test_diagnostic_tail_is_bounded():
lines = ["error: " + "x" * 500 for _ in range(20)]
assert len(srv._diagnostic_tail(lines)) <= 1500
def test_readiness_refuses_a_port_held_by_another_process(patched):
# The free port can be taken before sd-server binds it, and llama.cpp also answers /v1/models 200.
import types
popen = _FakePopen(lines = ["loading model"])
patched.setattr(srv.subprocess, "Popen", lambda *a, **k: popen)
s = _server_with(popen, _FakeClient(get = lambda url: _Resp(200, {"model": {}})))
fake_psutil = types.SimpleNamespace(
CONN_LISTEN = "LISTEN",
net_connections = lambda kind = "inet": [
types.SimpleNamespace(
laddr = types.SimpleNamespace(port = s.port),
status = "LISTEN",
pid = popen.pid + 1000,
)
],
Process = lambda pid: types.SimpleNamespace(parent = lambda: None),
)
patched.setitem(__import__("sys").modules, "psutil", fake_psutil)
assert s._port_is_ours() is False
def test_readiness_accepts_our_own_child_and_its_descendants(patched):
import types
popen = _FakePopen()
s = _server_with(popen, _FakeClient(get = lambda url: _Resp(200, {})))
def _conns(owner_pid):
return [
types.SimpleNamespace(
laddr = types.SimpleNamespace(port = s.port), status = "LISTEN", pid = owner_pid
)
]
patched.setitem(
__import__("sys").modules,
"psutil",
types.SimpleNamespace(
CONN_LISTEN = "LISTEN",
net_connections = lambda kind = "inet": _conns(popen.pid),
Process = lambda pid: types.SimpleNamespace(parent = lambda: None),
),
)
assert s._port_is_ours() is True
child_pid = popen.pid + 7
def _process(pid):
if pid == child_pid:
return types.SimpleNamespace(
parent = lambda: types.SimpleNamespace(pid = popen.pid, parent = lambda: None)
)
return types.SimpleNamespace(parent = lambda: None)
patched.setitem(
__import__("sys").modules,
"psutil",
types.SimpleNamespace(
CONN_LISTEN = "LISTEN",
net_connections = lambda kind = "inet": _conns(child_pid),
Process = _process,
),
)
assert s._port_is_ours() is True
def test_readiness_check_is_best_effort(patched):
# No psutil, an unreadable owner pid, or a raising lookup must never fail a healthy start.
import types
popen = _FakePopen()
s = _server_with(popen, _FakeClient(get = lambda url: _Resp(200, {})))
patched.setitem(__import__("sys").modules, "psutil", None)
assert s._port_is_ours() is True
def _boom(kind = "inet"):
raise PermissionError("not allowed")
patched.setitem(
__import__("sys").modules,
"psutil",
types.SimpleNamespace(CONN_LISTEN = "LISTEN", net_connections = _boom),
)
assert s._port_is_ours() is True
# Owner pid not visible (common for another user's process): unknown, so keep going.
patched.setitem(
__import__("sys").modules,
"psutil",
types.SimpleNamespace(
CONN_LISTEN = "LISTEN",
net_connections = lambda kind = "inet": [
types.SimpleNamespace(
laddr = types.SimpleNamespace(port = s.port), status = "LISTEN", pid = None
)
],
),
)
assert s._port_is_ours() is True
def test_readiness_refuses_a_hidden_owner_when_our_child_is_not_listening(monkeypatch):
# The Linux/macOS case: another user's socket shows no pid.
monkeypatch.setattr(srv, "_socket_owner_is_always_named", lambda: False)
import http.server
import subprocess
import sys
import threading
psutil = pytest.importorskip("psutil")
class _Ok(http.server.BaseHTTPRequestHandler):
def do_GET(self):
self.send_response(200)
self.end_headers()
def log_message(self, *a):
pass
squatter = http.server.HTTPServer(("127.0.0.1", 0), _Ok)
threading.Thread(target = squatter.serve_forever, daemon = True).start()
child = subprocess.Popen([sys.executable, "-c", "import time; time.sleep(30)"])
try:
s = srv.SdCppServer.__new__(srv.SdCppServer)
s._process = child
s.port = squatter.server_address[1]
real = psutil.net_connections
psutil.net_connections = lambda kind = "inet": [c._replace(pid = None) for c in real(kind = kind)]
try:
assert s._port_is_ours() is False
finally:
psutil.net_connections = real
finally:
child.kill()
child.wait()
squatter.shutdown()
squatter.server_close()
def test_readiness_refuses_a_child_that_already_exited():
# The child died (e.g. it could not bind) while a squatter answered the probe.
import subprocess
import sys
child = subprocess.Popen([sys.executable, "-c", "pass"])
child.wait()
s = srv.SdCppServer.__new__(srv.SdCppServer)
s._process = child
s.port = 1234
assert s._port_is_ours() is False
# ── Windows: psutil can misdescribe our own live listener (#15022) ──
@pytest.fixture
def idle_child():
import subprocess
import sys
child = subprocess.Popen([sys.executable, "-c", "import time; time.sleep(60)"])
yield child
child.kill()
child.wait()
_PORT = 50855
def _row(
status,
pid,
raddr = (),
):
import types
return types.SimpleNamespace(
laddr = types.SimpleNamespace(ip = "127.0.0.1", port = _PORT),
raddr = raddr,
status = status,
pid = pid,
)
def _owner_check(monkeypatch, child, *, own, everyone, windows):
psutil = pytest.importorskip("psutil")
monkeypatch.setattr(srv, "_socket_owner_is_always_named", lambda: windows)
monkeypatch.setattr(
psutil.Process, "net_connections", lambda self, kind = "inet": own, raising = False
)
monkeypatch.setattr(psutil, "net_connections", lambda kind = "inet": everyone)
s = srv.SdCppServer.__new__(srv.SdCppServer)
s._process = child
s.port = _PORT
return s._port_is_ours()
@pytest.mark.parametrize("windows", [True, False])
def test_our_child_reported_with_status_none_is_ours_on_windows(idle_child, monkeypatch, windows):
none = _row("NONE", idle_child.pid)
ours = _owner_check(monkeypatch, idle_child, own = [none], everyone = [none], windows = windows)
assert ours is windows
@pytest.mark.parametrize("windows", [True, False])
def test_a_listener_owned_by_pid_0_is_unknown_on_windows(idle_child, monkeypatch, windows):
everyone = [_row("LISTEN", 0)]
ours = _owner_check(monkeypatch, idle_child, own = [], everyone = everyone, windows = windows)
assert ours is windows
def test_a_named_foreign_listener_still_refuses_on_windows(idle_child, monkeypatch):
import types
accepted = _row("NONE", idle_child.pid, types.SimpleNamespace(ip = "127.0.0.1", port = 60000))
foreign = [_row("LISTEN", 0), _row("LISTEN", idle_child.pid + 100000)]
ours = _owner_check(monkeypatch, idle_child, own = [accepted], everyone = foreign, windows = True)
assert ours is False