plantillas-proyectos/docs/TESTING_GUIDE.md

Guía de Prueba Rápida - Anexo76

Esta guía te ayudará a probar todas las funcionalidades básicas de Anexo76 después de la instalación.

Prerrequisitos

✅ Haber ejecutado ./start.sh exitosamente
✅ Haber configurado Keycloak siguiendo docs/KEYCLOAK_SETUP.md
✅ Tener los servicios corriendo

Verificar Estado de Servicios

docker-compose ps

Deberías ver 4 servicios en estado "Up":

• postgres
• keycloak
• backend
• frontend

1. Probar Backend API

Health Check

curl http://localhost:8000/health

Respuesta esperada:

{
  "status": "healthy",
  "environment": "development"
}

Status de API

curl http://localhost:8000/v1/status

Respuesta esperada:

{
  "status": "ok",
  "version": "1.0.0",
  "api": "v1"
}

Documentación Interactiva

Abrir en navegador: http://localhost:8000/docs

Deberías ver la interfaz Swagger UI con todos los endpoints documentados.

2. Probar Autenticación con Keycloak

Obtener Token (vía API directa)

# Reemplaza YOUR_CLIENT_SECRET con el secret de Keycloak
curl -X POST http://localhost:8080/realms/master/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=anexo76-backend" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "username=demo" \
  -d "password=demo123" \
  -d "grant_type=password"

Respuesta esperada (fragmento):

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer"
}

Usar Token para Llamar API

# Guarda el access_token en una variable
TOKEN="tu-access-token-aqui"

# Llamar endpoint protegido
curl -X GET http://localhost:8000/v1/auth/me \
  -H "Authorization: Bearer $TOKEN"

Respuesta esperada:

{
  "sub": "a1b2c3d4-...",
  "email": "demo@empresa-demo.com",
  "name": "Usuario Demo",
  "preferred_username": "demo",
  "tenant_id": 1,
  "roles": ["user", "admin"]
}

3. Probar Módulo de Tenants

Listar Tenants (requiere rol admin)

curl -X GET http://localhost:8000/v1/tenants \
  -H "Authorization: Bearer $TOKEN"

Respuesta esperada:

{
  "tenants": [
    {
      "id": 1,
      "name": "Empresa Demo S.A. de C.V.",
      "slug": "empresa-demo",
      "type": "shared",
      "keycloak_realm": "master",
      "is_active": true,
      ...
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 50
}

Obtener Tenant por ID

curl -X GET http://localhost:8000/v1/tenants/1 \
  -H "Authorization: Bearer $TOKEN"

Obtener Tenant por Slug

curl -X GET http://localhost:8000/v1/tenants/slug/empresa-demo \
  -H "Authorization: Bearer $TOKEN"

4. Probar Módulo de Licencias

Obtener Mi Licencia

curl -X GET http://localhost:8000/v1/licenses/my-license \
  -H "Authorization: Bearer $TOKEN"

Respuesta esperada:

{
  "id": 1,
  "tenant_id": 1,
  "plan": "professional",
  "status": "active",
  "max_users": 50,
  "max_storage_gb": 100,
  "max_monthly_operations": 25000,
  "feature_api_access": true,
  "feature_advanced_reports": true,
  "feature_integrations": true,
  "feature_dedicated_support": false,
  "expires_at": "2026-10-17T...",
  ...
}

Validar Licencia

curl -X GET http://localhost:8000/v1/licenses/validate/1 \
  -H "Authorization: Bearer $TOKEN"

Respuesta esperada:

{
  "is_valid": true,
  "status": "active",
  "plan": "professional",
  "expires_at": "2026-10-17T...",
  "reason": null
}

Obtener Uso de Licencia

curl -X GET http://localhost:8000/v1/licenses/usage/1 \
  -H "Authorization: Bearer $TOKEN"

5. Probar Frontend

Abrir Aplicación

Abrir en navegador: http://localhost:5173

Probar Login

1. Click en botón "Iniciar Sesión"
2. Serás redirigido a Keycloak
3. Ingresar credenciales:
   • Usuario: demo
   • Password: demo123
4. Deberías ser redirigido de vuelta al dashboard

Verificar Dashboard

Después del login, deberías ver:

• ✅ Nombre y email del usuario
• ✅ Información de licencia (plan, estado, límites)
• ✅ Información de usuario (ID, roles, tenant ID)
• ✅ Botón "Cerrar Sesión"

Probar Logout

1. Click en "Cerrar Sesión"
2. Deberías volver a la pantalla de bienvenida

6. Pruebas de Middleware

Probar sin Token (debe fallar)

curl -X GET http://localhost:8000/v1/tenants/1

Respuesta esperada (error 401):

{
  "detail": "Missing or invalid authorization header"
}

Probar con Token Inválido (debe fallar)

curl -X GET http://localhost:8000/v1/tenants/1 \
  -H "Authorization: Bearer token-invalido"

Respuesta esperada (error 401):

{
  "detail": "Could not validate credentials"
}

Probar sin Tenant ID en Token (debe fallar)

Si el token no tiene tenant_id, debería recibir error 400:

{
  "detail": "Tenant ID not found in token"
}

7. Verificar Logs

Ver logs de todos los servicios

docker-compose logs -f

Ver logs solo del backend

docker-compose logs -f backend

Ver logs solo del frontend

docker-compose logs -f frontend

Ver logs de PostgreSQL

docker-compose logs -f postgres

8. Probar Base de Datos

Conectarse a PostgreSQL

docker-compose exec postgres psql -U postgres -d anexo76_core

Consultas útiles

-- Ver tenants
SELECT * FROM tenants;

-- Ver licencias
SELECT * FROM licenses;

-- Ver información de licencia con tenant
SELECT t.name, t.slug, l.plan, l.status, l.expires_at
FROM tenants t
JOIN licenses l ON l.tenant_id = t.id;

-- Salir
\q

9. Casos de Prueba Adicionales

Crear Nuevo Tenant (requiere rol admin)

curl -X POST http://localhost:8000/v1/tenants \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nueva Empresa S.A.",
    "slug": "nueva-empresa",
    "keycloak_realm": "master",
    "type": "shared",
    "contact_name": "Juan Pérez",
    "contact_email": "juan@nueva-empresa.com"
  }'

Actualizar Tenant

curl -X PUT http://localhost:8000/v1/tenants/1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_phone": "+52 55 9999 8888"
  }'

Crear Licencia para Tenant

curl -X POST http://localhost:8000/v1/licenses \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": 2,
    "plan": "basic",
    "max_users": 20,
    "max_storage_gb": 50,
    "max_monthly_operations": 10000,
    "starts_at": "2025-10-17T00:00:00Z",
    "expires_at": "2026-10-17T23:59:59Z"
  }'

Troubleshooting

Error: "Connection refused" al llamar API

• Verificar que el backend esté corriendo: docker-compose ps
• Ver logs: docker-compose logs backend
• Reiniciar: docker-compose restart backend

Error: "Tenant ID not found in token"

• Verificar que el usuario en Keycloak tenga el atributo tenant_id configurado
• Verificar que el mapper de Keycloak esté configurado correctamente

Frontend muestra "Cargando" indefinidamente

• Abrir consola del navegador (F12) y revisar errores
• Verificar que Keycloak esté accesible: http://localhost:8080
• Verificar configuración en frontend/.env

Base de datos vacía

• Ejecutar script de inicialización:

  docker-compose exec backend python init_db.py
  

Keycloak no responde

• Esperar unos minutos (puede tardar en iniciar)
• Ver logs: docker-compose logs keycloak
• Reiniciar: docker-compose restart keycloak

Limpiar y Reiniciar

Detener todo

docker-compose down

Detener y eliminar volúmenes (borra BD)

docker-compose down -v

Reiniciar desde cero

docker-compose down -v
./start.sh

Checklist de Verificación

• Backend responde en http://localhost:8000
• Frontend carga en http://localhost:5173
• Keycloak accesible en http://localhost:8080
• Documentación API visible en http://localhost:8000/docs
• Login funciona correctamente
• Dashboard muestra información de usuario
• Dashboard muestra información de licencia
• Logout funciona correctamente
• API responde a peticiones con token válido
• API rechaza peticiones sin token
• Base de datos tiene tenant y licencia de prueba

Próximos Pasos

Una vez que todas las pruebas pasen:

1. ✅ Revisar la documentación en docs/ARCHITECTURE.md
2. ✅ Explorar el código fuente de los módulos
3. ✅ Personalizar configuración según necesidades
4. ✅ Comenzar a desarrollar módulos adicionales
5. ✅ Configurar ambiente de producción

---

¿Problemas? Revisa los logs con docker-compose logs -f o abre un issue.

¡Todo funciona! 🎉 Estás listo para desarrollar sobre Anexo76.