CLI for SidePulse
Python
Test the install itself, not just the code
Peter Kuharea7d2422dd28
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.ymlindex d200e64..42d632a 100644--- a/.github/workflows/tests.yml+++ b/.github/workflows/tests.yml@@ -31,6 +31,13 @@ jobs:- name: Import contractrun: python -m pytest tests/test_packaging.py -v+ # Builds an empty virtualenv and installs from pyproject.toml alone,+ # then runs the real commands against it. An undeclared dependency is+ # simply absent there, which is how the ScriptingBridge bug reached a+ # user in the first place.+ - name: Clean-room install+ run: python -m pytest tests/test_environment.py -v+- name: Agent hook stabilityrun: python -m pytest tests/test_hook_stability.py -v@@ -41,7 +48,11 @@ jobs:SIDEPULSE_REQUIRE_UI_TESTS: "1"run: python -m pytest tests/test_status_bar_ui.py -v+ # Catch-all for anything the named steps above do not cover. The+ # clean-room install already ran, so skip rebuilding its virtualenv.- name: Full suite+ env:+ SIDEPULSE_SKIP_CLEAN_INSTALL: "1"run: python -m pytest tests -qlinux:@@ -62,6 +73,9 @@ jobs:python -m pip install --upgrade pippython -m pip install -e '.[test]'+ - name: Clean-room install+ run: python -m pytest tests/test_environment.py -v+# The macOS-only modules are darwin-gated, so this catches a top-level# AppKit import creeping into a cross-platform module.- name: Platform-independent suitediff --git a/README.md b/README.mdindex 2586b40..f3c8f02 100644--- a/README.md+++ b/README.md@@ -568,9 +568,14 @@ unless it passes. Four files, each guarding a different failure mode:| File | Guards against || --- | --- || `tests/test_packaging.py` | Importing a module no dependency declares. Every module-level import must resolve to a declared distribution, so a new `import` without a matching `pyproject.toml` entry fails at commit time rather than on a user's machine. |+| `tests/test_environment.py` | A working dev machine hiding a broken install. Builds an empty virtualenv, runs `pip install .` against `pyproject.toml` alone, then imports every module and runs the real commands — including `sidepulse status-bar start --foreground` — inside it. An undeclared dependency is simply absent there. || `tests/test_hook_stability.py` | Breaking somebody's agent session. Hooks must exit 0 and stay silent on stdout for every input and internal failure — and must still work with PyObjC entirely unavailable. || `tests/test_status_bar_ui.py` | Menus and windows that build but crash when clicked. Runs headlessly against a real `StatusBarController`; verifies every selector string resolves to a real method. || `tests/test_sidepulse.py` | Collector, settings, install, and provider logic. |The UI tests skip if AppKit is unavailable. Set `SIDEPULSE_REQUIRE_UI_TESTS=1`to turn that skip into a failure, which is how CI runs them.++The clean-room install tests take ~15s because they build a virtualenv and+install into it. Set `SIDEPULSE_SKIP_CLEAN_INSTALL=1` to skip them while+iterating; CI always runs them.diff --git a/src/sidepulse/__main__.py b/src/sidepulse/__main__.pyindex d3b65db..bfdcd0c 100644--- a/src/sidepulse/__main__.py+++ b/src/sidepulse/__main__.py@@ -1,5 +1,4 @@from .cli import main-print("Helo World")if __name__ == "__main__":raise SystemExit(main())diff --git a/tests/test_environment.py b/tests/test_environment.pynew file mode 100644index 0000000..6fd5533--- /dev/null+++ b/tests/test_environment.py@@ -0,0 +1,342 @@+"""Clean-room environment tests: install the project the way a user does.++Every other test in this repo runs inside the developer's environment, which+accumulates packages that were installed by hand. That is precisely how the+missing ``pyobjc-framework-ScriptingBridge`` dependency stayed invisible: the+framework was sitting in the working virtualenv, so imports succeeded locally+while a fresh install was broken.++These tests build an empty virtualenv, run ``pip install .`` against nothing+but ``pyproject.toml``, and then exercise the result. A dependency that is not+declared is simply absent, so the failure is real rather than theoretical.++They are slower than the rest of the suite (a few seconds with a warm wheel+cache, longer on a cold one). Set ``SIDEPULSE_SKIP_CLEAN_INSTALL=1`` to skip+them while iterating locally; CI always runs them.+"""++from __future__ import annotations++import json+import os+import subprocess+import sys+import tempfile+import textwrap+import unittest+from pathlib import Path++REPO_ROOT = Path(__file__).resolve().parents[1]++# The error the status bar prints when PyObjC imports fail. If a clean install+# ever produces this, the dependency list is wrong again.+DEPENDENCY_ERROR_MARKER = "requires PyObjC"++# Substrings that mean pip could not reach an index, as opposed to the package+# being genuinely broken. Only these downgrade a failure to a skip.+NETWORK_FAILURE_MARKERS = (+ "Temporary failure in name resolution",+ "Network is unreachable",+ "Could not find a version",+ "No matching distribution",+ "Failed to establish a new connection",+ "Connection refused",+ "Read timed out",+ "retries exceeded",+)+++ os.environ.get("SIDEPULSE_SKIP_CLEAN_INSTALL") == "1",+ "clean-install tests disabled via SIDEPULSE_SKIP_CLEAN_INSTALL",+)+class CleanInstallTests(unittest.TestCase):+ """Install into an empty virtualenv and exercise what a user would get."""++ @classmethod+ def setUpClass(cls):+ cls._tmp = tempfile.TemporaryDirectory(prefix="sidepulse-clean-env-")+ root = Path(cls._tmp.name)+ cls.venv = root / "venv"+ cls.home = root / "home"+ cls.home.mkdir()++ # No --system-site-packages: the environment starts empty, so the only+ # things importable are what pyproject.toml declares.+ create = subprocess.run(+ [sys.executable, "-m", "venv", str(cls.venv)],+ capture_output=True, text=True, timeout=300,+ )+ if create.returncode != 0:+ cls._tmp.cleanup()+ raise unittest.SkipTest(f"could not create virtualenv: {create.stderr}")++ cls.python = cls.venv / "bin" / "python"++ install = subprocess.run(+ [+ str(cls.python), "-m", "pip", "install",+ "--quiet", "--disable-pip-version-check", str(REPO_ROOT),+ ],+ capture_output=True, text=True, timeout=900,+ )+ if install.returncode != 0:+ output = install.stderr + install.stdout+ if any(marker in output for marker in NETWORK_FAILURE_MARKERS):+ cls._tmp.cleanup()+ raise unittest.SkipTest(f"no package index reachable: {output[-500:]}")+ cls._tmp.cleanup()+ raise AssertionError(+ f"`pip install .` failed on a clean environment:\n{output}"+ )++ @classmethod+ def tearDownClass(cls):+ cls._tmp.cleanup()++ # -- helpers ---------------------------------------------------------++ def env(self) -> dict:+ """A minimal environment: no PYTHONPATH leaking the source tree in."""+ env = {+ "PATH": f"{self.venv / 'bin'}:{os.environ.get('PATH', '')}",+ "HOME": str(self.home),+ "XDG_CONFIG_HOME": str(self.home / ".config"),+ "SIDEPULSE_DISABLE_EVENT_SOCKET": "1",+ "TMPDIR": os.environ.get("TMPDIR", "/tmp"),+ }+ return env++ def run_python(self, code: str, **kwargs) -> subprocess.CompletedProcess:+ """Run code with the installed interpreter, outside the source tree.++ cwd matters: from REPO_ROOT, `import sidepulse` could resolve against+ ./src rather than the installed package and prove nothing.+ """+ return subprocess.run(+ [str(self.python), "-c", textwrap.dedent(code)],+ capture_output=True, text=True, timeout=300,+ env=self.env(), cwd=str(self.home), **kwargs,+ )++ def run_script(self, name: str, args: list[str], **kwargs):+ return subprocess.run(+ [str(self.venv / "bin" / name), *args],+ capture_output=True, text=True, timeout=300,+ env=self.env(), cwd=str(self.home), **kwargs,+ )++ def shipped_modules(self) -> list[str]:+ names = []+ for path in sorted((REPO_ROOT / "src").rglob("*.py")):+ rel = path.relative_to(REPO_ROOT / "src")+ if rel.name == "__main__.py":+ continue # runs the CLI on import by design+ parts = list(rel.parts)+ parts[-1] = rel.stem+ if parts[-1] == "__init__":+ parts.pop()+ if parts:+ names.append(".".join(parts))+ return names++ # -- tests -----------------------------------------------------------++ def test_installed_package_is_not_the_source_tree(self):+ """Guard the guard: these tests are worthless if they import ./src."""+ result = self.run_python(+ "import sidepulse, sys; sys.stdout.write(sidepulse.__file__)"+ )+ self.assertEqual(0, result.returncode, result.stderr)+ self.assertIn(+ "site-packages",+ result.stdout,+ f"tests imported {result.stdout} instead of the installed package",+ )++ def test_status_bar_imports_after_plain_install(self):+ """The regression test for the ScriptingBridge dependency.++ `pip install .` and nothing else must be enough to import the status+ bar. No manual `pip install pyobjc-framework-...` may be required.+ """+ if sys.platform != "darwin":+ self.skipTest("status bar is macOS only")+ result = self.run_python("import sidepulse.status_bar")+ self.assertNotIn(+ DEPENDENCY_ERROR_MARKER,+ result.stderr + result.stdout,+ "a clean install still reports missing PyObjC dependencies:\n"+ f"{result.stderr}",+ )+ self.assertEqual(+ 0,+ result.returncode,+ f"importing the status bar failed on a clean install:\n{result.stderr}",+ )++ def test_every_shipped_module_imports_after_plain_install(self):+ darwin_only = {+ "sidepulse.status_bar",+ "sidepulse.virtual_device",+ "sidepulse.led_wasm",+ }+ for name in self.shipped_modules():+ if name in darwin_only and sys.platform != "darwin":+ continue+ with self.subTest(module=name):+ result = self.run_python(f"import {name}")+ self.assertEqual(+ 0,+ result.returncode,+ f"{name} does not import on a clean install:\n{result.stderr}",+ )++ def test_declared_frameworks_are_actually_installed(self):+ """Each PyObjC framework the code imports must arrive with the package."""+ if sys.platform != "darwin":+ self.skipTest("PyObjC frameworks are macOS only")+ for module in ("objc", "AppKit", "Foundation", "Quartz", "ScriptingBridge"):+ with self.subTest(framework=module):+ result = self.run_python(f"import {module}")+ self.assertEqual(+ 0,+ result.returncode,+ f"{module} is missing from a clean install; "+ f"add its distribution to pyproject.toml dependencies",+ )++ def test_console_scripts_are_installed(self):+ expected = ("sidepulse", "agent-monitor", "agent-status-bar", "sidepulse-reply")+ for name in expected:+ with self.subTest(script=name):+ self.assertTrue(+ (self.venv / "bin" / name).exists(),+ f"console script {name} was not installed",+ )++ def test_console_scripts_run(self):+ for name in ("sidepulse", "agent-monitor", "sidepulse-reply"):+ with self.subTest(script=name):+ result = self.run_script(name, ["--help"])+ self.assertIn(result.returncode, (0, 2), result.stderr)+ self.assertNotIn(DEPENDENCY_ERROR_MARKER, result.stderr)++ def test_packaged_resources_are_installed(self):+ """Package data declared in pyproject must survive the wheel build."""+ result = self.run_python(+ """+ import pathlib, sidepulse+ root = pathlib.Path(sidepulse.__file__).parent+ print("\\n".join(sorted(str(p.relative_to(root))+ for p in root.rglob("*")+ if p.is_file() and p.suffix != ".py")))+ """+ )+ self.assertEqual(0, result.returncode, result.stderr)+ source_resources = {+ p.name+ for p in (REPO_ROOT / "src/sidepulse/resources").rglob("*")+ if p.is_file()+ and p.suffix != ".py"+ and "__pycache__" not in p.parts+ }+ self.assertTrue(source_resources, "expected packaged resource files")+ for name in sorted(source_resources):+ with self.subTest(resource=name):+ self.assertIn(+ name,+ result.stdout,+ f"{name} is in the source tree but missing from the install",+ )++ def test_hook_works_from_the_installed_package(self):+ """The hook path must work end to end on a fresh install."""+ log_path = self.home / "hook.jsonl"+ result = subprocess.run(+ [+ str(self.venv / "bin" / "agent-monitor"), "hook-log",+ "--provider", "claude", "--log", str(log_path),+ ],+ input=json.dumps({"hook_event_name": "Stop", "session_id": "s1"}),+ capture_output=True, text=True, timeout=300,+ env=self.env(), cwd=str(self.home),+ )+ self.assertEqual(0, result.returncode, result.stderr)+ self.assertEqual("", result.stdout)+ self.assertTrue(log_path.exists(), "installed hook wrote no log")+ record = json.loads(log_path.read_text(encoding="utf-8").splitlines()[0])+ self.assertEqual("Stop", record["hook_event_name"])++ def test_installed_hook_command_points_at_the_installed_package(self):+ """`sidepulse install` writes a command into somebody's agent config.++ On a clean install that command must reference the installed package+ and run successfully, not a path that only exists on a dev machine.+ """+ result = self.run_python(+ """+ from pathlib import Path+ from sidepulse.install import hook_command+ print(hook_command("claude", Path.home() / "installed-hook.jsonl"))+ """+ )+ self.assertEqual(0, result.returncode, result.stderr)+ command = result.stdout.strip()+ self.assertTrue(command, "hook_command produced nothing")++ run = subprocess.run(+ command, shell=True,+ input=json.dumps({"hook_event_name": "Stop"}),+ capture_output=True, text=True, timeout=300,+ env=self.env(), cwd=str(self.home),+ )+ self.assertEqual(0, run.returncode, run.stderr)+ self.assertTrue(+ (self.home / "installed-hook.jsonl").exists(),+ f"the command written into agent configs logged nothing: {command}",+ )+++ @unittest.skipUnless(sys.platform == "darwin", "status bar is macOS only")+ def test_status_bar_start_foreground_gets_past_startup(self):+ """`sidepulse status-bar start --foreground` must not die on imports.++ This is the literal command that failed, run against a clean install.+ It enters a GUI event loop, so success looks like "still running when+ we kill it"; failure looks like exiting immediately with the PyObjC+ dependency error.+ """+ # Mark first-run setup complete so launching does not open a window on+ # the developer's screen.+ config_dir = self.home / ".config/sidepulse/agent-monitor"+ config_dir.mkdir(parents=True, exist_ok=True)+ (config_dir / "settings.json").write_text(+ json.dumps({"setup_screen_completed": True}), encoding="utf-8"+ )++ process = subprocess.Popen(+ [+ str(self.venv / "bin" / "sidepulse"),+ "status-bar", "start", "--foreground",+ ],+ stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True,+ env=self.env(), cwd=str(self.home),+ )+ try:+ stdout, stderr = process.communicate(timeout=8)+ except subprocess.TimeoutExpired:+ # Still alive after 8s: it got past imports and is running.+ process.kill()+ stdout, stderr = process.communicate()+ self.assertNotIn(DEPENDENCY_ERROR_MARKER, stdout + stderr)+ return++ self.fail(+ "status-bar exited immediately instead of running.\n"+ f"returncode={process.returncode}\nstdout={stdout}\nstderr={stderr}"+ )+++if __name__ == "__main__":+ unittest.main()diff --git a/tests/test_hook_stability.py b/tests/test_hook_stability.pyindex 19d7126..4715bb7 100644--- a/tests/test_hook_stability.py+++ b/tests/test_hook_stability.py@@ -407,6 +407,9 @@ class EntryPointSubprocessTests(unittest.TestCase):)self.assertEqual(0, result.returncode, result.stderr)self.assertTrue(log_path.exists())+ # Catches stray debug prints at module scope, which would corrupt the+ # hook protocol for anyone routing hooks through the CLI.+ self.assertEqual("", result.stdout, f"CLI printed to stdout: {result.stdout!r}")class InstalledCommandTests(unittest.TestCase):