nxtgauge-admin-solid/docs/Nxtgauge-End-to-End-Testing-Blueprint.md

Nxtgauge End-to-End Testing Blueprint

1. Scope

• Validate full lifecycle for external users from sign-up to role approval and role-specific module insertion.
• Validate admin-side verification and approval pipelines and state propagation into management modules.
• Validate runtime-config-driven onboarding/dashboard behavior and guard/redirect behavior.
• Validate notification and marketplace flows (customer requirement posting, professional discovery).
• Validate UI parity and visual regressions for management modules using Playwright + pixelmatch + Storybook + VisBug.
• Validate frontend (vitest, Playwright) and backend (cargo test --workspace) quality gates.

2. Business Logic Summary

• External users can exist before any role registration and must appear in Users Management.
• Role activation is gated: verification then approval.
• Approval produces side effects:
  • active role created,
  • role-specific table insertion,
  • notification event.
• Multi-role users are supported and role visibility must remain isolated by role/module.
• Runtime config must not silently mask missing onboarding/dashboard config.

3. Environments and Preconditions

• Frontend admin app: /Users/ashwin/workspace/nxtgauge-admin-solid
• Rust backend workspace: /Users/ashwin/workspace/nxtgauge-backend-rust
• Required ports:
  • Admin app: http://localhost:3000
  • Storybook: http://localhost:6006
• Preconditions:
  • npm install completed in admin repo.
  • Rust toolchain + dependencies available for backend repo.
  • Seed users/roles configured in backend DB (or fallback data strategy used in UI where applicable).
  • Admin preview mode supported with ?_preview=1 for deterministic UI checks.

4. Test Data Matrix

• External identities:
  • User without role.
  • User with pending role onboarding.
  • User with verified/pending approval role.
  • User with approved active role.
  • Multi-role user (2+ roles).
• Roles to cover:
  • COMPANY
  • JOB_SEEKER
  • CUSTOMER
  • DEVELOPER
  • PHOTOGRAPHER
  • SOCIAL_MEDIA_MANAGER
• Marketplace entities:
  • 2-3 customer accounts.
  • 2 requirements per customer.
  • Approved professional accounts for lead/job discovery.

5. End-to-End Test Scenarios

1. Auth split:
   • external identity blocked from admin login.
   • internal identity allowed and redirected to admin.
   • external-resolved session redirected to /login?from=....
2. Onboarding:
   • role-aware onboarding route loads via runtime config.
   • missing config renders explicit error state.
   • onboarding submissions persist and move to verification state.
3. Dashboard:
   • role-specific sidebar and tabs render correctly.
   • guarded routes reject wrong portal/session.
4. Verification:
   • submission appears in Verification Management.
   • reviewer decisions propagate to Approval Management.
5. Approval:
   • approved role appears in Users Management and role-specific module.
   • rejected role remains non-active but user remains visible.
6. Users Management:
   • users with zero roles are visible.
   • role states are visible per user.
7. Role-specific insertion:
   • approval inserts into the right module only.
8. Notifications:
   • approval emits and surfaces unread notification.
9. Requirements/leads:
   • customer creates requirements.
   • approved professionals discover and act on leads/jobs.

6. Playwright Automation Plan

• Existing specs:
  • tests/e2e/admin-auth.spec.ts
  • tests/e2e/admin-visual.spec.ts (pixelmatch)
• Added specs:
  • tests/e2e/management-parity.spec.ts
    • asserts Department-style controls for management modules.
    • asserts dashboard management pages are non-empty.
  • tests/e2e/storybook-admin-pages.spec.ts
    • Storybook admin story smoke checks.
• Execution commands:
  • npm run test:e2e
  • npm run test:management:parity
  • npm run test:visual
  • npm run test:storybook:e2e

7. API and Backend Validation Plan

• Validate gateway/admin API responses and status codes for:
  • /api/gateway/api/auth/session
  • /api/gateway/api/runtime-config
  • /api/gateway/api/admin/users
  • /api/gateway/api/admin/external-users
  • /api/gateway/api/admin/dashboard-config
  • /api/gateway/api/admin/roles
  • /api/gateway/api/admin/companies
• Assertions:
  • lifecycle transitions emit expected payload shape/state.
  • role key propagation remains consistent across services.
  • no silent fallback on missing config.

8. Database Validation Plan

• Validate tables/events after each phase:
  • user record creation at sign-up.
  • onboarding row/state creation.
  • verification record creation/update.
  • approval decision and role activation state.
  • role-specific module table insertion on approval only.
  • notification row insertion.
• Cross-check:
  • rejected records never inserted into approved role module tables.
  • multi-role user keeps separate role states.

9. Runtime Config Validation

• Validate:
  • role-specific onboarding config retrieval.
  • role-specific dashboard config retrieval.
  • UI behavior when config exists vs missing.
  • no hidden fallback that masks configuration defects.
• Internal/External dashboard management pages must show deterministic list/form states even when backend responses are empty.

10. Notification Validation

• Trigger approval and assert:
  • notification is created in backend.
  • notification module UI renders item.
  • unread/read transitions are persisted.
• Negative:
  • rejected approvals must not trigger approval-success notifications.

11. Lead / Requirement Marketplace Validation

• Customer flow:
  • create customer users.
  • create 2 requirements per customer.
  • assert requirement visibility in marketplace feeds.
• Professional flow:
  • approved professionals can access leads/jobs routes.
  • wrong-role users cannot access irrelevant lead pools.
  • apply/contact actions persist.

12. Edge Cases and Negative Cases

• User signs up but never picks role: visible in Users Management.
• Missing runtime config: explicit error/empty guard state.
• Session crossover:
  • external session cannot pass admin route guards.
  • admin session cannot leak into public workspace.
• Multi-role conflict:
  • role A approval should not auto-activate role B.
• Approval before verification must be blocked.
• API 404/401 on optional module endpoints should not crash page shell.

13. Release Blocking Acceptance Checklist

• Auth split tests pass.
• Verification → approval → insertion path validated for all required roles.
• Users Management shows no-role users.
• Role-specific management insertion validated.
• Notification creation/visibility validated.
• Management pages match Department-style controls and table shell.
• Visual diff (pixelmatch) within thresholds.
• vitest, existing unit tests, Playwright suites, and cargo test --workspace pass.

14. Recommended Folder Structure For Tests

• tests/e2e/admin-auth.spec.ts
• tests/e2e/admin-visual.spec.ts
• tests/e2e/management-parity.spec.ts
• tests/e2e/storybook-admin-pages.spec.ts
• tests/vitest/admin-auth.spec.ts
• tests/vitest/module-access.spec.ts
• tests/visual-artifacts/{actual,diff}
• docs/Nxtgauge-End-to-End-Testing-Blueprint.md

15. Suggested Seed Data / Factories

• User factories:
  • external_user_unregistered
  • external_user_pending_verification
  • external_user_pending_approval
  • external_user_approved_role
  • external_user_multi_role
• Domain factories:
  • customer_requirement_factory
  • professional_profile_factory
  • notification_factory
• Role fixtures for matrix roles listed in Section 4.

16. Risks and Likely Failure Points

• Role-key drift between onboarding, approval, and role-specific insertion.
• Guard and redirect regressions across admin/public portals.
• Runtime config partial failures causing invisible fallback behavior.
• Backend endpoint shape drift (users, external-users, dashboard-config) causing UI empty states.
• Visual regressions in shared table controls/icons across management modules.