===========================================
GUÍA - TAG @no_browser
Framework Hakalab - Pruebas sin Navegador
===========================================

¿QUÉ ES EL TAG @no_browser?
============================

El tag `@no_browser` es una etiqueta especial que desactiva la inicialización del navegador
para escenarios que no lo necesitan, como:
- Pruebas de API
- Validación semántica
- Testing con Gemini como Juez
- Pruebas de base de datos
- Validación de archivos

¿POR QUÉ USAR EL TAG?
======================

PROBLEMA SIN EL TAG:
- El hook `before_scenario` siempre intenta inicializar el navegador
- Si usas el step `desactivo el navegador`, el navegador ya se intentó crear
- Al final del escenario, intenta cerrar un navegador que no se abrió correctamente
- Resultado: Error "Browser.new_context: Target page, context or browser has been closed"

SOLUCIÓN CON EL TAG:
- El tag se detecta ANTES de que se ejecute cualquier step
- El navegador nunca se inicializa
- No hay errores de cierre de navegador
- Ejecución más rápida (no hay overhead de Playwright)

CÓMO USAR EL TAG
================

Sintaxis:
---------
@no_browser
Scenario: Nombre del escenario
  Given ...
  When ...
  Then ...

Ejemplo Básico:
---------------
@no_browser
Scenario: Validar respuesta con Gemini
  Given cargo el contexto de negocio "support" desde el archivo "context/support.txt"
  When establezco la respuesta del SUT como "Nuestro horario es de 9am a 6pm"
  Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.8

Ejemplo con API:
----------------
@no_browser
Scenario: Validar respuesta de API
  When realizo una petición GET a la URL "https://api.example.com/users/123"
  Then el código de respuesta debe ser 200
  And el campo "name" debe ser "Juan"

Ejemplo con Validación Semántica:
----------------------------------
@no_browser
Scenario: Validar similitud semántica
  Given uso la configuración semántica por defecto
  Then el texto "Compra exitosa" debe ser semánticamente similar a "Tu compra fue exitosa"

CASOS DE USO
============

1. TESTING DE IA GENERATIVA
----------------------------
@no_browser
Scenario: Validar respuesta de chatbot
  Given cargo el contexto de negocio "support" desde el archivo "context/support.txt"
  When establezco la respuesta del SUT como "Respuesta del chatbot"
  Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.8
  And valido que la respuesta del SUT está en idioma "español"
  And valido que la intención de la respuesta es "informativa"

2. TESTING DE API
-----------------
@no_browser
Scenario: Validar estructura JSON de API
  When realizo una petición POST a la URL "https://api.example.com/chat"
  And el cuerpo de la petición es:
    """
    {"message": "Hola"}
    """
  Then el código de respuesta debe ser 200
  And valido que la respuesta del SUT es un JSON válido
  And valido que el JSON de respuesta tiene la estructura "schemas/chat_response.json"

3. VALIDACIÓN SEMÁNTICA
-----------------------
@no_browser
Scenario: Validar similitud de textos
  Given uso la configuración semántica por defecto
  When calculo la similitud semántica entre "Texto 1" y "Texto 2" y la guardo en "similitud"
  Then el valor de la variable "similitud" debe ser mayor que 0.7

4. TESTING DE BASE DE DATOS
----------------------------
@no_browser
Scenario: Validar datos en base de datos
  Given me conecto a la base de datos "test_db"
  When ejecuto la consulta SQL "SELECT * FROM users WHERE id = 1"
  Then el resultado debe contener 1 fila
  And el campo "name" debe ser "Juan"

5. VALIDACIÓN DE ARCHIVOS
--------------------------
@no_browser
Scenario: Validar contenido de archivo
  Given cargo el contenido del archivo "data/test.json" en la variable "content"
  Then el valor de la variable "content" debe contener "expected_value"

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

Puedes combinar @no_browser con otros tags:

@no_browser @smoke
Scenario: Prueba rápida de API
  When realizo una petición GET a la URL "https://api.example.com/health"
  Then el código de respuesta debe ser 200

@no_browser @regression
Scenario: Validación completa de respuesta
  Given cargo el contexto de negocio "support" desde el archivo "context/support.txt"
  When establezco la respuesta del SUT como "Respuesta completa"
  Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.8

MIGRACIÓN DESDE EL STEP
========================

ANTES (usando step):
--------------------
Scenario: Validar respuesta
  Given desactivo el navegador para esta prueba  # ❌ Causa problemas
  When establezco la respuesta del SUT como "Respuesta"
  Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.8

DESPUÉS (usando tag):
---------------------
@no_browser  # ✅ Funciona correctamente
Scenario: Validar respuesta
  When establezco la respuesta del SUT como "Respuesta"
  Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.8

VENTAJAS DEL TAG
================

1. ✅ Ejecución más rápida (no hay overhead de Playwright)
2. ✅ No hay errores de cierre de navegador
3. ✅ Código más limpio (no necesitas el step de desactivar)
4. ✅ Se detecta antes de ejecutar cualquier step
5. ✅ Funciona con todos los tipos de pruebas sin navegador

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

Problema: "Browser.new_context: Target page, context or browser has been closed"
Solución: Usa el tag @no_browser en lugar del step "desactivo el navegador"

Problema: El navegador se abre aunque use @no_browser
Solución: Verifica que tu environment.py esté actualizado con el template más reciente

Problema: ¿Puedo usar @no_browser en un Background?
Solución: No, los tags se aplican a nivel de Scenario. Usa el tag en cada escenario.

EJEMPLOS COMPLETOS
==================

Ver archivos de ejemplo:
- hakalab_framework/examples/gemini_advanced_testing_example.feature
- hakalab_framework/examples/gemini_api_integration_example.feature
- hakalab_framework/examples/semantic_validation_example.feature
- hakalab_framework/examples/semantic_nlp_example.feature

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

1. El tag @no_browser NO es necesario si tu escenario usa el navegador
2. Solo usa el tag en escenarios que NO necesitan navegador
3. El step "desactivo el navegador" sigue funcionando pero se recomienda usar el tag
4. El tag se detecta automáticamente en el hook before_scenario

RESUMEN
=======

✅ USA @no_browser cuando:
- Pruebas de API
- Validación con Gemini
- Validación semántica
- Pruebas de base de datos
- Validación de archivos
- Cualquier prueba que NO necesite navegador

❌ NO uses @no_browser cuando:
- Necesitas interactuar con una página web
- Necesitas hacer click en elementos
- Necesitas navegar a URLs
- Necesitas capturar screenshots
- Cualquier prueba que SÍ necesite navegador
