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**:
```bash
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**:
```bash
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

```bash
cd cuatrolabs-auth-ms
./start_server.sh
```

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

### Step 2: Run the Tests

```bash
# 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
```bash
# Check if server is running
curl http://localhost:8002/health

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

### Authentication Failures
```bash
# Create initial users if needed
python3 create_initial_users.py
```

### Module Not Found Errors
```bash
# Install dependencies
cd cuatrolabs-auth-ms
source venv/bin/activate
pip install -r requirements.txt
```

### Database Connection Issues
```bash
# 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`