Skip to content

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.yml
index d200e64..42d632a 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -31,6 +31,13 @@ jobs:
- name: Import contract
run: 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 stability
run: 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 -q
linux:
@@ -62,6 +73,9 @@ jobs:
python -m pip install --upgrade pip
python -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 suite
diff --git a/README.md b/README.md
index 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__.py
index 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.py
new file mode 100644
index 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.py
index 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):