Skip to content

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.

test(subprocess): one stub kit for subprocess seams

Juan Denis3c24037b647f
diff --git a/backend/tests/conftest.py b/backend/tests/conftest.py
index 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.py
index 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.py
new file mode 100644
index 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.py
index 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 DockerService
from 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.fixture
diff --git a/backend/tests/test_container_registry.py b/backend/tests/test_container_registry.py
index 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 pytest
from app import db
@@ -18,11 +16,17 @@ from app.services.container_registry_service import ContainerRegistryService
from 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 argv
def 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 a
registry-bound docker app must `docker login` before `compose up`, then log
out (the try/finally around the local compose branch)."""
@@ -165,13 +146,15 @@ def test_start_app_authenticates_registry_before_compose_up(client, auth_headers
db.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_headers
assert 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 is
pulled, 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.py
index 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 _FakeProc
class _FakeFirewall:
diff --git a/backend/tests/test_speed_test.py b/backend/tests/test_speed_test.py
index 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 _FakeProc
class _FakeResponse:
diff --git a/backend/tests/test_subprocess_stub.py b/backend/tests/test_subprocess_stub.py
new file mode 100644
index 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)