=============================================================================
GUÍA DE MODO STEALTH (ANTI-DETECCIÓN)
=============================================================================

DESCRIPCIÓN
-----------
El modo stealth oculta las propiedades que delatan que estás usando 
automatización con Playwright. Esto es útil para:
- Evitar detección de bots en sitios con protección anti-scraping
- Pruebas en sitios que bloquean herramientas de automatización
- Simular comportamiento de navegador real más fielmente

IMPORTANTE: Este modo debe usarse SOLO para pruebas legítimas en sitios
donde tienes permiso para realizar automatización.

¿QUÉ OCULTA EL MODO STEALTH?
-----------------------------
El modo stealth modifica las siguientes propiedades del navegador:

1. navigator.webdriver
   - Normal: true (delata automatización)
   - Stealth: undefined (como navegador real)

2. navigator.plugins
   - Normal: array vacío
   - Stealth: plugins simulados (PDF, Chrome PDF, etc.)

3. navigator.languages
   - Normal: puede estar vacío
   - Stealth: idiomas del sistema

4. window.chrome
   - Normal: puede no existir
   - Stealth: objeto chrome simulado

5. Permisos y características
   - Oculta características que solo existen en automatización
   - Simula permisos de navegador real

6. User-Agent
   - Mantiene consistencia entre headers y JavaScript

INSTALACIÓN
-----------
El paquete playwright-stealth se instala AUTOMÁTICAMENTE con el framework.

Si instalaste el framework con:
  pip install haka-playwright-engine
  
O con:
  pip install -r requirements.txt

Entonces playwright-stealth ya está instalado y listo para usar.

NOTA: No necesitas instalar nada adicional, solo activar el modo en .env

CONFIGURACIÓN
-------------
Se controla mediante una variable de entorno en el archivo .env:

STEALTH_MODE
- Valores: true/false
- Por defecto: false
- Descripción: Activa o desactiva el modo stealth

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

# Activar modo stealth
STEALTH_MODE=true

CÓMO FUNCIONA
-------------
1. Al crear una nueva página, el framework detecta si STEALTH_MODE=true
2. Si está activado, aplica automáticamente playwright-stealth a la página
3. Todas las propiedades de automatización se ocultan
4. La página se comporta como un navegador real

MENSAJES EN CONSOLA
--------------------
Cuando el modo stealth está activado verás:
🥷 Modo stealth activado - Propiedades de automatización ocultas

Si playwright-stealth no está instalado:
⚠️ playwright-stealth no está instalado. Ejecuta: pip install playwright-stealth

EJEMPLO COMPLETO
----------------
Archivo: testing/.env
```
# Activar modo stealth
STEALTH_MODE=true

# Configuración del navegador
BROWSER=chromium
HEADLESS=false
```

Archivo: testing/features/login.feature
```gherkin
Feature: Login con modo stealth

  Scenario: Login en sitio con protección anti-bot
    Given navego a "https://ejemplo.com/login"
    When relleno el campo "username" con "usuario"
    And relleno el campo "password" con "contraseña"
    And hago click en el botón "Iniciar sesión"
    Then debería ver el texto "Bienvenido"
```

El modo stealth se aplica automáticamente, no necesitas cambiar tus features.

CASOS DE USO RECOMENDADOS
--------------------------
✅ USAR MODO STEALTH PARA:
- Sitios con protección Cloudflare, DataDome, PerimeterX
- Sitios que detectan y bloquean Selenium/Playwright
- Pruebas en sitios con CAPTCHA que se activa por automatización
- Scraping legítimo de datos públicos
- Pruebas de seguridad autorizadas

❌ NO USAR MODO STEALTH PARA:
- Bypass de seguridad sin autorización
- Scraping ilegal o no autorizado
- Actividades maliciosas
- Violación de términos de servicio

LIMITACIONES
------------
1. No es 100% indetectable
   - Sitios sofisticados pueden detectar otros patrones
   - El comportamiento del mouse/teclado puede delatar automatización

2. Puede no funcionar con todas las protecciones
   - Algunas protecciones usan técnicas más avanzadas
   - Puede requerir configuración adicional

3. Rendimiento
   - Puede agregar un pequeño overhead al crear páginas
   - No afecta significativamente la velocidad de ejecución

MEJORES PRÁCTICAS
-----------------
1. Combinar con otras técnicas:
   - Usar SLOW_MO para simular velocidad humana
   - Agregar esperas aleatorias entre acciones
   - Variar patrones de interacción

2. Configurar User-Agent realista:
   BROWSER_USER_AGENT=Mozilla/5.0 (Windows NT 10.0; Win64; x64)...

3. Usar viewport de tamaño común:
   VIEWPORT_WIDTH=1920
   VIEWPORT_HEIGHT=1080

4. Evitar patrones obvios:
   - No hacer clicks demasiado rápidos
   - No llenar formularios instantáneamente
   - Simular movimientos de mouse naturales

VERIFICAR SI FUNCIONA
----------------------
Puedes verificar si el modo stealth está funcionando visitando:

1. https://bot.sannysoft.com/
   - Muestra qué propiedades delatan automatización
   - Con stealth: menos propiedades detectadas

2. https://arh.antoinevastel.com/bots/areyouheadless
   - Detecta navegadores headless
   - Con stealth: mejor puntuación

3. https://pixelscan.net/
   - Análisis completo de fingerprinting
   - Con stealth: perfil más realista

EJEMPLO DE VERIFICACIÓN
------------------------
Feature: Verificar modo stealth

  Scenario: Comprobar que stealth está activo
    Given navego a "https://bot.sannysoft.com/"
    Then debería ver el texto "User-Agent"
    # Verificar que navigator.webdriver no está presente
    When ejecuto JavaScript "return navigator.webdriver" y guardo el resultado en "webdriver"
    Then verifico que la variable "webdriver" es igual a "undefined"

TROUBLESHOOTING
---------------
Problema: El sitio sigue detectando automatización
Solución: 
- Verifica que STEALTH_MODE=true
- Combina con SLOW_MO para simular velocidad humana
- Usa User-Agent realista
- Considera agregar esperas aleatorias

Problema: Error al activar modo stealth
Solución:
- Verifica que playwright-stealth está instalado
- Ejecuta: pip install playwright-stealth
- Verifica la versión: pip show playwright-stealth

Problema: El modo stealth no funciona en headless
Solución:
- Algunos sitios detectan headless independientemente
- Prueba con HEADLESS=false
- Considera usar argumentos adicionales del navegador

COMPATIBILIDAD
--------------
- ✅ Chromium/Chrome: Totalmente compatible
- ✅ Firefox: Compatible con limitaciones
- ⚠️ WebKit: Soporte limitado

COMBINACIÓN CON OTRAS CONFIGURACIONES
--------------------------------------
Configuración recomendada para máxima efectividad:

```env
# Modo stealth
STEALTH_MODE=true

# Navegador
BROWSER=chromium
HEADLESS=false

# Velocidad humana
SLOW_MO=100

# User-Agent realista
BROWSER_USER_AGENT=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36

# Viewport común
VIEWPORT_WIDTH=1920
VIEWPORT_HEIGHT=1080

# Deshabilitar algunas características para parecer más real
CHROME_DISABLE_EXTENSIONS=false
```

CONSIDERACIONES LEGALES Y ÉTICAS
---------------------------------
⚠️ IMPORTANTE:
- Solo usa modo stealth en sitios donde tienes autorización
- Respeta los términos de servicio de los sitios
- No uses para actividades ilegales o no éticas
- El modo stealth no te da derecho a violar políticas

PREGUNTAS FRECUENTES
--------------------
P: ¿El modo stealth hace que mi automatización sea completamente indetectable?
R: No. Reduce significativamente las señales obvias, pero sitios sofisticados
   pueden usar otras técnicas de detección.

P: ¿Puedo usar modo stealth con headless?
R: Sí, pero algunos sitios detectan headless independientemente. Para mejor
   resultado, usa HEADLESS=false.

P: ¿El modo stealth afecta el rendimiento?
R: El impacto es mínimo, solo un pequeño overhead al crear páginas.

P: ¿Funciona con todos los navegadores?
R: Funciona mejor con Chromium/Chrome. Firefox tiene soporte limitado.

P: ¿Necesito cambiar mis features?
R: No, el modo stealth se aplica automáticamente a todas las páginas.

P: ¿Puedo activar/desactivar stealth para escenarios específicos?
R: Actualmente es global. Puedes cambiar la variable de entorno entre
   ejecuciones.

RECURSOS ADICIONALES
--------------------
- Repositorio playwright-stealth: https://github.com/AtuboDad/playwright_stealth
- Documentación Playwright: https://playwright.dev/
- Bot detection tests: https://bot.sannysoft.com/

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