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:

# 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:

# 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:

# 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:

# 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:

# 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

# 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:

ssh -p 8022 android-dev@YOUR_ANDROID_IP

Test Termux API directly:

# 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

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

List Users

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:

# 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:

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

# 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

# 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

# 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

# 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:

#!/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 - Production deployment
• Security Setup - Security configuration
• Troubleshooting - Common issues and solutions