template-saas/orchestration/_archive/planes/PLAN-SPRINT-1-TESTS.md

PLAN SPRINT 1 - Test Coverage

Proyecto: template-saas Sprint: 1 Objetivo: Subir cobertura de tests de 62.56% a 80% Fecha Inicio: 2026-01-10 SP Total: 8

---

RESUMEN EJECUTIVO

Estado Actual

• Cobertura actual: 62.56%
• Tests actuales: 387 tests en 24 suites
• Objetivo: 80% cobertura

Gap a Cerrar

• Delta requerido: +17.44% de cobertura
• Tests estimados adicionales: ~80-100 tests nuevos

---

TAREAS DEL SPRINT

TST-001: Tests Auth Module Adicionales

Agente: Backend-Agent SP: 2 Dependencia: Ninguna Paralelo con: TST-002

Archivos a Leer

archivos:
  - apps/backend/src/modules/auth/services/auth.service.ts
  - apps/backend/src/modules/auth/services/token.service.ts
  - apps/backend/src/modules/auth/services/oauth.service.ts
  - apps/backend/src/modules/auth/__tests__/auth.service.spec.ts

Entregables

entregables:
  - apps/backend/src/modules/auth/__tests__/token.service.spec.ts
  - apps/backend/src/modules/auth/__tests__/oauth.service.spec.ts
  - apps/backend/src/modules/auth/__tests__/mfa.service.spec.ts

Casos de Test a Implementar

token.service.spec.ts:

• generateAccessToken - genera token valido
• generateAccessToken - incluye tenant_id en claims
• generateRefreshToken - genera token de refresh
• validateToken - valida token correcto
• validateToken - rechaza token expirado
• validateToken - rechaza token malformado
• revokeToken - revoca token existente
• revokeAllUserTokens - revoca todos los tokens de usuario

oauth.service.spec.ts:

• getOAuthUrl - genera URL para Google
• getOAuthUrl - genera URL para GitHub
• getOAuthUrl - genera URL para Microsoft
• handleCallback - procesa callback exitoso
• handleCallback - maneja error de proveedor
• linkAccount - vincula cuenta OAuth a usuario existente
• unlinkAccount - desvincula cuenta OAuth

mfa.service.spec.ts:

• generateSecret - genera secreto TOTP
• verifyCode - valida codigo correcto
• verifyCode - rechaza codigo incorrecto
• enableMfa - activa MFA para usuario
• disableMfa - desactiva MFA
• generateBackupCodes - genera codigos de respaldo

Criterios de Aceptacion

• Todos los tests pasan
• Cobertura del modulo auth >= 85%
• No hay tests flaky
• Mocks correctamente implementados

---

TST-002: Tests Billing Edge Cases

Agente: Backend-Agent SP: 2 Dependencia: Ninguna Paralelo con: TST-001

Archivos a Leer

archivos:
  - apps/backend/src/modules/billing/services/billing.service.ts
  - apps/backend/src/modules/billing/services/subscription.service.ts
  - apps/backend/src/modules/billing/services/stripe.service.ts
  - apps/backend/src/modules/billing/__tests__/

Entregables

entregables:
  - apps/backend/src/modules/billing/__tests__/subscription.service.spec.ts (ampliar)
  - apps/backend/src/modules/billing/__tests__/stripe-webhooks.spec.ts
  - apps/backend/src/modules/billing/__tests__/invoice.service.spec.ts

Casos de Test a Implementar

subscription.service.spec.ts (adicionales):

• createSubscription - con periodo trial
• createSubscription - sin metodo de pago (trial only)
• upgradeSubscription - prorratea correctamente
• downgradeSubscription - aplica al siguiente ciclo
• cancelSubscription - cancela inmediatamente
• cancelSubscription - cancela al fin de periodo
• reactivateSubscription - reactiva suscripcion cancelada
• handlePaymentFailure - suspende tras N intentos

stripe-webhooks.spec.ts:

• handleWebhook - valida firma correcta
• handleWebhook - rechaza firma invalida
• customer.subscription.updated - actualiza BD
• customer.subscription.deleted - marca cancelado
• invoice.paid - registra pago
• invoice.payment_failed - notifica admin
• checkout.session.completed - activa tenant

invoice.service.spec.ts:

• generateInvoice - crea invoice con items
• markAsPaid - actualiza estado
• sendInvoiceEmail - envia por email
• getInvoicePdf - genera PDF

Criterios de Aceptacion

• Todos los tests pasan
• Cobertura del modulo billing >= 85%
• Webhooks testeados con payloads reales
• Edge cases de suscripcion cubiertos

---

TST-003: Tests Notifications Queue

Agente: Backend-Agent SP: 2 Dependencia: Ninguna Paralelo con: TST-004

Archivos a Leer

archivos:
  - apps/backend/src/modules/notifications/services/notification-queue.service.ts
  - apps/backend/src/modules/notifications/services/push-notification.service.ts
  - apps/backend/src/modules/notifications/gateways/notifications.gateway.ts
  - apps/backend/src/modules/notifications/__tests__/

Entregables

entregables:
  - apps/backend/src/modules/notifications/__tests__/notification-queue.service.spec.ts
  - apps/backend/src/modules/notifications/__tests__/notifications.gateway.spec.ts
  - apps/backend/src/modules/notifications/__tests__/push-notification.service.spec.ts (ampliar)

Casos de Test a Implementar

notification-queue.service.spec.ts:

• enqueue - agrega a la cola correctamente
• enqueue - respeta prioridades
• process - procesa item de cola
• process - reintenta en fallo
• process - marca como fallido tras max retries
• getQueueStats - retorna estadisticas
• clearOldItems - limpia items procesados

notifications.gateway.spec.ts:

• handleConnection - registra cliente
• handleDisconnect - remueve cliente
• sendToUser - envia a usuario especifico
• sendToTenant - broadcast a tenant
• sendToRoom - envia a room especifica
• handleAcknowledgement - marca como leida

push-notification.service.spec.ts (adicionales):

• sendPush - envia a dispositivo valido
• sendPush - maneja dispositivo invalido
• sendBulk - envia a multiples dispositivos
• registerDevice - registra nuevo dispositivo
• unregisterDevice - remueve dispositivo

Criterios de Aceptacion

• Todos los tests pasan
• Cola BullMQ mockeada correctamente
• WebSocket gateway testeado
• Push notifications con VAPID testeadas

---

TST-004: Tests Storage Upload/Download

Agente: Backend-Agent SP: 2 Dependencia: Ninguna Paralelo con: TST-003

Archivos a Leer

archivos:
  - apps/backend/src/modules/storage/services/storage.service.ts
  - apps/backend/src/modules/storage/services/s3.service.ts
  - apps/backend/src/modules/storage/__tests__/

Entregables

entregables:
  - apps/backend/src/modules/storage/__tests__/storage.service.spec.ts (ampliar)
  - apps/backend/src/modules/storage/__tests__/s3.service.spec.ts
  - apps/backend/src/modules/storage/__tests__/storage.controller.spec.ts

Casos de Test a Implementar

storage.service.spec.ts (adicionales):

• uploadFile - sube archivo correctamente
• uploadFile - valida tipo de archivo
• uploadFile - valida tamano maximo
• uploadFile - respeta cuota de tenant
• downloadFile - descarga archivo existente
• downloadFile - error si no existe
• deleteFile - elimina archivo
• deleteFile - actualiza cuota usada
• getSignedUrl - genera URL firmada
• getSignedUrl - expira correctamente

s3.service.spec.ts:

• putObject - sube a S3
• getObject - descarga de S3
• deleteObject - elimina de S3
• getPresignedUrl - genera URL para upload
• getPresignedDownloadUrl - genera URL para download
• copyObject - copia entre buckets
• listObjects - lista objetos con prefijo

storage.controller.spec.ts:

• POST /upload - inicia upload
• POST /complete - completa upload multipart
• GET /:id - descarga archivo
• DELETE /:id - elimina archivo
• GET /usage - retorna uso de cuota

Criterios de Aceptacion

• Todos los tests pasan
• S3 mockeado con aws-sdk-mock
• Validaciones de archivo testeadas
• Cuotas de storage validadas

---

EJECUCION DEL SPRINT

Orden de Ejecucion

Dia 1-2:
  ├── TST-001 (Backend-Agent #1)  ──► Paralelo
  └── TST-002 (Backend-Agent #2)  ──► Paralelo

Dia 3-4:
  ├── TST-003 (Backend-Agent #1)  ──► Paralelo
  └── TST-004 (Backend-Agent #2)  ──► Paralelo

Dia 5:
  └── Validacion y merge (QA-Agent)

Comandos de Validacion

# Ejecutar todos los tests
cd apps/backend && npm run test

# Coverage report
cd apps/backend && npm run test:cov

# Tests especificos por modulo
cd apps/backend && npm run test -- --testPathPattern=auth
cd apps/backend && npm run test -- --testPathPattern=billing
cd apps/backend && npm run test -- --testPathPattern=notifications
cd apps/backend && npm run test -- --testPathPattern=storage

Metricas de Exito

Metrica	Antes	Objetivo
Total tests	387	~470
Test suites	24	~30
Coverage	62.56%	80%
Auth coverage	~70%	85%
Billing coverage	~65%	85%
Notifications coverage	~60%	85%
Storage coverage	~55%	85%

---

ACTUALIZACIONES POST-SPRINT

Inventarios a Actualizar

• orchestration/inventarios/BACKEND_INVENTORY.yml - tests count
• orchestration/PROJECT-STATUS.md - coverage metrics
• orchestration/PROXIMA-ACCION.md - siguiente sprint

Documentacion a Actualizar

• README.md - badge de coverage
• docs/02-devops/TESTING-GUIDE.md - nuevos patrones

---

REFERENCIAS

• orchestration/analisis/ANALISIS-MAESTRO-TEMPLATE-SAAS.md
• apps/backend/jest.config.js
• apps/backend/package.json (scripts de test)

---

Creado: 2026-01-10 Sprint: 1 de 5 Estado: COMPLETADO

---

REPORTE DE EJECUCION

Fecha Finalizacion: 2026-01-10

Resultados

Metrica	Objetivo	Resultado
Cobertura Total	80%	76.37%
Tests Nuevos	~80	+323
Tests Totales	~470	710
Test Suites	~30	31

Cobertura por Modulo (Sprint 1)

Modulo	Objetivo	Resultado
auth.service.ts	85%	100%
billing.service.ts	85%	100%
stripe.service.ts	85%	97.02%
notification-queue.service.ts	85%	98.52%
storage.service.ts	85%	95.9%
s3.provider.ts	85%	100%

Observaciones

1. Meta casi alcanzada: Cobertura de 76.37% vs objetivo de 80% (gap: 3.63%)
2. Servicios principales cubiertos: Todos los servicios core tienen cobertura >= 95%
3. Controladores pendientes: La cobertura faltante esta principalmente en controladores (stripe.controller, stripe-webhook.controller, devices.controller)
4. Dependencias faltantes: El modulo notifications tiene dependencias npm no instaladas (@nestjs/websockets, socket.io, web-push) que causan warnings en el coverage report pero los tests funcionan

Proximos Pasos

• Continuar con Sprint 2 (Onboarding Wizard) o
• Agregar tests adicionales para controladores si se requiere alcanzar 80% exacto