=============================================================================
GUÍA DE REINTENTOS AUTOMÁTICOS DE ESCENARIOS FALLIDOS
=============================================================================

DESCRIPCIÓN
-----------
El framework soporta reintentos automáticos de escenarios que fallan durante
la ejecución. Esto es útil para manejar fallos intermitentes causados por:
- Problemas de red temporales
- Timeouts ocasionales
- Elementos que tardan en cargar
- Condiciones de carrera en la aplicación

CONFIGURACIÓN
-------------
Se controla mediante dos variables de entorno en el archivo .env:

1. RETRY_FAILED_SCENARIOS
   - Valores: true/false
   - Por defecto: false
   - Descripción: Habilita o deshabilita el sistema de reintentos

2. MAX_SCENARIO_RETRIES
   - Valores: 1-5 (recomendado)
   - Por defecto: 1
   - Descripción: Número máximo de veces que se reintentará un escenario fallido

EJEMPLO DE CONFIGURACIÓN
-------------------------
En tu archivo .env:

# Habilitar reintentos
RETRY_FAILED_SCENARIOS=true

# Reintentar hasta 2 veces
MAX_SCENARIO_RETRIES=2

CÓMO FUNCIONA
-------------
1. Un escenario se ejecuta normalmente
2. Si el escenario falla:
   a. El framework verifica si los reintentos están habilitados
   b. Verifica si aún quedan reintentos disponibles
   c. Si hay reintentos disponibles:
      - Limpia el estado del escenario
      - Cierra y crea una nueva página del navegador
      - Limpia las variables del escenario
      - Re-ejecuta el escenario completo
   d. Si el escenario pasa en el reintento:
      - Se marca como exitoso
      - Se muestra un mensaje indicando cuántos reintentos fueron necesarios
   e. Si el escenario falla después de todos los reintentos:
      - Se marca como fallido
      - Se muestra un mensaje indicando que se agotaron los reintentos

MENSAJES EN CONSOLA
--------------------
Durante la ejecución verás mensajes como:

🔄 Reintentando escenario fallido: Login con credenciales válidas
   Intento 1 de 2
✅ Escenario preparado para reintento

Si el escenario pasa después de reintentos:
✅ Escenario pasó después de 1 reintento(s): Login con credenciales válidas

Si el escenario falla después de todos los reintentos:
❌ Escenario falló después de 2 reintentos: Login con credenciales válidas

INTEGRACIÓN CON ENVIRONMENT.PY
-------------------------------
El template de environment.py ya incluye soporte para reintentos.
Solo necesitas asegurarte de que tu after_scenario llame a auto_after_scenario:

from hakalab_framework.core.environment_config import auto_after_scenario

def after_scenario(context, scenario):
    # ... tu código de screenshots ...
    
    # Ejecutar lógica de reintentos automáticos
    auto_after_scenario(context, scenario)
    
    # ... resto de tu código ...

EJEMPLO COMPLETO
----------------
Archivo: testing/.env
```
RETRY_FAILED_SCENARIOS=true
MAX_SCENARIO_RETRIES=2
```

Archivo: testing/features/environment.py
```python
from hakalab_framework import setup_framework_context, setup_scenario_context
from hakalab_framework.core.environment_config import auto_after_scenario
from hakalab_framework.core.screenshot_manager import take_screenshot_on_failure
from hakalab_framework.steps import *

def before_all(context):
    setup_framework_context(context)

def before_scenario(context, scenario):
    setup_scenario_context(context, scenario)

def after_scenario(context, scenario):
    take_screenshot_on_failure(context, scenario)
    auto_after_scenario(context, scenario)  # ← Sistema de reintentos
    
    if not getattr(scenario, '_retry_requested', False):
        if hasattr(context, 'page') and context.page:
            context.page.close()
            context.page = None

def after_all(context):
    if hasattr(context, 'framework_config'):
        context.framework_config.cleanup()
```

CASOS DE USO RECOMENDADOS
--------------------------
✅ USAR REINTENTOS PARA:
- Pruebas de integración con APIs externas
- Pruebas que dependen de servicios de terceros
- Pruebas con elementos dinámicos que tardan en cargar
- Pruebas en ambientes inestables (staging, QA)

❌ NO USAR REINTENTOS PARA:
- Ocultar bugs reales en la aplicación
- Pruebas unitarias o de componentes
- Pruebas con datos críticos que no deben repetirse
- Ambientes de producción donde los fallos deben ser evidentes

MEJORES PRÁCTICAS
-----------------
1. Usa un número bajo de reintentos (1-2 es suficiente)
2. Investiga los escenarios que necesitan reintentos frecuentemente
3. Considera aumentar los timeouts antes de usar reintentos
4. Monitorea cuántos escenarios necesitan reintentos
5. Si un escenario siempre necesita reintentos, probablemente hay un bug

LIMITACIONES
------------
- Los reintentos se aplican a nivel de escenario completo, no a steps individuales
- Cada reintento ejecuta el escenario desde el principio
- Las variables de entorno se mantienen entre reintentos
- Los archivos generados (screenshots, videos) se mantienen de todos los intentos

TROUBLESHOOTING
---------------
Problema: Los reintentos no funcionan
Solución: Verifica que RETRY_FAILED_SCENARIOS=true en tu .env

Problema: Los escenarios se reintentan demasiadas veces
Solución: Reduce MAX_SCENARIO_RETRIES a un valor más bajo (1-2)

Problema: Los reintentos causan problemas con la sesión del navegador
Solución: Asegúrate de que after_scenario cierra la página correctamente

Problema: Las variables no se limpian entre reintentos
Solución: Verifica que variable_manager.clear_scenario_variables() se llama

INTEGRACIÓN CON JIRA/XRAY
--------------------------
Los reintentos son compatibles con la integración de Jira/Xray:
- Solo se reporta el resultado final del escenario
- Si un escenario pasa después de reintentos, se reporta como exitoso
- Si un escenario falla después de todos los reintentos, se reporta como fallido
- Los comentarios en Jira incluyen información sobre los reintentos

EJEMPLO DE REPORTE
-------------------
Escenario: Login con credenciales válidas
Estado: Passed (después de 1 reintento)

Comentario en Jira:
"Escenario ejecutado exitosamente después de 1 reintento.
Reporte HTML adjunto: Reporte_PROJ-123_06022026_1530.html"

PREGUNTAS FRECUENTES
--------------------
P: ¿Los reintentos afectan el tiempo de ejecución?
R: Sí, cada reintento ejecuta el escenario completo, aumentando el tiempo total.

P: ¿Puedo tener diferentes configuraciones de reintentos por feature?
R: No, la configuración es global para toda la ejecución.

P: ¿Los reintentos funcionan con paralelización?
R: Sí, cada worker maneja sus propios reintentos independientemente.

P: ¿Puedo deshabilitar reintentos para escenarios específicos?
R: Actualmente no, pero puedes usar tags para filtrar qué escenarios ejecutar.

VERSIÓN
-------
Funcionalidad disponible desde: haka-playwright-engine v1.2.0+
Última actualización: Febrero 2026
