From e94d97270a736a119497f261676a7bae2b3c4999 Mon Sep 17 00:00:00 2001 From: Manish Kumar Date: Fri, 18 Sep 2026 14:39:53 -0500 Subject: [PATCH] docs: improve test suite documentation Co-Authored-By: Claude Sonnet 5 --- tests/conftest.py | 7 ++++++- tests/test_conftest_hooks.py | 9 +++++++++ tests/test_generated_infra.py | 13 +++++++++++++ tests/test_manifest.py | 12 ++++++++++++ tests/test_static_contracts.py | 16 ++++++++++++++++ tests/test_video_service.py | 17 +++++++++++++++++ 6 files changed, 73 insertions(+), 1 deletion(-) diff --git a/tests/conftest.py b/tests/conftest.py index e7f6143..4035c10 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -1,4 +1,7 @@ -"""Shared test-environment handling for optional Docker integration tests.""" +"""Shared test-environment handling for optional Docker integration tests. + +Developer: Manish Kumar +""" import shutil import subprocess @@ -7,6 +10,8 @@ def pytest_runtest_setup(item): + """Skip a Docker-marked test when the docker executable is missing or the Docker daemon is + unreachable, leaving every other test untouched.""" if "docker" not in item.keywords: return docker = shutil.which("docker") diff --git a/tests/test_conftest_hooks.py b/tests/test_conftest_hooks.py index 4f23428..50b5408 100644 --- a/tests/test_conftest_hooks.py +++ b/tests/test_conftest_hooks.py @@ -5,6 +5,8 @@ two skip paths -- docker not installed, docker daemon unreachable -- are exercised here by calling the hook directly against a minimal fake item, rather than by actually uninstalling Docker. + +Developer: Manish Kumar """ import shutil @@ -16,16 +18,22 @@ class _FakeItem: + """Minimal stand-in for a pytest test item, carrying only the keywords the hook under test + inspects.""" + def __init__(self, keywords): self.keywords = keywords def test_pytest_runtest_setup_ignores_non_docker_items(): + """Leave a non-Docker test item alone: neither raise nor skip it.""" item = _FakeItem(keywords={}) _conftest.pytest_runtest_setup(item) # must not raise or skip def test_pytest_runtest_setup_skips_when_docker_executable_missing(monkeypatch): + """Skip a Docker-marked item, naming the missing docker executable, when Docker is not + installed.""" monkeypatch.setattr(shutil, "which", lambda name: None) item = _FakeItem(keywords={"docker": True}) with pytest.raises(pytest.skip.Exception, match="docker executable"): @@ -33,6 +41,7 @@ def test_pytest_runtest_setup_skips_when_docker_executable_missing(monkeypatch): def test_pytest_runtest_setup_skips_when_docker_daemon_unreachable(monkeypatch): + """Skip a Docker-marked item, naming the unreachable daemon, when docker info fails.""" monkeypatch.setattr(shutil, "which", lambda name: "/usr/bin/docker") monkeypatch.setattr( subprocess, "run", lambda *a, **k: subprocess.CompletedProcess(a, returncode=1) diff --git a/tests/test_generated_infra.py b/tests/test_generated_infra.py index 9a213d9..62a5dca 100644 --- a/tests/test_generated_infra.py +++ b/tests/test_generated_infra.py @@ -1,3 +1,10 @@ +"""Validate the video manifest against its schema and, when Docker is available, exercise the built +nginx image end to end: static routes, the manifest headers, video headers, SPA fallback, and the +health endpoint. + +Developer: Manish Kumar +""" + import os import json import subprocess @@ -103,30 +110,36 @@ def docker_service(): subprocess.run(["docker", "rm", CONTAINER_NAME], capture_output=True) def test_nginx_root_serving(docker_service): + """Serve the SPA index as HTML from the container's root route.""" r = requests.get(BASE_URL) assert r.status_code == 200 assert "text/html" in r.headers["Content-Type"] def test_nginx_guide_serving(docker_service): + """Serve guide.html from the running container.""" r = requests.get(f"{BASE_URL}/guide.html") assert r.status_code == 200 def test_manifest_headers_and_cors(docker_service): + """Serve videos.json with no-cache and a wildcard CORS header.""" r = requests.get(f"{BASE_URL}/videos.json") assert r.headers["Cache-Control"] == "no-cache" assert r.headers["Access-Control-Allow-Origin"] == "*" def test_video_infrastructure_headers(docker_service): + """Advertise byte-range support on a served video file, when the file is present.""" r = requests.get(f"{BASE_URL}/my_video.mov") if r.status_code == 200: # Some Nginx configurations or proxies might double-up the Accept-Ranges header assert "bytes" in r.headers["Accept-Ranges"] def test_spa_fallback_routing(docker_service): + """Fall back to the SPA index as HTML for an unrecognized path.""" r = requests.get(BASE_URL + "/any/random/path") assert r.status_code == 200 assert "text/html" in r.headers["Content-Type"] def test_health_check_payload(docker_service): + """Report {"status": "ok"} from the container's health endpoint.""" r = requests.get(f"{BASE_URL}/health") assert r.json() == {"status": "ok"} diff --git a/tests/test_manifest.py b/tests/test_manifest.py index 5663f98..30c2076 100644 --- a/tests/test_manifest.py +++ b/tests/test_manifest.py @@ -1,3 +1,9 @@ +"""Validate the video manifest file: existence, valid JSON, decode-error reporting, schema +conformance, and unique ordering. + +Developer: Manish Kumar +""" + import json import os import pytest @@ -7,9 +13,11 @@ PERMITTED_TAGS = {'intro', 'tutorial', 'workflow', 'demo', 'hpc'} def test_manifest_exists(): + """Require the manifest file to exist at its configured path.""" assert os.path.exists(MANIFEST_PATH), f"{MANIFEST_PATH} does not exist" def test_manifest_is_valid_json(): + """Load the manifest as a JSON list without error.""" with open(MANIFEST_PATH, 'r') as f: try: data = json.load(f) @@ -18,6 +26,7 @@ def test_manifest_is_valid_json(): pytest.fail(f"Manifest is not valid JSON: {e}") def test_manifest_is_valid_json_reports_decode_errors(tmp_path): + """Report a JSON decode error through pytest.fail when the manifest is malformed.""" global MANIFEST_PATH bad_manifest = tmp_path / "bad.json" bad_manifest.write_text("{not valid json") @@ -29,6 +38,8 @@ def test_manifest_is_valid_json_reports_decode_errors(tmp_path): MANIFEST_PATH = original def test_manifest_schema(): + """Require every manifest entry to carry its required fields, a permitted tag, an integer order, + and a video file that exists on disk.""" with open(MANIFEST_PATH, 'r') as f: data = json.load(f) @@ -50,6 +61,7 @@ def test_manifest_schema(): assert os.path.exists(video_path), f"Video file {item['filename']} not found in {CONTENT_DIR}" def test_manifest_ordering(): + """Require every manifest entry's order value to be unique.""" with open(MANIFEST_PATH, 'r') as f: data = json.load(f) diff --git a/tests/test_static_contracts.py b/tests/test_static_contracts.py index 1c09602..2270deb 100644 --- a/tests/test_static_contracts.py +++ b/tests/test_static_contracts.py @@ -2,6 +2,8 @@ These tests intentionally exercise the files that are packaged into the nginx image without requiring Docker, a network service, or video decoding. + +Developer: Manish Kumar """ import json @@ -21,11 +23,14 @@ def load_manifest(): + """Load and parse the video manifest file.""" with MANIFEST.open(encoding="utf-8") as handle: return json.load(handle) def test_docker_image_packages_the_documented_content_root(): + """Package the content directory and nginx config into the image and expose port 8086, per the + Dockerfile.""" dockerfile = DOCKERFILE.read_text(encoding="utf-8") assert "COPY content/ /usr/share/nginx/html/" in dockerfile assert "COPY nginx.conf /etc/nginx/conf.d/default.conf" in dockerfile @@ -33,6 +38,8 @@ def test_docker_image_packages_the_documented_content_root(): def test_manifest_entries_are_complete_unique_and_backed_by_files(): + """Require every manifest entry to have a unique filename and order, exactly its five documented + fields, a matching video file on disk, and non-blank string fields.""" entries = load_manifest() assert isinstance(entries, list) and entries @@ -51,6 +58,8 @@ def test_manifest_entries_are_complete_unique_and_backed_by_files(): def test_nginx_routes_match_the_packaged_layout_and_documented_endpoints(): + """Require nginx.conf's document root, videos.json alias, videos/ alias, and health route to + match the packaged layout.""" config = NGINX.read_text(encoding="utf-8") assert 'root /usr/share/nginx/html;' in config assert "location = /videos.json" in config @@ -62,6 +71,8 @@ def test_nginx_routes_match_the_packaged_layout_and_documented_endpoints(): @pytest.mark.xfail(strict=True, reason="Known production routing mismatch: index.js uses /videos/* while Dockerfile packages content at the nginx document root") def test_index_uses_the_same_video_urls_as_the_nginx_configuration(): + """Require index.html's fetch URLs to match the routes nginx actually serves (a known, + deliberately xfailed production routing mismatch).""" html = INDEX.read_text(encoding="utf-8") # This currently fails and records the production routing defect: the # image contains /usr/share/nginx/html/*, not /videos/*. @@ -71,6 +82,8 @@ def test_index_uses_the_same_video_urls_as_the_nginx_configuration(): def test_index_contains_manifest_filter_search_and_modal_contracts(): + """Require index.html to contain the manifest, filter, search, and modal hooks its script relies + on.""" html = INDEX.read_text(encoding="utf-8") for marker in ("videos.json", "filterVideos", "setFilter", "openModal", "closeModal", "searchInput", "videoCount"): assert marker in html @@ -79,6 +92,7 @@ def test_index_contains_manifest_filter_search_and_modal_contracts(): def test_guide_has_all_documented_sections_and_navigation_handler(): + """Require guide.html to contain every documented section id and its navigation handler.""" html = GUIDE.read_text(encoding="utf-8") for section in ("overview", "local", "cloud", "hpc", "llm", "workbench", "workflow", "faq"): assert f'id="p-{section}"' in html @@ -88,6 +102,8 @@ def test_guide_has_all_documented_sections_and_navigation_handler(): @pytest.mark.xfail(strict=True, reason="Several manifest-listed video assets are zero-byte placeholders in the repository") def test_video_files_are_non_empty_and_have_expected_media_extensions(): + """Require every manifest-listed video file to be present and non-empty (a known, deliberately + xfailed placeholder-file gap).""" manifest_names = {entry["filename"] for entry in load_manifest()} content_videos = { path.name for path in CONTENT.iterdir() if path.suffix.lower() in {".mp4", ".webm", ".mov"} diff --git a/tests/test_video_service.py b/tests/test_video_service.py index 5d8d551..697317f 100644 --- a/tests/test_video_service.py +++ b/tests/test_video_service.py @@ -1,3 +1,10 @@ +"""Superseded duplicate of test_generated_infra.py's Docker infrastructure tests (kept out of +coverage per pyproject.toml): build and run the packaged nginx image, then exercise its root +route, manifest headers, video headers, SPA fallback, and health endpoint. + +Developer: Manish Kumar +""" + import subprocess import time import pytest @@ -13,6 +20,8 @@ @pytest.fixture(scope="module", autouse=True) def docker_container(): + """Build the image and start the container for the module, removing any leftover container from + a prior run first and cleaning up afterwards.""" # A failed/interrupted previous run can leave the fixed-name container # behind. Remove only that test-owned container before starting. subprocess.run(["docker", "rm", "-f", CONTAINER_NAME], check=False, @@ -61,18 +70,23 @@ def docker_container(): stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL) def test_root_returns_index(): + """Serve the SPA index as HTML with a title from the container's root route.""" response = requests.get(BASE_URL) assert response.status_code == 200 assert "text/html" in response.headers["Content-Type"] assert "" in response.text # Assuming index.html has a title def test_manifest_headers(): + """Serve videos.json with no-cache and a wildcard CORS header, exercised via this module's own + container fixture.""" response = requests.get(f"{BASE_URL}/videos.json") assert response.status_code == 200 assert response.headers["Cache-Control"] == "no-cache" assert response.headers["Access-Control-Allow-Origin"] == "*" def test_video_headers(): + """Advertise byte-range support, a day-long cache, and a wildcard CORS header on a served video + file, when the file is present.""" # Test with a known video file from manifest or a mock one # content/my_video.mov exists according to the file listing response = requests.get(f"{BASE_URL}/my_video.mov") @@ -84,6 +98,8 @@ def test_video_headers(): pytest.skip("my_video.mov not found in container, skipping header test") def test_spa_fallback(): + """Fall back to the SPA index as HTML for an unrecognized path, exercised via this module's own + container fixture.""" # Random paths should return index.html response = requests.get(f"{BASE_URL}/some/random/path") assert response.status_code == 200 @@ -92,6 +108,7 @@ def test_spa_fallback(): assert "<title>" in response.text def test_health_endpoint(): + """Report status ok from the container's health endpoint.""" response = requests.get(f"{BASE_URL}/health") assert response.status_code == 200 assert response.json()["status"] == "ok"