campaign_connector/docs/guides/testing.md

# Testing Guide

This guide covers testing procedures for SMS Campaign Manager, including verification of security configuration, service health, and end-to-end functionality.

## Prerequisites

Before testing:

- Docker container running on Ubuntu server
- Android device accessible via Tailscale or local network
- API keys configured in `.env` file
- Termux SMS API server running on Android

## Quick Health Check

Verify all services are operational:

```bash
# Test Ubuntu web application
curl http://localhost:5000/health

# Test Android Termux API
curl http://YOUR_ANDROID_IP:5001/health

# Both should return healthy status
```

## Security Verification

### Docker Container Security

Verify the container is properly isolated:

```bash
# Check privileged mode (should be false)
docker inspect sms-campaign-manager | grep -i "privileged"

# Check network mode (should NOT be "host")
docker inspect sms-campaign-manager | grep -i "networkmode"
```

Expected output:
```
"Privileged": false,
"NetworkMode": "bridge" (or "campaign_connector_default")
```

### API Authentication

Test that authentication is enforced:

```bash
# Should fail with 401 (no API key)
curl http://localhost:5000/api/campaign/list

# Should succeed (with valid API key)
curl -H "X-API-Key: YOUR_USER_API_KEY" http://localhost:5000/api/campaign/list
```

### Termux API Authentication

Test Android server authentication:

```bash
# Get API key from .env
API_KEY=$(grep "^TERMUX_API_KEY=" .env | cut -d'=' -f2)

# Test health endpoint
curl http://YOUR_ANDROID_IP:5001/health

# Test authenticated endpoint
curl -H "X-API-Key: $API_KEY" http://YOUR_ANDROID_IP:5001/api/device/battery

# Test with wrong key (should fail)
curl -H "X-API-Key: wrong_key" http://YOUR_ANDROID_IP:5001/api/device/battery
```

## Web Dashboard Testing

### Login Flow

1. Open browser: `http://localhost:5000/`
2. Should redirect to `/login`
3. Enter credentials:
   - Username: `admin`
   - Password: (from `.env` ADMIN_PASSWORD)
4. Should redirect to dashboard after login

### API Access

Test API endpoints with session authentication:

```bash
# Login via API
curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"YOUR_PASSWORD"}'

# Check auth status
curl http://localhost:5000/api/auth/status
```

## SMS Functionality Testing

### Test SMS Sending

```bash
# Test via API (replace with your number)
curl -X POST http://localhost:5000/api/sms/test/real \
  -H "X-API-Key: YOUR_USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"YOUR_PHONE_NUMBER","message":"Test from SMS Campaign Manager"}'
```

### Check Termux Permissions

SSH into Android device:

```bash
ssh -p 8022 android-dev@YOUR_ANDROID_IP
```

Test Termux API directly:

```bash
# List recent SMS (should work if permissions granted)
termux-sms-list -l 1
```

If this fails, grant SMS permissions:
1. Open Android Settings
2. Apps → Termux:API
3. Permissions → SMS → Allow

## User Management Testing

### Create Test User

```bash
python3 manage_users.py
# Select option 1 (Create new user)
# Enter: testuser / TestPass123! / Role: User
```

### List Users

```bash
python3 manage_users.py
# Select option 2 (List all users)
```

### Test Login with New User

1. Log out of current session
2. Log in as new user
3. Verify access to dashboard

## Container Logs

Monitor application behavior:

```bash
# View real-time logs
docker compose logs -f sms-campaign

# Filter for authentication events
docker compose logs sms-campaign | grep -i "auth"

# Filter for errors
docker compose logs sms-campaign | grep -i "error"
```

## Android Service Logs

Check Termux server logs:

```bash
ssh -p 8022 android-dev@YOUR_ANDROID_IP

# View SMS API logs
tail -f ~/logs/sms-api.log

# View monitoring logs
tail -f ~/logs/monitoring.log
```

## End-to-End Test Checklist

### Infrastructure

- [ ] Docker container running and healthy
- [ ] Container NOT in privileged mode
- [ ] Container NOT using host networking
- [ ] Android device reachable via SSH
- [ ] Termux API server running on Android

### Authentication

- [ ] API calls without key return 401
- [ ] API calls with valid key succeed
- [ ] Wrong API key returns authentication error
- [ ] Web login with username/password works
- [ ] Session persists across page loads

### SMS Functionality

- [ ] Termux health check returns healthy
- [ ] SMS permissions granted in Android settings
- [ ] Test SMS sends successfully
- [ ] SMS delivery confirmed on receiving device

### User Management

- [ ] Admin user exists and can login
- [ ] Can create new users via CLI
- [ ] User roles enforced correctly
- [ ] Password change works

## Troubleshooting Test Failures

### Container Won't Start

```bash
# Check logs for errors
docker compose logs sms-campaign

# Verify environment variables
docker compose exec sms-campaign env | grep -E "(API_KEY|SECRET_KEY)"

# Rebuild container
docker compose down
docker compose build --no-cache
docker compose up -d
```

### Can't Reach Android Device

```bash
# Check Tailscale status
tailscale status

# Ping device
ping YOUR_ANDROID_IP

# Test SSH connection
ssh -p 8022 android-dev@YOUR_ANDROID_IP "whoami"
```

### SMS Not Sending

```bash
# Check Termux server is running
ssh -p 8022 android-dev@YOUR_ANDROID_IP "pgrep -f termux-sms-api-server"

# View server logs
ssh -p 8022 android-dev@YOUR_ANDROID_IP "tail -20 ~/logs/sms-api.log"

# Check SMS_API_SECRET is set
ssh -p 8022 android-dev@YOUR_ANDROID_IP "echo \$SMS_API_SECRET"
```

### Authentication Errors in Logs

```bash
# Check API keys match
grep API_KEY .env
docker compose exec sms-campaign env | grep API_KEY

# Restart to reload configuration
docker compose restart
```

## Automated Test Script

Create a quick verification script:

```bash
#!/bin/bash
# test-all.sh

echo "Testing Ubuntu health..."
curl -s http://localhost:5000/health | grep -q "ok" && echo "PASS" || echo "FAIL"

echo "Testing Android health..."
curl -s http://YOUR_ANDROID_IP:5001/health | grep -q "healthy" && echo "PASS" || echo "FAIL"

echo "Testing auth enforcement..."
STATUS=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:5000/api/campaign/list)
[ "$STATUS" = "401" ] && echo "PASS" || echo "FAIL"

echo "Testing Docker security..."
docker inspect sms-campaign-manager | grep -q '"Privileged": false' && echo "PASS" || echo "FAIL"

echo "All tests complete"
```

## Related Documentation

- [Deployment Guide](../deployment/deployment-guide.md) - Production deployment
- [Security Setup](../security/security-setup.md) - Security configuration
- [Troubleshooting](troubleshooting.md) - Common issues and solutions