ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
test(subprocess): one stub kit for subprocess seams
Juan Denis3c24037b647f
diff --git a/backend/tests/conftest.py b/backend/tests/conftest.pyindex a0626a7b..73d8366d 100644--- a/backend/tests/conftest.py+++ b/backend/tests/conftest.py@@ -135,6 +135,25 @@ def _popen_sbin_guard(monkeypatch):yield+def fake_subprocess(monkeypatch):+ """Scriptable subprocess seam — the one door for stubbing execs (§G7).++ Opt-in, not autouse: a test that does not ask for it keeps the real+ subprocess (and the §B2 runtime guard above). Asking for it replaces every+ exec entry point on the ``subprocess`` module, which covers BOTH the raw+ calls services still make and the ``run_privileged`` / ``run_unprivileged``+ helpers — they funnel through ``subprocess.run`` too. That is the point:+ when G1 moves services onto ``run_checked()``, this fixture is the single+ place that has to follow, instead of the 12 test files that currently+ hand-roll the same stub.++ Unscripted commands raise; see ``tests/subprocess_stub.py`` for why.+ """+ from subprocess_stub import ScriptedSubprocess+ return ScriptedSubprocess().install(monkeypatch)++@pytest.fixture(scope='session')def _flask_app():"""The Flask application and the schema, built ONCE for the test process.diff --git a/backend/tests/popen_guard.py b/backend/tests/popen_guard.pyindex 3988317d..2a9e2004 100644--- a/backend/tests/popen_guard.py+++ b/backend/tests/popen_guard.py@@ -94,20 +94,34 @@ def _routed_through_helper():return False+def guard_argv(argv):+ """Raise :class:`SbinPathError` when *argv* is a bare-name sbin-only exec.++ One door for the check itself. ``GuardedPopen`` calls it before a real+ exec; ``tests/subprocess_stub.py`` calls it before returning a *scripted*+ result, so stubbing subprocess does not punch a hole in this guard — a+ test that fakes ``subprocess.run`` still cannot smuggle a bare-name+ ``ufw`` past it. That matters more than it sounds: 44 of the suite's+ subprocess stubs mean 44 execs the runtime guard never sees.+ """+ head = offending_head(argv)+ if head is None or _routed_through_helper():+ return+ raise SbinPathError(+ f'{head!r} is exec\'d by bare name but only resolves through '+ f'an sbin dir. The panel\'s systemd unit ships a PATH with no '+ f'sbin, so this call raises FileNotFoundError in production '+ f'while passing every dev run — plan 74\'s outage class.\n'+ f' called from: {_callsite()}\n'+ f'Use run_privileged() (or run_unprivileged() when no root is '+ f'needed); both resolve argv[0] to an absolute path when '+ f'$PATH cannot.'+ )++class GuardedPopen(subprocess.Popen):"""``subprocess.Popen`` that refuses bare-name sbin-only execs (test-time)."""def __init__(self, args, *a, **kw):- head = offending_head(args)- if head is not None and not _routed_through_helper():- raise SbinPathError(- f'{head!r} is exec\'d by bare name but only resolves through '- f'an sbin dir. The panel\'s systemd unit ships a PATH with no '- f'sbin, so this call raises FileNotFoundError in production '- f'while passing every dev run — plan 74\'s outage class.\n'- f' called from: {_callsite()}\n'- f'Use run_privileged() (or run_unprivileged() when no root is '- f'needed); both resolve argv[0] to an absolute path when '- f'$PATH cannot.'- )+ guard_argv(args)super().__init__(args, *a, **kw)diff --git a/backend/tests/subprocess_stub.py b/backend/tests/subprocess_stub.pynew file mode 100644index 00000000..b6eb2f7e--- /dev/null+++ b/backend/tests/subprocess_stub.py@@ -0,0 +1,309 @@+"""Shared subprocess stub kit (plan 75 §G7).++The suite stubs subprocess by hand, everywhere, and the shape of those stubs+is what entrenches the very duplication plan 75 exists to remove:++* ``_FakeProc(returncode, stdout, stderr)`` is pasted **byte-identical** in+ four test modules (plus variants elsewhere);+* ~25 ``def fake_run`` closures re-implement argv dispatch;+* **zero** of them patch ``run_privileged``/``run_unprivileged``. Every stub+ targets raw ``subprocess`` *inside one service module*, so each new service+ test recreates the raw seam instead of the wrapper seam — the 250-raw-call+ surface grows a test that pins it in place.++This module is the single seam. Tests script argv → result; when G1 migrates+services onto ``run_checked()`` the retarget happens **here**, once, instead of+in twelve test files.++Two properties are deliberate, and both come straight from plan 74's outage:++1. **An unscripted command is an error, never a success.** A stub that invents+ ``returncode=0`` for a command the test never described is the same defect+ as a blanket ``except`` reporting "not installed" — a fact nobody+ established. :class:`UnscriptedCommand` is a ``BaseException`` for the same+ reason :class:`popen_guard.SbinPathError` is: services wrap subprocess in+ ``except Exception`` and convert it to ``{'success': False}``, so an+ ``AssertionError`` here would be swallowed by exactly the handlers this kit+ is meant to test, and the test would see a plausible failure dict instead+ of "you forgot to script this".++2. **Stubbed execs are still sbin-guarded.** Patching ``subprocess`` removes+ the §B2 runtime guard for the duration of the test. The kit calls+ :func:`popen_guard.guard_argv` itself, so scripting a command does not buy+ an exemption from the PATH rule.++Usage::++ def test_reload(fake_subprocess):+ fake_subprocess.script(['systemctl', 'reload'], stdout='')+ fake_subprocess.script(['nginx', '-t'], returncode=1, stderr='bad')+ ...+ assert fake_subprocess.argv_for(['nginx']) == ['nginx', '-t']++Matching ignores the two things that legitimately vary at the door: a ``sudo``+prefix (``run_privileged`` adds one only when the process is not root) and+argv[0] absolutisation (``/usr/sbin/nginx`` vs ``nginx``). A test asserts on+the command, not on how the helper had to spell it today.+"""++import os+import subprocess++from popen_guard import guard_argv++_SUDO_FLAGS_WITH_VALUE = ('-u', '--user', '-g', '--group')+++class UnscriptedCommand(BaseException):+ """A stubbed subprocess call the test never described.++ ``BaseException`` on purpose — see the module docstring. Do not "fix" this+ by making it an ``AssertionError``; a blanket ``except Exception`` in the+ service under test would eat it and the failure would surface as a+ confusing assertion about a result dict three layers away.+ """+++class FakeProc:+ """``subprocess.CompletedProcess`` stand-in — the one every test shares.++ Carries the same attribute surface tests actually use (``returncode``,+ ``stdout``, ``stderr``, ``args``) plus ``check_returncode()`` so code under+ test that calls it behaves like the real thing.+ """++ def __init__(self, returncode=0, stdout='', stderr='', args=None):+ self.returncode = returncode+ self.stdout = stdout+ self.stderr = stderr+ self.args = args++ def check_returncode(self):+ if self.returncode:+ raise subprocess.CalledProcessError(+ self.returncode, self.args, self.stdout, self.stderr)++ def __repr__(self):+ return (f'FakeProc(returncode={self.returncode!r}, '+ f'stdout={self.stdout!r}, stderr={self.stderr!r})')+++class FakePopen:+ """Minimal ``Popen`` stand-in over a :class:`FakeProc`.++ Separate type on purpose: a ``Popen``'s ``.stdout`` is an iterable of+ *lines* while a ``CompletedProcess``'s is a string, and one object cannot+ honestly be both — iterating a string yields characters, which is how a+ line-streaming test silently passes over nonsense.+ """++ def __init__(self, proc):+ self._proc = proc+ self.args = proc.args+ self.returncode = None+ text = proc.stdout or ''+ self.stdout = iter(text.splitlines(keepends=True)) if text else iter(())+ self.stderr = iter(())++ def wait(self, timeout=None):+ self.returncode = self._proc.returncode+ return self.returncode++ def poll(self):+ return self.returncode++ def communicate(self, input=None, timeout=None):+ self.returncode = self._proc.returncode+ return self._proc.stdout, self._proc.stderr++ def kill(self):+ self.returncode = self._proc.returncode++ terminate = kill++ def __enter__(self):+ return self++ def __exit__(self, *exc):+ self.wait()+ return False+++def normalize_argv(argv):+ """argv as the *test* means it: no ``sudo`` prefix, argv[0] by basename.++ ``run_privileged`` prepends ``sudo -n`` only when the process is not root,+ and resolves argv[0] to an absolute path only when ``$PATH`` misses it.+ Both are correct, both vary by machine, and neither is what a test is+ asserting about. Normalising here is what lets one scripted rule match on+ a root box, a sudo box, and a dev box alike.+ """+ if isinstance(argv, (str, bytes)) or not argv:+ return []+ parts = [str(a) for a in argv]+ if os.path.basename(parts[0]) == 'sudo':+ parts = parts[1:]+ while parts and parts[0].startswith('-'):+ if parts[0] in _SUDO_FLAGS_WITH_VALUE:+ parts = parts[2:]+ elif parts[0] == '--':+ parts = parts[1:]+ break+ else:+ parts = parts[1:]+ if not parts:+ return []+ return [os.path.basename(parts[0])] + parts[1:]+++class _Rule:+ def __init__(self, prefix, responder):+ self.prefix = list(prefix)+ self.responder = responder+++class ScriptedSubprocess:+ """Scriptable ``subprocess`` replacement: argv prefix → result.++ Rules are matched **longest prefix first**, ties broken by most recently+ scripted. So a broad rule can be laid down first and narrowed later::++ fake.script(['docker'], stdout='') # default+ fake.script(['docker', 'inspect'], returncode=1) # override+ """++ def __init__(self):+ self._rules = []+ self.calls = [] # [(argv, kwargs), ...] — every call, in order++ # ---- scripting -----------------------------------------------------+ def script(self, prefix, *, returncode=0, stdout='', stderr='',+ raises=None):+ """Answer any command starting with *prefix*.++ *raises* takes an exception instance or class and is raised instead of+ returning — this is how the §A probe-contract suites force+ ``FileNotFoundError`` / ``TimeoutExpired`` / ``PermissionError``+ without needing a machine that lacks the binary.+ """+ def responder(argv, kwargs):+ if raises is not None:+ raise raises() if isinstance(raises, type) else raises+ return FakeProc(returncode=returncode, stdout=stdout,+ stderr=stderr, args=argv)++ return self.when(prefix, responder)++ def when(self, prefix, responder):+ """Answer *prefix* with ``responder(argv, kwargs) -> FakeProc``.++ The responder receives the **normalised** argv (no sudo prefix,+ argv[0] by basename) for the same reason matching uses it: a stub that+ emulates ``tee`` should not have to know whether the door decided to+ add ``sudo`` on this machine. The raw argv is still recorded, and+ :meth:`argv_for` hands it back.+ """+ self._rules.append(_Rule(normalize_argv(prefix), responder))+ return self++ # ---- the patched entry points --------------------------------------+ def run(self, cmd, *args, **kwargs):+ return self._dispatch(cmd, kwargs)++ def popen(self, cmd, *args, **kwargs):+ return FakePopen(self._dispatch(cmd, kwargs))++ def check_output(self, cmd, *args, **kwargs):+ proc = self._dispatch(cmd, kwargs)+ proc.check_returncode()+ return proc.stdout++ def call(self, cmd, *args, **kwargs):+ return self._dispatch(cmd, kwargs).returncode++ def check_call(self, cmd, *args, **kwargs):+ proc = self._dispatch(cmd, kwargs)+ proc.check_returncode()+ return 0++ def install(self, monkeypatch, module=subprocess):+ """Patch every exec entry point on *module* onto this script."""+ monkeypatch.setattr(module, 'run', self.run)+ monkeypatch.setattr(module, 'Popen', self.popen)+ monkeypatch.setattr(module, 'check_output', self.check_output)+ monkeypatch.setattr(module, 'call', self.call)+ monkeypatch.setattr(module, 'check_call', self.check_call)+ return self++ # ---- assertions ----------------------------------------------------+ def commands(self):+ """Every argv seen, normalised — the list to assert ordering on."""+ return [normalize_argv(argv) for argv, _ in self.calls]++ def argv_for(self, prefix):+ """The RAW argv of the first call matching *prefix*, or ``None``.++ Raw, not normalised: this is what a test asserting "the secret went to+ stdin and never onto the argv" needs to inspect.+ """+ wanted = normalize_argv(prefix)+ for argv, _ in self.calls:+ if self._matches(normalize_argv(argv), wanted):+ return argv+ return None++ def kwargs_for(self, prefix):+ """The kwargs of the first call matching *prefix*, or ``None``."""+ wanted = normalize_argv(prefix)+ for argv, kwargs in self.calls:+ if self._matches(normalize_argv(argv), wanted):+ return kwargs+ return None++ def writes(self):+ """``{path: content}`` for every privileged file write seen.++ ``write_privileged_file`` (plan 75 §G2) spells a write as+ ``tee [-a] <path>`` with the content on stdin, and three suites already+ rebuilt this dict by hand from their own stub. Reading it here means+ that when the door switches to a tmp-file + ``os.replace`` write, the+ assertions follow in one place instead of in each of them.+ """+ out = {}+ for raw, kwargs in self.calls:+ argv = normalize_argv(raw)+ if not argv or argv[0] != 'tee':+ continue+ path = argv[2] if len(argv) > 2 and argv[1] == '-a' else argv[1]+ content = kwargs.get('input', '')+ out[path] = out.get(path, '') + content if argv[1] == '-a' else content+ return out++ def ran(self, prefix):+ """True when at least one call matched *prefix*."""+ return self.argv_for(prefix) is not None++ # ---- internals ------------------------------------------------------+ @staticmethod+ def _matches(argv, prefix):+ return len(argv) >= len(prefix) and argv[:len(prefix)] == prefix++ def _dispatch(self, cmd, kwargs):+ guard_argv(cmd)+ self.calls.append((cmd, kwargs))+ argv = normalize_argv(cmd)+ best = None+ for rule in self._rules:+ if not self._matches(argv, rule.prefix):+ continue+ if best is None or len(rule.prefix) >= len(best.prefix):+ best = rule+ if best is None:+ raise UnscriptedCommand(+ f'no scripted result for {list(cmd)!r} (normalised {argv!r}).\n'+ f' scripted: {[r.prefix for r in self._rules] or "nothing"}\n'+ 'A stub that answered anyway would be inventing a fact the '+ 'test never established — plan 74\'s bug class, in test form. '+ 'Call fake_subprocess.script([...]) for this command.'+ )+ return best.responder(argv, kwargs)diff --git a/backend/tests/test_app_volumes.py b/backend/tests/test_app_volumes.pyindex bc87db46..45c7ec99 100644--- a/backend/tests/test_app_volumes.py+++ b/backend/tests/test_app_volumes.py@@ -20,11 +20,9 @@ from app.services.docker_service import DockerServicefrom app.services.volume_service import VolumeService, VolumeError-class _FakeProc:- def __init__(self, returncode=0, stdout='', stderr=''):- self.returncode = returncode- self.stdout = stdout- self.stderr = stderr+# The shared stub kit (plan 75 §G7) — this class was pasted+# byte-identical in four test modules.+from subprocess_stub import FakeProc as _FakeProc@pytest.fixturediff --git a/backend/tests/test_container_registry.py b/backend/tests/test_container_registry.pyindex 45ef9c85..ed8cba8a 100644--- a/backend/tests/test_container_registry.py+++ b/backend/tests/test_container_registry.py@@ -8,8 +8,6 @@ Covers the proving points from docs/plans/09_CONTAINER_REGISTRY_AUTH.md:- the deploy path resolves an app's registry_id and authenticates before pull- API CRUD, masking, and admin-gating"""-import subprocess-import pytestfrom app import db@@ -18,11 +16,17 @@ from app.services.container_registry_service import ContainerRegistryServicefrom app.services.docker_service import DockerService-class _FakeProc:- def __init__(self, returncode=0, stdout='', stderr=''):- self.returncode = returncode- self.stdout = stdout- self.stderr = stderr+# The shared stub kit (plan 75 §G7). These tests used to patch+# `subprocess.run` per-test with a hand-rolled closure; they now script the+# one seam, so a later migration onto run_checked() retargets the fixture+# instead of this file.+from subprocess_stub import FakeProc+++def _docker_subcommands(fake):+ """The docker sub-command order seen so far: ['login','pull','logout']."""+ return [argv[1] for argv in fake.commands()+ if len(argv) > 1 and argv[0] == 'docker']@pytest.fixture@@ -59,26 +63,22 @@ def test_blank_url_defaults_to_docker_hub(app):# ── docker login ─────────────────────────────────────────────────────────────-def test_login_pipes_secret_via_stdin_never_on_argv(app, registry, monkeypatch):- captured = {}-- def fake_run(cmd, *args, **kwargs):- captured['cmd'] = cmd- captured['input'] = kwargs.get('input')- return _FakeProc(returncode=0)-- monkeypatch.setattr(subprocess, 'run', fake_run)+def test_login_pipes_secret_via_stdin_never_on_argv(app, registry, fake_subprocess):+ fake_subprocess.script(['docker', 'login'])result = ContainerRegistryService.login(registry)assert result['success'] is True+ # argv_for() hands back the RAW argv on purpose: "nowhere on the argv" is a+ # claim about what was actually exec'd, not about a normalised view of it.+ argv = fake_subprocess.argv_for(['docker', 'login'])# The secret is on stdin, and NOWHERE on the argv.- assert captured['input'] == 'ghp_supersecrettoken'- assert '--password-stdin' in captured['cmd']- assert 'ghp_supersecrettoken' not in captured['cmd']+ assert fake_subprocess.kwargs_for(['docker', 'login'])['input'] == 'ghp_supersecrettoken'+ assert '--password-stdin' in argv+ assert 'ghp_supersecrettoken' not in argv# Sanity: it targets the right host + user.- assert captured['cmd'][:2] == ['docker', 'login']- assert 'ghcr.io' in captured['cmd']- assert 'acme-bot' in captured['cmd']+ assert argv[:2] == ['docker', 'login']+ assert 'ghcr.io' in argv+ assert 'acme-bot' in argvdef test_login_fails_cleanly_without_a_secret(app):@@ -97,64 +97,45 @@ def test_ecr_username_defaults_to_AWS(app):# ── pull_image: login -> pull -> logout ordering + finally ───────────────────-def _sequence_recorder():- """Return (calls, fake_run) capturing the docker sub-command order."""- calls = []-- def fake_run(cmd, *args, **kwargs):- sub = cmd[1] if len(cmd) > 1 else cmd[0]- calls.append(sub)- # docker pull fails to exercise the finally-logout path when asked- if sub == 'pull' and fake_run.fail_pull:- return _FakeProc(returncode=1, stderr='denied')- return _FakeProc(returncode=0, stdout='ok')-- fake_run.fail_pull = False- return calls, fake_run---def test_pull_image_logs_in_then_pulls_then_logs_out(app, registry, monkeypatch):- calls, fake_run = _sequence_recorder()- monkeypatch.setattr(subprocess, 'run', fake_run)+def test_pull_image_logs_in_then_pulls_then_logs_out(app, registry, fake_subprocess):+ fake_subprocess.script(['docker'], stdout='ok')result = DockerService.pull_image('ghcr.io/acme/app', tag='v1', registry=registry)assert result['success'] is True- assert calls == ['login', 'pull', 'logout']+ assert _docker_subcommands(fake_subprocess) == ['login', 'pull', 'logout']-def test_pull_image_logs_out_even_when_pull_fails(app, registry, monkeypatch):- calls, fake_run = _sequence_recorder()- fake_run.fail_pull = True- monkeypatch.setattr(subprocess, 'run', fake_run)+def test_pull_image_logs_out_even_when_pull_fails(app, registry, fake_subprocess):+ fake_subprocess.script(['docker'], stdout='ok')+ # the narrower rule wins over the broad one: only the pull fails+ fake_subprocess.script(['docker', 'pull'], returncode=1, stderr='denied')result = DockerService.pull_image('ghcr.io/acme/app', tag='v1', registry=registry)assert result['success'] is False# logout still ran despite the failed pull (the try/finally).- assert calls == ['login', 'pull', 'logout']+ assert _docker_subcommands(fake_subprocess) == ['login', 'pull', 'logout']-def test_pull_image_anonymous_when_no_registry(app, monkeypatch):- calls, fake_run = _sequence_recorder()- monkeypatch.setattr(subprocess, 'run', fake_run)+def test_pull_image_anonymous_when_no_registry(app, fake_subprocess):+ fake_subprocess.script(['docker'], stdout='ok')DockerService.pull_image('nginx', tag='latest')- assert calls == ['pull'] # no login/logout for a public pull+ assert _docker_subcommands(fake_subprocess) == ['pull'] # no login/logout-def test_test_connection_logs_in_and_out(app, registry, monkeypatch):- calls, fake_run = _sequence_recorder()- monkeypatch.setattr(subprocess, 'run', fake_run)+def test_test_connection_logs_in_and_out(app, registry, fake_subprocess):+ fake_subprocess.script(['docker'], stdout='ok')result = ContainerRegistryService.test_connection(registry)assert result['success'] is True- assert calls == ['login', 'logout']+ assert _docker_subcommands(fake_subprocess) == ['login', 'logout']# ── proving test: deploy path authenticates before pull ──────────────────────-def test_start_app_authenticates_registry_before_compose_up(client, auth_headers, app, registry, monkeypatch):+def test_start_app_authenticates_registry_before_compose_up(client, auth_headers, app, registry, monkeypatch, fake_subprocess):"""The primary path for a private-image app is compose. Starting aregistry-bound docker app must `docker login` before `compose up`, then logout (the try/finally around the local compose branch)."""@@ -165,13 +146,15 @@ def test_start_app_authenticates_registry_before_compose_up(client, auth_headersdb.session.add(application)db.session.commit()+ # compose_up is stubbed at the service, not at subprocess, so the ordering+ # assertion needs one interleaved list rather than the fixture's call log.order = []- def fake_run(cmd, *args, **kwargs):- order.append(cmd[1] if len(cmd) > 1 else cmd[0]) # login / logout- return _FakeProc(returncode=0)+ def record(argv, kwargs):+ order.append(argv[1] if len(argv) > 1 else argv[0]) # login / logout+ return FakeProc(returncode=0)- monkeypatch.setattr(subprocess, 'run', fake_run)+ fake_subprocess.when(['docker'], record)monkeypatch.setattr(DockerService, 'compose_up',staticmethod(lambda *a, **k: order.append('compose_up') or {'success': True}))@@ -181,7 +164,7 @@ def test_start_app_authenticates_registry_before_compose_up(client, auth_headersassert order.index('login') < order.index('compose_up') < order.index('logout')-def test_deploy_docker_authenticates_before_pull(app, registry, monkeypatch):+def test_deploy_docker_authenticates_before_pull(app, registry, monkeypatch, fake_subprocess):"""A Docker app bound to a registry must `docker login` before the image ispulled, then run the container."""from app.services.deployment_service import DeploymentService@@ -207,11 +190,11 @@ def test_deploy_docker_authenticates_before_pull(app, registry, monkeypatch):order = []- def fake_run(cmd, *args, **kwargs):- order.append(cmd[1] if len(cmd) > 1 else cmd[0])- return _FakeProc(returncode=0, stdout='')+ def record(argv, kwargs):+ order.append(argv[1] if len(argv) > 1 else argv[0])+ return FakeProc(returncode=0, stdout='')- monkeypatch.setattr(subprocess, 'run', fake_run)+ fake_subprocess.when(['docker'], record)monkeypatch.setattr(DockerService, 'get_container', staticmethod(lambda *a, **k: None))monkeypatch.setattr(EnvService, 'get_effective_env', staticmethod(lambda *a, **k: {}))monkeypatch.setattr(DockerService, 'run_container',diff --git a/backend/tests/test_metadata_guard.py b/backend/tests/test_metadata_guard.pyindex 587d470e..49589d2c 100644--- a/backend/tests/test_metadata_guard.py+++ b/backend/tests/test_metadata_guard.py@@ -20,11 +20,9 @@ from app.services.metadata_guard_service import ()-class _FakeProc:- def __init__(self, returncode=0, stdout='', stderr=''):- self.returncode = returncode- self.stdout = stdout- self.stderr = stderr+# The shared stub kit (plan 75 §G7) — this class was pasted+# byte-identical in four test modules.+from subprocess_stub import FakeProc as _FakeProcclass _FakeFirewall:diff --git a/backend/tests/test_speed_test.py b/backend/tests/test_speed_test.pyindex 3f2b7449..aaab2722 100644--- a/backend/tests/test_speed_test.py+++ b/backend/tests/test_speed_test.py@@ -19,11 +19,9 @@ from app.services.speed_test_service import (pytestmark = pytest.mark.fresh_app-class _FakeProc:- def __init__(self, returncode=0, stdout='', stderr=''):- self.returncode = returncode- self.stdout = stdout- self.stderr = stderr+# The shared stub kit (plan 75 §G7) — this class was pasted+# byte-identical in four test modules.+from subprocess_stub import FakeProc as _FakeProcclass _FakeResponse:diff --git a/backend/tests/test_subprocess_stub.py b/backend/tests/test_subprocess_stub.pynew file mode 100644index 00000000..dc58d447--- /dev/null+++ b/backend/tests/test_subprocess_stub.py@@ -0,0 +1,261 @@+"""The stub kit's own contract (plan 75 §G7).++A shared test helper that is wrong is worse than twelve private ones: every+suite that adopts it inherits the same blind spot. So the properties this kit+claims are tested here, not assumed — particularly the two that exist to stop+a stub from manufacturing facts.+"""++import os+import subprocess++import pytest++from subprocess_stub import (FakePopen, FakeProc, ScriptedSubprocess,+ UnscriptedCommand, normalize_argv)+++class TestNormalisation:+ """One scripted rule must match on a root box, a sudo box, and a dev box."""++ def test_strips_sudo_and_its_flags(self):+ assert normalize_argv(['sudo', '-n', 'nginx', '-t']) == ['nginx', '-t']++ def test_strips_sudo_user_flag_with_its_value(self):+ assert normalize_argv(['sudo', '-u', 'www-data', 'php', '-v']) == ['php', '-v']++ def test_argv0_compared_by_basename(self):+ # run_privileged absolutises argv[0] only when $PATH misses it, so the+ # same call is spelled two ways on two machines.+ assert normalize_argv(['/usr/sbin/nginx', '-t']) == ['nginx', '-t']++ def test_does_not_strip_a_command_merely_containing_sudo(self):+ assert normalize_argv(['sudoedit', '-f']) == ['sudoedit', '-f']++ def test_string_form_and_empty_are_not_argv(self):+ assert normalize_argv('ls -la') == []+ assert normalize_argv([]) == []+++class TestUnscriptedIsAnError:+ def test_unscripted_command_raises(self, fake_subprocess):+ with pytest.raises(UnscriptedCommand):+ subprocess.run(['docker', 'ps'])++ def test_message_names_the_command_and_what_was_scripted(self, fake_subprocess):+ fake_subprocess.script(['git', 'status'])+ try:+ subprocess.run(['docker', 'ps'])+ except UnscriptedCommand as exc:+ assert 'docker' in str(exc) and 'git' in str(exc)+ else: # pragma: no cover - the raise above is the point+ pytest.fail('unscripted command returned a result')++ def test_a_blanket_except_cannot_eat_it(self, fake_subprocess):+ """The whole reason it is a BaseException.++ Services wrap subprocess in ``except Exception`` and convert it to+ ``{'success': False}``. If this were an AssertionError the test author+ would see a plausible failure dict instead of "you forgot to script+ this" — plan 74's bug class, reproduced inside the test harness.+ """+ def service_style_call():+ try:+ return subprocess.run(['ufw', 'status'])+ except Exception:+ return {'success': False, 'error': 'not installed'}++ with pytest.raises(UnscriptedCommand):+ service_style_call()+++class TestDispatch:+ def test_prefix_match_returns_scripted_result(self, fake_subprocess):+ fake_subprocess.script(['docker', 'ps'], stdout='CONTAINER ID\n')+ result = subprocess.run(['docker', 'ps', '-a'], capture_output=True)+ assert result.stdout == 'CONTAINER ID\n'+ assert result.returncode == 0++ def test_longest_prefix_wins_regardless_of_order(self, fake_subprocess):+ fake_subprocess.script(['docker'], stdout='broad')+ fake_subprocess.script(['docker', 'inspect'], stdout='narrow')+ assert subprocess.run(['docker', 'inspect', 'x']).stdout == 'narrow'+ assert subprocess.run(['docker', 'ps']).stdout == 'broad'++ def test_narrow_rule_wins_even_when_scripted_first(self, fake_subprocess):+ fake_subprocess.script(['docker', 'inspect'], stdout='narrow')+ fake_subprocess.script(['docker'], stdout='broad')+ assert subprocess.run(['docker', 'inspect', 'x']).stdout == 'narrow'++ def test_raises_scripts_an_exception(self, fake_subprocess):+ fake_subprocess.script(['ufw'], raises=FileNotFoundError)+ with pytest.raises(FileNotFoundError):+ subprocess.run(['ufw', 'status'])++ def test_raises_accepts_an_instance(self, fake_subprocess):+ fake_subprocess.script(['ufw'], raises=subprocess.TimeoutExpired('ufw', 5))+ with pytest.raises(subprocess.TimeoutExpired):+ subprocess.run(['ufw', 'status'])++ def test_when_gives_the_responder_argv_and_kwargs(self, fake_subprocess):+ seen = {}++ def responder(argv, kwargs):+ seen['argv'] = argv+ seen['input'] = kwargs.get('input')+ return FakeProc(returncode=0)++ fake_subprocess.when(['docker', 'login'], responder)+ subprocess.run(['docker', 'login', 'ghcr.io'], input='secret')+ assert seen['argv'] == ['docker', 'login', 'ghcr.io']+ assert seen['input'] == 'secret'+++class TestEveryEntryPointIsPatched:+ """``run`` is not the only door — ``check_output`` and friends bypass it."""++ def test_check_output_returns_stdout(self, fake_subprocess):+ fake_subprocess.script(['git', 'rev-parse'], stdout='abc123\n')+ assert subprocess.check_output(['git', 'rev-parse', 'HEAD']) == 'abc123\n'++ def test_check_output_raises_on_nonzero(self, fake_subprocess):+ fake_subprocess.script(['git'], returncode=128, stderr='fatal')+ with pytest.raises(subprocess.CalledProcessError):+ subprocess.check_output(['git', 'status'])++ def test_call_returns_the_code(self, fake_subprocess):+ fake_subprocess.script(['git'], returncode=1)+ assert subprocess.call(['git', 'status']) == 1++ def test_check_call_raises_on_nonzero(self, fake_subprocess):+ fake_subprocess.script(['git'], returncode=1)+ with pytest.raises(subprocess.CalledProcessError):+ subprocess.check_call(['git', 'status'])++ def test_popen_streams_lines_not_characters(self, fake_subprocess):+ fake_subprocess.script(['docker', 'compose'], stdout='one\ntwo\n')+ proc = subprocess.Popen(['docker', 'compose', 'up'])+ assert list(proc.stdout) == ['one\n', 'two\n']+ assert proc.wait() == 0+++class TestItCoversTheWrappersToo:+ """The point of patching the module, not a service's imported name."""++ def test_run_privileged_goes_through_the_script(self, fake_subprocess):+ from app.utils.system import run_privileged+ fake_subprocess.script(['nginx', '-t'], returncode=0, stdout='ok')+ result = run_privileged(['nginx', '-t'])+ assert result.stdout == 'ok'+ # matched despite whatever sudo/absolutisation the helper applied+ assert fake_subprocess.ran(['nginx', '-t'])++ def test_run_unprivileged_goes_through_the_script(self, fake_subprocess):+ from app.utils.system import run_unprivileged+ fake_subprocess.script(['dig'], stdout='1.2.3.4\n')+ assert run_unprivileged(['dig', '+short', 'a.test'])['stdout'] == '1.2.3.4\n'+++class TestRecording:+ def test_commands_are_recorded_in_order(self, fake_subprocess):+ fake_subprocess.script(['docker'], stdout='')+ subprocess.run(['docker', 'login'])+ subprocess.run(['docker', 'pull', 'x'])+ subprocess.run(['docker', 'logout'])+ assert fake_subprocess.commands() == [+ ['docker', 'login'], ['docker', 'pull', 'x'], ['docker', 'logout'],+ ]++ def test_argv_for_returns_the_raw_argv(self, fake_subprocess):+ """Raw on purpose: 'the secret is on stdin and NOWHERE on the argv'+ is an assertion about the real argv, not a normalised one."""+ fake_subprocess.script(['docker', 'login'])+ subprocess.run(['docker', 'login', '-u', 'bot', '--password-stdin'],+ input='tok')+ assert fake_subprocess.argv_for(['docker', 'login']) == [+ 'docker', 'login', '-u', 'bot', '--password-stdin']+ assert fake_subprocess.kwargs_for(['docker'])['input'] == 'tok'++ def test_ran_is_false_for_a_command_never_issued(self, fake_subprocess):+ fake_subprocess.script(['docker'], stdout='')+ subprocess.run(['docker', 'ps'])+ assert fake_subprocess.ran(['docker', 'ps'])+ assert not fake_subprocess.ran(['docker', 'rm'])+++class TestWritesAccessor:+ """`writes()` reads the privileged-write door's argv shape in one place."""++ def test_collects_path_to_content(self, fake_subprocess):+ from app.utils.system import write_privileged_file+ fake_subprocess.script(['tee'])+ write_privileged_file('/etc/nginx/sites-available/a', 'server {}')+ assert fake_subprocess.writes() == {'/etc/nginx/sites-available/a': 'server {}'}++ def test_append_accumulates_rather_than_replacing(self, fake_subprocess):+ from app.utils.system import write_privileged_file+ fake_subprocess.script(['tee'])+ write_privileged_file('/etc/postfix/main.cf', 'a=1\n', append=True)+ write_privileged_file('/etc/postfix/main.cf', 'b=2\n', append=True)+ assert fake_subprocess.writes() == {'/etc/postfix/main.cf': 'a=1\nb=2\n'}++ def test_a_truncating_write_replaces_what_append_accumulated(self, fake_subprocess):+ from app.utils.system import write_privileged_file+ fake_subprocess.script(['tee'])+ write_privileged_file('/etc/x', 'old\n', append=True)+ write_privileged_file('/etc/x', 'new\n')+ assert fake_subprocess.writes() == {'/etc/x': 'new\n'}++ def test_non_write_commands_are_not_collected(self, fake_subprocess):+ fake_subprocess.script(['systemctl'])+ subprocess.run(['systemctl', 'reload', 'nginx'])+ assert fake_subprocess.writes() == {}+++class TestStubbingIsNotAGuardExemption:+ """Patching subprocess removes the §B2 runtime guard for the test's+ duration. The kit re-applies it, so a scripted command cannot smuggle a+ bare-name sbin-only exec past the check the suite otherwise enforces."""++ @pytest.mark.skipif(os.name != 'posix', reason='sbin semantics are POSIX')+ def test_bare_name_sbin_only_exec_still_refused(self, fake_subprocess, monkeypatch):+ import shutil++ from popen_guard import SbinPathError, sanitized_path++ real_which = shutil.which++ def fake_which(cmd, path=None, **kw):+ if cmd == 'fakesbintool':+ # resolves on the normal PATH, not on the sbin-less one:+ # exactly the shape of the plan 74 outage.+ return None if path == sanitized_path() else '/usr/sbin/fakesbintool'+ return real_which(cmd, path=path, **kw) if path is None else real_which(cmd, path=path)++ monkeypatch.setattr('popen_guard.shutil.which', fake_which)+ fake_subprocess.script(['fakesbintool'], stdout='')+ with pytest.raises(SbinPathError):+ subprocess.run(['fakesbintool', 'status'])+++class TestFakeProcShape:+ def test_check_returncode_is_quiet_on_success(self):+ FakeProc(returncode=0).check_returncode()++ def test_check_returncode_raises_with_the_output_attached(self):+ proc = FakeProc(returncode=2, stdout='out', stderr='err', args=['x'])+ with pytest.raises(subprocess.CalledProcessError) as exc:+ proc.check_returncode()+ assert exc.value.stderr == 'err'++ def test_popen_stdout_is_empty_not_none_when_no_output(self):+ assert list(FakePopen(FakeProc()).stdout) == []++ def test_install_binds_the_module_to_this_script(self, fake_subprocess):+ assert getattr(subprocess.run, '__self__', None) is fake_subprocess++ def test_patch_does_not_leak_to_a_test_without_the_fixture(self):+ """If install() leaked, every later test in the session would silently+ run against a stub that answers nothing."""+ assert not isinstance(getattr(subprocess.run, '__self__', None),+ ScriptedSubprocess)