GUIA DE INSTALACION Y CONFIGURACION - HAKALAB FRAMEWORK v1.2.12

Esta guía te ayudará a instalar y configurar el Hakalab Framework desde cero en cualquier proyecto.

NUEVA VERSION 1.2.12: 300+ STEPS AVANZADOS! CSV, Variables Dinámicas, Timing Avanzado, Input Mejorado + Docker & CI/CD

TABLA DE CONTENIDOS

1. Requisitos Previos
2. Instalación del Framework
3. Configuración del Proyecto
4. Estructura de Archivos
5. Configuración de Variables de Entorno
6. Primer Test
7. Ejecución de Pruebas
8. HTML Reporter Personalizado
9. Docker y Contenedores
10. CI/CD y Paralelización
11. Funcionalidades Avanzadas v1.2.12
12. Solución de Problemas
13. Novedades v1.2.12

REQUISITOS PREVIOS

1. Python 3.8 o superior
python --version
# Debe mostrar Python 3.8.x o superior

2. pip (gestor de paquetes de Python)
pip --version

3. Git (opcional, para clonar proyectos)
git --version

4. Docker (opcional, para contenedores)
docker --version
docker-compose --version

5. Node.js (opcional, para CI/CD avanzado)
node --version
npm --version

INSTALACION DEL FRAMEWORK

Opción 1: Instalación desde PyPI (Recomendada)
pip install haka-playwright-engine

Opción 2: Instalación de Versión Específica
# Instalar versión específica (recomendado para producción)
pip install haka-playwright-engine==1.3.17

Opción 3: Instalación desde GitHub
pip install git+https://github.com/pipefariashaka/haka-playwright-engine.git

Opción 4: Instalación en Modo Desarrollo
git clone https://github.com/pipefariashaka/haka-playwright-engine.git
cd haka-playwright-engine
pip install -e .

Verificar la Instalación
python -c "import hakalab_framework; print(f'✅ Haka Playwright Engine v{hakalab_framework.__version__} instalado correctamente')"

Salida esperada:
✅ Haka Playwright Engine v1.3.17+ instalado correctamente

Instalar Navegadores de Playwright
playwright install

Salida esperada:
Downloading Chromium 130.0.6723.31...
Downloading Firefox 131.0...
Downloading Webkit 18.0...
✅ Navegadores instalados correctamente

CONFIGURACION DEL PROYECTO

Opción 1: Proyecto Estándar

Crea la siguiente estructura en tu proyecto:

mi_proyecto/
├── features/
│   ├── steps/
│   │   └── __init__.py
│   ├── environment.py
│   └── mi_primer_test.feature
├── json_poms/
│   └── FORMS.json
├── test_files/
│   └── sample_data.csv
├── .env
├── .env.example
├── Runner.py
└── report_config.json

ARCHIVOS PRINCIPALES

features/environment.py
"""
Template de environment.py para haka-playwright-engine v1.2.12+
Soporte completo: HTML Reporter + Video + Screenshots + Limpieza automática
"""

from hakalab_framework import (
    setup_framework_context,
    setup_scenario_context
)
from hakalab_framework.core.behave_html_integration import setup_html_reporting, generate_html_report
from hakalab_framework.core.screenshot_manager import take_screenshot_on_failure, take_screenshot
from hakalab_framework.core.video_manager import setup_video_recording, cleanup_video_recording

# Importar steps directamente para que Behave los reconozca
from hakalab_framework.steps import *

def before_all(context):
    """Configuración inicial - El framework hace todo el trabajo"""
    try:
        setup_framework_context(context)
        setup_html_reporting(context)
        setup_video_recording(context)
        print("✅ Framework configurado correctamente")
        print("✅ HTML Reporter configurado")
        print("✅ Video recording configurado")
    except Exception as e:
        print(f"❌ Error en before_all: {e}")
        raise

def before_scenario(context, scenario):
    """Configuración por escenario - El framework maneja todo"""
    try:
        setup_scenario_context(context, scenario)
        print(f"🚀 Iniciando escenario: {scenario.name}")
    except Exception as e:
        print(f"❌ Error en before_scenario: {e}")
        raise

def after_step(context, step):
    """Capturar screenshot después de cada paso (opcional)"""
    try:
        if hasattr(context, 'page') and context.page:
            step_name = step.name.replace(' ', '_').replace('"', '').replace("'", '')
            screenshot_name = f"step_{step.line}_{step_name[:50]}"
            take_screenshot(context, screenshot_name)
    except Exception as e:
        print(f"⚠️ Error capturando screenshot en step: {e}")

def after_scenario(context, scenario):
    """Screenshot si falla + limpieza de video"""
    try:
        take_screenshot_on_failure(context, scenario)
    except:
        pass
    
    try:
        cleanup_video_recording(context, scenario)
    except:
        pass
    
    try:
        if hasattr(context, 'page') and context.page:
            context.page.close()
            context.page = None
    except:
        pass

def after_all(context):
    """Cerrar Playwright y generar reportes"""
    try:
        if hasattr(context, 'framework_config') and context.framework_config:
            context.framework_config.cleanup()
            print("✅ Playwright cerrado correctamente")
    except Exception as e:
        print(f"⚠️ Error cerrando Playwright: {e}")
    
    try:
        generate_html_report(context)
        print("🎨 Reporte HTML personalizado generado")
    except Exception as e:
        print(f"⚠️ Error generando HTML Reporter: {e}")

ARCHIVO .ENV

# ===== CONFIGURACIÓN DEL NAVEGADOR =====
BROWSER=chromium                    # chromium, firefox, webkit
HEADLESS=false                      # true para ejecutar sin interfaz
TIMEOUT=30000                       # Timeout global en milisegundos
VIEWPORT_WIDTH=1920                 # Ancho de ventana
VIEWPORT_HEIGHT=1080                # Alto de ventana
SLOW_MO=0                          # Ralentizar acciones (ms)

# ===== URLs DE PRUEBA =====
BASE_URL=https://example.com        # URL base para navegación relativa
TEST_URL=https://httpbin.org        # URL para pruebas

# ===== CREDENCIALES DE PRUEBA =====
TEST_EMAIL=test@example.com         # Email para formularios
TEST_PASSWORD=password123           # Contraseña para login
TEST_USER_NAME=usuario_prueba       # Nombre de usuario

# ===== CONFIGURACIÓN DE REPORTES =====
HTML_REPORTS_DIR=html-reports       # Directorio de reportes HTML
SCREENSHOTS_DIR=screenshots         # Directorio de capturas
DOWNLOADS_DIR=downloads             # Directorio de descargas
VIDEOS_DIR=videos                   # Directorio de videos

# ===== CONFIGURACIÓN DE SCREENSHOTS =====
HTML_REPORT_CAPTURE_ALL_STEPS=true # Capturar screenshots en cada step
SCREENSHOT_FULL_PAGE=true          # Screenshots de página completa
AUTO_SCREENSHOT_ON_FAILURE=true    # Screenshot automático en fallos

# ===== CONFIGURACIÓN DE VIDEO =====
VIDEO_RECORDING_ENABLED=false      # Habilitar grabación de video
VIDEO_RECORDING_MODE=retain-on-failure # always, retain-on-failure, off
VIDEO_SIZE_WIDTH=1920              # Ancho del video
VIDEO_SIZE_HEIGHT=1080             # Alto del video

# ===== CONFIGURACIÓN DE LIMPIEZA =====
CLEANUP_OLD_FILES=true             # Limpiar archivos antiguos
CLEANUP_MODE=startup               # startup, shutdown, both
CLEANUP_MAX_AGE_HOURS=24          # Edad máxima de archivos (horas)

# ===== CONFIGURACIÓN DE LOGGING =====
LOG_LEVEL=INFO                      # DEBUG, INFO, WARNING, ERROR
LOG_FILE=                          # Archivo de log (opcional)
HAKALAB_SHOW_STEPS=false           # Mostrar carga de steps

# ===== CONFIGURACIÓN DE RED =====
IGNORE_HTTPS_ERRORS=false          # Ignorar errores SSL
USER_AGENT=                        # User agent personalizado

# ===== CONFIGURACIÓN DE PRUEBAS =====
AUTO_WAIT_FOR_LOAD=true            # Esperar carga automática
RETRY_FAILED_STEPS=0               # Reintentos para steps fallidos

# ===== CONFIGURACIÓN DE PARALELISMO =====
PARALLEL_WORKERS=4                  # Número de workers paralelos
MAX_BROWSER_INSTANCES=10           # Máximo de navegadores simultáneos
BROWSER_POOL_SIZE=5                # Tamaño del pool de navegadores
WORKER_TIMEOUT=300                 # Timeout de workers (segundos)

# ===== DATOS DE PRUEBA ADICIONALES =====
API_BASE_URL=https://api.example.com # URL base para APIs
JSON_POMS_PATH=json_poms            # Ruta de Page Object Models
CSV_FILES_PATH=test_files           # Ruta de archivos CSV