# Role API Test Report

## How to Run the Tests

**Run all role API tests:**
```bash
pytest --tb=short tests/api_tests/role/
```

---

## Test Results Summary

- **Total tests collected:** 33
- **All tests passed.**
- **Warnings:**
  - Deprecation warnings from Pydantic/Beanie (upgrade recommended for future compatibility).

---

## Test Case Explanations

### test_assign_permissions.py
- **test_assign_permissions_success**  
  Assign multiple permissions to a role successfully.
- **test_assign_permissions_fail_role_not_found**  
  Assigning permissions to a non-existent role fails.
- **test_assign_permissions_fail_permission_not_found**  
  Assigning a non-existent permission to a role fails.
- **test_assign_permissions_fail_empty_permission_ids**  
  Assigning with an empty permission list fails.
- **test_assign_permissions_fail_empty_role_id**  
  Assigning with an empty role ID fails.
- **test_assign_permissions_remove_duplicates**  
  Assigning duplicate permission IDs results in de-duplication.
- **test_assign_permissions_to_default_role**  
  Assigning permissions to a default role (should succeed if not restricted).

### test_create_role.py
- **test_create_role_success**  
  Admin user can create a role with valid and unique data.
- **test_create_role_fail_duplicate_role_key/name**  
  Creating a role with duplicate key or name fails.
- **test_create_role_fail_empty_role_key/name**  
  Creating a role with empty key or name fails.
- **test_create_role_success_empty_description**  
  Description is optional.
- **test_create_role_fail_by_non_admin**  
  Non-admin user cannot create roles.
- **test_create_role_success_after_grant_admin**  
  After admin grants admin role to a temp user and the user re-logs in, the user can create roles.

### test_delete_role.py
- **test_delete_role_success**  
  Admin user can delete a role.
- **test_delete_role_fail_not_found**  
  Deleting a non-existent role fails.
- **test_delete_default_role_fail**  
  Default roles cannot be deleted.
- **test_delete_role_fail_by_non_admin**  
  Non-admin user cannot delete roles.
- **test_delete_role_success_after_grant_admin**  
  After admin grants admin role to a temp user and the user re-logs in, the user can delete roles.

### test_query_role.py
- **test_query_all_roles**  
  Query all roles, expect a list.
- **test_query_roles_by_key/name**  
  Query roles by key or name (fuzzy search).
- **test_query_roles_pagination**  
  Query roles with pagination.

### test_update_role.py
- **test_update_role_success**  
  Admin user can update a role with valid and unique data.
- **test_update_role_fail_not_found**  
  Updating a non-existent role fails.
- **test_update_role_fail_duplicate_key/name**  
  Updating to a duplicate key or name fails.
- **test_update_role_fail_empty_key/name**  
  Updating with empty key or name fails.
- **test_update_default_role_fail**  
  Default roles cannot be updated.
- **test_update_role_fail_by_non_admin**  
  Non-admin user cannot update roles.
- **test_update_role_success_after_grant_admin**  
  After admin grants admin role to a temp user and the user re-logs in, the user can update roles.

---

## Summary

- These tests ensure that only admin users can manage roles, and that permission can be delegated by granting the admin role to other users.
- Each test case is designed to verify both positive and negative scenarios, including permission escalation and proper error handling.
- **Coverage reporting is not included in this report.**

---

If you need a more detailed, markdown-formatted report with actual coverage numbers, please enable coverage and re-run the tests.