RankFlow AI — Test Specification: User Dashboard UI

Version: 1.0.0
Date: 2026-06-13
Scope: All /dashboard/* routes, shell components, shared UI primitives, role-based access, responsive behavior, and content approval workflows.
Source Spec: docs/specs/user-dashboard-ui.md
Test Plan: docs/test-plan.md Section 3

---

1. Test Taxonomy & Tooling#

---

2. Shell & Layout Tests#

2.1 ClientLayout (src/app/(client)/layout.tsx)#

Unit Tests#

Integration Tests#

Success Criteria (Binary)#

• SC-LAYOUT-01: Authenticated users see dashboard shell; unauthenticated redirect to /login.
• SC-LAYOUT-02: Practice context is resolved and propagated to all children.
• SC-LAYOUT-03: Practice switcher appears only when user has >1 practice.
• SC-LAYOUT-04: Invalid practice ID in session triggers onboarding redirect.

Agent Context (Pre-conditions)#

• Required DB state: User with CLIENT role, linked Practice with ACTIVE status.
• Required env vars: NEXTAUTH_SECRET, NEXTAUTH_URL.
• Required external mocks: None.

Verification Commands#

# Unit tests
pnpm test:unit -- src/__tests__/unit/layout/ClientLayout.test.tsx

# Integration tests
pnpm test:integration -- src/__tests__/integration/layout/ClientLayout.test.ts

---

2.2 DashboardSidebar (src/components/dashboard/Sidebar.tsx)#

Unit Tests#

Interaction Tests#

Success Criteria (Binary)#

• SC-SIDEBAR-01: All 10 nav items render with correct labels and icons.
• SC-SIDEBAR-02: Active route is visually highlighted and accessible (aria-current).
• SC-SIDEBAR-03: Collapse/expand toggles layout width and persists in localStorage.
• SC-SIDEBAR-04: Practice switcher updates active practice context on selection.
• SC-SIDEBAR-05: Mobile drawer opens/closes with backdrop and trap focus.

Agent Context (Pre-conditions)#

• Required DB state: Practice with ACTIVE status.
• Required env vars: None.
• Required external mocks: next/navigation mock for router.

Verification Commands#

pnpm test:unit -- src/__tests__/unit/components/DashboardSidebar.test.tsx
pnpm test:e2e -- e2e/dashboard/sidebar-mobile.spec.ts

---

2.3 DashboardHeader (src/components/dashboard/Header.tsx)#

Unit Tests#

Success Criteria (Binary)#

• SC-HEADER-01: Breadcrumbs render correctly for all nested routes (≤3 levels).
• SC-HEADER-02: Notification bell displays unread count and opens dropdown.
• SC-HEADER-03: User menu shows name/avatar and logout triggers signOut.
• SC-HEADER-04: Header is sticky on scroll (position: sticky; top: 0).

Verification Commands#

pnpm test:unit -- src/__tests__/unit/components/DashboardHeader.test.tsx

---

3. Page-Level Test Specifications#

---

3.1 /dashboard — Home Overview#

Unit Tests#

Interaction Tests#

E2E Tests#

Success Criteria (Binary)#

• SC-HOME-01: All 6 stat cards render with correct labels, values, and trend indicators.
• SC-HOME-02: Recent GBP Posts section shows last 3 posts with status badges.
• SC-HOME-03: Latest Reviews section shows last 5 reviews with reply status.
• SC-HOME-04: Upcoming Social section shows next 5 scheduled posts.
• SC-HOME-05: Citation Health section displays NAP consistency percentage.
• SC-HOME-06: Quick Action buttons navigate to correct routes.
• SC-HOME-07: Loading state shows skeletons; empty state shows CTAs.
• SC-HOME-08: SEO score badge color changes based on score range (0-49 red, 50-79 yellow, 80-100 green).

Agent Context (Pre-conditions)#

• Required DB state: Practice with related RankTracking, Citation, Review, SocialPost, Report records.
• Required env vars: None.
• Required external mocks: msw handlers for practice.get, gbp.listPosts, review.list, social.listPosts, citation.list, report.list.

Verification Commands#

pnpm test:unit -- src/__tests__/unit/pages/DashboardHomePage.test.tsx
pnpm test:e2e -- e2e/dashboard/home-overview.spec.ts

---

3.2 /dashboard/gbp — GBP Overview (and sub-routes)#

Unit Tests — Overview Tab#

Unit Tests — Posts Tab#

Unit Tests — Reviews Tab#

Unit Tests — Insights Tab#

E2E Tests#

Success Criteria (Binary)#

• SC-GBP-01: Overview tab shows connected status, location count, and sync controls.
• SC-GBP-02: Posts tab supports calendar and list view with toggle.
• SC-GBP-03: Create Post modal opens, validates, and submits to gbp.createPost.
• SC-GBP-04: Edit Post works for scheduled posts only; published posts are read-only.
• SC-GBP-05: Delete Post requires confirmation via ConfirmDialog.
• SC-GBP-06: AI Assist button in post modal calls AI service and populates content.
• SC-GBP-07: Reviews tab lists all reviews with star, comment, date.
• SC-GBP-08: Inline reply opens text area; AI generate creates HIPAA-safe reply.
• SC-GBP-09: Filters (All / Unreplied / Negative / Positive) correctly filter list.
• SC-GBP-10: Bulk Reply selects multiple reviews and calls gbp.bulkReply.
• SC-GBP-11: Insights tab renders 4 charts without console errors.
• SC-GBP-12: Sync Now triggers gbp.sync and shows success/error toast.
• SC-GBP-13: Reconnect opens Google OAuth flow.

Agent Context (Pre-conditions)#

• Required DB state: Practice with GbpAccount (connected), GbpLocation (2), GbpPost (5), GbpReview (10), GbpInsight (30 days).
• Required env vars: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET.
• Required external mocks: msw for Google OAuth, GBP API, AI service.

Verification Commands#

pnpm test:unit -- src/__tests__/unit/pages/GbpOverviewPage.test.tsx
pnpm test:unit -- src/__tests__/unit/pages/GbpPostsPage.test.tsx
pnpm test:unit -- src/__tests__/unit/pages/GbpReviewsPage.test.tsx
pnpm test:unit -- src/__tests__/unit/pages/GbpInsightsPage.test.tsx
pnpm test:e2e -- e2e/dashboard/gbp-post-lifecycle.spec.ts
pnpm test:e2e -- e2e/dashboard/gbp-review-reply.spec.ts

---

3.3 /dashboard/social — Social Media#

Unit Tests#

Interaction Tests#

E2E Tests#

Success Criteria (Binary)#

• SC-SOCIAL-01: Account cards show platform, handle, follower count, and connection status.
• SC-SOCIAL-02: Disconnect requires confirmation and removes account from UI.
• SC-SOCIAL-03: Compose area supports text, media upload (≤4 images), and hashtag suggestions.
• SC-SOCIAL-04: Platform toggle determines which accounts receive the post.
• SC-SOCIAL-05: Date/time picker blocks past dates and respects timezone.
• SC-SOCIAL-06: Preview panel renders platform-specific post previews.
• SC-SOCIAL-07: Queue shows upcoming posts in chronological order.
• SC-SOCIAL-08: History shows past posts with engagement metrics.
• SC-SOCIAL-09: "Post Now" publishes immediately; "Schedule" adds to queue.
• SC-SOCIAL-10: Media upload validates file type (jpg, png, gif, mp4) and max size (10MB).

Agent Context (Pre-conditions)#

• Required DB state: Practice with SocialAccount (3), SocialPost (15 upcoming + 10 past).
• Required env vars: META_APP_ID, TWITTER_CLIENT_ID.
• Required external mocks: msw for Meta Graph API, Twitter API, AI hashtag service.

Verification Commands#

pnpm test:unit -- src/__tests__/unit/pages/SocialOverviewPage.test.tsx
pnpm test:e2e -- e2e/dashboard/social-schedule.spec.ts

---

3.4 /dashboard/citations — Citation Network#

Unit Tests#

E2E Tests#

Success Criteria (Binary)#

• SC-CITATIONS-01: Progress card shows accurate percentage and live/pending/failed counts.
• SC-CITATIONS-02: Directory table renders 30 rows with all columns.
• SC-CITATIONS-03: Status badges use correct semantic colors (green/yellow/red/blue).
• SC-CITATIONS-04: NAP match shows ✅ or ❌ with clickable mismatch details modal.
• SC-CITATIONS-05: Screenshot thumbnail opens lightbox on click.
• SC-CITATIONS-06: Submit to new directory opens modal and calls citation.submit.
• SC-CITATIONS-07: Re-verify NAP refreshes all rows and updates status.
• SC-CITATIONS-08: Download report generates CSV with correct headers and data.
• SC-CITATIONS-09: Table supports sorting by Directory, Status, and Last Checked.
• SC-CITATIONS-10: Table supports filtering by status (Live, Pending, Failed, Needs Update).

Agent Context (Pre-conditions)#

• Required DB state: Practice with 30 Citation records (mix of statuses), Directory (30).
• Required env vars: FIRECRAWL_API_KEY.
• Required external mocks: msw for Firecrawl NAP verification, directory submission APIs.

Verification Commands#

pnpm test:unit -- src/__tests__/unit/pages/CitationsPage.test.tsx
pnpm test:e2e -- e2e/dashboard/citation-submit.spec.ts

---

3.5 /dashboard/profile — Directory Profile#

Unit Tests#

Interaction Tests#

E2E Tests#

Success Criteria (Binary)#

• SC-SITE-01: Preview panel renders iframe with practice URL and device toggle (Desktop/Tablet/Mobile).
• SC-SITE-02: Editor panel lists all 7 editable sections with collapsible accordions.
• SC-SITE-03: Hero section edits (title, subtitle, CTA, background image) save and reflect in preview.
• SC-SITE-04: Image uploader validates file type (jpg, png, webp) and max size (5MB).
• SC-SITE-05: Profile template changes layout and preview reloads.
• SC-SITE-06: Color picker updates primary color in preview within 1 second.
• SC-SITE-07: Font selector changes font family in preview.
• SC-SITE-08: Directory profile URL input validates format and shows DNS/directory path status.
• SC-SITE-09: Publish toggle calls directoryProfile.publish; unpublish calls directoryProfile.unpublish.
• SC-SITE-10: Auto-update toggle persists and shows status badge.
• SC-SITE-11: Rich text editor in About section renders safe HTML (sanitized).
• SC-SITE-12: Mobile device toggle sets iframe width to 375px; tablet to 768px; desktop to 100%.

Agent Context (Pre-conditions)#

• Required DB state: Practice with DirectoryProfile record (template, sections, settings).
• Required env vars: NEXT_PUBLIC_SITE_DOMAIN, AWS_S3_BUCKET.
• Required external mocks: msw for S3 upload, DNS validation API.

Verification Commands#

pnpm test:unit -- src/__tests__/unit/pages/SitePreviewPage.test.tsx
pnpm test:e2e -- e2e/dashboard/profile-edit-publish.spec.ts

---

3.6 /dashboard/reports — Reports#

Unit Tests#

E2E Tests#

Success Criteria (Binary)#

• SC-REPORTS-01: Report cards render month, year, overall score, and 4 category mini-scores.
• SC-REPORTS-02: Category scores use color coding (≥80 green, 50-79 yellow, <50 red).
• SC-REPORTS-03: View PDF opens modal with embedded PDF viewer or iframe.
• SC-REPORTS-04: Email Report opens dialog and calls report.email with validated address.
• SC-REPORTS-05: Download triggers PDF file download with correct filename.
• SC-REPORTS-06: Generate Report creates new card with loading → success state transition.
• SC-REPORTS-07: Empty state shows CTA when no reports exist.
• SC-REPORTS-08: Reports sorted by date descending (newest first).

Agent Context (Pre-conditions)#

• Required DB state: Practice with Report records (12 monthly), RankTracking, Citation, Review, GbpInsight.
• Required env vars: PDF_SERVICE_URL or Puppeteer config.
• Required external mocks: msw for PDF generation service, email service (Resend).

Verification Commands#

pnpm test:unit -- src/__tests__/unit/pages/ReportsPage.test.tsx
pnpm test:e2e -- e2e/dashboard/report-generate.spec.ts

---

3.7 /dashboard/leads — Lead Inbox#

Unit Tests#

E2E Tests#

Success Criteria (Binary)#

• SC-LEADS-01: Lead list renders all columns with correct data alignment.
• SC-LEADS-02: Status badges use correct colors (NEW=blue, CONTACTED=yellow, CONVERTED=green, LOST=gray).
• SC-LEADS-03: Phone numbers are clickable tel: links.
• SC-LEADS-04: Mark Contacted, Convert, and Archive buttons call lead.updateStatus.
• SC-LEADS-05: Lead detail panel shows full message, source URL, and UTM parameters.
• SC-LEADS-06: Filters by source (Site, GBP, Social, Direct) work correctly.
• SC-LEADS-07: Filters by status work correctly.
• SC-LEADS-08: Search filters by name, phone, and message content.
• SC-LEADS-09: Empty state shows when no leads match filters.
• SC-LEADS-10: Archived leads can be viewed via "Archive" tab or toggle.

Agent Context (Pre-conditions)#

• Required DB state: Practice with Lead records (20), mix of statuses and sources.
• Required env vars: None.
• Required external mocks: None.

Verification Commands#

pnpm test:unit -- src/__tests__/unit/pages/LeadsPage.test.tsx
pnpm test:e2e -- e2e/dashboard/lead-management.spec.ts

---

3.8 /dashboard/content — Content Approval#

Unit Tests#

Interaction Tests#

E2E Tests#

Success Criteria (Binary)#

• SC-CONTENT-01: Content queue shows all pending items with type badge, preview, and countdown timer.
• SC-CONTENT-02: Countdown timer accurately reflects 24h auto-publish window.
• SC-CONTENT-03: Approve button calls content.approve and removes card from queue.
• SC-CONTENT-04: Reject button calls content.reject and archives content.
• SC-CONTENT-05: Edit button opens inline editor; save resets timer and updates content.
• SC-CONTENT-06: Content type badges match spec (GBP Post, Social Post, Review Reply, Directory Profile Content, FAQ).
• SC-CONTENT-07: Negative review replies require approval; positive review replies auto-approve.
• SC-CONTENT-08: FAQ content marked as "Optional" but still supports Approve/Reject.
• SC-CONTENT-09: Timer expiry auto-approves and publishes content.
• SC-CONTENT-10: Empty queue shows celebratory empty state.
• SC-CONTENT-11: Mobile swipe gestures work for Approve (right) and Reject (left).
• SC-CONTENT-12: Bulk approve selects multiple cards and processes in batch.

Agent Context (Pre-conditions)#

• Required DB state: Practice with Content records (5 pending: 2 GBP Posts, 1 Social Post, 1 Review Reply, 1 FAQ), mix of PENDING_REVIEW status.
• Required env vars: AI_SERVICE_URL.
• Required external mocks: msw for AI content generation, GBP publish API, Social publish API.

Verification Commands#

pnpm test:unit -- src/__tests__/unit/pages/ContentApprovalPage.test.tsx
pnpm test:e2e -- e2e/dashboard/content-approval.spec.ts
pnpm test:e2e -- e2e/dashboard/content-approval-mobile.spec.ts

---

3.9 /dashboard/settings — Practice Settings#

Unit Tests#

E2E Tests#

Success Criteria (Binary)#

• SC-SETTINGS-01: Business Info tab edits name, type, logo, and brand colors; saves via practice.update.
• SC-SETTINGS-02: Locations tab lists all locations with add/edit/delete functionality.
• SC-SETTINGS-03: Add Location modal validates required fields (name, address, phone).
• SC-SETTINGS-04: Delete Location requires confirmation and warns if only 1 location remains.
• SC-SETTINGS-05: Team Members tab lists all members with roles.
• SC-SETTINGS-06: Invite member sends email and shows pending status until accepted.
• SC-SETTINGS-07: Remove member requires confirmation and prevents removing owner (CLIENT).
• SC-SETTINGS-08: Change role updates immediately and reflects in permission matrix.
• SC-SETTINGS-09: Notifications tab toggles email preferences and persists.
• SC-SETTINGS-10: Integrations tab shows reconnect buttons for disconnected services.
• SC-SETTINGS-11: Tab navigation updates URL query parameter and persists on refresh.
• SC-SETTINGS-12: Logo upload validates image type and max size (2MB).

Agent Context (Pre-conditions)#

• Required DB state: Practice with Location (2), TeamMember (3: 1 CLIENT, 1 EDITOR, 1 VIEWER).
• Required env vars: RESEND_API_KEY.
• Required external mocks: msw for Resend email API, Google OAuth reconnect.

Verification Commands#

pnpm test:unit -- src/__tests__/unit/pages/SettingsPage.test.tsx
pnpm test:e2e -- e2e/dashboard/settings-team.spec.ts

---

3.10 /dashboard/billing — Billing#

Unit Tests#

E2E Tests#

Success Criteria (Binary)#

• SC-BILLING-01: Current plan card displays plan name, monthly price, next billing date, and all included features.
• SC-BILLING-02: Feature list uses checkmarks for included features and crosses for excluded.
• SC-BILLING-03: Upgrade button opens plan comparison modal.
• SC-BILLING-04: Plan comparison table shows all 4 plans with correct pricing and limits.
• SC-BILLING-05: Selecting a plan calls billing.createSubscription and shows success/error toast.
• SC-BILLING-06: Cancel subscription requires confirmation and shows retention offer modal.
• SC-BILLING-07: Invoice table lists all invoices with date, amount, status, and download link.
• SC-BILLING-08: Download invoice triggers PDF download with correct filename.
• SC-BILLING-09: Payment method shows last 4 digits and brand icon; update opens secure checkout.
• SC-BILLING-10: Billing history supports pagination (10 invoices per page).
• SC-BILLING-11: Failed payment shows error banner with "Update Payment Method" CTA.
• SC-BILLING-12: Trial badge shows days remaining if plan is in trial period.

Agent Context (Pre-conditions)#

• Required DB state: Practice with Subscription (Premium, active), Invoice (6 records), PaymentMethod (1 card).
• Required env vars: STRIPE_SECRET_KEY or RAZORPAY_KEY_ID, RAZORPAY_KEY_SECRET.
• Required external mocks: msw for Stripe/Razorpay API, checkout session.

Verification Commands#

pnpm test:unit -- src/__tests__/unit/pages/BillingPage.test.tsx
pnpm test:e2e -- e2e/dashboard/billing-upgrade.spec.ts

---

4. Shared Component Tests#

4.1 Reusable Dashboard Components#

Success Criteria (Binary)#

• SC-SHARED-01: StatCard renders all props correctly and shows skeleton when isLoading.
• SC-SHARED-02: StatusBadge maps every status enum to correct semantic color.
• SC-SHARED-03: DataTable supports column sorting, pagination, and row selection.
• SC-SHARED-04: EmptyState renders icon, title, description, and optional CTA.
• SC-SHARED-05: LoadingSkeleton has variants for card, table, list, and chart.
• SC-SHARED-06: ConfirmDialog requires explicit confirm; cancel closes without action.
• SC-SHARED-07: DatePicker blocks past dates and formats ISO string correctly.
• SC-SHARED-08: ImageUploader validates file type (jpg, png, webp, gif) and max size.
• SC-SHARED-09: RichTextEditor outputs sanitized HTML; toolbar buttons work.
• SC-SHARED-10: AIAssistButton shows loading spinner during generation and error tooltip on failure.

Verification Commands#

pnpm test:unit -- src/__tests__/unit/components/StatCard.test.tsx
pnpm test:unit -- src/__tests__/unit/components/StatusBadge.test.tsx
pnpm test:unit -- src/__tests__/unit/components/DataTable.test.tsx
pnpm test:unit -- src/__tests__/unit/components/EmptyState.test.tsx
pnpm test:unit -- src/__tests__/unit/components/LoadingSkeleton.test.tsx
pnpm test:unit -- src/__tests__/unit/components/ConfirmDialog.test.tsx
pnpm test:unit -- src/__tests__/unit/components/DatePicker.test.tsx
pnpm test:unit -- src/__tests__/unit/components/ImageUploader.test.tsx
pnpm test:unit -- src/__tests__/unit/components/RichTextEditor.test.tsx
pnpm test:unit -- src/__tests__/unit/components/AIAssistButton.test.tsx

---

5. Role-Based Access Matrix Tests#

5.1 Permission Enforcement#

For every route and mutation, verify UI enforcement and API enforcement across all three roles.

Unit Tests — UI Enforcement#

Integration Tests — API Enforcement#

E2E Tests#

Success Criteria (Binary)#

• SC-ACCESS-01: CLIENT role sees all nav items, buttons, and forms across all pages.
• SC-ACCESS-02: EDITOR role can create/edit content (posts, replies, social, site) but cannot edit settings, manage team, or view billing.
• SC-ACCESS-03: EDITOR role sees read-only settings and team tabs (or tabs are hidden).
• SC-ACCESS-04: VIEWER role sees all pages but all edit/create/approve buttons are hidden.
• SC-ACCESS-05: VIEWER role forms are disabled; no mutation buttons visible.
• SC-ACCESS-06: API returns 403 for unauthorized mutations regardless of UI state.
• SC-ACCESS-07: Navigation respects role: hidden nav items do not appear in sidebar.
• SC-ACCESS-08: Role change in settings immediately updates UI permissions without reload.

Agent Context (Pre-conditions)#

• Required DB state: User (3 records: 1 CLIENT, 1 EDITOR, 1 VIEWER), all linked to same Practice.
• Required env vars: NEXTAUTH_SECRET.
• Required external mocks: None.

Verification Commands#

pnpm test:unit -- src/__tests__/unit/access/RoleAccess.test.tsx
pnpm test:integration -- src/__tests__/integration/access/ApiAccess.test.ts
pnpm test:e2e -- e2e/access/viewer-readonly.spec.ts
pnpm test:e2e -- e2e/access/editor-limited.spec.ts

---

6. Responsive Behavior Tests#

6.1 Breakpoint Compliance#

Unit Tests — Responsive Hooks/Components#

E2E Tests — Responsive Flows#

Success Criteria (Binary)#

• SC-RESPONSIVE-01: Desktop (>1024px): sidebar fixed at 240px; all grids use multi-column layout.
• SC-RESPONSIVE-02: Tablet (768-1024px): sidebar collapsible to 64px; grids adjust to 2 columns.
• SC-RESPONSIVE-03: Mobile (<768px): sidebar hidden; hamburger opens drawer; bottom nav option available.
• SC-RESPONSIVE-04: Data tables render as card lists on mobile.
• SC-RESPONSIVE-05: Charts simplify or reduce data points on mobile.
• SC-RESPONSIVE-06: Site preview opens in modal or full-screen on mobile.
• SC-RESPONSIVE-07: Content approval supports swipe gestures on mobile.
• SC-RESPONSIVE-08: Lead detail opens as bottom sheet on mobile.
• SC-RESPONSIVE-09: Stat cards stack to 1 column on mobile.
• SC-RESPONSIVE-10: No horizontal scroll on any page at any breakpoint.
• SC-RESPONSIVE-11: Touch targets are ≥44px on mobile.
• SC-RESPONSIVE-12: Font sizes remain readable (≥14px) on all breakpoints.

Agent Context (Pre-conditions)#

• Required DB state: Standard practice data across all pages.
• Required env vars: None.
• Required external mocks: None.
• Required tooling: Playwright viewport emulation (Desktop 1280x720, Tablet 900x600, Mobile 375x812).

Verification Commands#

pnpm test:unit -- src/__tests__/unit/responsive/Responsive.test.tsx
pnpm test:e2e -- e2e/responsive/mobile-navigation.spec.ts
pnpm test:e2e -- e2e/responsive/tablet-collapse.spec.ts
pnpm test:e2e -- e2e/responsive/mobile-content-approval.spec.ts
pnpm test:e2e -- e2e/responsive/mobile-lead-inbox.spec.ts

---

7. Content Approval Workflow Tests#

7.1 State Machine Tests#

E2E Tests#

Success Criteria (Binary)#

• SC-WORKFLOW-01: DRAFT content auto-queues to PENDING_REVIEW within 5 minutes of generation.
• SC-WORKFLOW-02: PENDING_REVIEW content shows 24h countdown timer.
• SC-WORKFLOW-03: Approve transitions to APPROVED and triggers immediate publish.
• SC-WORKFLOW-04: Reject transitions to REJECTED and archives content.
• SC-WORKFLOW-05: Edit resets timer to 24h and keeps status as PENDING_REVIEW.
• SC-WORKFLOW-06: Timer expiry auto-approves and auto-publishes content.
• SC-WORKFLOW-07: APPROVED content transitions to PUBLISHED upon webhook confirmation.
• SC-WORKFLOW-08: Rejected content supports "Regenerate" which creates new DRAFT.
• SC-WORKFLOW-09: Medical compliance scan runs before every state transition to PUBLISHED.
• SC-WORKFLOW-10: Audit log records every state transition with user ID, timestamp, and action.

Agent Context (Pre-conditions)#

• Required DB state: Practice with Content records in each state (DRAFT, PENDING_REVIEW, APPROVED, PUBLISHED, REJECTED).
• Required env vars: AI_SERVICE_URL, BULLMQ_REDIS_URL.
• Required external mocks: msw for AI generation, GBP publish API, social publish API, webhook delivery.
• Required job queue: BullMQ worker running for content.autoPublish job.

Verification Commands#

pnpm test:unit -- src/__tests__/unit/workflow/ContentWorkflow.test.ts
pnpm test:e2e -- e2e/workflow/content-approval-lifecycle.spec.ts
pnpm test:e2e -- e2e/workflow/content-auto-publish.spec.ts
pnpm test:e2e -- e2e/workflow/content-reject-regenerate.spec.ts

---

8. Visual Regression Test Points#

8.1 Screenshot Coverage#

Capture baseline screenshots for the following states and pages. All tests run at Desktop (1280x720) and Mobile (375x812).

Success Criteria (Binary)#

• SC-VISUAL-01: Baseline screenshots exist for all 31 states listed above.
• SC-VISUAL-02: Argos diffs show ≤1% pixel variance for intentional changes.
• SC-VISUAL-03: Mobile screenshots capture bottom nav or drawer layout correctly.
• SC-VISUAL-04: Dark mode screenshots captured if theme toggle exists (optional).
• SC-VISUAL-05: Loading states show skeletons, not empty whitespace.
• SC-VISUAL-06: Modals and drawers are fully visible within viewport bounds.
• SC-VISUAL-07: Charts and graphs render consistently (no random data shifts in baselines).

Agent Context (Pre-conditions)#

• Required DB state: Full seeded dataset with consistent values (no random data).
• Required env vars: ARGOS_TOKEN (if using Argos CI).
• Required external mocks: All external APIs mocked to return deterministic responses.
• Required tooling: Playwright + @argos-ci/playwright.

Verification Commands#

# Capture baselines
pnpm test:visual:baseline

# Run visual diff
pnpm test:visual

# Update baselines after intentional change
pnpm test:visual:update

---

9. Cross-Cutting Concerns#

9.1 Accessibility (a11y)#

Success Criteria (Binary)#

• SC-A11Y-01: All pages pass axe-core with 0 critical violations.
• SC-A11Y-02: All interactive elements have focus indicators.
• SC-A11Y-03: All images have alt text; decorative images have alt="".
• SC-A11Y-04: Color contrast ratios ≥4.5:1 for normal text, ≥3:1 for large text.
• SC-A11Y-05: Form inputs have associated labels.
• SC-A11Y-06: Modal dialogs trap focus and restore focus on close.
• SC-A11Y-07: Sidebar navigation uses aria-current for active page.
• SC-A11Y-08: Status changes announced via live regions (toasts, loading states).

Verification Commands#

pnpm test:a11y -- e2e/a11y/

---

9.2 Performance#

Success Criteria (Binary)#

• SC-PERF-01: LCP < 2.5s on all dashboard pages.
• SC-PERF-02: INP < 200ms on all dashboard pages.
• SC-PERF-03: CLS < 0.1 on all dashboard pages.
• SC-PERF-04: Total JS bundle < 500KB gzipped.
• SC-PERF-05: Charts render within 500ms of data arrival.
• SC-PERF-06: Data tables with 30 rows render within 300ms.
• SC-PERF-07: No layout thrashing during sidebar collapse/expand.
• SC-PERF-08: Images lazy-loaded below the fold.

Verification Commands#

pnpm test:perf -- e2e/perf/
# OR
pnpm lighthouse --preset=desktop http://localhost:3000/dashboard

---

9.3 Error Handling & Edge Cases#

Success Criteria (Binary)#

• SC-ERROR-01: All tRPC errors show user-friendly toast with retry option.
• SC-ERROR-02: Offline state shows banner and queues non-critical actions.
• SC-ERROR-03: Session expiry redirects to login with original path preserved.
• SC-ERROR-04: Rate-limited APIs retry with exponential backoff (max 3 retries).
• SC-ERROR-05: Invalid file uploads rejected client-side before network request.
• SC-ERROR-06: Form validation prevents submission and shows inline errors.
• SC-ERROR-07: AI generation timeout shows progress and graceful failure message.
• SC-ERROR-08: Concurrent edit conflict detected and resolved with user choice.
• SC-ERROR-09: Malformed API responses fall back to empty state, not crash.
• SC-ERROR-10: 404 and 500 pages render with helpful navigation links.

Verification Commands#

pnpm test:unit -- src/__tests__/unit/error-handling/ErrorHandling.test.tsx

---

10. Verification Commands Summary#

Run All Dashboard UI Tests#

# 1. Unit tests (all dashboard pages + components + access + responsive + error handling)
pnpm test:unit -- src/__tests__/unit/pages/
pnpm test:unit -- src/__tests__/unit/components/
pnpm test:unit -- src/__tests__/unit/layout/
pnpm test:unit -- src/__tests__/unit/access/
pnpm test:unit -- src/__tests__/unit/responsive/
pnpm test:unit -- src/__tests__/unit/error-handling/

# 2. Integration tests (layout + API access)
pnpm test:integration -- src/__tests__/integration/layout/
pnpm test:integration -- src/__tests__/integration/access/

# 3. E2E tests (all dashboard flows)
pnpm test:e2e -- e2e/dashboard/
pnpm test:e2e -- e2e/access/
pnpm test:e2e -- e2e/responsive/
pnpm test:e2e -- e2e/workflow/

# 4. Visual regression
pnpm test:visual

# 5. Accessibility
pnpm test:a11y -- e2e/a11y/

# 6. Performance
pnpm test:perf -- e2e/perf/

# 7. Compliance (medical content)
pnpm test:compliance -- src/__tests__/compliance/

# 8. Full dashboard suite (CI)
pnpm test:dashboard

Quick Checklist for Agent Verification#

Before marking any dashboard page task as complete, run:

# Unit tests for the page
pnpm test:unit -- src/__tests__/unit/pages/[PageName].test.tsx

# Integration tests for related routers
pnpm test:integration -- src/__tests__/integration/routers/[router].test.ts

# E2E smoke test for the page
pnpm test:e2e -- e2e/dashboard/[page-smoke].spec.ts

# Visual regression for the page
pnpm test:visual -- e2e/visual/[page].spec.ts

Success Criteria Summary (All Binary)#

---

End of Test Specification — RankFlow AI User Dashboard UI v1.0.0