|
| 1 | +"""Integration tests for unified error response shape across the full app. |
| 2 | +
|
| 3 | +Verifies that ALL error status codes (401, 404, 422, 500) return the unified |
| 4 | +JSON error shape when using the full assembled app. Tests the complete |
| 5 | +middleware + error handler pipeline end-to-end. |
| 6 | +
|
| 7 | +Uses conftest.py fixtures: |
| 8 | + - client — authenticated TestClient (Supabase + auth overridden) |
| 9 | + - unauthenticated_client — TestClient with only Supabase overridden (401 on auth endpoints) |
| 10 | + - mock_supabase — MagicMock Supabase client (shared with client fixture) |
| 11 | +
|
| 12 | +Run: |
| 13 | + uv run pytest backend/tests/integration/test_error_responses.py -v |
| 14 | +""" |
| 15 | + |
| 16 | +import uuid |
| 17 | +from unittest.mock import MagicMock |
| 18 | + |
| 19 | +from fastapi.testclient import TestClient |
| 20 | +from postgrest.exceptions import APIError |
| 21 | + |
| 22 | +_PREFIX = "/api/v1" |
| 23 | + |
| 24 | +# --------------------------------------------------------------------------- |
| 25 | +# Security headers expected on every response |
| 26 | +# --------------------------------------------------------------------------- |
| 27 | + |
| 28 | +_EXPECTED_SECURITY_HEADERS: dict[str, str] = { |
| 29 | + "X-Content-Type-Options": "nosniff", |
| 30 | + "X-Frame-Options": "DENY", |
| 31 | + "X-XSS-Protection": "0", |
| 32 | + "Referrer-Policy": "strict-origin-when-cross-origin", |
| 33 | + "Permissions-Policy": "camera=(), microphone=(), geolocation=()", |
| 34 | +} |
| 35 | + |
| 36 | + |
| 37 | +# --------------------------------------------------------------------------- |
| 38 | +# TestUnifiedErrorShape — verifies shape for 401 / 404 / 422 / 500 |
| 39 | +# --------------------------------------------------------------------------- |
| 40 | + |
| 41 | + |
| 42 | +class TestUnifiedErrorShape: |
| 43 | + """Each error status code returns the unified JSON error shape.""" |
| 44 | + |
| 45 | + def test_401_returns_unified_error_shape( |
| 46 | + self, unauthenticated_client: TestClient |
| 47 | + ) -> None: |
| 48 | + """Unauthenticated request returns 401 with unified error body.""" |
| 49 | + response = unauthenticated_client.get(f"{_PREFIX}/entities/") |
| 50 | + |
| 51 | + assert response.status_code == 401 |
| 52 | + body = response.json() |
| 53 | + assert "error" in body |
| 54 | + assert "message" in body |
| 55 | + assert "code" in body |
| 56 | + assert "request_id" in body |
| 57 | + assert body["error"] == "UNAUTHORIZED" |
| 58 | + |
| 59 | + def test_404_returns_unified_error_shape( |
| 60 | + self, client: TestClient, mock_supabase: MagicMock |
| 61 | + ) -> None: |
| 62 | + """Request for a non-existent entity returns 404 with ENTITY_NOT_FOUND.""" |
| 63 | + mock_supabase.table.return_value.select.return_value.eq.return_value.eq.return_value.single.return_value.execute.side_effect = APIError( |
| 64 | + {"message": "No rows found", "code": "PGRST116"} |
| 65 | + ) |
| 66 | + |
| 67 | + nonexistent_id = str(uuid.uuid4()) |
| 68 | + response = client.get(f"{_PREFIX}/entities/{nonexistent_id}") |
| 69 | + |
| 70 | + assert response.status_code == 404 |
| 71 | + body = response.json() |
| 72 | + assert "error" in body |
| 73 | + assert "message" in body |
| 74 | + assert "code" in body |
| 75 | + assert "request_id" in body |
| 76 | + assert body["error"] == "NOT_FOUND" |
| 77 | + assert body["code"] == "ENTITY_NOT_FOUND" |
| 78 | + |
| 79 | + def test_422_returns_unified_error_shape(self, client: TestClient) -> None: |
| 80 | + """POST with missing required field returns 422 with details array.""" |
| 81 | + response = client.post( |
| 82 | + f"{_PREFIX}/entities/", |
| 83 | + json={"description": "no title"}, |
| 84 | + ) |
| 85 | + |
| 86 | + assert response.status_code == 422 |
| 87 | + body = response.json() |
| 88 | + assert "error" in body |
| 89 | + assert "message" in body |
| 90 | + assert "code" in body |
| 91 | + assert "request_id" in body |
| 92 | + assert "details" in body |
| 93 | + assert body["error"] == "VALIDATION_ERROR" |
| 94 | + assert isinstance(body["details"], list) |
| 95 | + assert len(body["details"]) >= 1 |
| 96 | + for detail in body["details"]: |
| 97 | + assert "field" in detail |
| 98 | + assert "message" in detail |
| 99 | + assert "type" in detail |
| 100 | + |
| 101 | + def test_500_returns_unified_error_shape( |
| 102 | + self, client: TestClient, mock_supabase: MagicMock |
| 103 | + ) -> None: |
| 104 | + """Unhandled server exception returns 500 without leaking internal details.""" |
| 105 | + mock_supabase.table.side_effect = RuntimeError("db crash") |
| 106 | + |
| 107 | + response = client.get(f"{_PREFIX}/entities/") |
| 108 | + |
| 109 | + assert response.status_code == 500 |
| 110 | + body = response.json() |
| 111 | + assert "error" in body |
| 112 | + assert "message" in body |
| 113 | + assert "code" in body |
| 114 | + assert "request_id" in body |
| 115 | + assert body["error"] == "INTERNAL_ERROR" |
| 116 | + assert "db crash" not in body["message"] |
| 117 | + |
| 118 | + |
| 119 | +# --------------------------------------------------------------------------- |
| 120 | +# TestErrorResponseMetadata — request_id and security headers |
| 121 | +# --------------------------------------------------------------------------- |
| 122 | + |
| 123 | + |
| 124 | +class TestErrorResponseMetadata: |
| 125 | + """Error responses include valid request_id and security headers.""" |
| 126 | + |
| 127 | + def test_error_response_includes_valid_request_id( |
| 128 | + self, unauthenticated_client: TestClient |
| 129 | + ) -> None: |
| 130 | + """request_id in error body is a valid UUID string.""" |
| 131 | + response = unauthenticated_client.get(f"{_PREFIX}/entities/") |
| 132 | + |
| 133 | + body = response.json() |
| 134 | + assert "request_id" in body |
| 135 | + # Raises ValueError if not a valid UUID — that is the assertion. |
| 136 | + uuid.UUID(body["request_id"]) |
| 137 | + |
| 138 | + def test_error_response_has_security_headers( |
| 139 | + self, unauthenticated_client: TestClient |
| 140 | + ) -> None: |
| 141 | + """All five security headers are present on error responses.""" |
| 142 | + response = unauthenticated_client.get(f"{_PREFIX}/entities/") |
| 143 | + |
| 144 | + for header, expected_value in _EXPECTED_SECURITY_HEADERS.items(): |
| 145 | + assert header in response.headers, f"Missing security header: {header}" |
| 146 | + assert response.headers[header] == expected_value, ( |
| 147 | + f"Header {header!r}: expected {expected_value!r}, " |
| 148 | + f"got {response.headers[header]!r}" |
| 149 | + ) |
| 150 | + |
| 151 | + def test_error_response_has_request_id_header( |
| 152 | + self, unauthenticated_client: TestClient |
| 153 | + ) -> None: |
| 154 | + """X-Request-ID response header is present and is a valid UUID.""" |
| 155 | + response = unauthenticated_client.get(f"{_PREFIX}/entities/") |
| 156 | + |
| 157 | + assert "X-Request-ID" in response.headers, "Missing X-Request-ID header" |
| 158 | + # Raises ValueError if not a valid UUID — that is the assertion. |
| 159 | + uuid.UUID(response.headers["X-Request-ID"]) |
0 commit comments