ARQUITECTURA DEL HAKALAB FRAMEWORK - GUÍA TÉCNICA COMPLETA
=========================================================

Esta guía técnica explica la arquitectura interna, componentes, patrones de diseño 
y flujos de trabajo del Hakalab Framework v1.2.23+.

ÍNDICE
======
1. Visión General de la Arquitectura
2. Estructura de Directorios
3. Componentes Core
4. Sistema de Steps
5. Sistema de Integraciones
6. Sistema de Reportes
7. Flujos de Trabajo
8. Patrones de Diseño
9. Extensibilidad
10. Debugging y Troubleshooting

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

1. VISIÓN GENERAL DE LA ARQUITECTURA
====================================

PRINCIPIOS ARQUITECTÓNICOS:
- Separación de Responsabilidades
- Inversión de Dependencias
- Principio Abierto/Cerrado
- Single Responsibility
- DRY (Don't Repeat Yourself)

CAPAS ARQUITECTÓNICAS:

1. CAPA DE PRESENTACIÓN (Steps Layer)
   - Steps de Behave organizados por funcionalidad
   - Interfaz de usuario para testers
   - Validación de parámetros de entrada

2. CAPA DE LÓGICA DE NEGOCIO (Core Layer)
   - Gestión de contexto y variables
   - Localización de elementos
   - Gestión de reportes y screenshots
   - Configuración del framework

3. CAPA DE INTEGRACIÓN (Integration Layer)
   - Integraciones con herramientas externas (Jira, Xray)
   - Hooks de Behave para automatización
   - Gestión de APIs externas

4. CAPA DE INFRAESTRUCTURA (Infrastructure Layer)
   - Playwright para automatización web
   - Sistema de archivos para reportes
   - Gestión de configuración y variables de entorno

TECNOLOGÍAS CORE:
- Playwright: Motor de automatización web
- Behave: Framework BDD para Python
- Pandas: Procesamiento de datos CSV
- Jinja2: Templates para reportes HTML
- Requests: Comunicación HTTP para integraciones
- JSON: Configuración y Page Object Models

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

2. ESTRUCTURA DE DIRECTORIOS
============================

haka-playwright-engine/
├── hakalab_framework/                    # Paquete principal
│   ├── __init__.py
│   ├── cli.py                           # Interfaz de línea de comandos
│   ├── cli_html_report.py               # CLI para reportes
│   │
│   ├── core/                            # Componentes core
│   │   ├── __init__.py
│   │   ├── behave_html_integration.py   # Integración HTML
│   │   ├── context_helpers.py           # Helpers de contexto
│   │   ├── element_locator.py           # Localización de elementos
│   │   ├── environment_config.py        # Configuración
│   │   ├── html_reporter.py             # Generador de reportes
│   │   ├── report_generator.py          # Motor de reportes
│   │   ├── screenshot_manager.py        # Gestión de screenshots
│   │   ├── step_suggester.py            # Sugerencias de steps
│   │   ├── variable_manager.py          # Gestión de variables
│   │   └── video_manager.py             # Grabación de videos
│   │
│   ├── steps/                           # Biblioteca de steps (35+ módulos)
│   │   ├── __init__.py
│   │   ├── navigation_steps.py
│   │   ├── interaction_steps.py
│   │   ├── assertion_steps.py
│   │   ├── wait_steps.py
│   │   ├── timing_steps.py
│   │   ├── advanced_input_steps.py
│   │   ├── variable_steps.py
│   │   ├── csv_file_steps.py
│   │   ├── drag_drop_steps.py
│   │   ├── modal_steps.py
│   │   ├── table_steps.py
│   │   ├── file_steps.py
│   │   ├── combobox_steps.py
│   │   ├── scroll_steps.py
│   │   ├── window_steps.py
│   │   ├── keyboard_mouse_steps.py
│   │   ├── data_extraction_steps.py
│   │   ├── advanced_steps.py
│   │   ├── environment_steps.py
│   │   ├── salesforce_steps.py
│   │   ├── jira_xray_steps.py
│   │   └── iframe_steps.py
│   │
│   ├── integrations/                    # Integraciones externas
│   │   ├── __init__.py
│   │   ├── jira_integration.py
│   │   ├── xray_integration.py
│   │   └── behave_hooks.py
│   │
│   ├── templates/                       # Plantillas
│   │   ├── __init__.py
│   │   ├── environment.py
│   │   ├── environment_with_html_report.py
│   │   ├── environment_with_jira_xray.py
│   │   └── report_config.json
│   │
│   ├── documentacion/                   # Documentación
│   │   ├── GUIA_COMPLETA_STEPS.md
│   │   ├── GUIA_INSTALACION.md
│   │   ├── GUIA_INTEGRACION_JIRA_XRAY.md
│   │   ├── GUIA_PARALELIZACION_CI_CD.md
│   │   └── [otros archivos]
│   │
│   └── examples/                        # Ejemplos
│       ├── basic_example.feature
│       ├── advanced_features_demo.feature
│       └── csv_handling_demo.feature
│
├── features/                            # Pruebas del usuario
├── json_poms/                           # Page Object Models
├── screenshots/                         # Screenshots automáticos
├── html-reports/                        # Reportes HTML
├── videos/                              # Videos de ejecución
├── downloads/                           # Archivos descargados
│
├── .env                                 # Variables de entorno
├── behave.ini                           # Configuración de Behave
├── requirements.txt                     # Dependencias
├── setup.py                             # Configuración de instalación
├── pyproject.toml                       # Configuración moderna
└── README.md                            # Documentación principal

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

3. COMPONENTES CORE
===================

ENVIRONMENT_CONFIG.PY:
- Inicialización de Playwright y navegadores
- Configuración de viewport y opciones
- Gestión del ciclo de vida del contexto
- Carga de variables de entorno
- Configuración de timeouts

ELEMENT_LOCATOR.PY:
- Resolución de selectores CSS, XPath, ID, Name, Class
- Integración con Page Object Models JSON
- Localización con timeouts y reintentos
- Validación de elementos antes de interacción

VARIABLE_MANAGER.PY:
- Almacenamiento y recuperación de variables
- Generación automática de datos
- Resolución de variables en strings
- Persistencia entre steps y escenarios

SCREENSHOT_MANAGER.PY:
- Screenshots automáticos en cada step
- Screenshots automáticos en fallos
- Screenshots manuales con nombres personalizados
- Organización y limpieza de archivos

HTML_REPORTER.PY:
- Generación de reportes HTML personalizados
- Integración de screenshots
- Navegación interactiva
- Gráficos y estadísticas

VIDEO_MANAGER.PY:
- Grabación automática de ejecución
- Configuración de calidad y resolución
- Gestión de almacenamiento
- Integración con reportes

CONTEXT_HELPERS.PY:
- Funciones auxiliares para contexto
- Shortcuts para operaciones comunes
- Integración entre componentes
- Gestión de estado

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

4. SISTEMA DE STEPS
===================

ORGANIZACIÓN MODULAR:
- Cada archivo se enfoca en una funcionalidad específica
- 35+ módulos especializados
- 1100+ variantes lingüísticas (inglés/español)
- 500+ funciones únicas

PATRÓN DE IMPLEMENTACIÓN:
@step('descripción del step con "{parametro}"')
def step_function(context, parametro):
    """Documentación del step"""
    try:
        # Validación de parámetros
        # Lógica principal
        # Logging y debugging
        # Manejo de errores
    except Exception as e:
        raise AssertionError(f"Error descriptivo: {str(e)}")

CATEGORÍAS DE STEPS:
- NAVEGACIÓN (15+ steps)
- INTERACCIÓN (25+ steps)
- VERIFICACIÓN (20+ steps)
- TIMING (15+ steps)
- AVANZADOS (50+ steps)
- Y muchas más...

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

5. SISTEMA DE INTEGRACIONES
===========================

PATRÓN DE INTEGRACIÓN:
- Clase principal de integración
- Configuración mediante variables de entorno
- Validación de configuración en inicialización
- Métodos públicos para funcionalidades
- Manejo robusto de errores

INTEGRACIÓN JIRA:
- Autenticación con API de Jira
- Búsqueda y validación de issues
- Adjunto de archivos a issues
- Comentarios automáticos
- Búsquedas JQL avanzadas

INTEGRACIÓN XRAY:
- Autenticación con Xray Cloud API
- Creación de Test Executions
- Actualización de estados de tests
- Vinculación a Historias de Usuario
- Validación de tipos de issues

HOOKS DE BEHAVE:
- Integración automática con ciclo de vida
- Recopilación de resultados
- Procesamiento automático
- Coordinación entre integraciones

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

6. SISTEMA DE REPORTES
======================

REPORTE HTML PERSONALIZADO:
- Dashboard ejecutivo con métricas
- Navegación interactiva
- Screenshots integrados
- Gráficos de estadísticas
- Filtros dinámicos
- Responsive design

INTEGRACIÓN CON BEHAVE:
- Captura automática de información
- Integración con hooks
- Recopilación de screenshots
- Generación de datos para reporte

GENERADOR DE REPORTES:
- Coordinación de generación
- Procesamiento de datos
- Aplicación de templates
- Optimización de archivos

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

7. FLUJOS DE TRABAJO
====================

FLUJO PRINCIPAL:
1. INICIALIZACIÓN (before_all)
   - Cargar configuración
   - Inicializar Playwright
   - Configurar navegador
   - Inicializar gestores
   - Validar integraciones

2. EJECUCIÓN DE FEATURE (before_feature)
   - Inicializar recopilación
   - Preparar contexto
   - Configurar reportes

3. EJECUCIÓN DE ESCENARIO (before_scenario)
   - Configurar contexto
   - Inicializar página
   - Configurar grabación
   - Preparar captura

4. EJECUCIÓN DE STEP
   - Validar parámetros
   - Resolver variables
   - Localizar elementos
   - Ejecutar acción
   - Capturar screenshot
   - Logging

5. FINALIZACIÓN DE ESCENARIO (after_scenario)
   - Capturar screenshot de fallo
   - Guardar video
   - Recopilar resultados
   - Limpiar recursos

6. FINALIZACIÓN DE FEATURE (after_feature)
   - Recopilar datos finales
   - Preparar información
   - Guardar estado

7. FINALIZACIÓN GLOBAL (after_all)
   - Generar reporte HTML
   - Procesar integraciones
   - Adjuntar reportes
   - Crear Test Executions
   - Vincular a Historias
   - Mostrar resumen
   - Limpiar recursos

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

8. PATRONES DE DISEÑO
====================

FACTORY PATTERN:
- Ubicación: environment_config.py
- Uso: Creación de navegadores Playwright
- Beneficio: Abstrae la creación

SINGLETON PATTERN:
- Ubicación: variable_manager.py
- Uso: Gestión global de variables
- Beneficio: Única instancia

STRATEGY PATTERN:
- Ubicación: element_locator.py
- Uso: Diferentes estrategias de localización
- Beneficio: Cambiar algoritmos dinámicamente

OBSERVER PATTERN:
- Ubicación: behave_hooks.py
- Uso: Hooks de Behave
- Beneficio: Desacopla lógica

TEMPLATE METHOD PATTERN:
- Ubicación: html_reporter.py
- Uso: Generación de reportes
- Beneficio: Estructura común

FACADE PATTERN:
- Ubicación: __init__.py files
- Uso: Simplifica interfaces
- Beneficio: Interfaz simple

DECORATOR PATTERN:
- Ubicación: steps/*.py
- Uso: Decoradores @step
- Beneficio: Añade funcionalidad

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

9. EXTENSIBILIDAD
=================

AGREGAR NUEVOS STEPS:
- Crear archivos .py en features/steps/
- Importar componentes del framework
- Seguir patrones establecidos

CREAR NUEVAS INTEGRACIONES:
- Crear clases en hakalab_framework/integrations/
- Implementar hooks en behave_hooks.py
- Configurar variables de entorno

PERSONALIZAR REPORTES:
- Extender clases base
- Crear templates Jinja2
- Configurar en report_config.json

AGREGAR NUEVOS LOCALIZADORES:
- Extender element_locator.py
- Agregar nuevos tipos de selectores
- Mantener compatibilidad

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

10. DEBUGGING Y TROUBLESHOOTING
===============================

HERRAMIENTAS DE DEBUGGING:
- Logging integrado en múltiples niveles
- Screenshots automáticos
- Variables de debug
- Step Suggester

VARIABLES DE DEBUG:
- HAKALAB_DEBUG=true
- HAKALAB_SHOW_STEPS=true
- SLOW_MO=1000
- HTML_REPORT_CAPTURE_ALL_STEPS=true

PROBLEMAS COMUNES:
- Elemento no encontrado
- Timeout en operaciones
- Problemas de integración
- Problemas de variables
- Problemas de reportes

HERRAMIENTAS DE DIAGNÓSTICO:
- Scripts de prueba
- Steps de diagnóstico
- Modo verbose
- Logs detallados

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

CONCLUSIÓN

El Hakalab Framework v1.2.23+ representa una arquitectura madura y extensible 
para automatización de pruebas empresariales. Su diseño modular, patrones de 
diseño bien establecidos, y sistema de integraciones robusto lo convierten en 
una herramienta poderosa para equipos de QA.

Con más de 300 steps disponibles, integración automática con Jira/Xray, y un 
sistema de reportes avanzado, el framework proporciona todo lo necesario para 
implementar una estrategia de automatización de pruebas completa y profesional.

=========================================================
Documento generado automáticamente - Hakalab Framework v1.3.0
Arquitectura del Framework
Fecha: Enero 2026
=========================================================
