"""Tests for _serve_startup — 100% branch coverage. The guard functions are imported into this module's namespace, so every patch targets ``_serve_startup.``: patching ``_serve_guard`` would not bite. No test here signals a real process — ``terminate`` is always a mock. """ from __future__ import annotations from unittest.mock import patch import pytest from steam_backlog_enforcer import _serve_startup from steam_backlog_enforcer._serve_startup import _describe, _replace_or_defer from steam_backlog_enforcer._web_server import DEFAULT_HOST, DEFAULT_PORT _PKG = "steam_backlog_enforcer._serve_startup" def _exits_1(argv: list[str]) -> None: """Assert that parsing *argv* fails with exit code 1.""" with patch(f"{_PKG}._echo"), pytest.raises(SystemExit) as exc: _serve_startup.parse_serve_args(argv) assert exc.value.code == 1 class TestParseServeArgs: """Tests for argument parsing.""" def test_defaults_when_no_flags(self) -> None: """No flags give the default host and port.""" assert _serve_startup.parse_serve_args([]) == (DEFAULT_HOST, DEFAULT_PORT) def test_port_flag(self) -> None: """--port overrides the port only.""" assert _serve_startup.parse_serve_args(["--port", "8123"]) == ( DEFAULT_HOST, 8123, ) def test_host_flag_accepts_literal_loopback(self) -> None: """Any literal 127/8 loopback address is accepted.""" assert _serve_startup.parse_serve_args(["--host", "127.0.0.2"]) == ( "127.0.0.2", DEFAULT_PORT, ) def test_host_alias_canonicalises(self) -> None: """localhost resolves to the default host.""" host, _ = _serve_startup.parse_serve_args(["--host", "localhost"]) assert host == DEFAULT_HOST def test_both_flags_together(self) -> None: """--host and --port combine.""" assert _serve_startup.parse_serve_args( ["--host", "localhost", "--port", "9000"] ) == (DEFAULT_HOST, 9000) def test_unknown_argument_exits(self) -> None: """An unknown flag exits 1.""" _exits_1(["--wat"]) def test_flag_without_value_exits(self) -> None: """A flag missing its value exits 1.""" _exits_1(["--port"]) def test_non_numeric_port_exits(self) -> None: """A non-numeric port exits 1.""" _exits_1(["--port", "eight"]) def test_privileged_port_exits(self) -> None: """A port below 1024 exits 1.""" _exits_1(["--port", "80"]) def test_port_above_range_exits(self) -> None: """A port above 65535 exits 1.""" _exits_1(["--port", "99999"]) def test_non_address_host_exits(self) -> None: """A hostname that is not an IP exits 1.""" _exits_1(["--host", "example.com"]) def test_routable_host_exits(self) -> None: """A routable address exits 1.""" # The dataset API is unauthenticated; a bind must never leave the box. _exits_1(["--host", "8.8.8.8"]) def test_ipv6_loopback_exits(self) -> None: """IPv6 loopback exits 1.""" # ThreadingHTTPServer is AF_INET, so ::1 would always crash at bind. _exits_1(["--host", "::1"]) class TestDescribe: """Tests for the pid description helper.""" def test_includes_argv_when_readable(self) -> None: """A readable cmdline is shown after the pid.""" with patch(f"{_PKG}.read_cmdline", return_value=["python", "-m", "x"]): assert _describe(42) == "pid 42 (python -m x)" def test_falls_back_to_bare_pid(self) -> None: """An unreadable cmdline shows only the pid.""" with patch(f"{_PKG}.read_cmdline", return_value=[]): assert _describe(42) == "pid 42" class TestEnsurePortAvailable: """Tests for the start-or-defer decision.""" def test_free_port_returns(self) -> None: """A free port lets startup continue.""" # Returning normally *is* the assertion: every other path exits. with patch(f"{_PKG}.port_is_free", return_value=True): _serve_startup.ensure_port_available(DEFAULT_HOST, 8000) def test_uninspectable_owner_exits_1(self) -> None: """A busy port with an unknown owner exits 1.""" with ( patch(f"{_PKG}.port_is_free", return_value=False), patch(f"{_PKG}.find_port_owner", return_value=None), patch(f"{_PKG}._echo") as echo, pytest.raises(SystemExit) as exc, ): _serve_startup.ensure_port_available(DEFAULT_HOST, 8000) assert exc.value.code == 1 assert "cannot inspect" in echo.call_args_list[0][0][0] def test_foreign_owner_exits_1_and_is_named(self) -> None: """A foreign owner exits 1 and is named.""" with ( patch(f"{_PKG}.port_is_free", return_value=False), patch(f"{_PKG}.find_port_owner", return_value=99), patch(f"{_PKG}.is_our_server", return_value=False), patch(f"{_PKG}.read_cmdline", return_value=["nginx"]), patch(f"{_PKG}._echo") as echo, pytest.raises(SystemExit) as exc, ): _serve_startup.ensure_port_available(DEFAULT_HOST, 8000) assert exc.value.code == 1 assert "pid 99 (nginx)" in echo.call_args_list[0][0][0] def test_our_server_delegates_to_replace_or_defer(self) -> None: """Our own server on the port goes to replace-or-defer.""" with ( patch(f"{_PKG}.port_is_free", return_value=False), patch(f"{_PKG}.find_port_owner", return_value=99), patch(f"{_PKG}.is_our_server", return_value=True), patch(f"{_PKG}._replace_or_defer") as replace, ): _serve_startup.ensure_port_available(DEFAULT_HOST, 8000) replace.assert_called_once_with(DEFAULT_HOST, 8000, 99) class TestReplaceOrDefer: """Tests for the stale-or-current decision about our own server.""" def test_current_server_exits_0_with_url(self) -> None: """An up-to-date server is reused: exit 0 with its URL.""" with ( patch(f"{_PKG}.process_started_at", return_value=1000.0), patch(f"{_PKG}.newest_py_since", return_value=None), patch(f"{_PKG}._echo") as echo, pytest.raises(SystemExit) as exc, ): _replace_or_defer(DEFAULT_HOST, 8000, 99) assert exc.value.code == 0 assert f"http://{DEFAULT_HOST}:8000" in echo.call_args_list[0][0][0] def test_stale_server_is_terminated(self) -> None: """A server older than the source is terminated.""" newer = "steam_backlog_enforcer/main/misc.py" with ( patch(f"{_PKG}.process_started_at", return_value=1000.0), patch(f"{_PKG}.newest_py_since", return_value=newer), patch(f"{_PKG}.is_our_server", return_value=True), patch(f"{_PKG}.terminate", return_value=True) as term, patch(f"{_PKG}._echo") as echo, ): _replace_or_defer(DEFAULT_HOST, 8000, 99) term.assert_called_once_with(99, DEFAULT_HOST, 8000) assert f"{newer} is newer" in echo.call_args_list[0][0][0] def test_unreadable_start_time_restarts(self) -> None: """An unreadable start time counts as stale.""" with ( patch(f"{_PKG}.process_started_at", return_value=None), patch(f"{_PKG}.is_our_server", return_value=True), patch(f"{_PKG}.terminate", return_value=True), patch(f"{_PKG}._echo") as echo, ): _replace_or_defer(DEFAULT_HOST, 8000, 99) assert "start time unreadable" in echo.call_args_list[0][0][0] def test_recycled_pid_is_never_signalled(self) -> None: """A pid that is no longer our server is never signalled.""" # Between the port scan and here the process can exit and its pid be # reused. Signalling on the stale answer would kill a bystander. with ( patch(f"{_PKG}.process_started_at", return_value=None), patch(f"{_PKG}.is_our_server", return_value=False), patch(f"{_PKG}.read_cmdline", return_value=["someone-else"]), patch(f"{_PKG}.terminate") as term, patch(f"{_PKG}._echo"), pytest.raises(SystemExit) as exc, ): _replace_or_defer(DEFAULT_HOST, 8000, 99) assert exc.value.code == 1 term.assert_not_called() def test_failed_termination_exits_1(self) -> None: """A server that will not die exits 1.""" with ( patch(f"{_PKG}.process_started_at", return_value=None), patch(f"{_PKG}.is_our_server", return_value=True), patch(f"{_PKG}.terminate", return_value=False), patch(f"{_PKG}._echo") as echo, pytest.raises(SystemExit) as exc, ): _replace_or_defer(DEFAULT_HOST, 8000, 99) assert exc.value.code == 1 assert "Could not free port 8000" in echo.call_args_list[-1][0][0]