HH/docs/SLA_TESTING_README.md

# Real-Time SLA Testing System

A comprehensive, realistic testing framework for complaint SLA workflows with time-compressed simulation.

## 🎯 Overview

This testing system allows you to **simulate real-world complaint workflows** in a fraction of the time by using time compression. All actual system code is executed - no mocking or shortcuts.

### Key Features

✅ **Real-Time Simulation**: 1 second = 1 hour (configurable)  
✅ **Actual System Execution**: Real Celery tasks, emails, database operations  
✅ **Complete Workflows**: Happy path and escalation scenarios  
✅ **Staff Hierarchy**: Multi-level escalation testing  
✅ **SLA Configuration**: Customizable deadlines and reminders  
✅ **Visual Progress**: Clear step-by-step execution logging  

## 📁 Files Created

### Core Testing Framework

- **`scenario_test_base.py`** - Base class with utilities for time compression, SLA setup, and verification
- **`test_scenario_1_successful_explanation.py`** - Happy path: Staff submits before deadline
- **`test_scenario_2_escalation_with_reminders.py`** - Escalation path: Staff doesn't respond, escalates through management chain

### Documentation

- **`SLA_TESTING_QUICKSTART.md`** - Get started in 5 minutes
- **`REAL_TIME_SLA_TESTING_GUIDE.md`** - Complete guide with detailed scenarios

## 🚀 Quick Start

```bash
# Run Scenario 1 (Happy Path - ~7 seconds)
python test_scenario_1_successful_explanation.py

# Run Scenario 2 (Escalation - ~37 seconds)
python test_scenario_2_escalation_with_reminders.py
```

For detailed instructions, see [SLA_TESTING_QUICKSTART.md](SLA_TESTING_QUICKSTART.md)

## 📊 Scenarios

### Scenario 1: Successful Explanation Submission

**Duration**: ~7 seconds  
**What it tests**: Staff member submits explanation before SLA deadline

**Workflow**:
1. Create complaint
2. Request explanation from staff
3. Staff submits explanation (before deadline)
4. Verify no escalation occurred

**Results**:
- ✅ Explanation submitted successfully
- ✅ No reminders needed
- ✅ No escalation triggered
- ✅ Workflow completed at staff level

### Scenario 2: Escalation with Reminders

**Duration**: ~37 seconds  
**What it tests**: Staff member doesn't respond, system sends reminders and escalates

**Workflow**:
1. Create complaint (high severity)
2. Request explanation from staff
3. First reminder sent (6 hours before deadline)
4. Second reminder sent (3 hours before deadline)
5. Deadline reached - escalate to manager
6. Manager deadline reached - escalate to department head

**Results**:
- ✅ Reminders sent at correct intervals
- ✅ Escalated to manager when deadline passed
- ✅ Manager receives explanation request
- ✅ Escalated to department head when manager didn't respond
- ✅ Multi-level escalation chain works correctly

## ⏱️ Time Compression

The system uses configurable time compression to simulate real workflows:

| Real Time | Simulated Time | Ratio | Use Case |
|------------|----------------|--------|----------|
| 1 second | 1 hour | 1:1 | Default testing |
| 1 second | 2 hours | 1:2 | Faster testing |
| 1 second | 30 minutes | 1:0.5 | Detailed debugging |

**Example**: Test a 48-hour SLA in 24 seconds (1:2 ratio) or 48 seconds (1:1 ratio)

## 🔧 What Gets Created

Each test scenario creates a complete test environment:

### Common Objects
- Hospital (Al Hammadi Hospital)
- Department (Emergency Department)
- ExplanationSLAConfig (customized per scenario)
- ComplaintSLAConfig (customized per scenario)

### Scenario 1 Objects
- 1 Staff member (Omar Al-Harbi - Nurse)
- 1 Complaint (medium severity, medium priority)
- 1 Explanation request (submitted)
- 1 Hospital Admin user

### Scenario 2 Objects
- 3 Staff members (Staff → Manager → Department Head)
- 1 Complaint (high severity, high priority)
- 1 Explanation request (overdue, escalated)
- 1 SecondReminderConfig (3 hours before deadline)
- 1 Hospital Admin user

## 🎨 How It Works

### 1. Time Compression

```python
class ScenarioTestBase:
    def __init__(self, time_compression_ratio=1):
        # 1 second = 1 hour of system time
        self.time_compression_ratio = time_compression_ratio
```

### 2. Step Execution with Sleep

```python
def print_step(self, message, duration_seconds=0):
    # Print step description
    print(f"[Step {self.step_number}] {message}")
    
    # Sleep for specified time
    for i in range(1, duration_seconds + 1):
        time.sleep(1)
        print(f"  [{i}/{duration_seconds}s] Simulated time: {i * ratio} hours")
```

### 3. Real Celery Task Execution

```python
# Send explanation request email
from apps.complaints.tasks import send_explanation_request_email
result = send_explanation_request_email(str(explanation.id))

# Check and send reminders
from apps.complaints.tasks import send_explanation_reminders
result = send_explanation_reminders()

# Escalate overdue explanations
from apps.complaints.tasks import escalate_overdue_explanations
result = escalate_overdue_explanations()
```

### 4. Database Verification

```python
def verify_explanation_state(self, explanation, expected_state):
    # Refresh from database
    explanation = ComplaintExplanation.objects.get(id=explanation.id)
    
    # Check state
    is_used = explanation.is_used
    is_overdue = explanation.is_overdue
    has_reminder = explanation.reminder_sent_at is not None
    has_escalation = explanation.escalated_to_manager is not None
    
    # Verify against expected state
    if expected_state == 'submitted':
        return is_used and not is_overdue
    # ... other states
```

## 🔍 Verification

After running tests, verify results:

### In Django Admin

```bash
python manage.py runserver
# Visit: http://localhost:8000/admin
```

Check:
- Complaints → All Complaints
- Complaints → Explanations
- Organizations → Staff
- Complaints → SLA Configurations

### In Database

```python
from apps.complaints.models import ComplaintExplanation
exp = ComplaintExplanation.objects.first()
print(f"is_used: {exp.is_used}")
print(f"is_overdue: {exp.is_overdue}")
print(f"escalated_to_manager: {exp.escalated_to_manager}")
```

### In Email Output

```python
from django.core.mail import outbox
print(f"Emails sent: {len(outbox)}")
print(f"Subject: {outbox[0].subject}")
print(f"Body: {outbox[0].body}")
```

## 🛠️ Customization

### Change Time Compression

```python
# Faster testing (1s = 2h)
test = Scenario1SuccessfulExplanation(time_compression_ratio=2)

# Slower testing (1s = 30min)
test = Scenario1SuccessfulExplanation(time_compression_ratio=0.5)
```

### Change SLA Deadlines

```python
self.create_explanation_sla_config(
    hospital=hospital,
    response_hours=24,  # Change deadline
    reminder_hours_before=12,  # Change reminder timing
    auto_escalate_enabled=True,
    escalation_hours_overdue=0,
    max_escalation_levels=3
)
```

### Test Different Severities

```python
complaint = Complaint.objects.create(
    hospital=hospital,
    department=department,
    staff=staff,
    severity='high',  # or 'medium', 'low'
    priority='high',  # or 'medium', 'low'
    # ... other fields
)
```

## 🧹 Cleanup

Delete test data after testing:

```bash
python manage.py shell
```

```python
# Delete test complaints
from apps.complaints.models import Complaint, ComplaintExplanation
Complaint.objects.filter(contact_name="Test Patient").delete()
Complaint.objects.filter(contact_name="Concerned Family Member").delete()

# Delete test staff
from apps.organizations.models import Staff
Staff.objects.filter(email__contains=".test").delete()

# Delete SLA configs
from apps.complaints.models import ExplanationSLAConfig, ComplaintSLAConfig, SecondReminderConfig
ExplanationSLAConfig.objects.all().delete()
ComplaintSLAConfig.objects.all().delete()
SecondReminderConfig.objects.all().delete()
```

## 🐛 Debugging

### Enable Django Debug Mode

```python
# In config/settings/dev.py
DEBUG = True
```

### Check Celery Tasks

```bash
# Check if Celery worker is running
ps aux | grep celery

# Start Celery worker
celery -A config worker -l info
```

### View Email Content

Use console email backend for testing:

```bash
# In .env
EMAIL_BACKEND=django.core.mail.backends.console.EmailBackend
```

## 📚 Documentation

- **[SLA_TESTING_QUICKSTART.md](SLA_TESTING_QUICKSTART.md)** - Get started in 5 minutes
- **[REAL_TIME_SLA_TESTING_GUIDE.md](REAL_TIME_SLA_TESTING_GUIDE.md)** - Complete guide with detailed scenarios
- **[SLA_SYSTEM_OVERVIEW.md](SLA_SYSTEM_OVERVIEW.md)** - SLA system architecture
- **[apps/complaints/models.py](../apps/complaints/models.py)** - Complaint and explanation models
- **[apps/complaints/tasks.py](../apps/complaints/tasks.py)** - Celery tasks for SLA processing

## ✅ Test Checklist

Before running tests:

- [ ] Django is properly configured
- [ ] Database is accessible and migrated
- [ ] Email service is configured (or use console backend)
- [ ] Celery worker is running (for background tasks)

After running tests:

- [ ] Verify all steps passed
- [ ] Check results in Django admin
- [ ] Review email output
- [ ] Verify SLA configurations
- [ ] Clean up test data if needed

## 🎓 Use Cases

### Development Testing
- Test SLA logic during development
- Verify reminder timing
- Test escalation chains
- Debug SLA calculations

### CI/CD Integration
- Automated regression testing
- SLA configuration validation
- Workflow verification
- Performance testing

### Pre-Production Validation
- Test new SLA configurations
- Verify email templates
- Validate escalation rules
- Test staff hierarchy changes

### Training and Demo
- Demonstrate SLA system
- Train staff on escalation process
- Show reminder workflow
- Explain escalation chain

## 🔗 Related Features

- **Complaint System**: Full complaint lifecycle management
- **Staff Hierarchy**: Multi-level management structure
- **Email Notifications**: Automated reminder and escalation emails
- **Celery Tasks**: Background job processing for SLA enforcement
- **Admin Interface**: Configure and monitor SLA settings

## 📈 Performance

- **Scenario 1**: ~7 seconds execution time
- **Scenario 2**: ~37 seconds execution time
- **Total test time**: ~45 seconds for both scenarios
- **Time compression**: 1 second = 1 hour (configurable)

## 🤝 Contributing

When adding new scenarios:

1. Extend `ScenarioTestBase`
2. Follow the step-by-step pattern
3. Include time compression
4. Verify database state at each step
5. Document expected results
6. Update this README

## 📞 Support

For issues or questions:

1. Check the documentation in `docs/` directory
2. Review Celery task logs
3. Check Django admin for verification
4. Examine email output
5. Review SLA configuration

---

**Ready to test? Start here:** [SLA_TESTING_QUICKSTART.md](SLA_TESTING_QUICKSTART.md)