GUÍA DE CONFIGURACIÓN AVANZADA DEL NAVEGADOR - HAKALAB FRAMEWORK
================================================================

Esta guía explica cómo configurar opciones avanzadas del navegador para diferentes 
escenarios de testing en el Hakalab Framework.

ÍNDICE
======
1. Configuración Básica
2. Variables de Entorno Avanzadas
3. Configuraciones Predefinidas
4. Archivos de Configuración JSON
5. Steps Disponibles
6. Ejemplos Prácticos
7. Configuraciones por Navegador
8. Consideraciones de Seguridad
9. Troubleshooting

================================================================

1. CONFIGURACIÓN BÁSICA
========================

Variables de Entorno Básicas (.env):
------------------------------------
# Configuración básica del navegador
BROWSER=chromium                    # chromium, chrome, firefox, webkit
HEADLESS=false                     # true/false
TIMEOUT=30000                      # Timeout en milisegundos
SLOW_MO=0                         # Delay entre acciones (ms)

# Viewport
VIEWPORT_WIDTH=1920
VIEWPORT_HEIGHT=1080
DEVICE_SCALE_FACTOR=1

DIFERENCIA ENTRE CHROME Y CHROMIUM:
-----------------------------------
- BROWSER=chromium: Usa Chromium descargado automáticamente por Playwright
  * Ventaja: No requiere instalación previa, siempre disponible
  * Desventaja: Puede ser detectado como bot en algunos sitios
  
- BROWSER=chrome: Usa Google Chrome instalado en tu sistema
  * Ventaja: Comportamiento más similar a un usuario real
  * Desventaja: Requiere tener Chrome instalado en el sistema
  * Nota: Si Chrome no está instalado, el framework usará Chromium automáticamente

Recomendación: Usa 'chrome' para pruebas que requieren evitar detección de bots,
y 'chromium' para pruebas estándar y CI/CD.

================================================================

2. VARIABLES DE ENTORNO AVANZADAS
==================================

Configuración Avanzada del Navegador:
-------------------------------------
# === CONFIGURACIÓN AVANZADA DEL NAVEGADOR ===
# Argumentos personalizados (separados por comas)
BROWSER_ARGS=--no-sandbox,--disable-dev-shm-usage

# Configuración predefinida
BROWSER_CONFIG_PRESET=performance   # performance, mobile, cicd, security_disabled

# Archivo de configuración personalizada
BROWSER_CONFIG_FILE=configs/chrome_custom.json

# Límite de memoria en MB
BROWSER_MEMORY_LIMIT=4096

# Proxy del navegador
BROWSER_PROXY=http://proxy.company.com:8080

# User Agent personalizado
BROWSER_USER_AGENT=Mozilla/5.0 Custom Agent

# Configuración de descargas
BROWSER_DOWNLOADS_DIR=downloads
BROWSER_DOWNLOAD_BEHAVIOR=auto      # auto, prompt

Configuraciones Específicas de Chrome:
--------------------------------------
# === CHROME/CHROMIUM ===
CHROME_DISABLE_SECURITY=false      # true=deshabilitar seguridad (solo testing)
CHROME_ENABLE_LOGGING=false        # true=habilitar logs detallados
CHROME_LOG_LEVEL=INFO              # INFO, WARNING, ERROR
CHROME_DISABLE_EXTENSIONS=true     # true=deshabilitar extensiones
CHROME_DISABLE_PLUGINS=true        # true=deshabilitar plugins
CHROME_DISABLE_IMAGES=false        # true=deshabilitar carga de imágenes
CHROME_DISABLE_JAVASCRIPT=false    # true=deshabilitar JavaScript

Configuraciones Específicas de Firefox:
---------------------------------------
# === FIREFOX ===
FIREFOX_PROFILE_PATH=              # Ruta a perfil personalizado
FIREFOX_DISABLE_ADDONS=true        # true=deshabilitar addons
FIREFOX_PRIVATE_MODE=false         # true=modo privado

Configuraciones Específicas de WebKit:
--------------------------------------
# === WEBKIT/SAFARI ===
WEBKIT_DISABLE_FEATURES=           # Características a deshabilitar (separadas por comas)

================================================================

3. CONFIGURACIONES PREDEFINIDAS
================================

1. Performance (BROWSER_CONFIG_PRESET=performance)
--------------------------------------------------
Optimizada para máximo rendimiento y velocidad:
BROWSER_CONFIG_PRESET=performance

Incluye:
- Deshabilitación de GPU
- Optimizaciones de memoria
- Deshabilitación de características no esenciales
- Configuración para paralelismo

2. Mobile (BROWSER_CONFIG_PRESET=mobile)
----------------------------------------
Configurada para testing móvil:
BROWSER_CONFIG_PRESET=mobile

Incluye:
- User agent móvil
- Eventos táctiles habilitados
- Viewport meta habilitado
- Notificaciones desktop deshabilitadas

3. CI/CD (BROWSER_CONFIG_PRESET=cicd)
-------------------------------------
Optimizada para entornos de integración continua:
BROWSER_CONFIG_PRESET=cicd

Incluye:
- Configuración headless optimizada
- Deshabilitación de extensiones y plugins
- Configuración de seguridad relajada
- Optimizaciones para contenedores

4. Security Disabled (BROWSER_CONFIG_PRESET=security_disabled)
--------------------------------------------------------------
⚠️ SOLO PARA TESTING - Deshabilita características de seguridad:
BROWSER_CONFIG_PRESET=security_disabled

Incluye:
- Seguridad web deshabilitada
- Certificados SSL ignorados
- CORS deshabilitado
- XSS auditor deshabilitado

================================================================

4. ARCHIVOS DE CONFIGURACIÓN JSON
==================================

Estructura del Archivo JSON:
----------------------------
{
  "name": "Mi Configuración Personalizada",
  "description": "Descripción de la configuración",
  "args": [
    "--no-sandbox",
    "--disable-dev-shm-usage",
    "--custom-flag=value"
  ],
  "prefs": {
    "profile.default_content_setting_values.notifications": 2,
    "download.prompt_for_download": false
  },
  "viewport": {
    "width": 1920,
    "height": 1080
  }
}

Configuraciones Incluidas:
--------------------------
El framework incluye configuraciones predefinidas en 
hakalab_framework/templates/browser_configs/:

- chrome_performance.json - Máximo rendimiento
- chrome_mobile.json - Testing móvil
- chrome_cicd.json - Entornos CI/CD
- chrome_security_disabled.json - Seguridad deshabilitada
- firefox_standard.json - Firefox estándar

================================================================

5. STEPS DISPONIBLES
=====================

Configuración de Argumentos:
----------------------------
# Añadir argumento individual
When establezco el argumento del navegador "--no-sandbox"

# Añadir múltiples argumentos
When establezco los argumentos del navegador desde la lista "--no-sandbox,--disable-gpu,--disable-dev-shm-usage"

# Limpiar argumentos
When limpio todos los argumentos del navegador

Configuración de Banderas de Chrome:
------------------------------------
# Establecer bandera con valor
When establezco la bandera de Chrome "disable-web-security" con valor "true"

# Habilitar característica experimental
When habilito la característica experimental de Chrome "WebAssembly"

# Deshabilitar característica experimental
When deshabilito la característica experimental de Chrome "AutofillShowTypePredictions"

Configuración de Preferencias:
------------------------------
# Establecer preferencia
When establezco la preferencia del navegador "download.prompt_for_download" con valor "false"

# Configurar descargas
When establezco el comportamiento de descarga del navegador a "auto" con ruta "downloads"

# Limpiar preferencias
When limpio todas las preferencias del navegador

Configuraciones Predefinidas:
-----------------------------
# Habilitar modo de rendimiento
When habilito el modo de rendimiento del navegador

# Configurar para móvil
When configuro el navegador para testing móvil

# Configurar para CI/CD
When configuro el navegador para entorno CI/CD

# Deshabilitar seguridad (solo testing)
When deshabilito las características de seguridad del navegador

Configuración de Red:
--------------------
# Establecer proxy
When establezco el proxy del navegador a "http://proxy.company.com:8080"

# Establecer límite de memoria
When establezco el límite de memoria del navegador a "4096" MB

Gestión de Archivos de Configuración:
-------------------------------------
# Cargar configuración desde archivo
When cargo la configuración del navegador desde el archivo "configs/chrome_custom.json"

# Guardar configuración actual
When guardo la configuración actual del navegador en el archivo "configs/my_config.json"

Información y Debug:
-------------------
# Mostrar configuración actual
When muestro la configuración actual del navegador

================================================================

6. EJEMPLOS PRÁCTICOS
======================

Ejemplo 1: Testing de Performance
---------------------------------
Feature: Testing de rendimiento con configuración optimizada

  Background:
    Given habilito el modo de rendimiento del navegador
    And establezco el límite de memoria del navegador a "8192" MB
    And establezco la bandera de Chrome "aggressive-cache-discard" con valor "true"

  Scenario: Prueba de carga rápida
    When voy a la url "https://example.com"
    Then la página debería cargar en menos de 2 segundos

Ejemplo 2: Testing Móvil
------------------------
Feature: Testing móvil con configuración específica

  Background:
    Given configuro el navegador para testing móvil
    And establezco el viewport del navegador a "375x667"

  Scenario: Navegación móvil
    When voy a la url "https://m.example.com"
    Then el menú móvil debería ser visible

Ejemplo 3: Testing con Proxy
----------------------------
Feature: Testing a través de proxy corporativo

  Background:
    Given establezco el proxy del navegador a "http://proxy.company.com:8080"
    And establezco la preferencia del navegador "proxy.bypass_list" con valor "localhost,127.0.0.1"

  Scenario: Acceso a través de proxy
    When voy a la url "https://external-site.com"
    Then debería acceder correctamente a través del proxy

Ejemplo 4: Testing con Configuración Personalizada
--------------------------------------------------
Feature: Testing con configuración desde archivo

  Background:
    Given cargo la configuración del navegador desde el archivo "configs/testing_config.json"
    And muestro la configuración actual del navegador

  Scenario: Prueba con configuración personalizada
    When voy a la url "https://app.example.com"
    Then la aplicación debería funcionar con la configuración personalizada

Ejemplo 5: Testing de Seguridad (Entorno Controlado)
----------------------------------------------------
Feature: Testing de seguridad en entorno controlado

  Background:
    Given deshabilito las características de seguridad del navegador
    And establezco la bandera de Chrome "ignore-certificate-errors" con valor "true"

  Scenario: Prueba con certificados autofirmados
    When voy a la url "https://self-signed.example.com"
    Then debería acceder sin errores de certificado

================================================================

7. CONFIGURACIONES POR NAVEGADOR
=================================

Chrome/Chromium - Argumentos Comunes:
-------------------------------------
# Rendimiento
--no-sandbox
--disable-dev-shm-usage
--disable-gpu
--disable-software-rasterizer
--max_old_space_size=4096

# Seguridad (solo testing)
--disable-web-security
--ignore-certificate-errors
--ignore-ssl-errors
--allow-running-insecure-content

# Características
--disable-extensions
--disable-plugins
--disable-images
--disable-javascript
--disable-notifications

# Móvil
--use-mobile-user-agent
--touch-events=enabled
--enable-viewport-meta

Firefox - Argumentos Comunes:
-----------------------------
# Básicos
--width=1920
--height=1080
--no-remote
--disable-dev-shm-usage

# Privacidad
--private-window
--safe-mode

WebKit - Configuraciones:
-------------------------
# Características a deshabilitar
--disable-notifications
--disable-geolocation
--disable-camera

================================================================

8. CONSIDERACIONES DE SEGURIDAD
================================

Configuraciones Seguras para Producción:
----------------------------------------
✅ Mantener características de seguridad habilitadas
✅ Usar certificados válidos
✅ Habilitar CORS apropiadamente
✅ Mantener extensiones de seguridad

Configuraciones Solo para Testing:
----------------------------------
⚠️ --disable-web-security - Solo en entornos controlados
⚠️ --ignore-certificate-errors - Solo para certificados de prueba
⚠️ --allow-running-insecure-content - Solo para testing específico

Mejores Prácticas:
------------------
1. Usar configuraciones predefinidas cuando sea posible
2. Documentar configuraciones personalizadas en archivos JSON
3. Separar configuraciones por entorno (dev, test, prod)
4. Validar configuraciones antes de usar en CI/CD
5. Monitorear rendimiento con diferentes configuraciones

================================================================

9. TROUBLESHOOTING
===================

Problemas Comunes:
------------------

El navegador no inicia:
----------------------
# Solución: Añadir argumentos básicos
BROWSER_ARGS=--no-sandbox,--disable-dev-shm-usage

Problemas de memoria en CI/CD:
------------------------------
# Solución: Configurar límites de memoria
BROWSER_MEMORY_LIMIT=2048
BROWSER_CONFIG_PRESET=cicd

Certificados SSL en testing:
----------------------------
# Solución: Deshabilitar validación SSL (solo testing)
CHROME_DISABLE_SECURITY=true

Problemas con proxy corporativo:
-------------------------------
# Solución: Configurar proxy y bypass
BROWSER_PROXY=http://proxy.company.com:8080
BROWSER_ARGS=--proxy-bypass-list=localhost,127.0.0.1

================================================================

RESUMEN DE FUNCIONALIDADES
===========================

El sistema de configuración avanzada del navegador del Hakalab Framework 
proporciona:

✅ 18+ nuevas funciones para configuración del navegador
✅ 36+ variantes lingüísticas (inglés/español)
✅ 4 configuraciones predefinidas (performance, mobile, cicd, security_disabled)
✅ 5 archivos de configuración JSON incluidos
✅ Soporte para Chrome, Firefox y WebKit
✅ Configuración por variables de entorno
✅ Configuración por archivos JSON
✅ Steps específicos para cada tipo de configuración
✅ Ejemplos prácticos para casos de uso comunes

CASOS DE USO PRINCIPALES:
========================
- Testing de rendimiento con optimizaciones específicas
- Testing móvil con configuraciones táctiles
- Ejecución en entornos CI/CD con configuraciones headless
- Testing de seguridad con validaciones deshabilitadas
- Testing a través de proxies corporativos
- Configuraciones personalizadas por proyecto
- Debugging con logs detallados del navegador

Esta funcionalidad permite adaptar el comportamiento del navegador a cualquier 
escenario de testing, desde pruebas básicas hasta configuraciones complejas 
para entornos empresariales.

================================================================
Documento generado automáticamente - Hakalab Framework v1.3.0
Configuración Avanzada del Navegador
Fecha: Enero 2026
================================================================