Add Error Testing Lab feature for simulated error handling

Author: JuanToledo23

README.md

@@ -109,6 +109,20 @@ Additional features:
 - **Fully responsive** layout (mobile, tablet, desktop) with safe-area support for iPhone
 - **Animated space background** with twinkling stars and shooting stars
 - **Image lightbox** for all galleries
+- **Error Testing Lab** — Easter egg to demonstrate error handling (triple-click SPACEX in header)
+
+## Error Testing Lab
+
+The dashboard includes an **Error Testing Lab** to demonstrate how errors are handled across the stack. Useful for QA, demos, and onboarding.
+
+**How to open:** Triple-click the "SPACEX" brand in the header (three clicks within ~500 ms).
+
+**What it demonstrates:**
+- **ErrorState** — Inline error panel with RETRY button (used across all views)
+- **NotificationToast** — Toast notifications for non-blocking errors
+- **API errors** — Real HTTP responses (404, 500, 502, 503, timeout) from the backend
+
+The backend endpoint `GET /api/dev/trigger-error?code=404|500|502|503|timeout` returns simulated errors. The timeout variant waits 5 seconds before responding. See [Frontend README](frontend/README.md#error-testing-lab-easter-egg) and [Backend README](backend/README.md#error-testing-dev-endpoint) for details.
 
 ## API Endpoints
 
@@ -135,6 +149,7 @@ Additional features:
 | GET    | `/api/ai/fun-fact`       | Random AI-generated SpaceX fun fact  |
 | GET    | `/api/notifications/stream` | Server-Sent Events stream for real-time notifications |
 | POST   | `/api/notifications/send`   | Send test notification (admin/internal)              |
+| GET    | `/api/dev/trigger-error`    | Easter egg: simulated errors (404, 500, 502, 503, timeout) for error-handling demos |
 
 For detailed query parameters and response schemas, see the [Backend README](backend/README.md).
 

backend/README.md

@@ -214,6 +214,24 @@ The AI service uses Groq (Llama 3.3 70B) to generate responses grounded in real
 | GET    | `/api/notifications/stream`   | SSE stream for real-time notifications  |
 | POST   | `/api/notifications/send`     | Send test notification                   |
 
+### Error Testing (Dev Endpoint)
+
+| Method | Path                     | Description                                      |
+|--------|--------------------------|--------------------------------------------------|
+| GET    | `/api/dev/trigger-error` | Simulated errors for error-handling demos        |
+
+**Query parameters:**
+
+| Param  | Type   | Values                    | Description                          |
+|--------|--------|---------------------------|--------------------------------------|
+| `code` | string | `404`, `500`, `502`, `503`, `timeout` | Error type to simulate (default: `500`) |
+
+**Behavior:**
+- `404`, `500`, `502`, `503` — Returns immediately with the corresponding HTTP status and structured body `{ code, message, trace_id }`
+- `timeout` — Waits 5 seconds, then returns 504 Gateway Timeout
+
+**Use case:** The frontend Error Testing Lab (triple-click SPACEX) uses this endpoint to demonstrate `ErrorState`, `NotificationToast`, and API error handling. Also useful for manual testing via curl or browser. Rate limited to 30 requests per minute per IP.
+
 ### Error Response Format
 
 All errors follow a consistent structure:
@@ -268,7 +286,7 @@ pytest --cov=app --cov-report=term-missing
 | Total tests | **203** |
 | Code coverage | **96.12%** |
 | Enforced minimum | **90%** (`--cov-fail-under=90` in CI) |
-| Test files | 24 (routes, services, cache, middleware, rate_limit, AI, notifications, etc.) |
+| Test files | 25 (routes, services, cache, middleware, rate_limit, AI, notifications, dev, etc.) |
 
 Tests cover all 14 API route modules, all 15 service modules, error handling, caching behavior, and the AI service. Requires Redis running locally — the CI pipeline uses a Redis service container.
 
@@ -286,7 +304,7 @@ ruff format .          # Auto-format
 backend/
 ├── app/
 │   ├── api/
-│   │   ├── routes/         # One file per resource (14 route modules)
+│   │   ├── routes/         # One file per resource (15 route modules, including dev.py)
 │   │   ├── middleware.py   # Request ID, structured logging, rate limiting (120 req/min)
 │   │   └── rate_limit.py   # Per-endpoint rate limiting
 │   ├── cache/

backend/app/api/routes/dev.py

@@ -0,0 +1,42 @@
+"""Easter egg: trigger simulated errors for testing error handling in the frontend."""
+
+import asyncio
+
+from fastapi import APIRouter, Request
+from starlette.responses import JSONResponse
+
+from app.api.rate_limit import check_rate_limit
+
+router = APIRouter(prefix="/api/dev", tags=["dev"])
+
+ERROR_MESSAGES: dict[str, tuple[int, str, str]] = {
+    "404": (404, "RESOURCE_NOT_FOUND", "Simulated 404 — Resource not found"),
+    "500": (500, "INTERNAL_ERROR", "Simulated 500 — Internal server error"),
+    "502": (502, "BAD_GATEWAY", "Simulated 502 — Bad gateway"),
+    "503": (503, "SERVICE_UNAVAILABLE", "Simulated 503 — Service unavailable"),
+    "timeout": (504, "GATEWAY_TIMEOUT", "Simulated timeout — Request took too long"),
+}
+
+
+@router.get("/trigger-error")
+async def trigger_error(request: Request, code: str = "500"):
+    """Return a simulated error response for testing frontend error handling.
+
+    Query params:
+        code: 404 | 500 | 502 | 503 | timeout
+
+    Use the Error Lab panel (triple-click SPACEX in header) to trigger from the UI.
+    """
+    await check_rate_limit(request, prefix="rl:dev", max_requests=30, window_seconds=60)
+
+    entry = ERROR_MESSAGES.get(code.lower(), ERROR_MESSAGES["500"])
+    status_code, error_code, message = entry
+
+    if code.lower() == "timeout":
+        await asyncio.sleep(5)  # Simulated delay; client timeout (30s) still allows response
+
+    trace_id = getattr(request.state, "trace_id", "unknown")
+    return JSONResponse(
+        status_code=status_code,
+        content={"code": error_code, "message": message, "trace_id": trace_id},
+    )

backend/app/main.py

@@ -11,6 +11,7 @@
     ai,
     cores,
     dashboard,
+    dev,
     economics,
     emissions,
     health,
@@ -72,3 +73,4 @@ async def lifespan(app: FastAPI):
 app.include_router(emissions.router)
 app.include_router(ai.router)
 app.include_router(notifications.router)
+app.include_router(dev.router)

backend/tests/test_dev_routes.py

@@ -0,0 +1,52 @@
+"""Tests for the dev/trigger-error easter egg endpoint."""
+
+import pytest
+
+
+@pytest.mark.asyncio
+async def test_trigger_error_404(client):
+    """Returns 404 with structured error body."""
+    resp = await client.get("/api/dev/trigger-error?code=404")
+    assert resp.status_code == 404
+    data = resp.json()
+    assert data["code"] == "RESOURCE_NOT_FOUND"
+    assert "404" in data["message"]
+    assert "trace_id" in data
+
+
+@pytest.mark.asyncio
+async def test_trigger_error_500(client):
+    """Returns 500 with structured error body."""
+    resp = await client.get("/api/dev/trigger-error?code=500")
+    assert resp.status_code == 500
+    data = resp.json()
+    assert data["code"] == "INTERNAL_ERROR"
+    assert "500" in data["message"]
+    assert "trace_id" in data
+
+
+@pytest.mark.asyncio
+async def test_trigger_error_502(client):
+    """Returns 502 with structured error body."""
+    resp = await client.get("/api/dev/trigger-error?code=502")
+    assert resp.status_code == 502
+    data = resp.json()
+    assert data["code"] == "BAD_GATEWAY"
+
+
+@pytest.mark.asyncio
+async def test_trigger_error_503(client):
+    """Returns 503 with structured error body."""
+    resp = await client.get("/api/dev/trigger-error?code=503")
+    assert resp.status_code == 503
+    data = resp.json()
+    assert data["code"] == "SERVICE_UNAVAILABLE"
+
+
+@pytest.mark.asyncio
+async def test_trigger_error_unknown_defaults_to_500(client):
+    """Unknown code defaults to 500."""
+    resp = await client.get("/api/dev/trigger-error?code=invalid")
+    assert resp.status_code == 500
+    data = resp.json()
+    assert data["code"] == "INTERNAL_ERROR"

frontend/README.md

@@ -102,6 +102,7 @@ Custom D3.js visualizations — each component uses `ResizeObserver` to adapt to
 |------------------|-----------------------------------------------------------------------------|
 | AiChat           | Floating AI assistant with markdown rendering and typewriter effect (lazy-loaded via `defineAsyncComponent`) |
 | DataTable        | Paginated table with clickable rows                                        |
+| ErrorLabPanel    | Easter egg panel for triggering simulated errors (triple-click SPACEX)     |
 | ErrorState       | Error message with retry button and `retrying` spinner state               |
 | FunFact          | AI-generated curiosity banner on site load with auto-dismiss (lazy-loaded via `defineAsyncComponent`) |
 | ImageLightbox    | Full-screen image viewer with keyboard navigation and focus trap           |
@@ -181,6 +182,7 @@ frontend/
 │   │   └── index.ts           # 11 routes with lazy loading
 │   ├── stores/
 │   │   ├── dashboard.ts
+│   │   ├── errorLab.ts
 │   │   ├── fleet.ts
 │   │   ├── launches.ts
 │   │   ├── notifications.ts
@@ -239,6 +241,29 @@ Every view has a tailored loading state that mirrors its actual content structur
 
 The `ErrorState` component includes a `retrying` prop that shows a spinner and "RETRYING..." label during automatic retry operations, avoiding UI flicker.
 
+## Error Testing Lab (Easter Egg)
+
+The dashboard includes a hidden **Error Testing Lab** to demonstrate error handling. See also the [Backend dev endpoint](backend/README.md#error-testing-dev-endpoint).
+
+**How to open:** Triple-click the "SPACEX" brand in the header (three clicks within ~500 ms).
+
+**Panel options:**
+- **Show ErrorState** — Simulates an inline error on Overview with a RETRY button
+- **Show error toast** — Displays a NotificationToast with type `error` (auto-dismisses after 12 s)
+- **API errors (404, 500, 502, 503, timeout)** — Calls the backend `/api/dev/trigger-error` and shows the resulting error on Overview
+
+**Direct API testing** (curl or browser):
+
+```bash
+# Local
+curl "http://localhost:8000/api/dev/trigger-error?code=404"
+curl "http://localhost:8000/api/dev/trigger-error?code=500"
+curl "http://localhost:8000/api/dev/trigger-error?code=timeout"   # waits 5s
+
+# Production
+curl "https://quadsci.juantoledo.com.mx/api/dev/trigger-error?code=404"
+```
+
 ## Tests
 
 The frontend test suite includes **242 tests** across **47 test files**, covering:

frontend/src/App.vue

@@ -24,6 +24,7 @@
     <AiChat />
     <FunFact />
     <NotificationToast />
+    <ErrorLabPanel />
   </div>
 </template>
 
@@ -32,6 +33,7 @@ import { defineAsyncComponent, onMounted } from 'vue'
 import AppHeader from '@/components/layout/AppHeader.vue'
 import AppFooter from '@/components/layout/AppFooter.vue'
 import RouteProgressBar from '@/components/layout/RouteProgressBar.vue'
+import ErrorLabPanel from '@/components/common/ErrorLabPanel.vue'
 import { useNotificationStore } from '@/stores/notifications'
 
 const SpaceBackground = defineAsyncComponent(() => import('@/components/layout/SpaceBackground.vue'))

frontend/src/api/index.ts

@@ -79,4 +79,8 @@ export const sendChatMessage = (message: string, history: ChatMessage[]): Promis
 export const fetchFunFact = (): Promise<FunFactResponse> =>
   api.get('/ai/fun-fact').then((r) => r.data)
 
+/** Trigger a simulated API error (404, 500, 502, 503, timeout) for error-handling demos. */
+export const triggerError = (code: string) =>
+  api.get('/dev/trigger-error', { params: { code } })
+
 export default api