===========================================
GUÍA DE SOFT ASSERTIONS
Haka Playwright Engine v1.3.24
===========================================

DESCRIPCIÓN
-----------
Soft Assertions permite que las validaciones continúen ejecutándose incluso después
de un fallo, acumulando todos los errores para reportarlos al final del escenario.

Esto es útil para obtener reportes más completos y saber exactamente cuántas
validaciones fallaron en lugar de detenerse en la primera.

CASOS DE USO
------------
✅ Múltiples validaciones en un escenario
✅ Testing de formularios con varios campos
✅ Validación de múltiples elementos en una página
✅ Reportes más completos de fallos
✅ Reducir tiempo de debugging

===========================================
REQUISITOS
===========================================

PROYECTOS NUEVOS (v1.3.24+):
✅ Solo necesitas agregar el tag @soft_assertions
✅ Los templates de environment ya incluyen los hooks necesarios

PROYECTOS EXISTENTES (actualizando desde v1.3.23 o anterior):
⚠️ DEBES actualizar tu archivo environment.py

Opción 1 - Reemplazar environment.py completo:
1. Actualiza el framework: pip install --upgrade haka-playwright-engine
2. Copia el nuevo template desde hakalab_framework/templates/environment.py
3. Reemplaza tu features/environment.py

Opción 2 - Agregar solo los hooks necesarios:
1. Actualiza el framework: pip install --upgrade haka-playwright-engine
2. Agrega estas importaciones al inicio de tu environment.py:

```python
from hakalab_framework.core.soft_assertion_hooks import (
    before_scenario_soft_assertions,
    after_step_soft_assertions,
    after_scenario_soft_assertions
)
```

3. Modifica tu función before_scenario para agregar:

```python
def before_scenario(context, scenario):
    # ... tu código existente ...
    
    # Agregar esta línea al final
    before_scenario_soft_assertions(context, scenario)
```

4. Modifica tu función after_step para agregar AL INICIO:

```python
def after_step(context, step):
    # Agregar esta línea AL INICIO (antes de screenshots)
    after_step_soft_assertions(context, step)
    
    # ... tu código existente de screenshots ...
```

5. Modifica tu función after_scenario para agregar AL INICIO:

```python
def after_scenario(context, scenario):
    # Agregar estas líneas AL INICIO
    try:
        after_scenario_soft_assertions(context, scenario)
    except AssertionError:
        pass
    
    # ... tu código existente ...
```

===========================================
USO BÁSICO
===========================================

PASO 1: Agregar el tag @soft_assertions al escenario
-----------------------------------------------------

Archivo: features/login.feature

```gherkin
@soft_assertions
Scenario: Validar múltiples campos del formulario
  Given navego a "https://example.com/login"
  Then verifico que el elemento "username_field" está visible
  And verifico que el elemento "password_field" está visible
  And verifico que el elemento "submit_button" está visible
  And verifico que el elemento "forgot_password_link" está visible
```

COMPORTAMIENTO:
- Si "username_field" no está visible → Captura el error y CONTINÚA
- Si "password_field" no está visible → Captura el error y CONTINÚA
- Si "submit_button" no está visible → Captura el error y CONTINÚA
- Si "forgot_password_link" no está visible → Captura el error y CONTINÚA
- Al final del escenario → Reporta TODOS los errores y marca como FAILED

SIN @soft_assertions:
- Si "username_field" no está visible → DETIENE el escenario inmediatamente
- Los demás steps NO se ejecutan

===========================================
EJEMPLO COMPLETO
===========================================

Archivo: features/product_validation.feature

```gherkin
@soft_assertions
Scenario: Validar información completa del producto
  Given navego a "https://shop.example.com/product/123"
  
  # Todas estas validaciones se ejecutarán incluso si alguna falla
  Then verifico que el texto del elemento "product_title" contiene "Laptop"
  And verifico que el texto del elemento "product_price" contiene "$999"
  And verifico que el elemento "add_to_cart_button" está visible
  And verifico que el elemento "product_image" está visible
  And verifico que el texto del elemento "stock_status" contiene "In Stock"
  And verifico que el elemento "reviews_section" está visible
  And verifico que el texto del elemento "rating" contiene "4.5"
```

SALIDA SI FALLAN 3 VALIDACIONES:

```
⚠️  SOFT ASSERTION FAILED: [Step 2] verifico que el texto del elemento "product_price" contiene "$999"
    Continuando con las siguientes validaciones...

⚠️  SOFT ASSERTION FAILED: [Step 5] verifico que el texto del elemento "stock_status" contiene "In Stock"
    Continuando con las siguientes validaciones...

⚠️  SOFT ASSERTION FAILED: [Step 7] verifico que el texto del elemento "rating" contiene "4.5"
    Continuando con las siguientes validaciones...

======================================================================
📊 RESUMEN DE SOFT ASSERTIONS
======================================================================
Total de validaciones fallidas: 3
======================================================================

======================================================================
ESCENARIO FALLIDO: 3 validación(es) fallaron
======================================================================

1. [Step 2] verifico que el texto del elemento "product_price" contiene "$999": Expected "$999" but got "$1099"

2. [Step 5] verifico que el texto del elemento "stock_status" contiene "In Stock": Element not found

3. [Step 7] verifico que el texto del elemento "rating" contiene "4.5": Expected "4.5" but got "4.2"

======================================================================
```

===========================================
VENTAJAS
===========================================

✅ REPORTES MÁS COMPLETOS
   Sabes exactamente cuántas validaciones fallaron, no solo la primera

✅ AHORRO DE TIEMPO
   No necesitas ejecutar el test múltiples veces para encontrar todos los errores

✅ MEJOR DEBUGGING
   Ves todos los problemas de una vez

✅ FÁCIL DE USAR
   Solo agrega el tag @soft_assertions

✅ COMPATIBLE
   Funciona con todos los steps de validación existentes

===========================================
CUÁNDO USAR
===========================================

USA @soft_assertions CUANDO:
✅ Tienes múltiples validaciones en un escenario
✅ Quieres un reporte completo de todos los fallos
✅ Estás validando formularios con muchos campos
✅ Estás validando múltiples elementos en una página
✅ Quieres reducir el tiempo de debugging

NO USES @soft_assertions CUANDO:
❌ Las validaciones dependen unas de otras
❌ Un fallo temprano hace que las siguientes no tengan sentido
❌ Quieres detener inmediatamente al primer error
❌ Estás haciendo acciones (clicks, fills) en lugar de validaciones

===========================================
EJEMPLO: VALIDACIÓN DE FORMULARIO
===========================================

```gherkin
@soft_assertions
Scenario: Validar campos requeridos del formulario de registro
  Given navego a "https://example.com/register"
  When hago click en el elemento "submit_button"
  
  # Validar que aparecen TODOS los mensajes de error
  Then verifico que el elemento "email_error" está visible
  And verifico que el texto del elemento "email_error" contiene "Email is required"
  And verifico que el elemento "password_error" está visible
  And verifico que el texto del elemento "password_error" contiene "Password is required"
  And verifico que el elemento "name_error" está visible
  And verifico que el texto del elemento "name_error" contiene "Name is required"
  And verifico que el elemento "phone_error" está visible
  And verifico que el texto del elemento "phone_error" contiene "Phone is required"
```

RESULTADO:
- Si faltan 2 de 4 mensajes de error, el reporte mostrará exactamente cuáles

===========================================
EJEMPLO: VALIDACIÓN DE TABLA
===========================================

```gherkin
@soft_assertions
Scenario: Validar datos de la tabla de productos
  Given navego a "https://example.com/products"
  
  # Validar múltiples filas de la tabla
  Then verifico que el texto de la celda en fila 1 columna "Name" contiene "Product A"
  And verifico que el texto de la celda en fila 1 columna "Price" contiene "$10"
  And verifico que el texto de la celda en fila 2 columna "Name" contiene "Product B"
  And verifico que el texto de la celda en fila 2 columna "Price" contiene "$20"
  And verifico que el texto de la celda en fila 3 columna "Name" contiene "Product C"
  And verifico que el texto de la celda en fila 3 columna "Price" contiene "$30"
```

===========================================
COMBINACIÓN CON OTROS TAGS
===========================================

Puedes combinar @soft_assertions con otros tags:

```gherkin
@smoke @soft_assertions
Scenario: Smoke test con validaciones múltiples
  ...

@regression @soft_assertions @no_browser
Scenario: Validación de API con múltiples checks
  ...
```

===========================================
NOTAS IMPORTANTES
===========================================

1. SOLO CAPTURA AssertionError
   - Solo los errores de validación (assert) se capturan
   - Otros errores (ElementNotFound, Timeout, etc.) detienen el escenario

2. EL ESCENARIO SIGUE MARCADO COMO FAILED
   - Aunque continúe ejecutándose, el escenario final será FAILED
   - Esto es correcto: queremos saber que hubo errores

3. ORDEN DE EJECUCIÓN
   - Los steps se ejecutan en orden secuencial
   - Si un step no es de validación, se ejecuta normalmente

4. SCREENSHOTS
   - Se capturan screenshots de todos los steps, incluso los que fallan

5. REPORTES HTML
   - Los reportes HTML mostrarán todos los errores capturados

===========================================
TROUBLESHOOTING
===========================================

PROBLEMA: El escenario se detiene en el primer error
SOLUCIÓN: Verifica que agregaste el tag @soft_assertions

PROBLEMA: No veo el resumen de errores
SOLUCIÓN: Verifica que tu environment.py incluye los hooks de soft assertions.
          Si actualizaste desde v1.3.23 o anterior, debes actualizar tu environment.py
          (ver sección REQUISITOS al inicio de esta guía)

PROBLEMA: Algunos errores no se capturan
SOLUCIÓN: Solo se capturan AssertionError. Otros errores detienen el escenario.

===========================================
CONFIGURACIÓN AVANZADA
===========================================

Si necesitas personalizar el comportamiento, puedes acceder al manager:

```python
# En un step personalizado
if context.soft_assertions.is_enabled():
    # Hacer algo especial cuando soft assertions está activo
    pass

# Obtener resumen de errores
summary = context.soft_assertions.get_summary()
print(f"Errores capturados: {summary['total_errors']}")
```

===========================================
RECURSOS
===========================================

- Código fuente: hakalab_framework/core/soft_assertions.py
- Hooks: hakalab_framework/core/soft_assertion_hooks.py
- Template: hakalab_framework/templates/environment.py
