Skip to content

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.

21.5 KB
Raw Blame
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0

"""unsloth studio stop must stop every server started; one PID file was overwritten per launch."""

from __future__ import annotations

import sys
from pathlib import Path
from types import SimpleNamespace

import pytest
from typer.testing import CliRunner


_REPO_ROOT = Path(__file__).resolve().parents[2]
if str(_REPO_ROOT) not in sys.path:
    sys.path.insert(0, str(_REPO_ROOT))


def _studio():
    from unsloth_cli.commands import studio as _studio_mod
    return _studio_mod


# Captured before _install stubs it, for the tests that exercise it.
_REAL_IS_STUDIO_SERVER = _studio()._pid_is_studio_server


def _install(
    monkeypatch,
    tmp_path,
    *,
    alive,
    killed = None,
):
    """Point the CLI at tmp_path and fake process liveness."""
    studio_mod = _studio()
    monkeypatch.setattr(studio_mod, "STUDIO_HOME", tmp_path)
    monkeypatch.setattr(studio_mod, "_PID_FILE", tmp_path / "studio.pid")
    monkeypatch.setattr(studio_mod.time, "sleep", lambda _s: None)

    live = set(alive)
    killed = killed if killed is not None else []

    monkeypatch.setattr(studio_mod, "_pid_alive", lambda pid: pid in live)
    monkeypatch.setattr(studio_mod, "_pid_is_studio_server", lambda pid, created_times = (): True)

    def fake_kill(pid, _sig):
        killed.append(pid)
        live.discard(pid)

    monkeypatch.setattr(studio_mod.os, "kill", fake_kill)
    monkeypatch.setattr(sys, "platform", "linux")
    return studio_mod, live, killed


def _write_pid(tmp_path, name, pid):
    (tmp_path / name).write_text(str(pid), encoding = "utf-8")


def _run_stop(studio_mod):
    import typer as _typer

    app = _typer.Typer()
    app.add_typer(studio_mod.studio_app, name = "studio")
    return CliRunner().invoke(app, ["studio", "stop"])


def test_stop_kills_every_recorded_server(monkeypatch, tmp_path):
    studio_mod, _live, killed = _install(monkeypatch, tmp_path, alive = {8550, 8600})
    _write_pid(tmp_path, "studio-8901-8550.pid", 8550)
    _write_pid(tmp_path, "studio-8902-8600.pid", 8600)

    result = _run_stop(studio_mod)

    assert result.exit_code == 0, result.output
    assert sorted(killed) == [8550, 8600]
    assert not list(tmp_path.glob("studio-*.pid"))


def test_stop_does_not_leave_the_older_instance_running(monkeypatch, tmp_path):
    studio_mod, live, _killed = _install(monkeypatch, tmp_path, alive = {8550, 8600})
    _write_pid(tmp_path, "studio-8901-8550.pid", 8550)
    _write_pid(tmp_path, "studio-8902-8600.pid", 8600)

    result = _run_stop(studio_mod)

    assert result.exit_code == 0, result.output
    assert live == set()


def test_stop_signals_each_server_once(monkeypatch, tmp_path):
    studio_mod = _studio()
    monkeypatch.setattr(studio_mod, "STUDIO_HOME", tmp_path)
    monkeypatch.setattr(studio_mod, "_PID_FILE", tmp_path / "studio.pid")
    monkeypatch.setattr(studio_mod.time, "sleep", lambda _s: None)
    monkeypatch.setattr(studio_mod, "_pid_alive", lambda pid: True)
    monkeypatch.setattr(studio_mod, "_pid_is_studio_server", lambda pid, created_times = (): True)
    killed = []
    monkeypatch.setattr(studio_mod.os, "kill", lambda pid, _sig: killed.append(pid))
    monkeypatch.setattr(sys, "platform", "linux")
    _write_pid(tmp_path, "studio-8901-8550.pid", 8550)
    _write_pid(tmp_path, "studio.pid", 8550)

    result = _run_stop(studio_mod)

    assert result.exit_code == 0, result.output
    assert killed == [8550]
    assert result.output.lower().count("sent shutdown signal") == 1


def test_stop_removes_every_stale_file_for_one_pid(monkeypatch, tmp_path):
    studio_mod, _live, killed = _install(monkeypatch, tmp_path, alive = set())
    _write_pid(tmp_path, "studio-8901-8550.pid", 8550)
    _write_pid(tmp_path, "studio.pid", 8550)

    result = _run_stop(studio_mod)

    assert result.exit_code == 0, result.output
    assert killed == []
    assert not list(tmp_path.glob("*.pid"))


def test_stop_does_not_signal_a_reused_pid(monkeypatch, tmp_path):
    studio_mod, _live, killed = _install(monkeypatch, tmp_path, alive = {8550})
    monkeypatch.setattr(studio_mod, "_pid_is_studio_server", lambda pid, created_times = (): False)
    _write_pid(tmp_path, "studio-8901-8550.pid", 8550)

    result = _run_stop(studio_mod)

    assert result.exit_code == 1, result.output
    assert killed == []
    assert (tmp_path / "studio-8901-8550.pid").exists()


def test_stop_signals_a_live_server_whose_pid_has_a_stale_record(monkeypatch, tmp_path):
    studio_mod, _live, killed = _install(monkeypatch, tmp_path, alive = {8550})
    monkeypatch.setattr(studio_mod, "_pid_is_studio_server", _REAL_IS_STUDIO_SERVER)

    class _FakeProcess:
        def __init__(self, pid):
            self.pid = pid

        def create_time(self):
            return 999.0

    monkeypatch.setitem(sys.modules, "psutil", SimpleNamespace(Process = _FakeProcess))
    (tmp_path / "studio-8888-8550.pid").write_text("8550\n111.5", encoding = "utf-8")
    (tmp_path / "studio-9000-8550.pid").write_text("8550\n999.0", encoding = "utf-8")

    result = _run_stop(studio_mod)

    assert result.exit_code == 0, result.output
    assert killed == [8550]
    assert not list(tmp_path.glob("studio-*.pid"))


def test_a_bare_run_py_command_line_is_not_rejected(monkeypatch):
    studio_mod = _studio()

    class _FakeProcess:
        def __init__(self, pid):
            self.pid = pid

        def cmdline(self):
            return ["python", "run.py", "--port", "8901"]

        def create_time(self):
            return 111.5

    monkeypatch.setitem(sys.modules, "psutil", SimpleNamespace(Process = _FakeProcess))

    assert studio_mod._pid_is_studio_server(8550) is True


def test_an_untimed_record_is_trusted(monkeypatch):
    studio_mod = _studio()

    assert studio_mod._pid_is_studio_server(8550) is True
    assert studio_mod._pid_is_studio_server(8550, [None]) is True


def test_an_unverifiable_record_is_still_stopped(monkeypatch):
    studio_mod = _studio()
    monkeypatch.setitem(sys.modules, "psutil", None)

    assert studio_mod._pid_is_studio_server(8550, [111.5]) is True
    assert studio_mod._pid_is_studio_server(8550, [None]) is True


def test_stop_signals_a_timestamped_record_without_psutil(monkeypatch, tmp_path):
    studio_mod, _live, killed = _install(monkeypatch, tmp_path, alive = {8550})
    monkeypatch.setattr(studio_mod, "_pid_is_studio_server", _REAL_IS_STUDIO_SERVER)
    monkeypatch.setitem(sys.modules, "psutil", None)
    (tmp_path / "studio-8901-8550.pid").write_text("8550\n111.5", encoding = "utf-8")

    result = _run_stop(studio_mod)

    assert result.exit_code == 0, result.output
    assert killed == [8550]
    assert not (tmp_path / "studio-8901-8550.pid").exists()


def test_the_untimed_legacy_record_does_not_cancel_a_timed_one(monkeypatch):
    studio_mod = _studio()

    class _FakeProcess:
        def __init__(self, pid):
            self.pid = pid

        def create_time(self):
            return 999.0

    monkeypatch.setitem(sys.modules, "psutil", SimpleNamespace(Process = _FakeProcess))

    assert studio_mod._pid_is_studio_server(8550, [111.5, None]) is False
    assert studio_mod._pid_is_studio_server(8550, [111.5]) is False
    assert studio_mod._pid_is_studio_server(8550, [111.5, 999.0]) is True
    assert studio_mod._pid_is_studio_server(8550, [None, None]) is True


def test_stop_does_not_signal_a_reused_pid_recorded_in_both_files(monkeypatch, tmp_path):
    studio_mod, _live, killed = _install(monkeypatch, tmp_path, alive = {8550})
    monkeypatch.setattr(studio_mod, "_pid_is_studio_server", _REAL_IS_STUDIO_SERVER)

    class _FakeProcess:
        def __init__(self, pid):
            self.pid = pid

        def create_time(self):
            return 999.0

    monkeypatch.setitem(sys.modules, "psutil", SimpleNamespace(Process = _FakeProcess))
    (tmp_path / "studio-8901-8550.pid").write_text("8550\n111.5\n127.0.0.1", encoding = "utf-8")
    (tmp_path / "studio.pid").write_text("8550", encoding = "utf-8")

    result = _run_stop(studio_mod)

    assert result.exit_code == 1, result.output
    assert killed == []
    assert len(list(tmp_path.glob("*.pid"))) == 2


def test_pid_identity_check_trusts_the_record_without_psutil(monkeypatch):
    studio_mod = _studio()
    monkeypatch.setitem(sys.modules, "psutil", None)

    assert studio_mod._pid_is_studio_server(8550) is True


def test_pid_identity_check_uses_the_recorded_start_time(monkeypatch):
    studio_mod = _studio()

    class _FakeProcess:
        def __init__(self, pid):
            self.pid = pid

        def create_time(self):
            return 111.5

    monkeypatch.setitem(sys.modules, "psutil", SimpleNamespace(Process = _FakeProcess))

    assert studio_mod._pid_is_studio_server(8550, [111.5]) is True
    assert studio_mod._pid_is_studio_server(8550, [999.0]) is False


def test_stop_keeps_a_live_record_whose_start_time_no_longer_matches(monkeypatch, tmp_path):
    studio_mod, _live, killed = _install(monkeypatch, tmp_path, alive = {8550})
    monkeypatch.setattr(studio_mod, "_pid_is_studio_server", _REAL_IS_STUDIO_SERVER)

    class _FakeProcess:
        def __init__(self, pid):
            self.pid = pid

        def create_time(self):
            return 999.0

    monkeypatch.setitem(sys.modules, "psutil", SimpleNamespace(Process = _FakeProcess))
    (tmp_path / "studio-8901-8550.pid").write_text("8550\n111.5", encoding = "utf-8")

    result = _run_stop(studio_mod)

    assert result.exit_code == 1, result.output
    assert killed == []
    assert (tmp_path / "studio-8901-8550.pid").exists()
    assert "invalid pid file" not in result.output.lower()


def test_stop_reads_the_legacy_single_pid_file(monkeypatch, tmp_path):
    studio_mod, _live, killed = _install(monkeypatch, tmp_path, alive = {4242})
    _write_pid(tmp_path, "studio.pid", 4242)

    result = _run_stop(studio_mod)

    assert result.exit_code == 0, result.output
    assert killed == [4242]
    assert not (tmp_path / "studio.pid").exists()


def test_stop_reports_nothing_running_without_pid_files(monkeypatch, tmp_path):
    studio_mod, _live, _killed = _install(monkeypatch, tmp_path, alive = set())

    result = _run_stop(studio_mod)

    assert result.exit_code == 0, result.output
    assert "no running unsloth server" in result.output.lower()


def test_stop_cleans_stale_pid_files_without_claiming_a_stop(monkeypatch, tmp_path):
    studio_mod, _live, killed = _install(monkeypatch, tmp_path, alive = set())
    _write_pid(tmp_path, "studio-8901-8550.pid", 8550)

    result = _run_stop(studio_mod)

    assert result.exit_code == 0, result.output
    assert killed == []
    assert not (tmp_path / "studio-8901-8550.pid").exists()
    assert "stopped" not in result.output.lower()


def test_stop_does_not_claim_a_stop_while_a_server_is_still_alive(monkeypatch, tmp_path):
    studio_mod = _studio()
    monkeypatch.setattr(studio_mod, "STUDIO_HOME", tmp_path)
    monkeypatch.setattr(studio_mod, "_PID_FILE", tmp_path / "studio.pid")
    monkeypatch.setattr(studio_mod.time, "sleep", lambda _s: None)
    monkeypatch.setattr(studio_mod, "_pid_alive", lambda pid: True)
    monkeypatch.setattr(studio_mod, "_pid_is_studio_server", lambda pid, created_times = (): True)
    monkeypatch.setattr(studio_mod.os, "kill", lambda pid, sig: None)
    monkeypatch.setattr(sys, "platform", "linux")
    _write_pid(tmp_path, "studio-8901-8550.pid", 8550)

    result = _run_stop(studio_mod)

    assert result.exit_code == 0, result.output
    assert "shutting down" in result.output.lower()
    assert "stopped" not in result.output.lower()
    assert (tmp_path / "studio-8901-8550.pid").exists()


def test_stop_continues_after_one_server_fails_to_stop(monkeypatch, tmp_path):
    studio_mod = _studio()
    monkeypatch.setattr(studio_mod, "STUDIO_HOME", tmp_path)
    monkeypatch.setattr(studio_mod, "_PID_FILE", tmp_path / "studio.pid")
    monkeypatch.setattr(studio_mod.time, "sleep", lambda _s: None)
    live = {8550, 8600}
    monkeypatch.setattr(studio_mod, "_pid_alive", lambda pid: pid in live)
    monkeypatch.setattr(studio_mod, "_pid_is_studio_server", lambda pid, created_times = (): True)

    def fake_kill(pid, _sig):
        if pid == 8550:
            raise PermissionError("not permitted")
        live.discard(pid)

    monkeypatch.setattr(studio_mod.os, "kill", fake_kill)
    monkeypatch.setattr(sys, "platform", "linux")
    _write_pid(tmp_path, "studio-8901-8550.pid", 8550)
    _write_pid(tmp_path, "studio-8902-8600.pid", 8600)

    result = _run_stop(studio_mod)

    combined = result.output or ""
    assert result.exit_code == 1, combined
    assert 8600 not in live
    assert "8550" in combined


def test_stop_never_signals_pid_zero_or_init(monkeypatch, tmp_path):
    studio_mod, _live, killed = _install(monkeypatch, tmp_path, alive = {0, 1})
    _write_pid(tmp_path, "studio-8901-0.pid", 0)
    _write_pid(tmp_path, "studio-8902-1.pid", 1)

    result = _run_stop(studio_mod)

    assert result.exit_code == 0, result.output
    assert killed == []
    assert not list(tmp_path.glob("*.pid"))


def test_signal_stop_refuses_pid_zero_or_init(monkeypatch, tmp_path):
    studio_mod, _live, killed = _install(monkeypatch, tmp_path, alive = {0, 1})

    assert studio_mod._signal_stop(0) is not None
    assert studio_mod._signal_stop(1) is not None
    assert killed == []


def test_stop_discards_a_corrupt_pid_file(monkeypatch, tmp_path):
    studio_mod, _live, _killed = _install(monkeypatch, tmp_path, alive = set())
    (tmp_path / "studio-8901-8550.pid").write_text("not-a-pid", encoding = "utf-8")

    result = _run_stop(studio_mod)

    assert result.exit_code == 0, result.output
    assert not (tmp_path / "studio-8901-8550.pid").exists()


def test_stop_keeps_a_record_it_cannot_read(monkeypatch, tmp_path):
    studio_mod, _live, killed = _install(monkeypatch, tmp_path, alive = {8550})
    path = tmp_path / "studio-8901-8550.pid"
    path.write_text("8550", encoding = "utf-8")
    real_read_text = Path.read_text

    def deny(self, *args, **kwargs):
        if self == path:
            raise PermissionError(13, "Permission denied")
        return real_read_text(self, *args, **kwargs)

    monkeypatch.setattr(Path, "read_text", deny)

    result = _run_stop(studio_mod)

    assert path.exists(), "an unreadable record must not be deleted"
    assert "cannot read" in result.output.lower()


def test_stop_does_not_claim_success_when_the_only_record_is_unreadable(monkeypatch, tmp_path):
    studio_mod, _live, killed = _install(monkeypatch, tmp_path, alive = {8550})
    path = tmp_path / "studio-8901-8550.pid"
    path.write_text("8550", encoding = "utf-8")
    real_read_text = Path.read_text

    def deny(self, *args, **kwargs):
        if self == path:
            raise PermissionError(13, "Permission denied")
        return real_read_text(self, *args, **kwargs)

    monkeypatch.setattr(Path, "read_text", deny)

    result = _run_stop(studio_mod)

    assert result.exit_code == 1, "an unreachable server is not a successful stop"
    output = result.output
    assert "no running unsloth server" not in output.lower()
    assert killed == []


def test_stop_reports_failure_when_one_record_is_unreadable_but_another_stops(
    monkeypatch, tmp_path
):
    studio_mod, _live, killed = _install(monkeypatch, tmp_path, alive = {8550, 8600})
    _write_pid(tmp_path, "studio-8901-8550.pid", 8550)
    hidden = tmp_path / "studio-8902-8600.pid"
    hidden.write_text("8600", encoding = "utf-8")
    real_read_text = Path.read_text

    def deny(self, *args, **kwargs):
        if self == hidden:
            raise PermissionError(13, "Permission denied")
        return real_read_text(self, *args, **kwargs)

    monkeypatch.setattr(Path, "read_text", deny)

    result = _run_stop(studio_mod)

    assert killed == [8550], "the readable server must still be stopped"
    assert result.exit_code == 1
    assert hidden.exists()


def test_stop_reaches_every_server_when_one_record_cannot_be_removed(monkeypatch, tmp_path):
    studio_mod, _live, killed = _install(monkeypatch, tmp_path, alive = {8600})
    _write_pid(tmp_path, "studio-8901-8550.pid", 8550)
    _write_pid(tmp_path, "studio-8902-8600.pid", 8600)
    real_unlink = Path.unlink

    def deny(self, *args, **kwargs):
        if self.name == "studio-8901-8550.pid":
            raise PermissionError(13, "Permission denied")
        return real_unlink(self, *args, **kwargs)

    monkeypatch.setattr(Path, "unlink", deny)

    result = _run_stop(studio_mod)

    assert killed == [8600], "the live server must still be signalled"
    assert result.exit_code == 0, result.output


def test_a_record_whose_pid_is_not_ascii_digits_is_discarded(monkeypatch, tmp_path):
    studio_mod, _live, _killed = _install(monkeypatch, tmp_path, alive = set())
    (tmp_path / "studio-8901-1.pid").write_text("²", encoding = "utf-8")

    result = _run_stop(studio_mod)

    assert result.exit_code == 0, result.output
    assert not (tmp_path / "studio-8901-1.pid").exists()


@pytest.mark.parametrize(
    "body, actual",
    [
        ("8550\n1000.0\n127.0.0.1\nlinux:boot:123\n", 4600.0),
        ("8550\n1000.0\n127.0.0.1", 999.0),
    ],
    ids = ["stable-clock-shift", "legacy-one-second-boundary"],
)
def test_stop_recognizes_a_live_record_after_an_epoch_shift(monkeypatch, tmp_path, body, actual):
    from studio.backend.utils import pid_records

    studio_mod, _live, killed = _install(monkeypatch, tmp_path, alive = {8550})
    monkeypatch.setattr(studio_mod, "_pid_is_studio_server", _REAL_IS_STUDIO_SERVER)
    monkeypatch.setattr(pid_records, "linux_process_identity", lambda pid: "linux:boot:123")
    monkeypatch.setitem(
        sys.modules,
        "psutil",
        SimpleNamespace(Process = lambda pid: SimpleNamespace(create_time = lambda: actual)),
    )
    (tmp_path / "studio-8901-8550.pid").write_text(body, encoding = "utf-8")
    result = _run_stop(studio_mod)
    assert result.exit_code == 0, result.output
    assert killed == [8550]


def test_windows_failed_liveness_probe_preserves_the_record(monkeypatch):
    import subprocess

    studio_mod = _studio()
    monkeypatch.setattr(sys, "platform", "win32")
    monkeypatch.setitem(sys.modules, "psutil", None)
    monkeypatch.setattr(
        subprocess, "run", lambda *args, **kwargs: SimpleNamespace(stdout = "", returncode = 1)
    )
    assert studio_mod._pid_alive(8550) is True


@pytest.mark.skipif(sys.platform != "linux", reason = "needs /proc for the stable identity")
def test_stop_drops_a_record_whose_stable_identity_proves_pid_reuse(monkeypatch, tmp_path):
    import os

    studio_mod, _live, killed = _install(monkeypatch, tmp_path, alive = {os.getpid()})
    monkeypatch.setattr(studio_mod, "_pid_is_studio_server", _REAL_IS_STUDIO_SERVER)
    boot = Path("/proc/sys/kernel/random/boot_id").read_text(encoding = "ascii").strip()
    record = tmp_path / f"studio-8901-{os.getpid()}.pid"
    record.write_text(f"{os.getpid()}\n111.5\n127.0.0.1\nlinux:{boot}:1\n", encoding = "utf-8")

    result = _run_stop(studio_mod)

    assert result.exit_code == 0, result.output
    assert killed == []
    assert not record.exists()


def test_stop_does_not_sleep_when_the_server_is_already_gone(monkeypatch, tmp_path):
    studio_mod = _studio()
    monkeypatch.setattr(studio_mod, "STUDIO_HOME", tmp_path)
    monkeypatch.setattr(studio_mod, "_PID_FILE", tmp_path / "studio.pid")
    sleeps = []
    monkeypatch.setattr(studio_mod.time, "sleep", sleeps.append)
    live = {8550}
    monkeypatch.setattr(studio_mod, "_pid_alive", lambda pid: pid in live)
    monkeypatch.setattr(studio_mod, "_pid_is_studio_server", lambda pid, created_times = (): True)
    monkeypatch.setattr(studio_mod.os, "kill", lambda pid, sig: live.discard(pid))
    monkeypatch.setattr(sys, "platform", "linux")
    _write_pid(tmp_path, "studio-8901-8550.pid", 8550)

    result = _run_stop(studio_mod)

    assert result.exit_code == 0, result.output
    assert "stopped (1)" in result.output
    assert sleeps == []
    assert not (tmp_path / "studio-8901-8550.pid").exists()


@pytest.mark.parametrize(
    "platform, steps", [("linux", [0.05] * 100), ("darwin", [0.05] * 100), ("win32", [0.5] * 10)]
)
def test_stop_waits_the_same_five_seconds_for_a_server_that_keeps_running(
    monkeypatch, tmp_path, platform, steps
):
    studio_mod = _studio()
    monkeypatch.setattr(studio_mod, "STUDIO_HOME", tmp_path)
    monkeypatch.setattr(studio_mod, "_PID_FILE", tmp_path / "studio.pid")
    sleeps = []
    monkeypatch.setattr(studio_mod.time, "sleep", sleeps.append)
    monkeypatch.setattr(studio_mod, "_pid_alive", lambda pid: True)
    monkeypatch.setattr(studio_mod, "_pid_is_studio_server", lambda pid, created_times = (): True)
    monkeypatch.setattr(studio_mod, "_signal_stop", lambda pid: None)
    monkeypatch.setattr(sys, "platform", platform)
    _write_pid(tmp_path, "studio-8901-8550.pid", 8550)

    result = _run_stop(studio_mod)

    assert sleeps == steps
    assert "is shutting down" in result.output


def test_stop_returns_within_one_short_step_once_a_posix_server_exits(monkeypatch, tmp_path):
    studio_mod = _studio()
    monkeypatch.setattr(studio_mod, "STUDIO_HOME", tmp_path)
    monkeypatch.setattr(studio_mod, "_PID_FILE", tmp_path / "studio.pid")
    sleeps = []
    monkeypatch.setattr(studio_mod.time, "sleep", sleeps.append)
    monkeypatch.setattr(studio_mod, "_pid_alive", lambda pid: len(sleeps) < 3)
    monkeypatch.setattr(studio_mod, "_pid_is_studio_server", lambda pid, created_times = (): True)
    monkeypatch.setattr(studio_mod, "_signal_stop", lambda pid: None)
    monkeypatch.setattr(sys, "platform", "linux")
    _write_pid(tmp_path, "studio-8901-8550.pid", 8550)

    result = _run_stop(studio_mod)

    assert result.exit_code == 0, result.output
    assert sleeps == [0.05] * 3
    assert "stopped (1)" in result.output