HAKALAB FRAMEWORK - README COMPLETO
===================================

Este es el README completo del Hakalab Framework v1.2.23+ con toda la información 
necesaria para comenzar a usar el framework.

CONTENIDO
=========

1. Introducción
2. Características Principales
3. Instalación
4. Uso Básico
5. Configuración
6. Ejemplos
7. Documentación
8. Soporte
9. Licencia

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

1. INTRODUCCIÓN
===============

El Hakalab Framework es un framework profesional de automatización de pruebas 
funcionales basado en Playwright y Behave. Proporciona más de 300 steps 
preconstruidos en inglés y español para crear pruebas automatizadas de forma 
rápida y eficiente.

Características Clave:
- 300+ steps preconstruidos
- Soporte multiidioma (inglés/español)
- Integración con Jira y Xray
- Reportes HTML personalizados
- Variables dinámicas
- Simulación de comportamiento humano
- Procesamiento de CSV
- Testing de APIs REST
- Y mucho más...

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

2. CARACTERÍSTICAS PRINCIPALES
==============================

CORE FEATURES:
- Playwright: Automatización web moderna
- Behave: Framework BDD para Python
- Multiidioma: Inglés y español
- Page Object Model: JSON-based
- Variables Dinámicas: Generación automática
- Reportes HTML: Personalizados
- Scenario Outlines: Pruebas parametrizadas

NUEVAS FUNCIONALIDADES v1.2.23+:
- Integración Jira/Xray automática
- Flujo optimizado de Xray
- Procesamiento avanzado de CSV
- Entrada de texto realista
- Control avanzado de tiempos
- Variables mejoradas
- Simulación de comportamiento humano
- Medición de rendimiento

INTEGRACIÓN JIRA/XRAY:
- Adjunto automático de reportes
- Creación automática de Test Executions
- Mapeo automático de estados
- Vinculación a Historias de Usuario
- Control granular por variables
- Validación automática
- Flujo optimizado

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

3. INSTALACIÓN
==============

OPCIÓN 1: Desde PyPI (Recomendada)

pip install haka-playwright-engine
python -m playwright install
haka-init my-project
cd my-project
behave

OPCIÓN 2: Desde GitHub

pip install git+https://github.com/pipefariashaka/haka-playwright-engine.git
python -m playwright install

OPCIÓN 3: Modo Desarrollo

git clone https://github.com/pipefariashaka/haka-playwright-engine.git
cd haka-playwright-engine
pip install -e .
python -m playwright install

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

4. USO BÁSICO
=============

CONFIGURACIÓN INICIAL:

cp .env.example .env

EJECUTAR PRUEBAS:

# Todas las pruebas
behave

# Con tags específicos
behave --tags=@smoke
behave --tags=@login,@regression

# Feature específico
behave features/example_login.feature

# Con reporte HTML
behave -f html -o html-reports/report.html

# Sin captura de salida
behave --no-capture

# Con navegador específico
BROWSER=firefox behave

# Modo headless
HEADLESS=true behave

GENERAR REPORTES:

Los reportes HTML se generan automáticamente en html-reports/

# Abrir reporte
open html-reports/report.html  # Mac
start html-reports/report.html # Windows
xdg-open html-reports/report.html # Linux

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

5. CONFIGURACIÓN
================

VARIABLES DE ENTORNO (.env):

# Navegador
BROWSER=chromium              # chromium, firefox, webkit
HEADLESS=false               # true/false
TIMEOUT=30000                # Timeout en milisegundos
WINDOW_SIZE=1920,1080        # Tamaño de ventana

# Directorios
JSON_POMS_PATH=json_poms
SCREENSHOTS_DIR=screenshots
HTML_REPORTS_DIR=html-reports
DOWNLOADS_DIR=downloads
VIDEOS_DIR=videos

# Funcionalidades
HTML_REPORT_CAPTURE_ALL_STEPS=true
SCREENSHOT_FULL_PAGE=true
VIDEO_RECORDING=false
CLEANUP_OLD_FILES=true
CLEANUP_MAX_AGE_HOURS=24

# Variables de Prueba
BASE_URL=https://example.com
TEST_EMAIL=test@example.com
TEST_PASSWORD=password123
API_KEY=your-api-key-here
DATABASE_URL=postgresql://localhost/testdb

# Jira
JIRA_ENABLED=true
JIRA_URL=https://hakalab.atlassian.net
JIRA_EMAIL=felipe.farias@hakalab.com
JIRA_TOKEN=ATATT3xFfGF0DWFjw9A1O4PHPyHbOz0Ntqaj7-yWjwm0w5OernZnl0OtsXfxK1sd9foBaPKUY90WLSCseC8OS5dHmqWaV0PKTOqDKj_SIq4R_n-HHUVBzb0dRCUS2Hwv6ZjQE6LS02dc5vLNYQZuxS941J6bwRyJSgMF28ZMyrjzciCjtDSWm7k=1E898852
JIRA_PROJECT=PROD
JIRA_COMMENT_MESSAGE=Reporte prueba de QA

# Xray
XRAY_ENABLED=true
XRAY_AUTHORIZATION_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZW5hbnQiOiIyNjI1MGIzNC04YTMyLTNiZWMtOGI1MC04MjljZGJkNmMwMDciLCJhY2NvdW50SWQiOiI1ZmIyOTFiYWRkMGM1OTAwNzU5MWVhOWYiLCJpc1hlYSI6ZmFsc2UsImlhdCI6MTc2Nzk3MTg2NSwiZXhwIjoxNzY4MDU4MjY1LCJhdWQiOiIzRUJBM0IyRjA2MEI0Q0Q3QjRFQzE4NzgwQ0M1MDBFNyIsImlzcyI6ImNvbS54cGFuZGl0LnBsdWdpbnMueHJheSIsInN1YiI6IjNFQkEzQjJGMDYwQjRDRDdCNEVDMTg3ODBDQzUwMEU3In0.7HStiUpL2C7edzUDALpPHFQfJOxn8WzD6DLT3BLxva0
XRAY_BASE_URL=https://xray.cloud.getxray.app

# Debug
HAKALAB_SHOW_STEPS=false
DEBUG_MODE=false
SLOW_MO=0

CONFIGURACIÓN DE BEHAVE (behave.ini):

[behave]
paths = features
format = html
outdir = html-reports
show_timings = true
logging_level = INFO
show_skipped = false
show_multiline = true
color = true

[behave.formatters]
html = hakalab_framework.core.behave_html_integration:HtmlFormatter

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

6. EJEMPLOS
===========

EJEMPLO 1: Login Básico

Feature: Login de usuario

  Scenario: Login exitoso
    Given voy a la url "https://example.com/login"
    When relleno el campo "email" con "test@example.com" con identificador "#email-input"
    And relleno el campo "password" con "password123" con identificador "#password-input"
    And hago click en el botón "Login" con identificador "#login-btn"
    Then debería ver el texto "Bienvenido"
    And la url actual debería contener "/dashboard"

EJEMPLO 2: Procesamiento de CSV

Feature: Procesamiento de datos CSV

  Scenario: Cargar y filtrar datos
    Given cargo el archivo CSV "data/empleados.csv" en la variable "empleados"
    When filtro el CSV "empleados" donde "departamento" contiene "Desarrollo" y guardo como "desarrolladores"
    And ordeno el CSV "desarrolladores" por columna "salario" de forma "descendente" y guardo como "dev_ordenados"
    Then muestro un resumen del CSV "dev_ordenados"

EJEMPLO 3: Testing de API

Feature: Testing de API REST

  Scenario: Crear usuario via API
    When envío una petición POST a "/api/usuarios" con el JSON:
      """
      {
        "nombre": "Juan Pérez",
        "email": "juan@example.com",
        "rol": "usuario"
      }
      """
    Then la respuesta debería tener código de estado 201
    And la respuesta JSON debería tener el campo "id"

EJEMPLO 4: Integración Jira/Xray

Feature: Prueba con integración Jira/Xray
  @PROD-90
  
  Scenario: Test con trazabilidad automática
    @PROD-91
    Given voy a la url "https://example.com"
    When hago click en el botón "Crear" con identificador "#create-btn"
    Then debería ver el texto "Creado exitosamente"

# Resultado automático:
# ✅ Reporte HTML adjuntado a issue PROD-90
# ✅ UN Test Execution creado
# ✅ TODOS los tests incluidos
# ✅ Estados actualizados automáticamente
# ✅ Test Execution vinculado a Historia de Usuario

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

7. DOCUMENTACIÓN
================

GUÍAS DISPONIBLES:

- GUIA_COMPLETA_STEPS.md - Referencia completa de todos los steps (300+)
- GUIA_INTEGRACION_JIRA_XRAY.md - Integración completa con Jira y Xray Cloud
- GUIA_INSTALACION.md - Guía detallada de instalación
- GUIA_ARQUITECTURA_FRAMEWORK.md - Arquitectura técnica del framework
- GUIA_CONFIGURACION_NAVEGADOR_AVANZADA.md - Configuración avanzada del navegador
- GUIA_API_TESTING.md - Testing de APIs REST
- GUIA_VALIDACIONES.md - Validaciones y verificaciones
- GUIA_ELEMENTOS_WEB.md - Manipulación de elementos web
- GUIA_NAVEGACION_NAVEGADOR.md - Navegación del navegador
- GUIA_OCR.md - Reconocimiento óptico de caracteres
- GUIA_ARCHIVOS_DATOS.md - Manejo de archivos y datos
- GUIA_BASE_DATOS.md - Testing de bases de datos
- INDICE_FUNCIONALIDADES.md - Índice completo de funcionalidades
- INVENTARIO_STEPS.md - Inventario de steps disponibles

EJEMPLOS PRÁCTICOS:

- features/advanced_features_demo.feature
- features/csv_handling_demo.feature
- features/example_login.feature
- features/example_forms.feature

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

8. SOPORTE
==========

OBTENER AYUDA:

1. Documentación: Revisa las guías completas incluidas
2. Issues: Busca en los issues existentes del repositorio
3. Discusiones: Participa en las discusiones de la comunidad
4. Soporte: Contacta al equipo de desarrollo

REPORTAR PROBLEMAS:

Al reportar un issue, incluye:
- Versión del framework: pip show haka-playwright-engine
- Sistema operativo: Windows/Mac/Linux
- Versión de Python: python --version
- Logs completos: Copia el output completo del error
- Feature file: El código que causa el problema
- Screenshots: Si es un problema visual

ROADMAP:

- v1.3.0: Integración con bases de datos
- v1.4.0: Soporte para APIs REST
- v1.5.0: Integración con CI/CD avanzada
- v2.0.0: Soporte para testing móvil

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

9. LICENCIA
===========

Este proyecto está bajo la Licencia MIT - ver el archivo LICENSE para detalles.

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

COMIENZA AHORA
==============

# Instalación rápida
pip install haka-playwright-engine
python -m playwright install

# Crear proyecto
hakalab-init mi-proyecto
cd mi-proyecto

# Ejecutar primera prueba
behave

El Hakalab Framework está listo para llevar tus pruebas automatizadas al siguiente nivel!

Con 300+ steps reales, integración completa con Jira y Xray Cloud, simulación de 
comportamiento humano, procesamiento de CSV, cronómetros de rendimiento y variables 
dinámicas, tienes todo lo necesario para crear automatizaciones de nivel empresarial 
con trazabilidad completa.

INTEGRACIÓN JIRA/XRAY - TRAZABILIDAD AUTOMÁTICA:

✅ Adjunto automático de reportes HTML a issues de Jira
✅ Creación automática de Test Executions en Xray Cloud
✅ Flujo optimizado: Una sola llamada API para crear, adjuntar y actualizar
✅ Vinculación automática a Historias de Usuario
✅ Mapeo automático de estados (passed/failed/skipped)
✅ Control granular con variables de entorno
✅ Steps específicos para gestión manual
✅ Validación automática de tipos de issues
✅ Logs detallados del proceso completo

===================================
Documento generado automáticamente - Hakalab Framework v1.2.23+
README Completo
Fecha: Enero 2026
===================================
