TEST_SCRIPTS_README.md

System Users API Test Scripts

Overview

This directory contains comprehensive test scripts for the System Users API, aligned with the updated API specification where system users are created ONLY via Employee or Merchant flows.

Files Created

1. test_system_users_api.py

Purpose: Automated Python test script that tests all system users endpoints

Features:

• Tests all list operations (with/without projection, with filters)
• Tests individual user operations (get, suspend, unlock, reset, deactivate)
• Tests role lookup endpoint
• Tests internal endpoints (from-employee, from-merchant)
• Validates projection list functionality
• Validates merchant isolation
• Provides detailed output with success/error indicators

Usage:

python3 test_system_users_api.py

2. test_system_users_api.sh

Purpose: Shell script wrapper for easy test execution

Features:

• Checks if server is running
• Runs the Python test script
• Provides clear output

Usage:

chmod +x test_system_users_api.sh
./test_system_users_api.sh

3. SYSTEM_USERS_API_TESTING.md

Purpose: Comprehensive testing guide and documentation

Contents:

• Prerequisites and setup instructions
• Manual testing with cURL commands
• Test scenarios and validation checklist
• Performance benchmarks
• Error cases to test
• Troubleshooting guide

Quick Start

Step 1: Start the Server

cd cuatrolabs-auth-ms
./start_server.sh

Wait for the server to start (you should see "Application startup complete")

Step 2: Run the Tests

# Option 1: Use the shell script
./test_system_users_api.sh

# Option 2: Run Python script directly
python3 test_system_users_api.py

Step 3: Review Results

The test script will output:

• ✅ Success indicators for passing tests
• ❌ Error indicators for failing tests
• Detailed response data for each endpoint
• Summary of test execution

API Endpoints Tested

Public Endpoints (Require JWT Auth)

1. POST /system-users - List users with optional projection
2. GET /system-users/{system_user_id} - Get user details
3. PUT /system-users/{system_user_id}/suspend - Suspend user
4. PUT /system-users/{system_user_id}/unlock - Unlock user
5. PUT /system-users/{system_user_id}/reset-password - Reset password
6. GET /system-users/{system_user_id}/login-attempts - View login logs
7. DELETE /system-users/{system_user_id} - Deactivate user
8. GET /roles - Get roles by scope

Internal Endpoints (Require Service Auth)

1. POST /internal/system-users/from-employee - Create from employee
2. POST /internal/system-users/from-merchant - Create merchant admin

Key Features Tested

Projection List Support

• ✅ List without projection returns full objects
• ✅ List with projection returns only specified fields
• ✅ Projection excludes _id field
• ✅ Projection returns raw dicts instead of models
• ✅ MongoDB projection used for performance

Security & Authorization

• ✅ JWT authentication required
• ✅ Merchant isolation enforced
• ✅ Admin operations require admin role
• ✅ Cross-merchant access prevented

User Lifecycle

• ✅ Users created only via Employee/Merchant flows
• ✅ Suspend/unlock functionality
• ✅ Password reset
• ✅ Soft delete (deactivation)
• ✅ Login attempt tracking

Test Configuration

Default Credentials

• Email: superadmin@cuatrolabs.com
• Password: Admin@123

Server Configuration

• Base URL: http://localhost:8002
• Auth Endpoint: /auth/login
• System Users Endpoint: /system-users

Expected Results

Successful Test Run

================================================================================
  SYSTEM USERS API TEST SUITE
================================================================================
Base URL: http://localhost:8002
Testing as: superadmin@cuatrolabs.com

================================================================================
  AUTHENTICATION
================================================================================

🧪 Login as Admin
✅ Logged in successfully
   Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

================================================================================
  LIST ENDPOINTS
================================================================================

🧪 List Users (without projection)
   Status: 200
✅ Retrieved 5 users
   Sample user keys: ['user_id', 'username', 'email', 'status', ...]

🧪 List Users (with projection)
   Status: 200
✅ Retrieved 5 users with projection
   Projected fields: ['user_id', 'username', 'email', 'status']
✅ _id field correctly excluded

... (more tests)

================================================================================
  TEST SUITE COMPLETED
================================================================================
✅ All tests executed

Troubleshooting

Server Not Running

# Check if server is running
curl http://localhost:8002/health

# If not, start it
cd cuatrolabs-auth-ms
./start_server.sh

Authentication Failures

# Create initial users if needed
python3 create_initial_users.py

Module Not Found Errors

# Install dependencies
cd cuatrolabs-auth-ms
source venv/bin/activate
pip install -r requirements.txt

Database Connection Issues

# Check database status
curl http://localhost:8002/debug/db-status

Notes

• Admin operations are skipped by default to avoid modifying data
• Uncomment the admin operation tests in the script to test them
• Internal endpoints may return 401/403 without proper service authentication
• The test script is safe to run multiple times

Next Steps

1. Run the test script to validate current implementation
2. Review any failing tests
3. Implement missing endpoints or fix issues
4. Update the spec if requirements change
5. Re-run tests to verify fixes

Related Documentation

• Spec: .kiro/specs/system-users-management/
  • requirements.md - API requirements
  • design.md - API design and architecture
  • tasks.md - Implementation tasks
• API Standards: cuatrolabs-scm-ms/API_STANDARDS.md
• Projection Guide: cuatrolabs-scm-ms/PROJECTION_LIST_IMPLEMENTATION.md