simple-module-background-tasks 0.0.3__tar.gz → 0.0.5__tar.gz

{simple_module_background_tasks-0.0.3 → simple_module_background_tasks-0.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simple_module_background_tasks
-Version: 0.0.3
+Version: 0.0.5
 Summary: Celery + Redis task queue with admin UI for monitoring and retrying failed/stuck tasks
 Project-URL: Homepage, https://github.com/antosubash/simple_module_python
 Project-URL: Repository, https://github.com/antosubash/simple_module_python
@@ -23,9 +23,9 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: celery[redis]>=5.4
 Requires-Dist: redis>=5
-Requires-Dist: simple-module-core==0.0.3
-Requires-Dist: simple-module-db==0.0.3
-Requires-Dist: simple-module-hosting==0.0.3
+Requires-Dist: simple-module-core==0.0.5
+Requires-Dist: simple-module-db==0.0.5
+Requires-Dist: simple-module-hosting==0.0.5
 Description-Content-Type: text/markdown
 
 # simple_module_background_tasks

{simple_module_background_tasks-0.0.3 → simple_module_background_tasks-0.0.5}/background_tasks/celery_app.py

@@ -55,6 +55,11 @@ def build_celery(settings: BackgroundTasksSettings) -> Celery:
         broker_url=settings.broker_url,
         result_backend=settings.result_backend,
         task_default_queue=settings.task_default_queue,
+        # Run tasks synchronously inside the calling process. Tests
+        # toggle this on (via ``SM_BG_TASKS_TASK_ALWAYS_EAGER=true``) so
+        # ``task.delay()`` doesn't reach for a real broker.
+        task_always_eager=settings.task_always_eager,
+        task_eager_propagates=settings.task_eager_propagates,
         # ``task_track_started`` gives us the ``STARTED`` state so
         # ``task_prerun`` can flip our row to ``running``.
         task_track_started=True,

{simple_module_background_tasks-0.0.3 → simple_module_background_tasks-0.0.5}/background_tasks/constants.py

@@ -32,7 +32,7 @@ ADMIN_ROUTER_PREFIX = "/admin"
 # ── Menu ────────────────────────────────────────────────────────
 MENU_LABEL = "Background Tasks"
 MENU_ICON = "activity"
-MENU_ORDER = 80
+MENU_ORDER = 120
 
 # ── Page identifiers ────────────────────────────────────────────
 # Kept as literals at the call site (see endpoints/views.py) so

{simple_module_background_tasks-0.0.3 → simple_module_background_tasks-0.0.5}/background_tasks/contracts/schemas.py

@@ -64,3 +64,24 @@ class TaskExecutionListResponse(SQLModel):
     per_page: int
     status: TaskStatus | None = None
     task_name: str | None = None
+
+
+class WorkerInfo(SQLModel):
+    """One Celery worker as reported by ``celery.control.inspect()``."""
+
+    hostname: str
+    online: bool
+    queues: list[str] = []
+    active_task_count: int = 0
+    pool_size: int | None = None
+    total_processed: int | None = None
+    software: str | None = None
+
+
+class WorkerSnapshot(SQLModel):
+    """Point-in-time picture of every worker known to the broker."""
+
+    broker_reachable: bool
+    polled_at: datetime
+    workers: list[WorkerInfo] = []
+    error: str | None = None

{simple_module_background_tasks-0.0.3 → simple_module_background_tasks-0.0.5}/background_tasks/endpoints/api_admin.py

@@ -2,9 +2,10 @@
 
 from __future__ import annotations
 
+import asyncio
 import uuid
 
-from fastapi import APIRouter, Depends, HTTPException, Query
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
 from simple_module_hosting.permissions import RequiresPermission
 
 from background_tasks.constants import (
@@ -17,9 +18,11 @@ from background_tasks.constants import (
 from background_tasks.contracts.schemas import (
     TaskExecutionDetail,
     TaskExecutionListResponse,
+    WorkerSnapshot,
 )
 from background_tasks.deps import get_background_task_service
 from background_tasks.service import BackgroundTaskService
+from background_tasks.worker_inspector import WorkerInspector
 
 router = APIRouter(
     prefix=ADMIN_ROUTER_PREFIX,
@@ -60,3 +63,11 @@ async def retry_execution(
     service: BackgroundTaskService = Depends(get_background_task_service),
 ) -> TaskExecutionDetail:
     return await service.retry(execution_id)
+
+
+@router.get("/workers", response_model=WorkerSnapshot)
+async def get_workers(request: Request) -> WorkerSnapshot:
+    """Live snapshot of every Celery worker reachable via the broker."""
+    celery = request.app.state.background_tasks.celery
+    inspector = WorkerInspector(celery)
+    return await asyncio.to_thread(inspector.snapshot)

{simple_module_background_tasks-0.0.3 → simple_module_background_tasks-0.0.5}/background_tasks/endpoints/views.py

@@ -2,9 +2,10 @@
 
 from __future__ import annotations
 
+import asyncio
 import uuid
 
-from fastapi import APIRouter, Depends, HTTPException, Query
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
 from inertia import InertiaResponse
 from simple_module_hosting.inertia_deps import InertiaDep
 from simple_module_hosting.permissions import RequiresPermission
@@ -15,6 +16,7 @@ from background_tasks.constants import (
 )
 from background_tasks.deps import get_background_task_service
 from background_tasks.service import BackgroundTaskService
+from background_tasks.worker_inspector import WorkerInspector
 
 router = APIRouter(dependencies=[Depends(RequiresPermission(PERM_VIEW))])
 
@@ -52,6 +54,16 @@ async def index(
     )
 
 
+@router.get("/workers", response_model=None)
+async def workers(inertia: InertiaDep, request: Request) -> InertiaResponse:
+    celery = request.app.state.background_tasks.celery
+    snapshot = await asyncio.to_thread(WorkerInspector(celery).snapshot)
+    return await inertia.render(
+        "BackgroundTasks/Workers",
+        {"snapshot": snapshot.model_dump(mode="json")},
+    )
+
+
 @router.get("/{execution_id}", response_model=None)
 async def detail(
     execution_id: str,

{simple_module_background_tasks-0.0.3 → simple_module_background_tasks-0.0.5}/background_tasks/module.py

@@ -75,6 +75,7 @@ class BackgroundTasksModule(ModuleBase):
                 order=MENU_ORDER,
                 section=MenuSection.SIDEBAR,
                 roles=["admin"],
+                group="Administration",
             )
         )
 

{simple_module_background_tasks-0.0.3 → simple_module_background_tasks-0.0.5}/background_tasks/pages/Detail.tsx

@@ -8,7 +8,13 @@ import { AuthenticatedLayout } from '@simple-module-py/ui/layouts/AuthenticatedL
 import { ArrowLeft, RefreshCcw } from 'lucide-react';
 import type { ReactNode } from 'react';
 import { RetryConfirmDialog } from './components/RetryConfirmDialog';
-import { RETRYABLE_STATUSES, STATUS_BADGE_VARIANT, type TaskStatus, VIEW_BASE } from './constants';
+import {
+  formatTs,
+  RETRYABLE_STATUSES,
+  STATUS_BADGE_VARIANT,
+  type TaskStatus,
+  VIEW_BASE,
+} from './constants';
 import { retryExecution } from './retry';
 
 interface Execution {
@@ -44,10 +50,6 @@ function pretty(value: unknown): string {
   }
 }
 
-function formatTs(ts: string | null): string {
-  return ts ? new Date(ts).toLocaleString() : '—';
-}
-
 function JsonCard({ title, children }: { title: string; children: ReactNode }) {
   return (
     <Card className="p-4">

{simple_module_background_tasks-0.0.3 → simple_module_background_tasks-0.0.5}/background_tasks/pages/Index.tsx

@@ -1,4 +1,4 @@
-import { router, usePage } from '@inertiajs/react';
+import { Link, router, usePage } from '@inertiajs/react';
 import { PageShell } from '@simple-module-py/ui/components/PageShell';
 import { Button } from '@simple-module-py/ui/components/ui/button';
 import { Card } from '@simple-module-py/ui/components/ui/card';
@@ -20,7 +20,7 @@ import {
 } from '@simple-module-py/ui/components/ui/table';
 import { usePermissions } from '@simple-module-py/ui/hooks/use-permissions';
 import { AuthenticatedLayout } from '@simple-module-py/ui/layouts/AuthenticatedLayout';
-import { Activity, Search } from 'lucide-react';
+import { Activity, Search, ServerCog } from 'lucide-react';
 import { useEffect, useState } from 'react';
 import { ExecutionRow, statusLabel } from './components/ExecutionRow';
 import { STATUS_ORDER, VIEW_BASE } from './constants';
@@ -93,22 +93,30 @@ function Index() {
             className="pl-9"
           />
         </div>
-        <Select
-          value={statusValue}
-          onValueChange={(v) => pushFilters({ status: v, task_name: search }, 1)}
-        >
-          <SelectTrigger className="w-full sm:w-48">
-            <SelectValue placeholder="Status" />
-          </SelectTrigger>
-          <SelectContent>
-            <SelectItem value={STATUS_ALL}>All statuses</SelectItem>
-            {STATUS_ORDER.map((s) => (
-              <SelectItem key={s} value={s}>
-                {statusLabel(s)}
-              </SelectItem>
-            ))}
-          </SelectContent>
-        </Select>
+        <div className="flex items-center gap-2">
+          <Select
+            value={statusValue}
+            onValueChange={(v) => pushFilters({ status: v, task_name: search }, 1)}
+          >
+            <SelectTrigger className="w-full sm:w-48">
+              <SelectValue placeholder="Status" />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value={STATUS_ALL}>All statuses</SelectItem>
+              {STATUS_ORDER.map((s) => (
+                <SelectItem key={s} value={s}>
+                  {statusLabel(s)}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+          <Button variant="outline" asChild>
+            <Link href={`${VIEW_BASE}/workers`}>
+              <ServerCog className="mr-2 size-4" />
+              Workers
+            </Link>
+          </Button>
+        </div>
       </div>
 
       <Card>

simple_module_background_tasks-0.0.5/background_tasks/pages/Workers.tsx

@@ -0,0 +1,154 @@
+import { Link, usePage } from '@inertiajs/react';
+import { PageShell } from '@simple-module-py/ui/components/PageShell';
+import { Badge } from '@simple-module-py/ui/components/ui/badge';
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import { Card } from '@simple-module-py/ui/components/ui/card';
+import { AuthenticatedLayout } from '@simple-module-py/ui/layouts/AuthenticatedLayout';
+import { ArrowLeft, RefreshCw, ServerCrash, ServerOff } from 'lucide-react';
+import { useState } from 'react';
+import { toast } from 'sonner';
+import { API_BASE, formatTs, VIEW_BASE, type WorkerInfo, type WorkerSnapshot } from './constants';
+
+interface Props {
+  snapshot: WorkerSnapshot;
+}
+
+function WorkerCard({ worker }: { worker: WorkerInfo }) {
+  return (
+    <Card className="p-4">
+      <div className="flex items-start justify-between gap-4">
+        <div className="flex items-start gap-3">
+          <span
+            role="img"
+            className={`mt-1.5 size-2.5 rounded-full ${
+              worker.online ? 'bg-green-500' : 'bg-muted-foreground'
+            }`}
+            aria-label={worker.online ? 'online' : 'offline'}
+          />
+          <div>
+            <h3 className="font-medium">{worker.hostname}</h3>
+            {worker.software && <p className="text-xs text-muted-foreground">{worker.software}</p>}
+          </div>
+        </div>
+        <Badge variant={worker.online ? 'secondary' : 'outline'}>
+          {worker.online ? 'Online' : 'Offline'}
+        </Badge>
+      </div>
+
+      <dl className="mt-4 grid grid-cols-2 gap-3 text-sm sm:grid-cols-4">
+        <div>
+          <dt className="text-muted-foreground">Active</dt>
+          <dd className="font-medium">{worker.active_task_count}</dd>
+        </div>
+        <div>
+          <dt className="text-muted-foreground">Pool</dt>
+          <dd className="font-medium">{worker.pool_size ?? '—'}</dd>
+        </div>
+        <div>
+          <dt className="text-muted-foreground">Processed</dt>
+          <dd className="font-medium">{worker.total_processed ?? '—'}</dd>
+        </div>
+        <div className="col-span-2 sm:col-span-1">
+          <dt className="text-muted-foreground">Queues</dt>
+          <dd className="flex flex-wrap gap-1">
+            {worker.queues.length === 0 ? (
+              <span className="text-muted-foreground">—</span>
+            ) : (
+              worker.queues.map((q) => (
+                <Badge key={q} variant="outline" className="font-normal">
+                  {q}
+                </Badge>
+              ))
+            )}
+          </dd>
+        </div>
+      </dl>
+    </Card>
+  );
+}
+
+function Workers() {
+  const { snapshot: initial } = usePage<{ props: Props }>().props as unknown as Props;
+  const [snapshot, setSnapshot] = useState<WorkerSnapshot>(initial);
+  const [loading, setLoading] = useState(false);
+
+  async function refresh() {
+    setLoading(true);
+    try {
+      const res = await fetch(`${API_BASE}/workers`, {
+        headers: { Accept: 'application/json' },
+      });
+      if (res.ok) {
+        setSnapshot((await res.json()) as WorkerSnapshot);
+      } else {
+        toast.error(`Failed to refresh workers (HTTP ${res.status})`);
+      }
+    } catch {
+      toast.error('Failed to refresh workers');
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  return (
+    <PageShell title="Workers" description="Celery workers connected to the broker.">
+      <div className="mb-4 flex items-center justify-between gap-3">
+        <Button variant="outline" size="sm" asChild>
+          <Link href={VIEW_BASE}>
+            <ArrowLeft className="mr-2 size-4" />
+            Back to executions
+          </Link>
+        </Button>
+        <div className="flex items-center gap-3">
+          <span className="text-xs text-muted-foreground">
+            Last updated {formatTs(snapshot.polled_at)}
+          </span>
+          <Button variant="outline" size="sm" onClick={refresh} disabled={loading}>
+            <RefreshCw className={`mr-2 size-4 ${loading ? 'animate-spin' : ''}`} />
+            Refresh
+          </Button>
+        </div>
+      </div>
+
+      {!snapshot.broker_reachable ? (
+        <Card className="p-6">
+          <div className="flex items-start gap-3">
+            <ServerCrash className="size-5 text-destructive" />
+            <div>
+              <h3 className="font-medium">Broker unreachable</h3>
+              <p className="mt-1 text-sm text-muted-foreground">
+                {snapshot.error ?? 'No error message reported.'}
+              </p>
+              <p className="mt-2 text-xs text-muted-foreground">
+                Check the <code>SM_BG_TASKS_BROKER_URL</code> setting and confirm the broker process
+                is running.
+              </p>
+            </div>
+          </div>
+        </Card>
+      ) : snapshot.workers.length === 0 ? (
+        <Card className="p-6">
+          <div className="flex items-start gap-3">
+            <ServerOff className="size-5 text-muted-foreground" />
+            <div>
+              <h3 className="font-medium">No workers connected</h3>
+              <p className="mt-1 text-sm text-muted-foreground">
+                The broker is reachable but no Celery workers are responding. Start one with{' '}
+                <code>uv run python scripts/run_worker.py</code>.
+              </p>
+            </div>
+          </div>
+        </Card>
+      ) : (
+        <div className="grid gap-3">
+          {snapshot.workers.map((w) => (
+            <WorkerCard key={w.hostname} worker={w} />
+          ))}
+        </div>
+      )}
+    </PageShell>
+  );
+}
+
+Workers.layout = (page: React.ReactNode) => <AuthenticatedLayout>{page}</AuthenticatedLayout>;
+export default Workers;

{simple_module_background_tasks-0.0.3 → simple_module_background_tasks-0.0.5}/background_tasks/pages/constants.ts

@@ -4,6 +4,27 @@
 export const API_BASE = '/api/background_tasks/admin';
 export const VIEW_BASE = '/admin/background-tasks';
 
+export function formatTs(ts: string | null): string {
+  return ts ? new Date(ts).toLocaleString() : '—';
+}
+
+export interface WorkerInfo {
+  hostname: string;
+  online: boolean;
+  queues: string[];
+  active_task_count: number;
+  pool_size: number | null;
+  total_processed: number | null;
+  software: string | null;
+}
+
+export interface WorkerSnapshot {
+  broker_reachable: boolean;
+  polled_at: string;
+  workers: WorkerInfo[];
+  error: string | null;
+}
+
 export const TASK_STATUS = {
   PENDING: 'pending',
   RUNNING: 'running',

{simple_module_background_tasks-0.0.3 → simple_module_background_tasks-0.0.5}/background_tasks/settings.py

@@ -22,6 +22,7 @@ import os
 
 from pydantic import Field, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
+from simple_module_core.dotenv import env_bool
 from simple_module_core.environments import NON_PROD_ENVIRONMENTS
 
 from background_tasks.constants import (
@@ -47,6 +48,13 @@ class BackgroundTasksSettings(BaseSettings):
     result_backend: str = Field(default=DEFAULT_RESULT_BACKEND, json_schema_extra=_CELERY_RESTART)
     task_default_queue: str = Field(default=DEFAULT_QUEUE, json_schema_extra=_CELERY_RESTART)
 
+    # Run tasks synchronously inside the calling process. Read at
+    # module-import time so tests can flip it on via ``SM_BG_TASKS_*``
+    # without going through DB-backed hydration (which never fires for
+    # suites that don't use the FastAPI lifespan).
+    task_always_eager: bool = env_bool("SM_BG_TASKS_TASK_ALWAYS_EAGER")
+    task_eager_propagates: bool = True
+
     # A task that has been ``running`` longer than this without a heartbeat is
     # flipped to ``stuck`` by the beat sweep. 5 min is long enough to cover
     # normal slow jobs while still surfacing wedged workers within one UI

simple_module_background_tasks-0.0.5/background_tasks/worker_inspector.py

@@ -0,0 +1,117 @@
+"""Read-only adapter around ``celery.control.inspect()``.
+
+Produces a :class:`WorkerSnapshot` for the admin Workers page. All broker
+errors are caught and surfaced through ``snapshot.broker_reachable`` /
+``snapshot.error`` so the page can render a clear operator-facing state
+instead of the endpoint returning a 5xx.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+from kombu.exceptions import OperationalError
+from redis.exceptions import RedisError
+
+from background_tasks.contracts.schemas import WorkerInfo, WorkerSnapshot
+
+if TYPE_CHECKING:
+    from celery import Celery
+
+logger = logging.getLogger(__name__)
+
+
+class WorkerInspector:
+    """Synchronous adapter; call from async code via ``asyncio.to_thread``."""
+
+    def __init__(self, celery: Celery, *, timeout: float = 1.0) -> None:
+        self.celery = celery
+        self.timeout = timeout
+
+    def snapshot(self) -> WorkerSnapshot:
+        polled_at = datetime.now(UTC)
+
+        # Probe the broker first so we can distinguish "broker down" from
+        # "broker up but no workers replied". Without this, both look like
+        # ``inspect.*() == None``.
+        try:
+            with self.celery.connection() as conn:
+                conn.ensure_connection(max_retries=1, timeout=self.timeout)
+        except (OperationalError, RedisError, ConnectionError, OSError) as exc:
+            logger.info("Broker unreachable: %s", exc)
+            return WorkerSnapshot(
+                broker_reachable=False,
+                polled_at=polled_at,
+                workers=[],
+                error=str(exc),
+            )
+
+        inspect = self.celery.control.inspect(timeout=self.timeout)
+        try:
+            ping = inspect.ping() or {}
+            stats = inspect.stats() or {}
+            queues = inspect.active_queues() or {}
+            active = inspect.active() or {}
+        except (OperationalError, RedisError, ConnectionError, OSError) as exc:
+            logger.info("inspect() failed mid-call: %s", exc)
+            return WorkerSnapshot(
+                broker_reachable=False,
+                polled_at=polled_at,
+                workers=[],
+                error=str(exc),
+            )
+
+        hostnames = sorted(set(ping) | set(stats) | set(queues) | set(active))
+        workers = [
+            _build_worker_info(
+                hostname=h,
+                pinged=h in ping,
+                stats=stats.get(h) or {},
+                queues=queues.get(h) or [],
+                active=active.get(h) or [],
+            )
+            for h in hostnames
+        ]
+        return WorkerSnapshot(
+            broker_reachable=True,
+            polled_at=polled_at,
+            workers=workers,
+            error=None,
+        )
+
+
+def _build_worker_info(
+    *,
+    hostname: str,
+    pinged: bool,
+    stats: dict[str, Any],
+    queues: list[dict[str, Any]],
+    active: list[dict[str, Any]],
+) -> WorkerInfo:
+    pool = stats.get("pool") or {}
+    pool_size = pool.get("max-concurrency")
+    if pool_size is None and isinstance(pool.get("processes"), list):
+        pool_size = len(pool["processes"])
+
+    total = stats.get("total")
+    total_processed: int | None = None
+    if isinstance(total, dict):
+        total_processed = sum(int(v) for v in total.values() if isinstance(v, int | float))
+    elif isinstance(total, int):
+        total_processed = total
+
+    sw_ident = stats.get("sw_ident")
+    sw_ver = stats.get("sw_ver")
+    software = f"{sw_ident}:{sw_ver}" if sw_ident and sw_ver else (sw_ident or sw_ver)
+
+    return WorkerInfo(
+        hostname=hostname,
+        online=pinged,
+        queues=[q.get("name", "") for q in queues if q.get("name")],
+        active_task_count=len(active),
+        pool_size=pool_size,
+        total_processed=total_processed,
+        software=software,
+    )

{simple_module_background_tasks-0.0.3 → simple_module_background_tasks-0.0.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_background_tasks"
-version = "0.0.3"
+version = "0.0.5"
 description = "Celery + Redis task queue with admin UI for monitoring and retrying failed/stuck tasks"
 readme = "README.md"
 license = "MIT"
@@ -21,9 +21,9 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "simple_module_core==0.0.3",
-    "simple_module_db==0.0.3",
-    "simple_module_hosting==0.0.3",
+    "simple_module_core==0.0.5",
+    "simple_module_db==0.0.5",
+    "simple_module_hosting==0.0.5",
     "celery[redis]>=5.4",
     "redis>=5",
 ]

simple_module_background_tasks-0.0.5/tests/conftest.py

@@ -0,0 +1,22 @@
+"""Shared fixtures for background_tasks tests."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+import pytest
+
+
+@pytest.fixture
+async def _stub_celery(app) -> None:
+    """Replace the real Celery instance with a MagicMock.
+
+    Opt-in via ``pytestmark = pytest.mark.usefixtures("_stub_celery")`` at
+    module scope — not autouse, because signal tests deliberately exercise
+    an unstarted app and would be broken by the implicit ``app`` dependency.
+    ``send_task.return_value.id`` is pre-set so retry flows that read it
+    (see ``test_admin_api.py``) work without further setup.
+    """
+    celery = MagicMock(name="Celery")
+    celery.send_task.return_value.id = "mocked-celery-id"
+    app.state.background_tasks.celery = celery

{simple_module_background_tasks-0.0.3 → simple_module_background_tasks-0.0.5}/tests/test_admin_api.py

@@ -4,7 +4,6 @@ from __future__ import annotations
 
 import uuid
 from datetime import UTC, datetime
-from unittest.mock import MagicMock
 
 import httpx
 import pytest
@@ -13,19 +12,7 @@ from background_tasks.models import TaskExecution
 
 ADMIN_BASE = "/api/background_tasks/admin"
 
-
-@pytest.fixture(autouse=True)
-async def _stub_celery(app) -> None:
-    """Replace the real Celery instance with a MagicMock for the admin suite.
-
-    ``BackgroundTasksModule.on_startup`` builds a live Celery app which tries
-    to talk to a real Redis broker on the first ``send_task`` call. The admin
-    tests only care that ``retry`` flows through the API — mocking keeps the
-    test hermetic.
-    """
-    celery = MagicMock(name="Celery")
-    celery.send_task.return_value.id = "mocked-celery-id"
-    app.state.background_tasks.celery = celery
+pytestmark = pytest.mark.usefixtures("_stub_celery")
 
 
 async def _seed_failed(app, **overrides) -> TaskExecution:

simple_module_background_tasks-0.0.5/tests/test_worker_inspector.py

@@ -0,0 +1,106 @@
+"""Unit tests for WorkerInspector — wraps celery.control.inspect()."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+from celery import Celery
+
+
+def _make_celery_with_dead_broker() -> Celery:
+    """Build a Celery app pointed at an unreachable broker.
+
+    Port 1 is reserved/refused, so any connection attempt fails fast.
+    """
+    app = Celery("test", broker="redis://127.0.0.1:1/0", backend="redis://127.0.0.1:1/1")
+    app.conf.broker_connection_retry_on_startup = False
+    return app
+
+
+def test_dead_broker_returns_unreachable_snapshot():
+    from background_tasks.worker_inspector import WorkerInspector
+
+    inspector = WorkerInspector(_make_celery_with_dead_broker(), timeout=0.2)
+    snapshot = inspector.snapshot()
+
+    assert snapshot.broker_reachable is False
+    assert snapshot.workers == []
+    assert snapshot.error is not None
+    assert snapshot.polled_at is not None
+
+
+def test_inspect_payloads_are_merged_into_worker_info():
+    from background_tasks.worker_inspector import WorkerInspector
+
+    celery = MagicMock(spec=Celery)
+    # Probe call: ensure_connection succeeds (broker reachable).
+    celery.connection.return_value.ensure_connection.return_value = None
+
+    inspect = celery.control.inspect.return_value
+    inspect.ping.return_value = {"celery@host-a": {"ok": "pong"}}
+    inspect.stats.return_value = {
+        "celery@host-a": {
+            "pool": {"max-concurrency": 4, "processes": [1, 2, 3, 4]},
+            "total": {"demo.task": 17},
+            "broker": {"transport": "redis"},
+            "sw_ident": "py-celery",
+            "sw_ver": "5.3.6",
+        },
+    }
+    inspect.active_queues.return_value = {
+        "celery@host-a": [{"name": "default"}, {"name": "high"}],
+    }
+    inspect.active.return_value = {
+        "celery@host-a": [{"id": "task-1"}, {"id": "task-2"}],
+    }
+
+    snapshot = WorkerInspector(celery, timeout=0.1).snapshot()
+
+    assert snapshot.broker_reachable is True
+    assert snapshot.error is None
+    assert len(snapshot.workers) == 1
+    w = snapshot.workers[0]
+    assert w.hostname == "celery@host-a"
+    assert w.online is True
+    assert w.queues == ["default", "high"]
+    assert w.active_task_count == 2
+    assert w.pool_size == 4
+    assert w.total_processed == 17
+    assert w.software == "py-celery:5.3.6"
+
+
+def test_worker_in_stats_but_not_ping_is_offline():
+    from background_tasks.worker_inspector import WorkerInspector
+
+    celery = MagicMock(spec=Celery)
+    celery.connection.return_value.ensure_connection.return_value = None
+    inspect = celery.control.inspect.return_value
+    inspect.ping.return_value = {}  # no replies
+    inspect.stats.return_value = {"celery@host-b": {"pool": {"max-concurrency": 2}}}
+    inspect.active_queues.return_value = {}
+    inspect.active.return_value = {}
+
+    snapshot = WorkerInspector(celery, timeout=0.1).snapshot()
+
+    assert snapshot.broker_reachable is True
+    assert len(snapshot.workers) == 1
+    assert snapshot.workers[0].hostname == "celery@host-b"
+    assert snapshot.workers[0].online is False
+
+
+def test_redis_error_during_probe_returns_unreachable_snapshot():
+    """A redis-py exception (e.g. auth failure) is converted, not propagated."""
+    from background_tasks.worker_inspector import WorkerInspector
+    from redis.exceptions import AuthenticationError
+
+    celery = MagicMock(spec=Celery)
+    celery.connection.return_value.__enter__.return_value.ensure_connection.side_effect = (
+        AuthenticationError("invalid password")
+    )
+
+    snapshot = WorkerInspector(celery, timeout=0.1).snapshot()
+
+    assert snapshot.broker_reachable is False
+    assert snapshot.workers == []
+    assert snapshot.error is not None
+    assert "invalid password" in snapshot.error

simple_module_background_tasks-0.0.5/tests/test_workers_endpoints.py

@@ -0,0 +1,99 @@
+"""End-to-end tests for the Workers endpoints (Inertia view + JSON admin)."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+import httpx
+import pytest
+from background_tasks import worker_inspector as wi
+from background_tasks.contracts.schemas import WorkerInfo, WorkerSnapshot
+
+JSON_BASE = "/api/background_tasks/admin"
+VIEW_BASE = "/admin/background-tasks"
+
+pytestmark = pytest.mark.usefixtures("_stub_celery")
+
+
+@pytest.fixture
+def fake_snapshot() -> WorkerSnapshot:
+    return WorkerSnapshot(
+        broker_reachable=True,
+        polled_at=datetime(2026, 5, 1, 12, 0, tzinfo=UTC),
+        workers=[
+            WorkerInfo(
+                hostname="celery@host-a",
+                online=True,
+                queues=["default"],
+                active_task_count=1,
+                pool_size=4,
+                total_processed=42,
+                software="py-celery:5.3.6",
+            ),
+        ],
+        error=None,
+    )
+
+
+class TestWorkersJsonEndpoint:
+    async def test_unauthenticated_request_is_rejected(self, client: httpx.AsyncClient):
+        resp = await client.get(f"{JSON_BASE}/workers", follow_redirects=False)
+        assert resp.status_code in {302, 401, 403}
+
+    async def test_returns_snapshot_payload(
+        self,
+        monkeypatch,
+        authenticated_client: httpx.AsyncClient,
+        fake_snapshot: WorkerSnapshot,
+    ):
+        monkeypatch.setattr(wi.WorkerInspector, "snapshot", lambda self: fake_snapshot)
+
+        resp = await authenticated_client.get(f"{JSON_BASE}/workers")
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["broker_reachable"] is True
+        assert len(body["workers"]) == 1
+        assert body["workers"][0]["hostname"] == "celery@host-a"
+        assert body["workers"][0]["pool_size"] == 4
+
+    async def test_unreachable_broker_is_200_with_error_field(
+        self,
+        monkeypatch,
+        authenticated_client: httpx.AsyncClient,
+    ):
+        unreachable = WorkerSnapshot(
+            broker_reachable=False,
+            polled_at=datetime(2026, 5, 1, 12, 0, tzinfo=UTC),
+            workers=[],
+            error="Connection refused",
+        )
+        monkeypatch.setattr(wi.WorkerInspector, "snapshot", lambda self: unreachable)
+
+        resp = await authenticated_client.get(f"{JSON_BASE}/workers")
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["broker_reachable"] is False
+        assert body["error"] == "Connection refused"
+        assert body["workers"] == []
+
+
+class TestWorkersInertiaView:
+    async def test_renders_page_with_snapshot_prop(
+        self,
+        monkeypatch,
+        authenticated_client: httpx.AsyncClient,
+        fake_snapshot: WorkerSnapshot,
+    ):
+        monkeypatch.setattr(wi.WorkerInspector, "snapshot", lambda self: fake_snapshot)
+
+        # Inertia returns JSON when X-Inertia is present.
+        resp = await authenticated_client.get(
+            f"{VIEW_BASE}/workers",
+            headers={"X-Inertia": "true", "Accept": "application/json"},
+        )
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["component"] == "BackgroundTasks/Workers"
+        snapshot = body["props"]["snapshot"]
+        assert snapshot["broker_reachable"] is True
+        assert snapshot["workers"][0]["hostname"] == "celery@host-a"