""" E2E Download Flow Tests. These tests verify the complete download journey from search to file retrieval. They require external services to be available and may take longer to run. Run with: uv run pytest tests/e2e/test_download_flow.py -v -m e2e """ import time import pytest from .conftest import ( DOWNLOAD_TIMEOUT, SUCCESS_DOWNLOAD_STATES, APIClient, DownloadTracker, assert_queue_order_response, assert_queued_download_response, ) def _assert_terminal_download_result( result: dict[str, object], *, source_id: str, expected_title: str, expected_source: str | None = None, ) -> None: """Assert that a finished download produced a structured queue payload.""" state = result["state"] entry = result["data"] assert isinstance(entry, dict) if state == "error": error_message = str( entry.get("status_message") or entry.get("last_error_message") or "" ).strip() pytest.fail( f"{expected_source or source_id} download failed" f"{f': {error_message}' if error_message else f': {entry!r}'}" ) assert state in SUCCESS_DOWNLOAD_STATES, ( f"{expected_source or source_id} ended in unexpected state {state!r}: {entry!r}" ) assert entry.get("id") == source_id assert entry.get("title") == expected_title if expected_source is not None: assert entry.get("source") == expected_source status = entry.get("status") assert status is None or status in SUCCESS_DOWNLOAD_STATES | {"queued"} def _is_duplicate_queue_error(response) -> bool: """Whether the API refused to queue a release because it already exists.""" if response.status_code != 500: return False try: payload = response.json() except ValueError: return False return payload == {"error": "Release is already in the download queue"} def _require_json_object( response, *, context: str, skip_statuses: set[int] | frozenset[int] = frozenset({503}) ) -> dict[str, object]: if response.status_code in skip_statuses: pytest.skip(f"{context} unavailable: {response.status_code}") assert response.status_code == 200, f"{context} failed: {response.status_code} {response.text}" payload = response.json() assert isinstance(payload, dict), f"{context} did not return a JSON object: {payload!r}" return payload def _extract_result_list(payload: object, *, context: str) -> list[dict[str, object]]: if isinstance(payload, dict): if "books" in payload: results = payload["books"] elif "releases" in payload: results = payload["releases"] else: results = payload.get("results", payload) else: results = payload if isinstance(results, dict): list_values = [value for value in results.values() if isinstance(value, list)] if not list_values: pytest.fail(f"{context} returned an unexpected result structure: {payload!r}") if not any(list_values): pytest.skip(f"{context} returned no results") results = next(value for value in list_values if value) if not isinstance(results, list): pytest.fail(f"{context} did not return a result list: {payload!r}") if not results: pytest.skip(f"{context} returned no results") return results def _require_queue_entry( api_client: APIClient, book_id: str, *, context: str, timeout: int = 20, ) -> dict[str, object]: deadline = time.time() + timeout while time.time() < deadline: queue_resp = api_client.get("/api/queue/order") if queue_resp.status_code == 200: queue_order = assert_queue_order_response(queue_resp) for entry in queue_order: if entry.get("id") == book_id: return entry elif queue_resp.status_code == 503: pytest.skip(f"{context} queue endpoint unavailable") else: pytest.fail( f"{context} queue lookup failed: {queue_resp.status_code} {queue_resp.text}" ) status_resp = api_client.get("/api/status") if status_resp.status_code == 200: status_data = status_resp.json() if isinstance(status_data, dict): for state in ("complete", "done", "available", "error", "cancelled"): state_entries = status_data.get(state) if isinstance(state_entries, dict) and book_id in state_entries: pytest.fail( f"{context} reached terminal state {state} before it was observed in the queue: " f"{state_entries[book_id]!r}" ) time.sleep(1) pytest.fail(f"{context} never appeared in the queue") def _wait_for_queue_absence( api_client: APIClient, book_id: str, *, context: str, timeout: int = 20, ) -> None: deadline = time.time() + timeout while time.time() < deadline: queue_resp = api_client.get("/api/queue/order") if queue_resp.status_code == 200: queue_order = assert_queue_order_response(queue_resp) if all(entry.get("id") != book_id for entry in queue_order): return elif queue_resp.status_code == 503: pytest.skip(f"{context} queue endpoint unavailable") else: pytest.fail( f"{context} queue lookup failed: {queue_resp.status_code} {queue_resp.text}" ) time.sleep(1) pytest.fail(f"{context} still appeared in the queue after cancellation") def _find_available_provider(api_client: APIClient) -> str | None: """Find a working metadata provider.""" resp = api_client.get("/api/metadata/providers") if resp.status_code == 503: pytest.skip("Metadata providers unavailable") assert resp.status_code == 200, f"Metadata providers failed: {resp.status_code} {resp.text}" providers_data = resp.json() if not isinstance(providers_data, (dict, list)): pytest.fail(f"Metadata providers returned an unexpected payload: {providers_data!r}") providers = ( providers_data.get("providers", []) if isinstance(providers_data, dict) else providers_data ) provider_names = [ provider.get("name") for provider in providers if ( isinstance(provider, dict) and provider.get("name") and provider.get("enabled") is True and provider.get("available") is True ) ] for name in provider_names: test_resp = api_client.get( "/api/metadata/search", params={"query": "test", "provider": name}, timeout=30, ) if test_resp.status_code == 200: return name if test_resp.status_code != 503: pytest.fail( f"Metadata provider {name} failed during availability check: " f"{test_resp.status_code} {test_resp.text}" ) pytest.skip("No working metadata providers available") @pytest.mark.e2e @pytest.mark.slow class TestMetadataToReleaseFlow: """Test the flow from metadata search to release listing.""" def test_search_to_releases_flow(self, protected_api_client: APIClient): """Test searching metadata then finding releases.""" # Find a working provider provider = _find_available_provider(protected_api_client) # Search for a public domain book search_resp = protected_api_client.get( "/api/metadata/search", params={"query": "Moby Dick Herman Melville", "provider": provider}, timeout=30, ) search_data = _require_json_object(search_resp, context="metadata search") results = _extract_result_list(search_data, context="metadata search") # Get the first result first_result = results[0] book_id = first_result.get("id") or first_result.get("provider_id") assert book_id, "Search result missing ID" # Now search for releases releases_resp = protected_api_client.get( "/api/releases", params={ "provider": provider, "book_id": book_id, "title": first_result.get("title", ""), "author": first_result.get("author", ""), }, timeout=60, ) releases_data = _require_json_object(releases_resp, context="release lookup") releases = releases_data.get("releases") if not isinstance(releases, list): pytest.fail(f"Release lookup returned an invalid releases payload: {releases_data!r}") if not releases: pytest.skip("No releases available") assert "book" in releases_data @pytest.mark.e2e @pytest.mark.slow class TestFullDownloadJourney: """ Test the complete download journey. This test: 1. Searches for a book 2. Finds releases 3. Queues a download 4. Waits for completion 5. Verifies the file exists """ def test_complete_download_flow( self, protected_api_client: APIClient, download_tracker: DownloadTracker ): """Test the complete search -> download -> verify flow.""" # Find a working provider provider = _find_available_provider(protected_api_client) if not provider: pytest.skip("No metadata providers available") # Search for a public domain book search_resp = protected_api_client.get( "/api/metadata/search", params={"query": "Pride and Prejudice Jane Austen", "provider": provider}, timeout=30, ) search_data = _require_json_object(search_resp, context="metadata search") results = _extract_result_list(search_data, context="metadata search") first_result = results[0] book_id = first_result.get("id") or first_result.get("provider_id") # Get releases releases_resp = protected_api_client.get( "/api/releases", params={ "provider": provider, "book_id": book_id, "title": first_result.get("title", ""), }, timeout=60, ) releases_data = _require_json_object(releases_resp, context="release lookup") releases = releases_data.get("releases", []) if not releases: pytest.skip("No releases available") # Find an epub release (prefer smaller files) target_release = None for release in releases: fmt = release.get("format", "").lower() if fmt == "epub": target_release = release break if not target_release: # Fall back to first release target_release = releases[0] # Queue the download source_id = target_release.get("source_id") or target_release.get("id") download_tracker.track(source_id) queue_resp = protected_api_client.post( "/api/releases/download", json={ "source": target_release.get("source", "direct_download"), "source_id": source_id, "title": target_release.get("title", "Test Book"), "format": target_release.get("format"), "size": target_release.get("size"), }, ) if not _is_duplicate_queue_error(queue_resp): assert_queued_download_response(queue_resp) # Wait for download to complete (or error) result = download_tracker.wait_for_status( source_id, target_states=["complete", "done", "available"], timeout=DOWNLOAD_TIMEOUT, ) if result is None: # Check if it errored status_resp = protected_api_client.get("/api/status") if status_resp.status_code == 200: status_data = status_resp.json() error_info = status_data.get("error", {}).get(source_id) if error_info: pytest.fail(f"Download failed: {error_info}") pytest.fail("Download timed out") _assert_terminal_download_result( result, source_id=source_id, expected_title=target_release.get("title", "Test Book"), expected_source=target_release.get("source", "direct_download"), ) @pytest.mark.e2e @pytest.mark.slow class TestDirectSourceReleaseFlow: """Test direct-mode search, record lookup, and download via shared release APIs.""" def test_direct_source_search_and_download( self, protected_api_client: APIClient, download_tracker: DownloadTracker ): """Test the shared direct-mode source query -> record -> release download flow.""" search_resp = protected_api_client.get( "/api/releases", params={"source": "direct_download", "query": "Frankenstein Mary Shelley"}, timeout=30, ) if search_resp.status_code == 503: pytest.skip("Direct source query unavailable") assert search_resp.status_code == 200, ( f"Direct source query failed: {search_resp.status_code} {search_resp.text}" ) payload = search_resp.json() assert isinstance(payload, dict), ( f"Direct source query returned an unexpected payload: {payload!r}" ) results = payload.get("releases") or [] if not isinstance(results, list): pytest.fail(f"Direct source query returned an unexpected payload: {payload!r}") if not results: pytest.skip("No direct source query results") first_result = results[0] source = first_result.get("source") source_id = first_result.get("source_id") assert source == "direct_download", "Result missing direct source context" assert source_id, "Result missing source_id" info_resp = protected_api_client.get(f"/api/release-sources/{source}/records/{source_id}") if info_resp.status_code != 200: pytest.fail(f"Source record endpoint failed: {info_resp.status_code}") # Queue download from the shared release payload download_tracker.track(source_id) download_resp = protected_api_client.post( "/api/releases/download", json={**first_result, "content_type": "ebook", "search_mode": "direct"}, ) if not _is_duplicate_queue_error(download_resp): assert_queued_download_response(download_resp) result = download_tracker.wait_for_status( source_id, target_states=["complete", "done", "available"], timeout=DOWNLOAD_TIMEOUT, ) assert result is not None, "Direct source download did not reach a terminal state" _assert_terminal_download_result( result, source_id=source_id, expected_title=first_result.get("title", "Unknown title"), expected_source="direct_download", ) @pytest.mark.e2e class TestDownloadCancellation: """Test download cancellation functionality.""" def test_cancel_queued_download( self, protected_api_client: APIClient, download_tracker: DownloadTracker ): """Test cancelling a queued download.""" # Queue a fake download test_id = f"cancel-test-{int(time.time())}" download_tracker.track(test_id) queue_resp = protected_api_client.post( "/api/releases/download", json={ "source": "test_source", "source_id": test_id, "title": "Cancel Test Book", }, ) assert_queued_download_response(queue_resp) _require_queue_entry( protected_api_client, test_id, context="cancel download precondition", ) # Cancel it cancel_resp = protected_api_client.delete(f"/api/download/{test_id}/cancel") assert cancel_resp.status_code == 200 cancel_data = cancel_resp.json() assert cancel_data == {"status": "cancelled", "book_id": test_id} _wait_for_queue_absence( protected_api_client, test_id, context="cancel download", ) def test_cancel_removes_from_queue( self, protected_api_client: APIClient, download_tracker: DownloadTracker ): """Test that cancellation removes item from queue.""" test_id = f"cancel-verify-{int(time.time())}" download_tracker.track(test_id) # Queue it protected_api_client.post( "/api/releases/download", json={ "source": "test_source", "source_id": test_id, "title": "Cancel Verify Test", }, ) _require_queue_entry( protected_api_client, test_id, context="cancel verification precondition", ) # Cancel it cancel_resp = protected_api_client.delete(f"/api/download/{test_id}/cancel") assert cancel_resp.status_code == 200 assert cancel_resp.json() == {"status": "cancelled", "book_id": test_id} # Check it's not in the queue _wait_for_queue_absence( protected_api_client, test_id, context="cancel verification", ) @pytest.mark.e2e class TestQueuePriority: """Test queue priority functionality.""" def test_set_priority(self, protected_api_client: APIClient, download_tracker: DownloadTracker): """Test setting download priority.""" test_id = f"priority-test-{int(time.time())}" download_tracker.track(test_id) # Queue it queue_resp = protected_api_client.post( "/api/releases/download", json={ "source": "test_source", "source_id": test_id, "title": "Priority Test", "priority": 0, }, ) assert_queued_download_response(queue_resp) _require_queue_entry( protected_api_client, test_id, context="priority update precondition", ) # Update priority priority_resp = protected_api_client.put( f"/api/queue/{test_id}/priority", json={"priority": 10}, ) assert priority_resp.status_code == 200 assert priority_resp.json() == {"status": "updated", "book_id": test_id, "priority": 10} queue_resp = protected_api_client.get("/api/queue/order") queue_order = assert_queue_order_response(queue_resp) matching_entries = [entry for entry in queue_order if entry.get("id") == test_id] assert len(matching_entries) == 1 assert matching_entries[0]["priority"] == 10