RankFlow AI — Admin Dashboard & Observability Test Specification

Version: 1.0.0
Date: 2026-06-13
Target Specs: docs/specs/admin-dashboard-ui.md, docs/business_flow_map.md Section 6
Systems Under Test: Next.js Admin Shell, tRPC Admin Router, BullMQ Job Monitor, KPI Aggregations, Alert Engine
Test Tooling: Vitest, React Testing Library, msw, ioredis-mock, @testing-library/user-event, bullmq test helpers

---

1. Admin Layout & Access Control Tests#

1.1 Unit Tests — Layout Components#

1.2 Integration Tests — Access Control & Role Enforcement#

1.3 Success Criteria (Binary) — Layout & Access Control#

• AdminShell renders with sidebar, header, and content area for ADMIN role
• AdminSidebar displays all 9 navigation routes with correct icons and labels
• Active nav item has aria-current="page" and visual highlight
• AdminHeader renders breadcrumbs matching current route hierarchy
• Notification bell displays unread count badge; dropdown opens on click
• User menu dropdown shows admin user details and sign-out option
• DataTable supports sorting, filtering, and pagination
• StatCard renders label, formatted value, and color variant correctly
• StatusBadge maps all statuses (ACTIVE, TRIAL, CHURNED, SUSPENDED, PENDING) to correct colors
• ConfirmDialog renders title, description, cancel, and confirm buttons; fires callbacks correctly
• FilterBar applies date range and dropdown filters; calls onFilterChange with correct shape
• PracticeSelect renders searchable dropdown of all practices
• JsonViewer renders structured JSON with syntax highlighting and collapsible nodes
• /admin/* routes redirect non-ADMIN users to /dashboard with 302
• Unauthenticated users are redirected to /login with redirect query param
• All admin.* tRPC procedures return 403 FORBIDDEN for non-admin roles
• All admin.* tRPC procedures return 401 UNAUTHORIZED for unauthenticated requests
• Mobile (<768px) renders sidebar as drawer; tables as card lists; charts stacked
• Tablet (768-1024px) renders collapsible sidebar; reduced table columns
• Desktop (>1024px) renders fixed 240px sidebar; full table columns; charts side-by-side

1.4 Agent Context (Pre-conditions) — Layout & Access Control#

• Required DB state: User table with at least 3 records: role: "ADMIN", role: "CLIENT", role: "EDITOR"; ClientProfile with at least 1 record
• Required env vars: NEXTAUTH_SECRET (mocked); ADMIN_ROLE="ADMIN"
• Required mocks: next-auth/react getServerSession mocked for role-based tests; next/navigation useRouter mocked for redirect assertions
• Session state: Admin session with user.id, user.email, user.role: "ADMIN"; client session with user.role: "CLIENT"
• Viewport mocks: @testing-library/react render with window.innerWidth mocked for responsive tests

1.5 Verification Commands — Layout & Access Control#

# Unit: layout components
pnpm test:unit -- src/__tests__/unit/admin/

# Integration: access control + responsive
pnpm test:integration -- src/__tests__/integration/admin/access.test.ts
pnpm test:integration -- src/__tests__/integration/admin/responsive.test.tsx

# API access control
pnpm test:integration -- src/__tests__/integration/admin/api.access.test.ts

# Full layout suite
pnpm test:unit -- src/__tests__/unit/admin/

---

2. KPI Dashboard (/admin) Tests#

2.1 Unit Tests — KPI Page Components#

2.2 Integration Tests — KPI Data Fetching#

2.3 Success Criteria (Binary) — KPI Dashboard#

• /admin page renders all 6 sections: Stat Row, Revenue Chart, Client Status, Job Health, API Costs, Activity Feed
• Stat Row shows Total Clients, Active Clients, Trial Clients, Churned Clients, MRR, ARR, Active Jobs, Failed Jobs (24h), Citation Health
• MRR and ARR values are formatted in INR with proper comma separators (e.g., ₹4,80,000)
• Citation Health card color-codes: >=90% green, 80-89% amber, <80% red
• Revenue Chart renders 12-month MRR trend with correct X/Y axes and tooltips
• Client Status Pie Chart shows Trial vs Active vs Churned with percentages
• Job Health Bar Chart shows Completed, Failed, Running counts; failed bar is red
• API Cost Chart shows 7-day breakdown by provider (Claude, OpenAI, DataForSEO, SerpAPI, Hyperbrowser, Firecrawl)
• Activity Feed displays last 20 audit log entries in reverse chronological order
• Activity Feed shows empty state when no entries exist
• Skeleton loaders appear during data fetching; real data replaces them on success
• Error state displays friendly message and retry button on tRPC failure
• KPI data auto-refreshes every 60 seconds (or on window focus)
• citationHealth is calculated as (MATCHED citations / total attempted) * 100 with correct rounding
• apiCosts7d aggregates per-provider spend from AiUsage table over rolling 7-day window
• recentActivity is limited to exactly 20 entries, newest first

2.4 Agent Context (Pre-conditions) — KPI Dashboard#

• Required DB state: User (100 records), ClientProfile (80 ACTIVE, 15 TRIAL, 5 CHURNED), Subscription (with status and amount), Citation (26 MATCHED, 4 FAILED), AiUsage (100 records across 6 providers), AuditLog (50+ records), JobLog (1200 completed, 30 failed, 5 running)
• Required env vars: ADMIN_ROLE="ADMIN"; CURRENCY_CODE="INR"
• Required mocks: recharts components can be shallow-rendered or mocked if causing issues in JSDOM
• tRPC mocks: admin.getKPIs and admin.getSystemHealth return deterministic mock data
• Timer control: vi.useFakeTimers() for auto-refresh tests

2.5 Verification Commands — KPI Dashboard#

# Unit: KPI components
pnpm test:unit -- src/__tests__/unit/admin/kpi/

# Integration: KPI data + calculations
pnpm test:integration -- src/__tests__/integration/admin/kpi/

# Smoke: admin KPI page render
pnpm test:integration -- src/__tests__/integration/admin/kpi/data.test.tsx

---

3. Client Management Tests#

3.1 Unit Tests — Client List (/admin/clients)#

3.2 Unit Tests — Client Detail (/admin/clients/[id])#

3.3 Integration Tests — Client API#

3.4 Success Criteria (Binary) — Client Management#

• /admin/clients renders data table with all 9 columns (Name, Slug, Type, Tier, Status, Locations, Created, Trial Ends, Actions)
• All sortable columns (Name, Slug, Type, Tier, Status, Locations, Created, Trial Ends) support ascending/descending sort
• All filterable columns (Name search, Type dropdown, Tier dropdown, Status dropdown, Created date) filter rows correctly
• Search filter matches against name and slug fields
• Date range filter matches createdAt and trialEndsAt fields
• Row actions: "View" navigates to /admin/clients/{id}; "Edit" opens inline modal; "Suspend" shows confirmation; "Delete" shows confirmation (soft delete)
• Bulk actions: "Change tier" updates all selected rows; "Export CSV" downloads correct data; "Send email" opens email modal
• Pagination works with configurable page size; total count and page count accurate
• Empty state renders when no clients match filters
• /admin/clients/[id] renders 9 tabs: Overview, Locations, GBP, Social, Citations, Site, Jobs, Billing, Audit Log
• Overview tab shows profile card with logo, name, type, tier, status, members, locations, and action buttons (Edit, Impersonate, Suspend)
• Locations tab shows location cards with GBP connection status per location
• GBP tab shows account status, posts table, reviews table, and insights charts
• Social tab shows connected accounts with platform, name, status, followers, last sync
• Citations tab shows all 30 directory submissions with status, NAP match, and screenshot
• Site tab shows template name, section list with visibility toggles, and live preview
• Jobs tab shows all jobs for this practice with pagination and status badges
• Billing tab shows invoices and subscription status
• Audit Log tab shows all actions with actor, timestamp, IP, and action type filter
• Non-existent client ID renders 404 error page with link back to list
• admin.listClients returns paginated list with correct filtering, sorting, and search
• admin.getClient returns full practice with all 9 tab relations populated
• admin.updateClient updates DB, returns updated record, and creates auditLog entry
• Suspend action updates status to SUSPENDED and pauses recurring jobs
• Soft delete sets deletedAt without removing data; blocks login
• Bulk tier changes apply atomically per client; no partial updates

3.5 Agent Context (Pre-conditions) — Client Management#

• Required DB state: ClientProfile (50+ records across all types, tiers, statuses), Location (2 per practice), GbpAccount (1 per practice), GbpLocation (1 per location), SocialAccount (0-4 per practice), Citation (30 per practice), DirectoryProfileSection (7 per practice), JobLog (20 per practice), Invoice (12 per practice), AuditLog (50 per practice), User (members per practice)
• Required env vars: ADMIN_ROLE="ADMIN"
• Required mocks: next/navigation useRouter and redirect mocked; next-auth/react useSession mocked for admin role
• tRPC mocks: admin.listClients, admin.getClient, admin.updateClient return deterministic data
• File mocks: URL.createObjectURL and Blob mocked for CSV export tests

3.6 Verification Commands — Client Management#

# Unit: client list + detail pages
pnpm test:unit -- src/__tests__/unit/admin/clients/

# Integration: client API
pnpm test:integration -- src/__tests__/integration/admin/clients/api.test.ts

# Full client management suite
pnpm test:unit -- src/__tests__/unit/admin/clients/
pnpm test:integration -- src/__tests__/integration/admin/clients/

---

4. Infrastructure Tests#

4.1 Unit Tests — Domain Management (/admin/directory)#

4.2 Unit Tests — Website Management (/admin/directory-profiles)#

4.3 Integration Tests — Infrastructure API#

4.4 Success Criteria (Binary) — Infrastructure#

• /admin/directory table shows all 7 columns with correct data
• DNS Status displays 3 states: Propagated (green), Pending (yellow), Error (red)
• SSL Status displays 2 states: Active (green), Expired (red)
• CDN Status displays 2 states: Cached (green), Bypass (amber)
• "DNS Check" action performs live DNS lookup and updates status badge
• "Force Revalidate" action triggers ISR revalidation for the domain
• Domain list supports filtering by DNS, SSL, and CDN status
• /admin/directory-profiles table shows all 7 columns with correct data
• Health status shows Active (green) or Down (red) with uptime/error details
• Authority Score sorts numerically; Post Count sorts numerically
• Linked Practice column links to client detail page
• Empty state renders when no blog sites exist
• admin.listDomains returns all practice domains with correct status fields
• admin.checkDNS performs DNS resolution and returns accurate status
• admin.revalidateDomain calls revalidation endpoint and returns success
• admin.listWebsites returns all owned blog pages with health and metadata
• admin.checkWebsiteHealth performs HTTP check and returns accurate status

4.5 Agent Context (Pre-conditions) — Infrastructure#

• Required DB state: Practice (20 records with directorySlug, directoryProfileUrl, domainStatus, sslStatus, cdnStatus), BlogSite (15 records with domain, niche, authorityScore, postCount, linkedPracticeId, health, lastPublished)
• Required env vars: BASE_DOMAIN="rankflow.in"; API_REVALIDATE_SECRET (mocked)
• Required mocks: DNS resolver mocked (dns.resolve or equivalent); HTTP fetch mocked for health checks; next/navigation mocked
• tRPC mocks: admin.listDomains, admin.listWebsites, admin.checkDNS, admin.revalidateDomain return deterministic data

4.6 Verification Commands — Infrastructure#

# Unit: domain + website pages
pnpm test:unit -- src/__tests__/unit/admin/directory/
pnpm test:unit -- src/__tests__/unit/admin/directory-profiles/

# Integration: infrastructure API
pnpm test:integration -- src/__tests__/integration/admin/infrastructure/api.test.ts

---

5. Social Connections Tests#

5.1 Unit Tests — Social Connections (/admin/social-connections)#

5.2 Integration Tests — Social API#

5.3 Success Criteria (Binary) — Social Connections#

• /admin/social-connections table shows all 7 columns with correct data
• Platform icons render correctly for Facebook, Instagram, LinkedIn, Twitter
• Status badges show Active (green), Expired (red), Pending (amber)
• "Disconnect" action calls social.disconnect and updates status
• "Refresh Token" action calls social.refreshToken and updates status on success
• Expired accounts show "Reconnect" action; pending accounts show clock icon
• Filter by platform and practice works correctly
• Sort by follower count works numerically descending
• admin.listSocialConnections returns all connected accounts with correct metadata
• social.disconnect calls Composio API, updates DB, and creates audit log entry
• social.refreshToken fetches new token, updates DB, and reactivates account
• Token refresh failure returns clear error without crashing

5.4 Agent Context (Pre-conditions) — Social Connections#

• Required DB state: SocialAccount (25 records across 4 platforms with varied statuses), Practice (linked to accounts), ClientProfile
• Required env vars: COMPOSIO_API_KEY (mocked)
• Required mocks: Composio API mocked for disconnect and refresh; next/navigation mocked
• tRPC mocks: admin.listSocialConnections, social.disconnect, social.refreshToken return deterministic data

5.5 Verification Commands — Social Connections#

# Unit: social connections page
pnpm test:unit -- src/__tests__/unit/admin/social/

# Integration: social API
pnpm test:integration -- src/__tests__/integration/admin/social/api.test.ts

---

6. Job Monitor Tests#

6.1 Unit Tests — Job Monitor (/admin/jobs)#

6.2 Integration Tests — Job Monitor API#

6.3 Success Criteria (Binary) — Job Monitor#

• /admin/jobs renders 4 stat cards (Pending, Running, Completed, Failed) with correct colors
• Job table shows all 8 columns (Job ID, Skill, Practice, Status, Duration, Cost, Started, Actions)
• Status badges render correctly for PENDING, RUNNING, COMPLETED, FAILED
• "Retry" action on failed job calls admin.retryJob and shows toast confirmation
• "View logs" action opens modal with JsonViewer showing payload, error, and attempt history
• Status multi-select filter shows only jobs with selected statuses
• Practice dropdown filter shows only jobs for selected practice
• Skill dropdown filter shows only jobs for selected skill
• Date range filter shows only jobs within selected range
• Table auto-refreshes every 10 seconds with updated queue state
• Duration formatted as seconds with 1 decimal (e.g., "12.3s")
• Cost formatted as USD with 2 decimals (e.g., "$0.05")
• Pagination works with configurable page size
• Empty state renders when no jobs match filters
• admin.listJobs returns paginated, filtered job list with all metadata
• admin.retryJob re-queues failed job from DLQ to original queue
• admin.retryJob rejects non-failed jobs with clear error message
• admin.retryJob returns clear error for non-existent job IDs
• admin.getJobStats returns accurate queue depth counts per status
• admin.getJobLogs returns full attempt history with error details

6.4 Agent Context (Pre-conditions) — Job Monitor#

• Required DB state: JobLog (200+ records across all statuses), Practice (linked to jobs), DLQ with 20 failed jobs
• Required env vars: REDIS_URL for ioredis-mock; BULLMQ_PREFIX (optional)
• Required mocks: BullMQ queue state mocked with known job counts; next/navigation mocked
• Mock Redis state: Fresh ioredis-mock with populated queues; flushall between suites
• tRPC mocks: admin.listJobs, admin.retryJob, admin.getJobStats, admin.getJobLogs return deterministic data
• Timer control: vi.useFakeTimers() for auto-refresh tests

6.5 Verification Commands — Job Monitor#

# Unit: job monitor page
pnpm test:unit -- src/__tests__/unit/admin/jobs/

# Integration: job API + retry
pnpm test:integration -- src/__tests__/integration/admin/jobs/api.test.ts

# Full job monitor suite
pnpm test:unit -- src/__tests__/unit/admin/jobs/
pnpm test:integration -- src/__tests__/integration/admin/jobs/

---

7. Content Review Tests#

7.1 Unit Tests — Content Review (/admin/content)#

7.2 Integration Tests — Content API#

7.3 Success Criteria (Binary) — Content Review#

• /admin/content renders split view: list left, preview right; Prompt Management tab available
• Content list shows all 6 columns (Title/Type, Practice, Status, AI Provider, Cost, Created)
• Status badges render correctly for DRAFT, PENDING_REVIEW, APPROVED, PUBLISHED, REJECTED, FAILED
• PENDING_REVIEW badge shows 24-hour auto-publish countdown timer
• Preview panel renders HTML content safely; SEO score and readability score visible
• "Approve" action calls admin.approveContent; status changes to APPROVED; toast confirms
• "Reject" action calls admin.rejectContent; status changes to REJECTED; toast confirms
• "Edit" action opens inline editor; save calls admin.updateContent
• Prompt Management tab lists all prompt templates with system and user prompts
• Prompt edit opens inline editor; save increments version and creates audit log entry
• profile variant test variants show performance scores; winner highlighted
• Filter by status, practice, and AI provider works correctly
• Empty state renders when no content pieces match filters
• admin.listContent returns paginated, filtered content list with all metadata
• admin.approveContent updates status, schedules publish, and creates audit log entry
• admin.rejectContent updates status, creates audit log, and optionally triggers regeneration
• admin.updatePrompt updates template, increments version, and preserves profile variant test config
• content.getPreview returns rendered HTML with SEO and readability scores

7.4 Agent Context (Pre-conditions) — Content Review#

• Required DB state: ContentPiece (40 records across all statuses, types, providers), Practice (linked to content), PromptTemplate (5 templates with A/B variants), AuditLog
• Required env vars: AI_MODELS config (mocked)
• Required mocks: next/navigation mocked; HTML sanitizer mocked if needed
• tRPC mocks: admin.listContent, admin.approveContent, admin.rejectContent, admin.updatePrompt, content.getPreview return deterministic data

7.5 Verification Commands — Content Review#

# Unit: content review page
pnpm test:unit -- src/__tests__/unit/admin/content/

# Integration: content API
pnpm test:integration -- src/__tests__/integration/admin/content/api.test.ts

---

8. Billing Tests#

8.1 Unit Tests — Billing (/admin/billing)#

8.2 Integration Tests — Billing API#

8.3 Success Criteria (Binary) — Billing#

• /admin/billing renders 4 revenue cards (MRR, ARR, Active Subscriptions, Failed Payments)
• MRR and ARR formatted in INR with comma separators
• Failed Payments card shows red color when > 0
• Subscriptions table shows 5 columns (Practice, Tier, Status, Next Billing, Amount)
• Invoices table shows 5 columns (Invoice ID, Practice, Amount, Status, Paid Date)
• Failed Charges table shows 4 columns (Practice, Amount, Failure Reason, Retry Count)
• Filter by tier, status, and practice search works correctly
• Revenue export CSV downloads correct monthly revenue data
• Empty state renders when no invoices or failed charges exist
• admin.getRevenue calculates MRR as sum of all active subscription amounts
• admin.getRevenue calculates ARR as MRR × 12
• admin.getRevenue returns accurate activeSubscriptions count by tier
• admin.getRevenue returns accurate failedPayments count for last 7 days
• billing.listInvoices returns paginated, filtered invoice list with all metadata
• admin.getFailedCharges returns all failed payments in last 7 days with retry info
• billing.getSubscription returns full subscription details including trial status

8.4 Agent Context (Pre-conditions) — Billing#

• Required DB state: Subscription (80 active across 4 tiers), Invoice (200 records), Billing (with failed charges), ClientProfile (linked to subscriptions), PaymentMethod (linked to billing)
• Required env vars: CURRENCY_CODE="INR"; STRIPE_WEBHOOK_SECRET / RAZORPAY_WEBHOOK_SECRET (mocked)
• Required mocks: next/navigation mocked; CSV export utilities mocked
• tRPC mocks: admin.getRevenue, billing.listInvoices, admin.getFailedCharges, billing.getSubscription return deterministic data

8.5 Verification Commands — Billing#

# Unit: billing page
pnpm test:unit -- src/__tests__/unit/admin/billing/

# Integration: billing API + MRR calculation
pnpm test:integration -- src/__tests__/integration/admin/billing/api.test.ts

---

9. System Reports Tests#

9.1 Unit Tests — System Reports (/admin/reports)#

9.2 Integration Tests — Reports API#

9.3 Success Criteria (Binary) — System Reports#

• /admin/reports renders 6 report cards: Revenue by Month, Client Churn, Citation Success Rate, API Cost Breakdown, Content Generation Volume, Support Ticket Summary
• Each report card shows period label and export buttons (CSV, PDF where applicable)
• Revenue by Month table shows month, MRR, new clients, churned clients, net revenue
• Client Churn table shows month, starting clients, churned, churn rate %, reason breakdown
• Citation Success Rate table shows week, submitted, failed, success rate %, top failing directories
• API Cost Breakdown table shows day, provider, requests, cost; stacked bar chart renders
• Content Generation Volume table shows week, articles, GBP posts, social posts, total cost
• Support Ticket Summary table shows month, total, resolved, avg resolution time, categories
• CSV export downloads correct data with proper headers
• PDF export downloads branded report for Revenue by Month
• Global date range filter updates all report cards simultaneously
• Empty state renders when no data for selected period
• admin.getRevenue returns monthly revenue data with accurate MRR, new clients, churned clients
• Churn rate calculated as (churned / startingClients) * 100 with correct rounding
• Citation success rate calculated as (submitted / attempted) * 100 with correct rounding
• API cost breakdown aggregates per provider per day with correct totals
• Content volume report counts all content types and sums generation costs
• Gross margin calculated as ((MRR - COGS) / MRR) * 100 with correct rounding

9.4 Agent Context (Pre-conditions) — System Reports#

• Required DB state: Subscription (12 months), ClientProfile (with churnedAt dates), Citation (with weekly batch data), AiUsage (daily records), ContentPiece (weekly counts), SupportTicket (monthly records), Invoice (monthly)
• Required env vars: CURRENCY_CODE="INR"
• Required mocks: CSV/PDF generation utilities mocked; next/navigation mocked
• tRPC mocks: admin.getRevenue, admin.getChurnReport, admin.getCitationSuccessReport, admin.getApiCostReport, admin.getContentVolumeReport, admin.getSupportTicketReport return deterministic data

9.5 Verification Commands — System Reports#

# Unit: reports page
pnpm test:unit -- src/__tests__/unit/admin/reports/

# Integration: reports API + calculations
pnpm test:integration -- src/__tests__/integration/admin/reports/api.test.ts

---

10. Impersonation Feature Tests#

10.1 Unit Tests — Impersonation#

10.2 Integration Tests — Impersonation API & Flow#

10.3 Success Criteria (Binary) — Impersonation#

• "Impersonate" button visible on client detail page for ADMIN role only
• Clicking "Impersonate" opens confirmation modal with warning message
• Confirming impersonation updates session with impersonating: true and impersonatedPracticeId
• x-practice-id header set to impersonated practice ID on all subsequent requests
• Admin gains temporary practiceProcedure access for the impersonated practice only
• Access to other practices is blocked during impersonation (403 FORBIDDEN)
• Client dashboard renders correctly when accessed via impersonation
• Client sidebar replaces admin sidebar during impersonation
• Red impersonation banner shows practice name and "Exit Impersonation" button at top of page
• Clicking "Exit Impersonation" clears session flags, removes header, redirects to admin client detail
• AuditLog entry created with IMPERSONATE_START on impersonation begin
• AuditLog entry created with IMPERSONATE_END on impersonation end
• All actions performed during impersonation are logged with impersonating: true flag
• Non-admin users cannot call admin.impersonate (403 FORBIDDEN)
• Impersonating non-existent practice returns 404 NOT FOUND
• Impersonating suspended practice returns 400 BAD REQUEST with clear message
• Impersonation state persists across page reloads (session-backed)
• Impersonation auto-expires after 2 hours of inactivity; session cleared

10.4 Agent Context (Pre-conditions) — Impersonation#

• Required DB state: User (1 admin, 1 client), ClientProfile (2 practices: 1 active, 1 suspended), AuditLog (empty or seeded), ContentPiece (pending review for impersonated practice)
• Required env vars: IMPERSONATION_TIMEOUT_MINUTES=120; ADMIN_ROLE="ADMIN"
• Required mocks: next-auth/react getServerSession mocked to return admin session with impersonation flags; next/navigation mocked for redirect assertions
• Session state: Admin session must support impersonating and impersonatedPracticeId fields
• tRPC mocks: admin.impersonate, admin.endImpersonate, practice.get return deterministic data based on impersonation state
• Timer control: vi.useFakeTimers() for timeout tests

10.5 Verification Commands — Impersonation#

# Unit: impersonation components
pnpm test:unit -- src/__tests__/unit/admin/impersonation/

# Integration: impersonation API + flow
pnpm test:integration -- src/__tests__/integration/admin/impersonation/api.test.ts
pnpm test:integration -- src/__tests__/integration/admin/impersonation/flow.test.tsx

# Full impersonation suite
pnpm test:unit -- src/__tests__/unit/admin/impersonation/
pnpm test:integration -- src/__tests__/integration/admin/impersonation/

---

11. KPI Calculation Tests#

11.1 Unit Tests — KPI Calculation Logic#

11.2 Integration Tests — KPI Aggregation from DB#

11.3 Success Criteria (Binary) — KPI Calculation#

• MRR calculated as sum of all active subscription amounts; trial, churned, and paused excluded
• ARR calculated as MRR × 12
• Citation health calculated as (MATCHED citations / total attempted citations) * 100 with no division by zero
• Churn rate calculated as (churned clients / starting clients) * 100 with no division by zero
• API cost 7-day aggregation sums per provider correctly from AiUsage table
• Gross margin calculated as ((MRR - COGS) / MRR) * 100 with no division by zero
• NAP consistency calculated as (MATCHED live citations / total live citations) * 100
• GBP post success rate calculated as (PUBLISHED / total scheduled) * 100
• Social post success rate calculated as (PUBLISHED / total scheduled) * 100
• Token refresh success rate calculated as (successful refreshes / total attempts) * 100
• Email delivery rate calculated as (DELIVERED / total sent) * 100
• Failed jobs 24h count only includes jobs failed in last 24 hours
• Active jobs count includes both RUNNING and PENDING statuses
• Customer engagement rate calculated as (clients with >=2 logins this week / total active clients) * 100
• All KPI DB aggregations match direct SQL query results exactly
• All percentage calculations handle zero denominators gracefully (return 0.0%)

11.4 Agent Context (Pre-conditions) — KPI Calculation#

• Required DB state: Subscription (80 active, 15 trial, 5 churned), ClientProfile (with churnedAt dates), Citation (30 records with varied matchStatus), AiUsage (100 records over 7 days across 6 providers), JobLog (mixed statuses and timestamps), AuditLog (50 records), EmailLog (1000 records with varied statuses), OauthToken (50 records with refresh history)
• Required env vars: CURRENCY_CODE="INR"
• Required mocks: Prisma aggregation queries mocked if using mock DB; direct SQL assertions via test DB
• Calculation baseline: Pre-computed expected values for all KPIs to assert against

11.5 Verification Commands — KPI Calculation#

# Unit: KPI calculation logic
pnpm test:unit -- src/__tests__/unit/admin/kpi/calculations.test.ts

# Integration: DB aggregation accuracy
pnpm test:integration -- src/__tests__/integration/admin/kpi/db-aggregation.test.ts

# Full KPI suite
pnpm test:unit -- src/__tests__/unit/admin/kpi/
pnpm test:integration -- src/__tests__/integration/admin/kpi/

---

12. Job Monitoring & Alert Threshold Tests#

12.1 Unit Tests — Alert Threshold Logic#

12.2 Integration Tests — Alert Engine#

12.3 Integration Tests — Job Monitoring Metrics#

12.4 Success Criteria (Binary) — Job Monitoring & Alerts#

• Queue depth alert triggers when any queue has > 100 waiting jobs (WARNING)
• Job failure rate alert triggers when > 5% of jobs fail within 1-hour rolling window (WARNING)
• API cost alert triggers when per-practice daily AI spend > $50 (WARNING); flags for review
• Citation success rate alert triggers when < 70% per batch (ALERT); notifies admin + client
• NAP mismatch alert triggers when > 3 mismatches per client (ALERT); schedules update workflow
• GBP token expiry alert triggers when < 7 days until expiry (ALERT); triggers refresh job
• Negative review alert triggers when 1-2 star review unreplied > 24h (ALERT); escalates to client
• Payment failed alert triggers on Stripe/Razorpay payment_failed webhook (ALERT); initiates retry
• System health alert triggers when /api/health returns non-200 (CRITICAL); PagerDuty + Slack
• Disk usage alert triggers when > 80% (CRITICAL); auto-scales storage
• Memory usage alert triggers when > 90% (CRITICAL); restarts container
• DLQ count alert triggers when > 10 jobs in DLQ within 24h (WARNING); admin Slack + email
• Worker CPU alert triggers when > 80% for > 5 minutes (WARNING); scales to next tier
• Inngest latency alert triggers when any step takes > 5 minutes
• Duration alert triggers when average job duration exceeds 2× baseline per job type
• All alerts include: type, severity, affected entity, recommended action, timestamp
• Alert deduplication prevents duplicate notifications within 15-minute window
• Alert resolution notification sent when condition returns to normal
• Critical alerts have 15-minute response SLA; Warning = 2 hours; Low = 24 hours
• Job monitor dashboard refreshes every 10 seconds
• KPI stat cards refresh every 60 seconds
• API cost chart refreshes every 5 minutes
• Citation health refreshes every 1 hour
• Revenue chart refreshes every 1 hour
• Queue metrics accurately reflect BullMQ Redis state
• Failure rate calculation uses rolling 1-hour window
• Average duration calculation correctly computes mean per job type
• Per-client daily cost aggregation matches AiUsage table rollup

12.5 Agent Context (Pre-conditions) — Job Monitoring & Alerts#

• Required DB state: BullMQ queues with known job counts (waiting/active/completed/failed), AiUsage (daily records per practice), Citation (batch data), GbpAccount (with varied tokenExpiresAt), Review (with negative unreplied), Subscription (with past due records), JobLog (with timestamps for rolling window), AlertLog (empty for dedup tests)
• Required env vars: ALERT_SLACK_WEBHOOK_URL (mocked); ALERT_PAGERDUTY_KEY (mocked); ADMIN_EMAIL=admin@rankflow.in; QUEUE_DEPTH_THRESHOLD=100; FAILURE_RATE_THRESHOLD=0.05; API_COST_DAILY_THRESHOLD=50; CITATION_SUCCESS_THRESHOLD=0.70; NAP_MISMATCH_THRESHOLD=3; TOKEN_EXPIRY_DAYS_THRESHOLD=7; DLQ_THRESHOLD=10; CPU_THRESHOLD=80; CPU_DURATION_MINUTES=5; MEMORY_THRESHOLD=90; DISK_THRESHOLD=80; INNGEST_LATENCY_THRESHOLD_MINUTES=5; DURATION_BASELINE_MULTIPLIER=2
• Required mocks: Slack webhook mocked; PagerDuty API mocked; email provider mocked; next/navigation mocked
• Mock Redis state: BullMQ queues with known counts for metric accuracy tests
• Alert engine state: Alert rules engine initialized with all threshold configs

12.6 Verification Commands — Job Monitoring & Alerts#

# Unit: alert threshold logic
pnpm test:unit -- src/__tests__/unit/admin/alerts/thresholds.test.ts

# Integration: alert engine
pnpm test:integration -- src/__tests__/integration/admin/alerts/engine.test.ts

# Integration: job metrics
pnpm test:integration -- src/__tests__/integration/admin/jobs/metrics.test.ts

# Full alert + monitoring suite
pnpm test:unit -- src/__tests__/unit/admin/alerts/
pnpm test:integration -- src/__tests__/integration/admin/alerts/
pnpm test:integration -- src/__tests__/integration/admin/jobs/metrics.test.ts

---

13. Cross-Cutting Integration Tests#

13.1 End-to-End Admin Flow Tests#

13.2 API Router Protection Tests#

13.3 Success Criteria (Binary) — Cross-Cutting#

• Admin login → /admin KPI dashboard loads within 3 seconds with all sections visible
• Full client CRUD flow (create → edit → suspend → view → delete) completes without errors
• Job retry from DLQ changes status from FAILED to PENDING; DLQ count decreases
• Content approval from admin dashboard updates status to APPROVED and reflects on client dashboard
• Impersonation flow: admin → client dashboard → exit → admin detail page works end-to-end
• Billing CSV export downloads file with correct revenue data
• Report CSV export downloads file with correct report data
• Alert notification sends Slack payload with correct type and severity when threshold breached
• Domain revalidate triggers ISR cache purge and shows success toast
• Social disconnect updates status and calls Composio API
• All 15+ admin tRPC procedures return 403 FORBIDDEN for non-admin roles
• All admin tRPC procedures return 401 UNAUTHORIZED for unauthenticated requests
• All admin tRPC procedures return 200 with valid data for authenticated admin
• No admin API endpoint leaks data across practice boundaries (except list aggregated views)

13.4 Agent Context (Pre-conditions) — Cross-Cutting#

• Required DB state: Full production-like dataset: 100 ClientProfile, 100 Location, 100 GbpAccount, 400 SocialAccount, 3000 Citation, 700 DirectoryProfileSection, 2000 JobLog, 1200 Invoice, 2000 AuditLog, 400 ContentPiece, 50 PromptTemplate, 80 Subscription, 500 AiUsage, 1000 EmailLog, 20 SupportTicket
• Required env vars: All production env vars set to test values; NODE_ENV=test; E2E_BASE_URL=http://localhost:3000
• Required external mocks: All third-party APIs mocked (Stripe, Razorpay, Google, Composio, Resend, Slack, PagerDuty, DataForSEO, SerpAPI, Hyperbrowser, Firecrawl, Claude, OpenAI)
• Mock Redis state: Full BullMQ queue state with realistic job counts; DLQ populated with 10-20 failed jobs
• Browser state: Playwright or Cypress with admin session cookie pre-set
• Network mocks: msw server running for all external API calls

13.5 Verification Commands — Cross-Cutting#

# E2E: admin flows
pnpm test:e2e -- e2e/admin/kpi.spec.ts
pnpm test:e2e -- e2e/admin/client-crud.spec.ts
pnpm test:e2e -- e2e/admin/job-retry.spec.ts
pnpm test:e2e -- e2e/admin/content-approval.spec.ts
pnpm test:e2e -- e2e/admin/impersonation.spec.ts
pnpm test:e2e -- e2e/admin/billing-export.spec.ts
pnpm test:e2e -- e2e/admin/report-export.spec.ts
pnpm test:e2e -- e2e/admin/alert-notification.spec.ts
pnpm test:e2e -- e2e/admin/directory-profile-revalidate.spec.ts
pnpm test:e2e -- e2e/admin/social-disconnect.spec.ts

# Integration: API protection
pnpm test:integration -- src/__tests__/integration/admin/api.protection.test.ts

# Full E2E suite
pnpm test:e2e -- e2e/admin/

---

14. Execution Plan & Agent Assignments#

Phase 1: Component Infrastructure (Day 1)#

Phase 2: Page Unit Tests (Days 2-3)#

Phase 3: API Integration Tests (Days 4-5)#

Phase 4: E2E & Cross-Cutting (Day 6)#

Phase 5: Verification & Compliance (Day 7)#

---

Appendix A: Test Data Constants#

---

Appendix B: Admin tRPC Procedure Registry#

---

End of Admin Dashboard & Observability Test Specification — RankFlow AI v1.0.0