Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python
11.9 KB
Raw Blame
"""Desktop shell lifecycle and singleton contracts."""

import threading
from pathlib import Path
from unittest.mock import MagicMock, patch

import pytest

from free_claude_code.cli.commands import ServerStatus, ServerSupervisor
from free_claude_code.cli.desktop import DesktopController
from free_claude_code.config.settings import Settings
from free_claude_code.core.interprocess_lock import InterprocessFileLock


def _settings() -> Settings:
    return Settings.model_construct(host="0.0.0.0", port=8082)


def test_desktop_instance_lock_is_exclusive_and_reusable(tmp_path: Path) -> None:
    lock_path = tmp_path / "desktop.lock"
    first = InterprocessFileLock(lock_path)
    second = InterprocessFileLock(lock_path)

    assert first.acquire() is True
    assert first.acquire() is True
    assert second.acquire() is False

    first.release()
    first.release()
    assert second.acquire() is True
    second.release()


def test_supervisor_accepts_restart_during_scheduled_startup() -> None:
    supervisor = ServerSupervisor(console_logging=False)
    settings = _settings()

    with (
        patch(
            "free_claude_code.cli.commands.load_server_settings",
            return_value=settings,
        ),
        patch.object(supervisor, "_run_once", return_value=False) as run_once,
        patch("free_claude_code.cli.commands.kill_all_best_effort"),
    ):
        assert supervisor.schedule_run() is True
        assert supervisor.status is ServerStatus.STARTING
        assert supervisor.request_restart() is True
        supervisor.run(open_admin_browser=False)

    run_once.assert_called_once_with(
        settings,
        open_admin_browser=False,
        restart_generation=1,
    )
    assert supervisor.status is ServerStatus.STOPPED


def test_desktop_controller_owns_server_thread_and_graceful_quit() -> None:
    opened = threading.Event()

    class FakeSupervisor:
        def __init__(self) -> None:
            self.status = ServerStatus.STARTING
            self.started = threading.Event()
            self.stopped = threading.Event()
            self.run_arguments: list[bool | None] = []
            self.schedule_count = 0
            self.restart_count = 0
            self.stop_count = 0

        def schedule_run(self) -> bool:
            self.schedule_count += 1
            return True

        def run(self, *, open_admin_browser: bool | None = None) -> None:
            self.run_arguments.append(open_admin_browser)
            self.status = ServerStatus.RUNNING
            self.started.set()
            assert self.stopped.wait(2)
            self.status = ServerStatus.STOPPED

        def request_restart(self) -> bool:
            self.restart_count += 1
            return True

        def request_stop(self) -> None:
            self.stop_count += 1
            self.status = ServerStatus.STOPPING
            self.stopped.set()

    class FakeTray:
        def __init__(self, controller: DesktopController) -> None:
            self.controller = controller
            self.run_thread_id: int | None = None
            self.stop_count = 0

        def run(self, setup) -> None:
            setup()
            self.run_thread_id = threading.get_ident()
            assert supervisor.started.wait(2)
            self.controller.open_admin()
            self.controller.restart_server()
            self.controller.quit()

        def stop(self) -> None:
            self.stop_count += 1

    supervisor = FakeSupervisor()
    tray: FakeTray | None = None

    def make_tray(controller: DesktopController) -> FakeTray:
        nonlocal tray
        tray = FakeTray(controller)
        return tray

    main_thread_id = threading.get_ident()
    controller = DesktopController(supervisor, make_tray, opened.set)
    controller.run()

    assert tray is not None
    assert tray.run_thread_id == main_thread_id
    assert supervisor.run_arguments == [None]
    assert supervisor.schedule_count == 1
    assert supervisor.restart_count == 1
    assert supervisor.stop_count >= 1
    assert tray.stop_count >= 1
    assert opened.is_set()


def test_restart_during_server_startup_is_accepted_without_waiting() -> None:
    class StartupSupervisor:
        def __init__(self) -> None:
            self.status = ServerStatus.STARTING
            self.run_called = threading.Event()
            self.allow_run = threading.Event()
            self.worker_started = threading.Event()
            self.release_worker = threading.Event()
            self.run_scheduled = False
            self.restart_count = 0
            self.accepted_restart_count = 0

        def schedule_run(self) -> bool:
            self.run_scheduled = True
            return True

        def run(self, *, open_admin_browser: bool | None = None) -> None:
            assert open_admin_browser is None
            self.run_called.set()
            assert self.allow_run.wait(2)
            self.run_scheduled = False
            self.worker_started.set()
            assert self.release_worker.wait(2)
            self.status = ServerStatus.STOPPED

        def request_restart(self) -> bool:
            self.restart_count += 1
            if self.run_scheduled:
                self.accepted_restart_count += 1
                return True
            return False

        def request_stop(self) -> None:
            self.release_worker.set()

    class WaitingTray:
        def __init__(self, _controller: DesktopController) -> None:
            self.started = threading.Event()
            self.stopped = threading.Event()

        def run(self, setup) -> None:
            setup()
            self.started.set()
            assert self.stopped.wait(2)

        def stop(self) -> None:
            self.stopped.set()

    supervisor = StartupSupervisor()
    tray: WaitingTray | None = None

    def make_tray(controller: DesktopController) -> WaitingTray:
        nonlocal tray
        tray = WaitingTray(controller)
        return tray

    controller = DesktopController(supervisor, make_tray, MagicMock())
    controller_thread = threading.Thread(target=controller.run)
    controller_thread.start()
    assert tray is not None
    assert tray.started.wait(2)
    assert supervisor.run_called.wait(2)

    restart_thread = threading.Thread(target=controller.restart_server)
    restart_thread.start()
    restart_thread.join(0.5)
    restart_blocked = restart_thread.is_alive()

    supervisor.allow_run.set()
    assert supervisor.worker_started.wait(2)
    controller.quit()
    supervisor.release_worker.set()
    restart_thread.join(2)
    controller_thread.join(2)

    assert restart_blocked is False
    assert supervisor.restart_count == 1
    assert supervisor.accepted_restart_count == 1
    assert not restart_thread.is_alive()
    assert not controller_thread.is_alive()


def test_second_desktop_launch_opens_existing_admin_without_new_server() -> None:
    from free_claude_code.cli import desktop

    settings = _settings()
    instance_lock = MagicMock()
    instance_lock.acquire.return_value = False

    controller = MagicMock()
    with (
        patch.object(desktop, "load_server_settings", return_value=settings),
        patch.object(desktop, "InterprocessFileLock", return_value=instance_lock),
        patch.object(desktop, "open_admin_when_ready", return_value=True) as open_admin,
        patch.object(desktop, "ServerSupervisor") as supervisor,
        patch.object(desktop, "DesktopController", return_value=controller) as shell,
    ):
        controller.run.side_effect = lambda: shell.call_args.args[3]()
        desktop.launch_desktop(MagicMock())

    open_admin.assert_called_once_with(
        settings, stop_event=supervisor.return_value.stop_event
    )
    supervisor.assert_called_once_with(console_logging=False)
    supervisor.return_value.run.assert_not_called()
    instance_lock.release.assert_not_called()


@pytest.mark.parametrize("loser", ["singleton", "existing_server"])
def test_automatically_started_duplicate_does_not_open_admin(
    loser: str,
) -> None:
    from free_claude_code.cli import desktop

    settings = _settings()
    instance_lock = MagicMock()
    instance_lock.acquire.return_value = loser != "singleton"
    controller = MagicMock()
    with (
        patch.object(desktop, "load_server_settings", return_value=settings),
        patch.object(desktop, "InterprocessFileLock", return_value=instance_lock),
        patch.object(desktop, "open_admin_when_ready") as open_admin,
        patch.object(desktop, "ServerSupervisor") as supervisor,
        patch.object(desktop, "DesktopController", return_value=controller) as shell,
    ):
        controller.run.side_effect = lambda: shell.call_args.args[3]()
        if loser == "existing_server":
            supervisor.return_value.run.side_effect = lambda **kwargs: kwargs[
                "existing_server"
            ](settings)
        desktop.launch_desktop(MagicMock(), auto_started=True)

    open_admin.assert_not_called()
    controller.quit.assert_called_once_with()


@pytest.mark.parametrize("endpoint_ready", [False, True])
def test_desktop_attaches_to_terminal_server_instead_of_binding_twice(
    endpoint_ready: bool,
) -> None:
    from free_claude_code.cli import desktop

    settings = _settings()
    instance_lock = MagicMock()
    instance_lock.acquire.return_value = True

    controller = MagicMock()
    with (
        patch.object(desktop, "load_server_settings", return_value=settings),
        patch.object(desktop, "InterprocessFileLock", return_value=instance_lock),
        patch.object(
            desktop, "open_admin_when_ready", return_value=endpoint_ready
        ) as open_admin,
        patch.object(desktop, "ServerSupervisor") as supervisor,
        patch.object(desktop, "DesktopController", return_value=controller) as shell,
    ):
        controller.run.side_effect = lambda: shell.call_args.args[3]()
        supervisor.return_value.run.side_effect = lambda **kwargs: kwargs[
            "existing_server"
        ](settings)
        desktop.launch_desktop(MagicMock())

    open_admin.assert_called_once_with(
        settings, stop_event=supervisor.return_value.stop_event
    )
    supervisor.assert_called_once_with(console_logging=False)
    supervisor.return_value.run.assert_called_once()
    instance_lock.release.assert_called_once_with()
    controller.quit.assert_called_once_with()


def test_fresh_desktop_launch_uses_console_free_supervisor() -> None:
    from free_claude_code.cli import desktop

    settings = _settings()
    instance_lock = MagicMock()
    instance_lock.acquire.return_value = True
    supervisor = MagicMock()
    controller = MagicMock()

    with (
        patch.object(desktop, "load_server_settings", return_value=settings),
        patch.object(desktop, "InterprocessFileLock", return_value=instance_lock),
        patch.object(desktop, "ServerSupervisor", return_value=supervisor) as owner,
        patch.object(desktop, "DesktopController", return_value=controller) as shell,
    ):
        tray_factory = MagicMock()
        controller.run.side_effect = lambda: shell.call_args.args[3]()
        desktop.launch_desktop(tray_factory)

    owner.assert_called_once_with(console_logging=False)
    assert shell.call_args.args[:2] == (supervisor, tray_factory)
    controller.run.assert_called_once_with()
    instance_lock.release.assert_called_once_with()


def test_desktop_lock_failure_closes_tray_without_starting_server():
    from free_claude_code.cli import desktop

    instance_lock = MagicMock()
    instance_lock.acquire.side_effect = PermissionError("locked directory")
    controller = MagicMock()
    with (
        patch.object(desktop, "load_server_settings", return_value=_settings()),
        patch.object(desktop, "InterprocessFileLock", return_value=instance_lock),
        patch.object(desktop, "ServerSupervisor") as supervisor,
        patch.object(desktop, "DesktopController", return_value=controller) as shell,
    ):
        controller.run.side_effect = lambda: shell.call_args.args[3]()
        desktop.launch_desktop(MagicMock())
    controller.quit.assert_called_once()
    supervisor.return_value.run.assert_not_called()