# Manual de Calidad, Testing y Automatización — Radar GovTech

Este documento especifica la estrategia de aseguramiento de calidad, la arquitectura de pruebas en dos capas y el desglose exhaustivo de la suite automatizada de **Radar** ([licitacion.co](https://licitacion.co)).

---

## 1. Filosofía de Calidad y Principios de Testing

La plataforma se rige por tres principios innegociables:
1. **Cero Dependencias de Terceros en Pruebas:** El ejecutor [`test_runner.py`](file:///c:/Users/Darg/Documents/Volrisk/Herramientas/Radar/test_runner.py) utiliza única y exclusivamente la biblioteca estándar de Python 3 (`os`, `sys`, `json`, `re`, `subprocess`, `tempfile`, `struct`, `shutil`, `html.parser`). No requiere `pip install`, eliminando cualquier riesgo de incompatibilidad o vulnerabilidad en la cadena de suministro.
2. **Velocidad Extrema de Verificación:** La suite completa de **394 pruebas** se ejecuta en menos de **4 segundos** (promedio: 3.7s en Windows/Linux), permitiendo validaciones continuas sin fricción para el desarrollador.
3. **Pruebas en Motor Real de Navegador:** Además de análisis estático y lógico, la suite ejecuta Chromium / Microsoft Edge en modo *Headless*, validando la reactividad real del DOM, la ejecución de JavaScript en el motor V8 y la persistencia en `localStorage`.

---

## 2. Arquitectura de Pruebas en Dos Capas (Híbrida)

Para conciliar la protección contra roturas de código con el control total de costos en la nube, Radar implementa un modelo de validación escalonado:

```mermaid
flowchart TD
    Desarrollo["Cambios en Código (index.html)"] --> GitCommit["git commit"]
    GitCommit --> GitPush["git push origin main"]
    
    subgraph Capa1["Capa 1: Guardia Local (Git Hook pre-push)"]
        Hook[".githooks/pre-push"]
        RunnerLocal["test_runner.py (394 Pruebas en ~3.8s)"]
        Hook --> RunnerLocal
    end
    
    GitPush --> Capa1
    RunnerLocal -- "Si alguna prueba falla" --> BloqueoLocal["Push Cancelado Inmediatamente (Costo $0)"]
    RunnerLocal -- "394/394 Aprobadas (100% OK)" --> GitHub["Envío a Servidores de GitHub"]
    
    subgraph Capa2["Capa 2: Nube (GitHub Actions CI)"]
        Workflow[".github/workflows/ci.yml"]
        UbuntuRunner["Ubuntu Latest + Chromium Headless"]
        Badge["Badge de CI Verde en Repositorio"]
        Workflow --> UbuntuRunner --> Badge
    end
    
    GitHub --> Capa2
```

### Capa 1: Guardia Local (`.githooks/pre-push`)
* **Activación en el repositorio:** `git config core.hooksPath .githooks`
* **Mecanismo:** Intercepta el comando `git push` de manera transparente.
* **Costo:** **\$0.00** permanente. Funciona completamente offline y en cualquier estación de trabajo.
* **Beneficio:** Si se introduce un error de sintaxis, una violación tipográfica o una rotura funcional, el push se cancela en 3 segundos sin gastar un solo minuto de GitHub Actions ni exponer código roto al repositorio remoto.

### Capa 2: Integración Continua en la Nube (GitHub Actions)
* **Archivo de flujo:** [`.github/workflows/ci.yml`](file:///c:/Users/Darg/Documents/Volrisk/Herramientas/Radar/.github/workflows/ci.yml)
* **Entorno:** `ubuntu-latest` con Python 3.11 y Google Chrome / Chromium headless.
* **Disparadores:** Cada `push` o `pull request` hacia la rama `main`.
* **Resiliencia Financiera:** Si los minutos gratuitos mensuales de la cuenta de GitHub se agotan, la Capa 1 local sigue salvaguardando la calidad del proyecto con la misma rigurosidad.

---

## 3. Desglose de los 394 Casos de Prueba

La suite se divide en 8 módulos especializados de verificación:

### Módulo 1: Integridad Estática y Estructura DOM
* Balance estricto de etiquetas HTML5 (apertura y cierre de contenedores, tablas, modales).
* Unicidad de atributos `id` en todo el documento para prevenir colisiones en selectores.
* Verificación estricta de ausencia de la clase CSS `uppercase` en componentes interactivos, títulos y etiquetas.
* Comprobación de metadatos SEO, viewport móvil y enlace al manifiesto PWA.

### Módulo 2: Simulador Financiero y Deducciones Estatales
* Verificación matemática del cálculo de margen neto e impuestos colombianos.
* Independencia de las deducciones estatales (estampillas, ReteFuente, ICA) ante variaciones del margen operativo.
* Validación del simulador en modo **AIU**:
  * Comprobación en V8 del cálculo paramétrico ($A=18\%$, $I=2\%$, $U=5\%$).
  * Liquidación estricta del IVA (19%) aplicado únicamente a la Utilidad ($U$), verificando que no se grave indebidamente la Administración o los Imprevistos.
* Resiliencia ante convocatorias de cuantía indeterminada ($0 COP).

### Módulo 3: Motor Analítico de Actores
* Detección automática del rol del proponente frente a la entidad compradora (ej. *Divri* o *Invías* como compradoras vs. consultores o contratistas como proveedores).
* Cálculo de indicadores de concentración de compras y listado de contrapartes habituales.

### Módulo 4: Diccionario de Estados Contractuales
* Cobertura de definiciones y glosario legal para la totalidad de estados de Secop:
  * *Borrador*, *Convocado*, *Seleccionado*, *Celebrado*, *En ejecución*, *Liquidado*, *Terminado*, *Desierto*.
* Verificación del badge visual de estado asignado a cada expediente.

### Módulo 5: Módulo de Compartir, Enlaces Permanentes y Calendario
* Sanitización de cadenas y generación de slugs semánticos legibles.
* Formateo de mensajes optimizados para difusión ejecutiva en WhatsApp, Telegram y correo electrónico.
* Exportación estructurada a formato CSV.
* Generación de eventos de calendario (.ics y Google Calendar) con el prefijo institucional `[vía licitacion.co]`.

### Módulo 6: Zona de Usuario, Perfil de Proponente & Alertas a la Medida
* Persistencia y recuperación del perfil de empresa proponente en `localStorage`.
* Gestión reactiva de códigos RUP, palabras clave de interés y términos excluidos.
* Watchlist de entidades vigiladas con soporte de filtrado por umbral de actividad (10+ o 5+ convocatorias activas).
* Generación de feeds RSS unificados para entidades bajo seguimiento.

### Módulo 6b: Checklist Pre-Vuelo, Comparador Cara a Cara & Termómetro de Urgencia
* Inicialización obligatoria de los 6 requisitos habilitantes de la legislación contractual colombiana.
* Reactividad en la adición y eliminación de requisitos específicos del pliego.
* Gestión de la bandeja comparadora multi-proceso (límite estricto de hasta 3 licitaciones concurrentes).
* Clasificación algorítmica en el termómetro de urgencia: cubeta crítica (<48h con alerta de pulso visual), cubeta semana (<7d) y normal (>7d).

### Módulo 6c: PWA Manifest, A11y, Enlaces Seguros & Freemium Gate
* Validación de atributos de seguridad en enlaces salientes (`rel="noopener noreferrer"`).
* Accesibilidad web: foco accesible, navegación por teclado (`Escape`, `Enter`, `/`, `Ctrl+K`), y trampas de foco en modales (`trapModalFocus`).
* Control Freemium:
  * Intercepción de la acción "Guardar en Seguimiento" para usuarios invitados, desplegando la pantalla modal de registro.
  * Renderizado adaptativo de la pestaña de seguimiento para usuarios no autenticados, ofreciendo invitación clara y beneficios de registro.
* Auto-Sonar: Verificación de frecuencias simplificadas en el menú desplegable (10 min, 15 min, 30 min, 1 hora, pausar, sin repeticiones de la palabra "Cada").

### Módulo 7: Pruebas de Integración en Navegador Real (Chromium Headless)
* Carga de `index.html` en Microsoft Edge / Chromium headless sin emitir una sola advertencia o excepción en consola (`window.onerror = 0`).
* Prueba de interoperabilidad de `localStorage` con lectura y escritura de objetos complejos.
* Renderizado reactivo de tarjetas, apertura y cierre de modales de pantalla completa.

---

## 4. Regla Tipográfica Permanente (Cero Mayúsculas Sostenidas)

El proyecto cuenta con una regla tipográfica obligatoria implementada para garantizar sobriedad y legibilidad institucional:
* **Prohibición de altas sostenidas:** Prohibido el uso de mayúsculas sostenidas en cualquier texto de interfaz de 4 o más letras.
* **Siglas de 4+ letras:** Deben formatearse obligatoriamente con inicial mayúscula y el resto en minúsculas (ej. `Secop`, `Secop I`, `Secop II`, `Invías`, `Unspsc`, `Icbf`, `Sena`, `Eaab`, `Dane`, `Dian`, `Cenit`, `Findeter`, `Jaggaer`, `Ungm`, `Pnud`, `Unicef`, `Acnur`, `Pador`, `Sedia`, `Idiger`, `Divri`, `Soda`).
* **Siglas de 3 letras o menos:** Se mantienen en mayúsculas sostenidas (ej. `RUP`, `NIT`, `IDU`, `EPM`, `ANI`, `CPS`, `IVA`, `ICA`, `TI`, `IA`, `PDF`, `CSV`, `RSS`, `API`, `COP`, `VIP`, `OEI`, `CAF`, `FAO`, `ONU`).
* **Validación en el Test Runner:** La suite analiza automáticamente los textos de títulos, botones, modales y etiquetas para asegurar que ninguna sigla de 4+ letras esté en mayúsculas sostenidas, garantizando cero regresiones.

---

## 5. Instrucciones de Ejecución

### Ejecución de la Suite Completa (Modo Rápido)
```bash
python test_runner.py
```

### Ejecución con Diagnóstico de APIs Socrata en Vivo
Para verificar en tiempo real la latencia y disponibilidad de los endpoints de datos abiertos de Secop I y Secop II en Colombia:
```bash
python test_runner.py --live
```

### Ejemplo de Salida Exitosa
```text
=================================================================
RESUMEN DE PRUEBAS AUTOMATIZADAS — RADAR GOVTECH
=================================================================
Total de pruebas ejecutadas: 394
Pruebas exitosas:          394
Pruebas fallidas:          0
Tiempo total:              3.82 segundos

🎉 TODAS LAS PRUEBAS PASARON EXITOSAMENTE (100% OK)
```