faster linux build

tests/test_harness_guards.py

@@ -93,6 +93,32 @@ def test_fixtures_are_registered_with_pytest(request):
     )
 
 
+def test_import_precedence_is_correct():
+    """examples/ must beat build/ for `gui`; build/ must beat site-packages.
+
+    Regression guard: build/gui is a package named `gui`, so if build/ precedes
+    examples/ on sys.path then `import gui.viewer2d` resolves to the build
+    tooling and tests/test_qt_viewer_backend.py fails at collection.
+    """
+    import common
+    import gui
+    import wheel
+
+    examples_gui = (REPO_ROOT / "examples" / "gui").resolve()
+    build_root = (REPO_ROOT / "build").resolve()
+
+    assert Path(gui.__file__).resolve().parent == examples_gui, (
+        f"`gui` resolved to {gui.__file__} instead of {examples_gui}; "
+        "examples/ must precede build/ on sys.path"
+    )
+    for module in (common, wheel):
+        resolved = Path(module.__file__).resolve()
+        assert build_root in resolved.parents, (
+            f"`{module.__name__}` resolved to {resolved}, outside {build_root}; "
+            "build/ must precede site-packages on sys.path"
+        )
+
+
 def test_tests_run_against_checkout_not_stale_install():
     """Fail loudly when an old orisys in site-packages shadows src/orisys."""
     src_pkg = (REPO_ROOT / "src" / "orisys").resolve()