Test Cases: Role Management

Module: RBAC - Role Management

Backend Endpoints (mounted at /api/admin; legacy alias /admin):

GET /api/admin/permissions — list all permissions grouped by module (guard ADMIN:VIEW:roles)
GET /api/admin/roles — list roles with permissionCount + userCount (guard ADMIN:VIEW:roles)
GET /api/admin/roles/:roleId — single role with full permission key list
GET /api/admin/roles/:roleId/users — users assigned to a role
GET /api/admin/roles/audit — role audit log (guard ADMIN:VIEW:audit-log)
POST /api/admin/roles — create custom role (guard ADMIN:EDIT:roles)
PUT /api/admin/roles/:roleId — update metadata: name/description/color/icon (code immutable)
PUT /api/admin/roles/:roleId/permissions — replace a role's permissions (see TC-RBAC-002)
DELETE /api/admin/roles/:roleId — soft-delete a custom role; optional ?reassignTo=<roleId>
POST /api/admin/roles/:roleId/duplicate — clone a role with all its permissions
POST /api/admin/roles/initialize — (re)seed default roles & permissions for the tenant

Frontend Page: frontend/pwa-app/src/pages/AdminRolesPermissionsPage.tsx (+ components/roles/)

How to reach the page: there is no direct sidebar link. Log in as ADMIN → sidebar Organization > Settings → click the "Roles & Permissions" card (route /admin/roles).

Prerequisites

User logged in with ADMIN role (admin@rcme.membervu.com / Admin123!).
Default system roles + permissions initialized for the tenant (RCME seed does this).

Test Data — System Roles (all are system / non-deletable)

Role Code	Display Name	Is System	Deletable
ADMIN	Administrator	Yes	No
OFFICER	Officer	Yes	No
FINANCE_MANAGER	Treasurer	Yes	No
EVENT_MANAGER	Events Manager	Yes	No
MEMBERSHIP_MANAGER	Membership Manager	Yes	No
COMMUNICATIONS_MANAGER	Communications Manager	Yes	No
MEMBER	Member	Yes	No
PENDING_MEMBER	Pending Member	Yes	No
EXPIRED_MEMBER	Expired Member	Yes	No
GUEST	Guest	Yes	No

Test Cases

TC-RBAC-001: View All Roles

Step	Action	Expected Result
1	Login as ADMIN. Open Settings → "Roles & Permissions" card.	Roles & Permissions page (`/admin/roles`) loads.
2	Look at the left "Roles" panel.	Roles grouped under "System Roles" and "Custom Roles" headers.
3	Verify all 10 system roles present.	ADMIN, OFFICER, FINANCE_MANAGER, EVENT_MANAGER, MEMBERSHIP_MANAGER, COMMUNICATIONS_MANAGER, MEMBER, PENDING_MEMBER, EXPIRED_MEMBER, GUEST — each with a "System" lock badge.
4	Verify each row shows colour dot, role name, role code (monospace), and user count.	Metadata displayed per role.

TC-RBAC-002: View Role Details & Permissions

Step	Action	Expected Result
1	Click the FINANCE_MANAGER (Treasurer) role.	Right detail panel loads.
2	Verify header: colour avatar, name "Treasurer", "System Role" badge, code `FINANCE_MANAGER`.	Shown.
3	Verify the Role Summary bar + module tabs (Members, Finance, Events, Communications, Organization, Admin).	Tabs render; Finance tab shows granted permissions.
4	Click the Finance tab.	Permission matrix: rows = resources (invoices, payments, dues, donations, bank-accounts, dashboard); columns = View / Create / Edit / Delete; granted boxes checked.
5	Scroll to "Assigned Users".	Lists users with this role (e.g. Ana Reyes), or "0".

TC-RBAC-003: Create New Custom Role

Step	Action	Expected Result
1	Click "New Role" (left panel header).	"Create New Role" modal opens.
2	Enter Role Name: "Volunteer Coordinator".	Code auto-fills as `VOLUNTEER_COORDINATOR` (uppercase).
3	Enter a Description; pick a Colour.	Values set.
4	Click "Create Role".	Calls `POST /api/admin/roles`. Toast "Role created successfully". New role auto-selected, appears under "Custom Roles" with 0 permissions.

Note: the create modal has NO permission picker — permissions are granted afterward in the detail panel matrix (TC-RBAC-002 in the Permission Assignment set).

TC-RBAC-004: Create Role — Validation

Step	Action	Expected Result
1	Open "New Role" modal. Leave Name empty.	"Create Role" button disabled.
2	Type a Code containing lowercase / spaces.	Normalized to UPPERCASE_UNDERSCORE; hint "Uppercase letters, numbers, and underscores only".
3	Enter Code `ADMIN` (a system code) and submit.	Rejected — code conflicts with a system role.
4	Enter the code of an existing custom role and submit.	Rejected — duplicate code within tenant.

TC-RBAC-005: Edit Role Metadata (name / description / colour)

Step	Action	Expected Result
1	Select any role. Click the pencil icon next to its name.	Inline name editor appears.
2	Change the name, press Enter (or blur).	Calls `PUT /api/admin/roles/:roleId`. Name updated.
3	Note: this works for system roles too (name/description/colour are editable).	System role name can be changed; the code stays immutable.

TC-RBAC-006: Cannot Delete System Role

Step	Action	Expected Result
1	Select ADMIN. Look for a delete (trash) button in the detail header, and open the ⋮ menu on its row.	No Delete option exists for system roles — the trash button is absent and the ⋮ menu shows only "Duplicate".
2	API: `DELETE /api/admin/roles/<ADMIN role id>`.	Status `400` — system roles cannot be deleted.

TC-RBAC-007: Delete Custom Role (with reassignment)

Step	Action	Expected Result
1	Select a custom role with NO assigned users. Click Delete (⋮ menu or trash icon).	"Delete Role" modal. Delete button enabled.
2	Confirm "Delete Role".	Calls `DELETE /api/admin/roles/:roleId` (soft-delete). Toast "Role deleted successfully".
3	For a custom role with assigned users: click Delete.	Modal shows "This role has N assigned user(s)" + a reassign-to dropdown; Delete stays disabled until a target role is chosen.

TC-RBAC-008: Duplicate Role

Step	Action	Expected Result
1	On EVENT_MANAGER, click "Duplicate" (⋮ menu or copy icon).	"Duplicate Role" modal. Name pre-filled "Events Manager (Copy)", code "EVENT_MANAGER_COPY".
2	Adjust name/code, click "Duplicate Role".	Calls `POST /api/admin/roles/:roleId/duplicate`. New custom role created with the same permissions. Toast "Role duplicated successfully".

TC-RBAC-009: View Role Users

Step	Action	Expected Result
1	Select FINANCE_MANAGER. Scroll to "Assigned Users (N)".	Avatars/names of assigned users (e.g. Ana Reyes). Backed by `GET /api/admin/roles/:roleId/users`.

TC-RBAC-010: Role Audit Log

Step	Action	Expected Result
1	API: `GET /api/admin/roles/audit?limit=50` as ADMIN.	`200` with `{ logs: [...] }`; entries record create/update/delete/permission changes with actor + timestamp. Guard: `ADMIN:VIEW:audit-log`.

TC-RBAC-011: Non-Admin Cannot Manage Roles

Step	Action	Expected Result
1	Login as Ana Reyes (FINANCE_MANAGER). Try to open Settings → Roles & Permissions, or browse directly to `/admin/roles`.	The "Settings" sidebar item is hidden; visiting `/admin/roles` directly silently redirects to `/home` (no 403 page).
2	API: `POST /api/admin/roles` as FINANCE_MANAGER.	Status `403` (lacks `ADMIN:EDIT:roles`).

API Test Cases

TC-RBAC-API-001: GET /api/admin/roles

Expected: 200 OK — { "roles": [ { "id", "code", "name", "description", "color", "isSystem", "permissionCount", "userCount" }, ... ] }. All 10 system roles have isSystem: true.

TC-RBAC-API-002: POST /api/admin/roles

Request body:

{ "name": "Volunteer Coordinator", "code": "VOLUNTEER_COORDINATOR", "description": "Manages event volunteers", "color": "#3B82F6" }

Expected: 201 Created — { "role": { "id", "code": "VOLUNTEER_COORDINATOR", "isSystem": false, "permissions": [] } }. (Permissions are set via a separate call — see TC-RBAC-API-008.)

TC-RBAC-API-003: PUT /api/admin/roles/:roleId (metadata)

Request: PUT /api/admin/roles/<roleId> body { "description": "Updated description", "color": "#10B981" } → Expected: 200 OK. Body may contain any subset of name/description/color/icon. code is NOT updatable.

TC-RBAC-API-004: DELETE /api/admin/roles/:roleId

Custom role, no users: DELETE /api/admin/roles/<customId> → 200 OK { "success": true }. With users: add ?reassignTo=<targetRoleId>.

TC-RBAC-API-005: DELETE System Role (blocked)

DELETE /api/admin/roles/<ADMIN id> → Expected: 400 Bad Request — system roles cannot be deleted.

TC-RBAC-API-006: POST /api/admin/roles/:roleId/duplicate

POST /api/admin/roles/<EVENT_MANAGER id>/duplicate body { "name": "Event Coordinator", "code": "EVENT_COORDINATOR" } → Expected: 201 Created; new role copies all source permissions.