Skip to content

StreamVault is a TV-first free IPTV player for Android TV built with Kotlin, Jetpack Compose, Room, Hilt, and Media3.

test(catalog): add rerunnable xtream fixture

David Nashash06fcf4a23e66
diff --git a/docs/COMPOSE_REDUCTION_AND_UI_ARCHITECTURE_PLAN.md b/docs/COMPOSE_REDUCTION_AND_UI_ARCHITECTURE_PLAN.md
index ef0aedff..b03c9a74 100644
--- a/docs/COMPOSE_REDUCTION_AND_UI_ARCHITECTURE_PLAN.md
+++ b/docs/COMPOSE_REDUCTION_AND_UI_ARCHITECTURE_PLAN.md
@@ -981,8 +981,10 @@ paths, plus reversible quick-filter save/reload/remove persistence. The full
extracted under `:feature:catalog`; its execution report records passing
connected goldens, a public-M3U Home/Live/Movies/Series/Search smoke pass,
and a diagnostic temporary Xtream fixture run covering VOD/series details,
- episodes, saved filters, and cross-type Search. The committed-fixture,
- remaining action/direct-Favorites/accessibility journeys, successful
+ episodes, saved filters, and cross-type Search. The checked-in
+ `tools/catalog_xtream_fixture.py` now provides a rerunnable development
+ seed; the remaining action/direct-Favorites/accessibility journeys,
+ successful
diagnostic Dashboard benchmark rerun after populating a scrollable seeded
Home shelf, open paired benchmark gate, refreshed release-like profiles, and
current app lint baseline failure remain explicitly tracked. System remains
diff --git a/docs/COMPOSE_REDUCTION_PHASE5_CATALOG_REPORT.md b/docs/COMPOSE_REDUCTION_PHASE5_CATALOG_REPORT.md
index 15ece502..35990774 100644
--- a/docs/COMPOSE_REDUCTION_PHASE5_CATALOG_REPORT.md
+++ b/docs/COMPOSE_REDUCTION_PHASE5_CATALOG_REPORT.md
@@ -107,9 +107,10 @@ series details, season/episode rows, movie and series favourite toggles, saved
filters, and a five-result cross-type Search query (Live TV 1, Movies 2,
Series 2). The semantic route/title/count evidence and the exact fixture
limitations are recorded in
-`validation/phase5_catalog/task14-xtream-fixture-journeys.md`. This is
-diagnostic evidence from a temporary ignored server, not a committed fixture
-harness or a production-provider pass.
+`validation/phase5_catalog/task14-xtream-fixture-journeys.md`. The fixture is
+now available as the checked-in development tool
+`tools/catalog_xtream_fixture.py`; this remains diagnostic evidence, not a
+production-provider pass.
The remaining Dashboard customization, load-more/reorder/return, download,
Cast chooser, direct Favorites-host, touch/phone/tablet, RTL,
@@ -167,10 +168,10 @@ execution-time project access.
## Next acceptance work
-1. Promote the temporary Xtream responses into a committed, rerunnable
- production-activity fixture (or use approved provider data), then execute
- the remaining Dashboard, browse, detail-action, direct Favorites, and
- accessibility journeys.
+1. Use the checked-in Xtream fixture (or approved provider data) to execute the
+ remaining Dashboard, browse, detail-action, direct Favorites, and
+ accessibility journeys, and keep the fixture invocation in the validation
+ protocol.
2. Capture a cache-equivalent pre-extraction run and pair it with the
successful Dashboard benchmark evidence, using the same seeded content,
device, iteration count, and compilation mode. Keep app lint remediation and
diff --git a/docs/COMPOSE_REDUCTION_PHASE5_ROADMAP.md b/docs/COMPOSE_REDUCTION_PHASE5_ROADMAP.md
index d48d31c7..069b4805 100644
--- a/docs/COMPOSE_REDUCTION_PHASE5_ROADMAP.md
+++ b/docs/COMPOSE_REDUCTION_PHASE5_ROADMAP.md
@@ -117,8 +117,9 @@ checks and current-checkout build-isolation samples. The public-M3U seeded
Home/Live/Movies/Series/Search smoke pass is supplemented by a diagnostic
temporary Xtream fixture run covering VOD/series details, episodes, saved
filters, and cross-type Search; the semantic evidence is recorded in the
-Catalog validation directory. A committed rerunnable fixture is still needed
-for the remaining Dashboard/action/direct-Favorites/accessibility journeys.
+Catalog validation directory. The checked-in `tools/catalog_xtream_fixture.py`
+now provides a rerunnable development seed for the remaining
+Dashboard/action/direct-Favorites/accessibility journeys.
A focused Dashboard macrobenchmark rerun passed 1/1 with five warm iterations
once public-M3U live-channel activity populated a scrollable Home shelf
(`frameCount` min/median/max 88/91/98; `frameOverrunMs` P50/P90/P95/P99
diff --git a/docs/superpowers/plans/2026-09-02-catalog-feature-extraction.md b/docs/superpowers/plans/2026-09-02-catalog-feature-extraction.md
index f479d569..da1bfc68 100644
--- a/docs/superpowers/plans/2026-09-02-catalog-feature-extraction.md
+++ b/docs/superpowers/plans/2026-09-02-catalog-feature-extraction.md
@@ -32,9 +32,10 @@ work is also recorded there. The available seeded Home/Live/Movies/Series/
Search smoke pass is documented. A temporary local Xtream fixture follow-up
also exercised VOD/series details, episodes, saved filters, and cross-type
Search in the production activity; its semantic evidence is in
-`validation/phase5_catalog/task14-xtream-fixture-journeys.md`. A committed
-rerunnable fixture is still needed for the remaining Dashboard/action/direct-
-Favorites/accessibility journeys, and repository-wide app lint remains open.
+`validation/phase5_catalog/task14-xtream-fixture-journeys.md`. The checked-in
+`tools/catalog_xtream_fixture.py` now provides a rerunnable development seed
+for the remaining Dashboard/action/direct-Favorites/accessibility journeys;
+repository-wide app lint remains open.
A focused Dashboard macrobenchmark rerun now passes after public-M3U
live-channel activity populates a scrollable seeded Home shelf, but it is
diagnostic after-run evidence rather than the required cache-equivalent paired
diff --git a/tools/catalog_xtream_fixture.py b/tools/catalog_xtream_fixture.py
new file mode 100644
index 00000000..5007fadb
--- /dev/null
+++ b/tools/catalog_xtream_fixture.py
@@ -0,0 +1,329 @@
+#!/usr/bin/env python3
+"""Deterministic local Xtream fixture for Catalog production-activity checks.
+
+Run this process on the host and point the Android debug build at
+``http://10.0.2.2:8765``. The fixture intentionally models only the Xtream
+player API fields consumed by the app; it never contacts a provider and logs
+actions without query credentials.
+"""
+
+from __future__ import annotations
+
+import argparse
+import copy
+import json
+import sys
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import parse_qs, urlparse
+
+
+DEFAULT_PORT = 8765
+ASSET_BASE = f"http://10.0.2.2:{DEFAULT_PORT}/assets"
+
+LIVE_CATEGORIES = [
+ {"category_id": "101", "category_name": "Fixture Live", "parent_id": 0, "is_adult": 0},
+]
+VOD_CATEGORIES = [
+ {"category_id": "201", "category_name": "Fixture Movies", "parent_id": 0, "is_adult": 0},
+]
+SERIES_CATEGORIES = [
+ {"category_id": "301", "category_name": "Fixture Series", "parent_id": 0, "is_adult": 0},
+]
+
+
+def configure_port(port: int) -> None:
+ global ASSET_BASE
+ ASSET_BASE = f"http://10.0.2.2:{port}/assets"
+
+
+def live_streams() -> list[dict[str, object]]:
+ return [
+ {
+ "num": 1,
+ "name": "Fixture News",
+ "stream_type": "live",
+ "stream_id": 501,
+ "stream_icon": f"{ASSET_BASE}/live.svg",
+ "epg_channel_id": "fixture-news",
+ "category_id": "101",
+ "category_name": "Fixture Live",
+ "container_extension": "ts",
+ "tv_archive": 0,
+ "is_adult": 0,
+ },
+ ]
+
+
+def vod_streams() -> list[dict[str, object]]:
+ return [
+ {
+ "num": 1,
+ "name": "Fixture Movie One",
+ "stream_type": "movie",
+ "stream_id": 1001,
+ "stream_icon": f"{ASSET_BASE}/movie-one.svg",
+ "cover_big": f"{ASSET_BASE}/movie-one.svg",
+ "added": "1704067200",
+ "category_id": "201",
+ "category_name": "Fixture Movies",
+ "container_extension": "mp4",
+ "rating": "8.4",
+ "rating_5based": "4.2",
+ "tmdb": "9001",
+ "is_adult": 0,
+ },
+ {
+ "num": 2,
+ "name": "Fixture Movie Two",
+ "stream_type": "movie",
+ "stream_id": 1002,
+ "stream_icon": f"{ASSET_BASE}/movie-two.svg",
+ "cover_big": f"{ASSET_BASE}/movie-two.svg",
+ "added": "1704153600",
+ "category_id": "201",
+ "category_name": "Fixture Movies",
+ "container_extension": "mp4",
+ "rating": "7.6",
+ "rating_5based": "3.8",
+ "tmdb": "9002",
+ "is_adult": 0,
+ },
+ ]
+
+
+def series_streams() -> list[dict[str, object]]:
+ return [
+ {
+ "series_id": 2001,
+ "name": "Fixture Series One",
+ "cover": f"{ASSET_BASE}/series-one.svg",
+ "cover_big": f"{ASSET_BASE}/series-one.svg",
+ "movie_image": f"{ASSET_BASE}/series-one.svg",
+ "plot": "A deterministic series fixture for Catalog acceptance journeys.",
+ "description": "A deterministic series fixture for Catalog acceptance journeys.",
+ "cast": "Fixture Actor",
+ "director": "Fixture Director",
+ "genre": "Drama",
+ "releaseDate": "2024-01-01",
+ "rating": "8.1",
+ "rating_5based": "4.0",
+ "category_id": "301",
+ "category_name": "Fixture Series",
+ "last_modified": "1704067200",
+ "is_adult": 0,
+ },
+ {
+ "series_id": 2002,
+ "name": "Fixture Series Two",
+ "cover": f"{ASSET_BASE}/series-two.svg",
+ "cover_big": f"{ASSET_BASE}/series-two.svg",
+ "movie_image": f"{ASSET_BASE}/series-two.svg",
+ "plot": "A second deterministic series fixture.",
+ "description": "A second deterministic series fixture.",
+ "genre": "Comedy",
+ "releaseDate": "2024-02-01",
+ "rating": "7.4",
+ "rating_5based": "3.7",
+ "category_id": "301",
+ "category_name": "Fixture Series",
+ "last_modified": "1706745600",
+ "is_adult": 0,
+ },
+ ]
+
+
+def movie_info(stream_id: int) -> dict[str, object]:
+ stream = next(item for item in vod_streams() if item["stream_id"] == stream_id)
+ return {
+ "info": {
+ "movie_image": stream["stream_icon"],
+ "tmdb_id": int(stream["tmdb"]),
+ "plot": "A deterministic movie fixture for Catalog acceptance journeys.",
+ "cast": "Fixture Actor, Fixture Actor Two",
+ "director": "Fixture Director",
+ "genre": "Adventure",
+ "releasedate": "2024-01-01",
+ "rating": stream["rating"],
+ "rating_5based": stream["rating_5based"],
+ "duration_secs": 5400,
+ "duration": "1h 30m",
+ "backdrop_path": [stream["cover_big"]],
+ "youtube_trailer": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+ },
+ "movie_data": {
+ "stream_id": stream_id,
+ "name": stream["name"],
+ "added": stream["added"],
+ "category_id": stream["category_id"],
+ "container_extension": "mp4",
+ "direct_source": "",
+ "tmdb": stream["tmdb"],
+ "is_adult": 0,
+ },
+ }
+
+
+def series_info(series_id: int) -> dict[str, object]:
+ series = next(item for item in series_streams() if item["series_id"] == series_id)
+ return {
+ "info": series,
+ "seasons": [
+ {
+ "season_number": 1,
+ "name": "Season 1",
+ "cover": series["cover"],
+ "air_date": "2024-01-01",
+ "episode_count": 2,
+ },
+ ],
+ "episodes": {
+ "1": [
+ {
+ "id": str(series_id * 10 + 1),
+ "episode_num": 1,
+ "title": f"{series['name']} - Pilot",
+ "container_extension": "mp4",
+ "added": "1704067200",
+ "season": 1,
+ "direct_source": "",
+ "info": {
+ "movie_image": series["cover"],
+ "plot": "The first fixture episode.",
+ "releasedate": "2024-01-01",
+ "duration_secs": 1800,
+ "duration": "30m",
+ "name": f"{series['name']} - Pilot",
+ },
+ },
+ {
+ "id": str(series_id * 10 + 2),
+ "episode_num": 2,
+ "title": f"{series['name']} - Second Signal",
+ "container_extension": "mp4",
+ "added": "1704153600",
+ "season": 1,
+ "direct_source": "",
+ "info": {
+ "movie_image": series["cover"],
+ "plot": "The second fixture episode.",
+ "releasedate": "2024-01-02",
+ "duration_secs": 1800,
+ "duration": "30m",
+ "name": f"{series['name']} - Second Signal",
+ },
+ },
+ ],
+ },
+ }
+
+
+def payload(action: str | None, query: dict[str, list[str]]) -> object:
+ if action is None:
+ return {
+ "user_info": {
+ "username": "fixture",
+ "password": "fixture",
+ "auth": 1,
+ "status": "Active",
+ "exp_date": "4102444800",
+ "is_trial": "0",
+ "active_cons": "0",
+ "created_at": "1704067200",
+ "max_connections": "1",
+ "allowed_output_formats": ["mp4", "ts"],
+ },
+ "server_info": {
+ "url": "10.0.2.2",
+ "port": str(DEFAULT_PORT),
+ "server_protocol": "http",
+ "api_version": "1.0",
+ "timezone": "UTC",
+ "timestamp_now": int(time.time()),
+ "time_now": "2024-01-01 00:00:00",
+ },
+ }
+ if action == "get_live_categories":
+ return copy.deepcopy(LIVE_CATEGORIES)
+ if action == "get_live_streams":
+ return live_streams()
+ if action == "get_vod_categories":
+ return copy.deepcopy(VOD_CATEGORIES)
+ if action == "get_vod_streams":
+ return vod_streams()
+ if action == "get_vod_info":
+ return movie_info(int(query.get("vod_id", ["1001"])[0]))
+ if action == "get_series_categories":
+ return copy.deepcopy(SERIES_CATEGORIES)
+ if action == "get_series":
+ return series_streams()
+ if action == "get_series_info":
+ return series_info(int(query.get("series_id", ["2001"])[0]))
+ if action in {"get_short_epg", "get_simple_data_table", "get_simple_data_table_by_stream_id"}:
+ return {"epg_listings": []}
+ return []
+
+
+class Handler(BaseHTTPRequestHandler):
+ server_version = "StreamVaultCatalogFixture/1.0"
+
+ def log_message(self, fmt: str, *args: object) -> None:
+ sys.stderr.write("[catalog-fixture] " + (fmt % args) + "\n")
+
+ def do_GET(self) -> None: # noqa: N802 (BaseHTTPRequestHandler API)
+ parsed = urlparse(self.path)
+ if parsed.path == "/player_api.php":
+ query = parse_qs(parsed.query)
+ action = query.get("action", [None])[0]
+ action_name = action or "authenticate"
+ self.log_message("action=%s", action_name)
+ body = json.dumps(payload(action, query), separators=(",", ":")).encode("utf-8")
+ self.send_response(200)
+ self.send_header("Content-Type", "application/json")
+ self.send_header("Content-Length", str(len(body)))
+ self.end_headers()
+ self.wfile.write(body)
+ return
+ if parsed.path == "/xmltv.php":
+ self.log_message("xmltv")
+ body = b"<?xml version=\"1.0\" encoding=\"UTF-8\"?><tv></tv>"
+ self.send_response(200)
+ self.send_header("Content-Type", "application/xml")
+ self.send_header("Content-Length", str(len(body)))
+ self.end_headers()
+ self.wfile.write(body)
+ return
+ if parsed.path.startswith("/assets/"):
+ label = parsed.path.rsplit("/", 1)[-1].replace(".svg", "").replace("-", " ").title()
+ body = (
+ "<svg xmlns='http://www.w3.org/2000/svg' width='320' height='480'>"
+ "<rect width='100%' height='100%' fill='#283044'/>"
+ f"<text x='20' y='240' fill='white' font-size='24'>{label}</text></svg>"
+ ).encode("utf-8")
+ self.send_response(200)
+ self.send_header("Content-Type", "image/svg+xml")
+ self.send_header("Content-Length", str(len(body)))
+ self.end_headers()
+ self.wfile.write(body)
+ return
+ self.send_response(404)
+ self.end_headers()
+
+
+def main() -> None:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--port", type=int, default=DEFAULT_PORT)
+ args = parser.parse_args()
+ configure_port(args.port)
+ server = ThreadingHTTPServer(("0.0.0.0", args.port), Handler)
+ print(f"Catalog Xtream fixture listening on 0.0.0.0:{args.port}", flush=True)
+ try:
+ server.serve_forever()
+ except KeyboardInterrupt:
+ pass
+ finally:
+ server.server_close()
+
+
+if __name__ == "__main__":
+ main()
diff --git a/tools/tests/test_catalog_xtream_fixture.py b/tools/tests/test_catalog_xtream_fixture.py
new file mode 100644
index 00000000..7bdfdbee
--- /dev/null
+++ b/tools/tests/test_catalog_xtream_fixture.py
@@ -0,0 +1,43 @@
+import importlib.util
+import json
+import threading
+import unittest
+from pathlib import Path
+from urllib.request import urlopen
+
+
+MODULE_PATH = Path(__file__).parents[1] / "catalog_xtream_fixture.py"
+SPEC = importlib.util.spec_from_file_location("catalog_xtream_fixture", MODULE_PATH)
+if SPEC is None or SPEC.loader is None:
+ raise RuntimeError(f"Unable to load fixture module from {MODULE_PATH}")
+FIXTURE = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(FIXTURE)
+
+
+class CatalogXtreamFixtureTest(unittest.TestCase):
+ def test_payload_contains_vod_and_series_acceptance_data(self):
+ movies = FIXTURE.payload("get_vod_streams", {})
+ series = FIXTURE.payload("get_series_info", {"series_id": ["2001"]})
+
+ self.assertEqual([1001, 1002], [item["stream_id"] for item in movies])
+ self.assertEqual("Fixture Series One", series["info"]["name"])
+ self.assertEqual(2, len(series["episodes"]["1"]))
+
+ def test_http_handler_serves_player_api_json(self):
+ server = FIXTURE.ThreadingHTTPServer(("127.0.0.1", 0), FIXTURE.Handler)
+ thread = threading.Thread(target=server.serve_forever, daemon=True)
+ thread.start()
+ try:
+ url = f"http://127.0.0.1:{server.server_address[1]}/player_api.php?action=get_vod_streams"
+ with urlopen(url, timeout=2) as response:
+ self.assertEqual(200, response.status)
+ body = json.load(response)
+ self.assertEqual("Fixture Movie One", body[0]["name"])
+ finally:
+ server.shutdown()
+ server.server_close()
+ thread.join(timeout=2)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/validation/phase5_catalog/task14-xtream-fixture-journeys.md b/validation/phase5_catalog/task14-xtream-fixture-journeys.md
index 6272ce74..2d521705 100644
--- a/validation/phase5_catalog/task14-xtream-fixture-journeys.md
+++ b/validation/phase5_catalog/task14-xtream-fixture-journeys.md
@@ -9,18 +9,34 @@ physical 1920x1080 at 320 dpi.
The public M3U seed used by Task 12 contains live channels only, so it cannot
exercise the Catalog's movie, series, detail, or saved-content paths. To test
whether the open journey gate was caused by the provider data rather than the
-extracted UI, a temporary local Xtream-compatible HTTP fixture was run on the
+extracted UI, the checked-in `tools/catalog_xtream_fixture.py` was run on the
host at port 8765. The emulator reached it through `10.0.2.2`; the debug APK
was configured through the existing `xtream.dev.*` `local.properties` hooks,
-then the settings were removed after the run. The fixture process and route
-captures remain ignored local artifacts and are not application code or a
-production-provider claim.
+then the settings were removed after the run. Route captures remain ignored
+local artifacts; the fixture is a development diagnostic, not a production-
+provider claim.
The fixture returned one live channel, two movies, two series, movie metadata,
and one season with two episodes per series. All observed player-API, XMLTV,
and image requests returned HTTP 200. No credentials or raw provider URLs are
included in this evidence.
+## Rerun protocol
+
+1. Run `python -m unittest tools.tests.test_catalog_xtream_fixture`.
+2. Add the four `xtream.dev.*` entries described in `docs/DEV_SEEDING.md` to
+ the ignored root `local.properties`, using `http://10.0.2.2:8765` as the
+ server and the fixture account values.
+3. Start `python tools/catalog_xtream_fixture.py --port 8765` from the repo
+ root, build/install the debug APK, clear `com.streamvault.app.debug`, and
+ launch `MainActivity`.
+4. Exercise the journeys below with D-pad/UIAutomator, then stop the server and
+ remove the four local fixture entries.
+
+The fixture test uses an ephemeral loopback port and does not require Android.
+The production-activity run uses port 8765 because that is the emulator-host
+mapping used by `10.0.2.2`.
+
## Journey results
| Surface | Evidence observed |
@@ -45,12 +61,13 @@ in because they contain no additional contract beyond the semantic dumps.
This run demonstrates that the extracted Catalog production activity can load
seeded VOD/series data, navigate detail and season/episode surfaces, toggle
movie and series favourites, apply saved filters, and search across all three
-content types. It narrows the previous Task 12 blocker: the checkout lacks a
-committed/reusable production-activity fixture harness, not a Catalog UI path.
+content types. It narrows the previous Task 12 blocker: the checkout lacked a
+fixture capable of exercising these paths, not a Catalog UI path. The checked-
+in fixture now makes this diagnostic run rerunnable.
-The run does not close the full Phase 5 acceptance gate. The temporary server
-was not committed, the public M3U flow remains live-only, and the following
-journeys still need a stable rerunnable fixture or approved provider data:
+The run does not close the full Phase 5 acceptance gate. The public M3U flow
+remains live-only, and the following journeys still need to be executed against
+the checked-in fixture (or approved provider data):
- Dashboard customization save/cancel and focus traversal;
- browse load-more, reorder, return-route, download enqueue, and Cast chooser;