Support Flathub test refs in runtime smoke

docs/flathub.md

@@ -14,6 +14,9 @@ Use this note when maintaining the Mini EQ Flathub package.
 - The manifest builds in project CI and installs the desktop file, AppStream
   metadata, icons, licenses, PipeWire filter-chain module, pipewire-gobject,
   NumPy, and libebur128.
+- PyGObject is supplied by the GNOME runtime's system Python/GI stack. Do not
+  add it to `python3-dependencies.yaml`; that file is for bundled PyPI
+  dependencies such as NumPy.
 - `flatpak-builder-lint manifest io.github.bhack.mini-eq.yaml` passes locally.
 
 ## Repository Split
@@ -67,6 +70,7 @@ packaging branch and open, submit, and merge the Flathub PR manually.
    tag or commit URL before publishing.
 6. Keep `python3-dependencies.yaml` unchanged unless Python dependencies
    changed. If dependencies changed, regenerate it and update both repositories.
+   PyGObject is a runtime-provided GI binding, not a bundled PyPI dependency.
 7. Run the validation commands below.
 8. As the maintainer, open a pull request against the Flathub repository's
    `master` branch.
@@ -86,7 +90,12 @@ before merging.
 Use Flathub PR test builds for normal release handoff validation. Flathub starts
 a temporary test build for pull requests and the bot posts an installable bundle
 when the build is ready; test that build before merging runtime-sensitive
-changes.
+changes. The temporary build installs as the Flatpak `test` branch, so target
+that branch explicitly when running runtime smoke:
+
+```bash
+python3 tools/check_flatpak_runtime.py --app-ref io.github.bhack.mini-eq//test
+```
 
 Use the Flathub `beta` branch only for release-candidate or high-risk changes
 that need a user-installable Flatpak before the stable update. The Flathub
@@ -184,11 +193,19 @@ If a `repo/` is produced, run:
 flatpak run --command=flatpak-builder-lint org.flatpak.Builder repo repo
 ```
 
+Local repo lint can report screenshot mirroring errors when the generated repo
+does not include Flathub's mirrored screenshot refs. If those are the only repo
+lint errors, confirm the AppStream screenshot URLs point at an immutable tag or
+commit and are reachable; then treat the Flathub PR build's `Build ready`
+status as the authoritative screenshot-mirroring check.
+
 ## Packaging Notes
 
 - Mini EQ is an upstream-maintained GTK/Libadwaita graphical application.
 - The app ID `io.github.bhack.mini-eq` matches the GitHub repository ownership.
 - The app requires `xdg-run/pipewire-0` to create and use PipeWire audio nodes.
+- PyGObject comes from `org.gnome.Platform`; bundling it from PyPI would risk
+  mismatches with the runtime GLib, GTK, and GObject-Introspection stack.
 - The Flatpak bundles only the PipeWire filter-chain module and SPA builtin
   filter graph plugin needed inside the app process; it does not bundle or run
   a PipeWire daemon or session manager.

tests/test_check_flatpak_runtime.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import pytest
+
+from tools import check_flatpak_runtime
+
+
+@pytest.mark.parametrize(
+    "app_ref",
+    [
+        "io.github.bhack.mini-eq//test",
+        "app/io.github.bhack.mini-eq/aarch64/test",
+        "app/io.github.bhack.mini-eq/x86_64/test",
+    ],
+)
+def test_flatpak_runtime_smoke_accepts_flathub_test_refs(app_ref: str) -> None:
+    assert check_flatpak_runtime.flatpak_app_ref(app_ref) == app_ref
+    assert check_flatpak_runtime.flatpak_run_command(app_ref, "--check-deps") == [
+        "flatpak",
+        "run",
+        app_ref,
+        "--check-deps",
+    ]

tools/check_flatpak_runtime.py

@@ -17,18 +17,24 @@
 APP_ID = "io.github.bhack.mini-eq"
 DEFAULT_APP_REF = f"{APP_ID}//master"
 STABLE_APP_REF = f"{APP_ID}//stable"
+TEST_APP_REF = f"{APP_ID}//test"
 FULL_AARCH64_MASTER_REF = f"app/{APP_ID}/aarch64/master"
 FULL_AARCH64_STABLE_REF = f"app/{APP_ID}/aarch64/stable"
+FULL_AARCH64_TEST_REF = f"app/{APP_ID}/aarch64/test"
 FULL_X86_64_MASTER_REF = f"app/{APP_ID}/x86_64/master"
 FULL_X86_64_STABLE_REF = f"app/{APP_ID}/x86_64/stable"
+FULL_X86_64_TEST_REF = f"app/{APP_ID}/x86_64/test"
 FLATPAK_APP_REFS = (
     APP_ID,
     DEFAULT_APP_REF,
     STABLE_APP_REF,
+    TEST_APP_REF,
     FULL_AARCH64_MASTER_REF,
     FULL_AARCH64_STABLE_REF,
+    FULL_AARCH64_TEST_REF,
     FULL_X86_64_MASTER_REF,
     FULL_X86_64_STABLE_REF,
+    FULL_X86_64_TEST_REF,
 )
 SMOKE_APPLICATION_NAME = "mini-eq-flatpak-smoke"
 SMOKE_MEDIA_ROLE = "MiniEQSmoke"
@@ -82,14 +88,20 @@ def flatpak_run_command(app_ref: str, *app_args: str) -> list[str]:
         return ["flatpak", "run", DEFAULT_APP_REF, *app_args]
     if app_ref == STABLE_APP_REF:
         return ["flatpak", "run", STABLE_APP_REF, *app_args]
+    if app_ref == TEST_APP_REF:
+        return ["flatpak", "run", TEST_APP_REF, *app_args]
     if app_ref == FULL_AARCH64_MASTER_REF:
         return ["flatpak", "run", FULL_AARCH64_MASTER_REF, *app_args]
     if app_ref == FULL_AARCH64_STABLE_REF:
         return ["flatpak", "run", FULL_AARCH64_STABLE_REF, *app_args]
+    if app_ref == FULL_AARCH64_TEST_REF:
+        return ["flatpak", "run", FULL_AARCH64_TEST_REF, *app_args]
     if app_ref == FULL_X86_64_MASTER_REF:
         return ["flatpak", "run", FULL_X86_64_MASTER_REF, *app_args]
     if app_ref == FULL_X86_64_STABLE_REF:
         return ["flatpak", "run", FULL_X86_64_STABLE_REF, *app_args]
+    if app_ref == FULL_X86_64_TEST_REF:
+        return ["flatpak", "run", FULL_X86_64_TEST_REF, *app_args]
     raise RuntimeError(f"unsupported Flatpak app ref: {app_ref}")