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

> Policy Update (2026-04-05): External onboarding management is deprecated and removed. After sign-up/login, users are routed directly by role key to role-specific dashboard/runtime modules. Any legacy references to /onboarding, /choose-role onboarding flows, onboarding schema management, or fallback data strategies should be treated as obsolete. Runtime config and canonical backend APIs are the only source of truth.

# 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 role-key dashboard routing 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 role/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:9202`
  - 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 (no UI fallback data strategy).
  - Admin preview mode supported with `?_preview=1` for deterministic UI checks.

## 4. Test Data Matrix
- External identities:
  - User without role.
  - User with assigned role key and pending approval.
  - 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. Role Runtime:
   - role-key based dashboard route resolves via runtime config.
   - missing runtime config renders explicit error state.
   - role state persists and moves to verification/approval 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 runtime config.

## 8. Database Validation Plan
- Validate tables/events after each phase:
  - user record creation at sign-up.
  - role state creation/update.
  - 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.