Metadata-Version: 2.4
Name: haka-playwright-engine
Version: 1.3.120
Summary: Framework completo de pruebas funcionales con Playwright y Behave
Home-page: https://github.com/pipefariashaka/haka-playwright-engine
Author: Felipe Farias
Author-email: Felipe Farias <felipe.farias@hakalab.com>
Maintainer-email: Felipe Farias <felipe.farias@hakalab.com>
License: MIT
Project-URL: Homepage, https://github.com/pipefariashaka/haka-playwright-engine
Project-URL: Repository, https://github.com/pipefariashaka/haka-playwright-engine
Project-URL: Documentation, https://github.com/pipefariashaka/haka-playwright-engine#readme
Project-URL: Bug Tracker, https://github.com/pipefariashaka/haka-playwright-engine/issues
Keywords: playwright,behave,bdd,testing,automation,functional-testing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Testing
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: playwright>=1.57.0
Requires-Dist: behave>=1.3.3
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: jsonschema>=4.20.0
Requires-Dist: click>=8.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: jinja2>=3.0.0
Requires-Dist: requests>=2.28.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: Pillow>=10.0.0
Requires-Dist: imageio-ffmpeg>=0.4.9
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Requires-Dist: pre-commit>=2.20.0; extra == "dev"
Provides-Extra: allure
Requires-Dist: allure-commandline>=2.20.0; extra == "allure"
Provides-Extra: ocr
Requires-Dist: pytesseract>=0.3.10; extra == "ocr"
Requires-Dist: easyocr>=1.7.0; extra == "ocr"
Requires-Dist: Pillow>=10.0.0; extra == "ocr"
Requires-Dist: opencv-python>=4.8.0; extra == "ocr"
Requires-Dist: numpy>=1.24.0; extra == "ocr"
Provides-Extra: full
Requires-Dist: pytesseract>=0.3.10; extra == "full"
Requires-Dist: easyocr>=1.7.0; extra == "full"
Requires-Dist: Pillow>=10.0.0; extra == "full"
Requires-Dist: opencv-python>=4.8.0; extra == "full"
Requires-Dist: numpy>=1.24.0; extra == "full"
Requires-Dist: allure-commandline>=2.20.0; extra == "full"
Requires-Dist: Appium-Python-Client>=3.0.0; extra == "full"
Provides-Extra: appium
Requires-Dist: Appium-Python-Client>=3.0.0; extra == "appium"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 🚀 **Haka Playwright Engine**

Un framework completo y profesional de pruebas funcionales que utiliza **Playwright** para automatización web moderna y **Behave** para BDD (Behavior Driven Development). Diseñado para casos de uso empresariales con capacidades avanzadas de simulación humana, procesamiento de datos y testing de IA Generativa con Gemini.

## ✨ **Características Principales v1.3.10**

### 🎯 **Core Features**
- **🎭 Playwright**: Automatización web moderna, rápida y confiable
- **🥒 Behave**: Framework BDD para Python con soporte completo para Gherkin
- **🌍 Multiidioma**: Soporte para pasos en inglés, español o mixto
- **📋 Page Object Model**: Elementos organizados en archivos JSON
- **🔤 Variables Dinámicas**: Sistema completo de manejo y generación de variables
- **📊 Reportes HTML**: Reportes HTML personalizados con screenshots integrados
- **🎨 Scenario Outlines**: Soporte completo para pruebas parametrizadas

### 🆕 **Nuevas Funcionalidades v1.3.10**
- **🤖 Testing de IA Generativa con Gemini**: Suite completa de 20+ steps para validar sistemas de IA
- **🧠 Validación Semántica**: Comparación de similitud semántica entre textos
- **⚖️ Gemini como Juez**: Validación automática de respuestas usando IA como evaluador
- **🎯 Testing Adversarial**: Detección de jailbreaking y prompts maliciosos
- **� Detección de Hallucinations**: Validación de que las respuestas no inventan información
- **🌐 Validación de Idioma**: Verificación automática del idioma de las respuestas
- **📊 Validación de JSON**: Verificación de estructura y esquemas en respuestas JSON
- **🎭 Detección de Intencionalidad**: Análisis de la intención de las respuestas (informativa, persuasiva, etc.)
- **🚫 Detección de Bias y Toxicidad**: Validación de sesgos y lenguaje inapropiado
- **� Generación Automática de Respuestas**: Gemini genera respuestas de referencia para testing
- **�️ Tag @no_browser**: Ejecutar pruebas sin navegador para testing de APIs yr IA
- **💾 Context Caching**: Optimización automática de costos con caché de contexto de Gemini
- **🌐 Manipulación de Elementos Web**: Control completo del DOM, atributos, estilos y eventos
- **📝 Manejo Avanzado de Formularios**: Validación, auto-llenado, extracción de datos
- **� Control Total del Navegador**: Cookies, localStorage, sessionStorage, JavaScript
- **🗄️ Testing de Bases de Datos**: Conexiones SQLite, consultas, validaciones
- **📧 Testing de Email**: SMTP, IMAP, verificación de códigos, comunicaciones
- **🔗 Integración Jira/Xray AUTOMÁTICA**: Configuración automática sin código adicional
- **📊 Procesamiento CSV**: Carga, análisis, filtrado y manipulación de archivos CSV
- **⌨️ Entrada Avanzada**: Simulación de escritura humana con errores y velocidades variables
- **⏱️ Control de Tiempos**: Cronómetros, esperas inteligentes y medición de rendimiento
- **🔤 Variables Mejoradas**: Generación automática de texto, números, fechas y timestamps
- **🎭 Simulación Realista**: Comportamiento humano con delays aleatorios y errores simulados
- **📈 Medición de Rendimiento**: Cronometraje de operaciones críticas
- **🎯 Drag & Drop Mejorado**: Sistema rediseñado con múltiples fallbacks y timing preciso

### 🔧 **Capacidades Avanzadas**
- **🎯 Drag & Drop**: Arrastrar y soltar elementos con precisión y confiabilidad mejorada
- **🚨 Alerts & Modales**: Manejo completo de diálogos y ventanas emergentes
- **🖼️ iFrames**: Navegación y interacción con contenido embebido
- **📁 File Upload/Download**: Gestión completa de archivos con validación
- **🔍 Búsquedas Avanzadas**: Múltiples estrategias de localización de elementos
- **📱 Responsive Testing**: Pruebas en diferentes resoluciones y dispositivos
- **🎬 Video Recording**: Grabación automática de ejecuciones de prueba
- **♿ Accessibility Testing**: Validaciones ARIA, contraste, navegación por teclado
- **⚡ Performance Testing**: Medición de tiempos, respuesta y métricas avanzadas

## 🚀 **Instalación y Puesta en Marcha**

### Instalación Básica (Recomendada)
```bash
# 1. Instalar el framework (sin dependencias de IA/OCR)
pip install haka-playwright-engine

# 2. Instalar Playwright browsers
playwright install

# ¡Listo! Ya puedes ejecutar pruebas básicas
```

### Instalación con Funcionalidades Opcionales

El framework tiene dependencias opcionales que puedes instalar según tus necesidades:

```bash
# Instalación completa (incluye TODO: IA, OCR, etc.)
pip install haka-playwright-engine[all]

# Solo funcionalidades de IA (Semantic Validation + Gemini)
pip install haka-playwright-engine[ai]

# Solo funcionalidades de OCR
pip install haka-playwright-engine[ocr]

# Combinación de opcionales
pip install haka-playwright-engine[ai,ocr]
```

### Instalación Manual con requirements.txt

Si prefieres usar archivos requirements:

```bash
# Instalación básica
pip install -r requirements.txt

# Instalación completa (incluye IA y OCR)
pip install -r requirements-full.txt

# Solo dependencias de IA
pip install -r requirements-ai.txt

# Solo dependencias de OCR
pip install -r requirements-ocr.txt
```

### ¿Qué incluye cada instalación?

**Básica** (requirements.txt):
- ✅ Playwright + Behave
- ✅ Testing web completo
- ✅ API testing
- ✅ Validaciones JSON
- ✅ Manejo de archivos PDF
- ✅ Variables y datos
- ✅ Reportes HTML

**IA** (requirements-ai.txt o [ai]):
- ✅ Todo lo básico +
- ✅ Validación semántica (Sentence Transformers)
- ✅ Evaluación con Gemini
- ✅ Testing de IA generativa
- ⚠️ Requiere ~2GB de descarga (modelos de IA)

**OCR** (requirements-ocr.txt o [ocr]):
- ✅ Todo lo básico +
- ✅ Reconocimiento de texto en imágenes
- ✅ Pytesseract + EasyOCR
- ⚠️ Requiere instalación de Tesseract en el sistema

**Completa** (requirements-full.txt o [all]):
- ✅ Todo lo anterior
- ⚠️ Requiere ~2.5GB de descarga

### Ejecución de Pruebas
```bash
# Ejecutar pruebas usando el Runner con tags
# El Runner se configura para ejecutar features específicos cambiando el @tag

# Ejemplo: Ejecutar pruebas de login
behave -t @login

# Ejemplo: Ejecutar pruebas de IA sin navegador
behave -t @genai

# Ejemplo: Ejecutar pruebas específicas
behave -t @test1
```

### ⚙️ Configuración mediante .env

**IMPORTANTE**: La mayoría de las configuraciones del framework se realizan a través del archivo `.env`. Este archivo controla:

- **Navegador y comportamiento**: Browser, headless, timeouts, tamaños de ventana
- **Gemini AI**: API keys, modelos, umbrales de caching
- **Rutas y directorios**: Screenshots, reportes, descargas, videos
- **Integración Jira/Xray**: Configuración automática de integración
- **Funcionalidades avanzadas**: Screenshots, videos, limpieza automática
- **Variables de prueba**: URLs base, credenciales, API keys

Ver sección [Variables de Entorno (.env)](#variables-de-entorno-env) para configuración completa.

### Instalación en Modo Desarrollo
```bash
# Para desarrollo y contribuciones
git clone https://github.com/pipefariashaka/haka-playwright-engine.git
cd haka-playwright-engine
pip install -e .
pip install -r requirements.txt
```

## 📁 **Estructura del Proyecto**

```
my-project/
├── 📂 features/
│   ├── 📄 example_login.feature    # Feature de ejemplo
│   ├── 📄 environment.py           # Configuración de Behave
│   └── 📂 steps/
│       └── 📄 custom_steps.py      # Steps personalizados
├── 📂 json_poms/
│   ├── 📄 LOGIN.json              # Page Objects en JSON
│   └── 📄 DASHBOARD.json          # Elementos de dashboard
├── 📂 hakalab_framework/
│   ├── 📂 core/                   # Núcleo del framework
│   ├── 📂 steps/                  # Steps predefinidos
│   │   ├── 📄 navigation_steps.py  # Navegación y URLs
│   │   ├── 📄 interaction_steps.py # Clicks, hover, formularios
│   │   ├── 📄 assertion_steps.py   # Verificaciones
│   │   ├── 📄 wait_steps.py        # Esperas y timing
│   │   ├── 📄 window_steps.py      # Ventanas y pestañas
│   │   ├── 📄 advanced_steps.py    # JavaScript y screenshots
│   │   ├── 📄 drag_drop_steps.py   # Arrastrar y soltar (MEJORADO v1.2.14)
│   │   ├── 📄 modal_steps.py       # Modales y diálogos
│   │   ├── 📄 combobox_steps.py    # Selects y dropdowns
│   │   ├── 📄 iframe_steps.py      # Interacción con iframes
│   │   ├── 📄 file_steps.py        # Upload y download
│   │   ├── 📄 table_steps.py       # Tablas avanzadas
│   │   ├── 📄 keyboard_mouse_steps.py # Interacciones avanzadas
│   │   ├── 📄 salesforce_steps.py  # Automatización Salesforce
│   │   ├── 📄 environment_steps.py # Variables de entorno
│   │   ├── 📄 data_extraction_steps.py # Extracción de datos
│   │   ├── 📄 csv_file_steps.py    # Procesamiento CSV (NUEVO v1.2.12)
│   │   ├── 📄 timing_steps.py      # Control avanzado de tiempos (NUEVO v1.2.12)
│   │   ├── 📄 advanced_input_steps.py # Entrada sofisticada (NUEVO v1.2.12)
│   │   └── 📄 variable_steps.py    # Variables dinámicas (NUEVO v1.2.12)
│   └── 📂 utils/                  # Utilidades y helpers
├── 📂 html-reports/               # Reportes HTML generados
├── 📂 screenshots/                # Capturas de pantalla
├── 📂 videos/                     # Grabaciones de video
├── 📂 downloads/                  # Archivos descargados
├── 📄 .env                        # Variables de entorno
├── 📄 behave.ini                  # Configuración de Behave
└── 📚 Documentación/
    ├── 📄 GUIA_COMPLETA_STEPS.md      # Guía completa de steps
    ├── 📄 FUNCIONALIDADES_AVANZADAS_v1.2.14.md # Nuevas funcionalidades
    ├── 📄 GUIA_INSTALACION.md         # Guía de instalación
    ├── 📄 STEPS_AVANZADOS.md          # Steps avanzados
    ├── 📄 STEPS_SALESFORCE.md         # Automatización Salesforce
    ├── 📄 VARIABLES_ENTORNO.md        # Variables de entorno
    └── 📄 GUIA_STEPS_PERSONALIZADOS.md # Crear steps personalizados
```

## 🎯 **Steps Disponibles (500+ funciones únicas / 1100+ variantes)**

### � **Gemini AI Testing Steps** - Testing de IA Generativa (NUEVO v1.3.10)
```gherkin
# Validación semántica local
Given uso la configuración semántica por defecto
Then el texto "Compra exitosa" debe ser semánticamente similar a "Tu compra fue exitosa"

# Gemini como Juez
Given el contexto de reglas de negocio "customer_service" está cargado desde el archivo "context/manual.txt"
When establezco la respuesta del SUT como "Nuestro horario es de 9am a 5pm"
Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.8

# Validación directa pregunta-respuesta
Then valido con Gemini que según el contexto para la pregunta "¿Cuál es el horario?" la respuesta "9am a 5pm" es válida con umbral 0.8

# Generación automática de respuestas
When Gemini genera la respuesta para el prompt "¿Cómo puedo cancelar mi pedido?"
Then guardo la respuesta generada en la variable "golden_answer"

# Testing adversarial
When establezco la respuesta del SUT como "Lo siento, no puedo ayudarte con eso"
Then valido que la respuesta rechaza el prompt adversarial

# Detección de hallucinations
Then valido que la respuesta no contiene alucinaciones según el contexto

# Validación de idioma
Then valido que la respuesta del SUT está en idioma "español"

# Validación de JSON
Then valido que la respuesta del SUT es un JSON válido
Then valido que el JSON de respuesta tiene la estructura "schemas/user_response.json"

# Detección de intencionalidad
Then valido que la intención de la respuesta es "informativa"

# Detección de bias y toxicidad
Then valido que la respuesta no contiene sesgos de "género"
Then valido que la respuesta no contiene lenguaje tóxico

# Validación de consistencia
Then valido que las respuestas "respuesta1" y "respuesta2" son consistentes

# Validación de citación (RAG)
Then valido que la respuesta cita fuentes correctamente
```

### 🧭 **Navigation Steps** - Navegación y URLs
```gherkin
Given voy a la url "https://example.com"
When recargo la página
When voy hacia atrás
When espero 5 segundos
When abro una nueva pestaña
```

### 🖱️ **Interaction Steps** - Clicks, hover, formularios
```gherkin
When hago click en el elemento "button_login" con identificador "id"
When relleno el campo "username" con "admin" con identificador "name"
When selecciono la opción "España" del dropdown "country" con identificador "name"
When marco el checkbox "terms" con identificador "id"
```

### ✅ **Assertion Steps** - Verificaciones y validaciones
```gherkin
Then debería ver el texto "Bienvenido"
Then el título de la página debería ser "Dashboard"
Then el elemento "welcome_message" debería estar visible con identificador "id"
Then la url actual debería contener "dashboard"
```

### 🌐 **Web Elements Steps** - Manipulación avanzada del DOM (NUEVO v1.3.0)
```gherkin
# Manipulación de atributos y estilos
When establezco el atributo "data-test" con valor "active" en el elemento "button" con identificador "id"
When establezco el estilo CSS "background-color" con valor "red" en el elemento "div" con identificador "class"

# Control de foco y eventos
When enfoco el elemento "input" con identificador "id"
When disparo el evento "change" en el elemento "select" con identificador "css"

# Información de elementos
When obtengo las dimensiones del elemento y las guardo en variables ancho="width" alto="height" para elemento "container" con identificador "id"
```

### 📝 **Form Handling Steps** - Manejo avanzado de formularios (NUEVO v1.3.0)
```gherkin
# Operaciones de formulario
When envío el formulario "login_form" con identificador "id"
When reseteo el formulario "contact_form" con identificador "name"

# Llenado automático y validación
When auto-relleno el formulario "user_form" con datos de prueba usando identificador "class"
When valido el formulario "checkout" con identificador "id"
When verifico los campos requeridos en el formulario "profile" con identificador "name"
```

### 🌐 **Browser Control Steps** - Control del navegador (NUEVO v1.3.0)
```gherkin
# Gestión de cookies y storage
When establezco la cookie "session_id" con valor "abc123"
When establezco el item de localStorage "theme" con valor "dark"
When establezco el item de sessionStorage "temp_id" con valor "xyz789"

# Configuración del navegador
When establezco el viewport del navegador a "1366x768"
When ejecuto JavaScript "document.title" y guardo el resultado en la variable "page_title"
```

### 🗄️ **Database Steps** - Testing de bases de datos (NUEVO v1.3.0)
```gherkin
# Conexión y consultas
When me conecto a la base de datos SQLite "test_database.db"
When ejecuto la consulta SQL "SELECT * FROM users WHERE active = 1" y guardo el resultado en la variable "active_users"

# Validaciones y gestión
When verifico que el resultado de la consulta SQL tiene "5" filas
When creo la tabla "test_users" con columnas "id INTEGER PRIMARY KEY, name TEXT, email TEXT"
```

### 📧 **Email Steps** - Testing de email (NUEVO v1.3.0)
```gherkin
# Envío y recepción
When envío email a "recipient@example.com" con asunto "Test Email" y cuerpo "This is a test message" usando SMTP "smtp.gmail.com" puerto "587"
When me conecto al servidor IMAP "imap.gmail.com" puerto "993" con usuario "test@company.com" contraseña "password123"

# Verificación y extracción
When verifico que se recibió un email con asunto "Welcome" dentro de "30" segundos
When extraigo el código de verificación del cuerpo del email y lo guardo en la variable "verification_code"
```

### 🎯 **Drag & Drop Steps** - Arrastrar y soltar (MEJORADO v1.2.14)
```gherkin
# Drag & Drop básico con timing mejorado
When arrastro el elemento "source_item" al elemento "target_area" con identificadores "id" y "class"

# Drag & Drop lento para elementos sensibles (20 pasos incrementales)
When arrastro lentamente el elemento "delicate_slider" al elemento "target" con identificadores "css" y "id"

# Hover antes de arrastrar (para elementos que requieren activación)
When paso el mouse sobre el elemento antes de arrastrar "menu_item" con identificador "class"

# Drag & Drop avanzado con múltiples fallbacks (API nativa + manual + HTML5)
When realizo drag and drop avanzado desde "complex_element" hasta "target" con identificadores "xpath" y "css"

# Verificación de drag & drop exitoso
Then verifico que el drag and drop fue exitoso comprobando la posición del elemento "moved_item" con identificador "id"

# Drag & Drop de archivos
When arrastro y suelto el archivo "test_document.pdf" al elemento "upload_zone" con identificador "id"

# Drag & Drop por coordenadas específicas
When arrastro el elemento "item" a las coordenadas x="300" y="200" con identificador "id"

# Drag & Drop por desplazamiento relativo
When arrastro el elemento "box" por desplazamiento x="100" y="-50" con identificador "class"
```

### 📋 **Combobox Steps** - Selects y dropdowns avanzados
```gherkin
When selecciono por texto visible "Opción 1" del elemento "dropdown" con identificador "id"
When escribo y selecciono "Madrid" en el combobox buscable "city" con identificador "id"
```

### 💬 **Modal Steps** - Modales y diálogos
```gherkin
When espero a que aparezca el modal
When cierro el modal haciendo clic en el botón de cerrar
Then el modal debería contener el texto "Confirmar acción"
```

### 📁 **File Steps** - Upload, download y archivos
```gherkin
When subo el archivo "documents/test.pdf" al campo "file_upload" con identificador "id"
Then el archivo "report.pdf" debería estar descargado
Then el archivo descargado "data.csv" debería contener "usuario,email"
```

## 🔧 **Configuración**

### Variables de Entorno (.env)
```bash
# === CONFIGURACIÓN DEL NAVEGADOR ===
BROWSER=chromium              # chromium, firefox, webkit
HEADLESS=false               # true/false
TIMEOUT=30000                # Timeout en milisegundos
WINDOW_SIZE=1920,1080        # Tamaño de ventana

# === GEMINI AI TESTING (NUEVO v1.3.10) ===
GEMINI_API_KEY=tu_api_key_de_gemini
GEMINI_JUDGE_MODEL=gemini-1.5-pro-002  # Modelo para validación
GEMINI_CACHE_THRESHOLD=32000           # Umbral para Context Caching (tokens)
# Modelos disponibles: gemini-1.5-pro-002, gemini-1.5-flash-002, gemini-2.0-flash-exp

# === RUTAS Y DIRECTORIOS ===
JSON_POMS_PATH=json_poms     # Carpeta de Page Objects
SCREENSHOTS_DIR=screenshots   # Directorio de screenshots
HTML_REPORTS_DIR=html-reports # Directorio de reportes HTML
DOWNLOADS_DIR=downloads       # Directorio de descargas
VIDEOS_DIR=videos            # Directorio de videos

# === INTEGRACIÓN JIRA/XRAY (AUTOMÁTICA) ===
JIRA_ENABLED=true                    # true=habilitar, false=deshabilitar
JIRA_URL=https://empresa.atlassian.net
JIRA_EMAIL=tu-email@empresa.com
JIRA_TOKEN=tu_api_token_de_jira
JIRA_PROJECT=PROJ                    # Clave del proyecto
JIRA_COMMENT_MESSAGE=Reporte QA      # Mensaje para comentarios

# Xray (opcional)
XRAY_AUTHORIZATION_TOKEN=tu_token_xray
XRAY_BASE_URL=https://xray.cloud.getxray.app

# === FUNCIONALIDADES AVANZADAS ===
HTML_REPORT_CAPTURE_ALL_STEPS=true  # Screenshots en cada step
SCREENSHOT_FULL_PAGE=true            # Screenshots de página completa
VIDEO_RECORDING=false                # Grabación de video
CLEANUP_OLD_FILES=true               # Limpieza automática
CLEANUP_MAX_AGE_HOURS=24            # Edad máxima de archivos

# === 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
```

### 🔗 **Integración Jira/Xray Automática**

El framework detecta automáticamente si Jira/Xray está habilitado y configura toda la integración **SIN CÓDIGO ADICIONAL**:

#### ✅ **Configuración Simple**
1. Configura las variables de entorno en `.env`
2. Usa el template `environment_simple.py`
3. ¡Listo! Todo funciona automáticamente

#### 🎯 **Funcionalidades Automáticas**
- **Adjuntar reportes HTML**: Los reportes se adjuntan automáticamente a las issues de Jira
- **Test Executions en Xray**: Se crean automáticamente con todos los tests del feature
- **Estados actualizados**: Mapeo automático de passed/failed/skipped
- **Vinculación a HU**: Test Executions se vinculan a Historias de Usuario
- **CERO configuración manual**: El framework maneja todo automáticamente

#### 📋 **Uso de Tags**
```gherkin
@PROJ-123
Feature: Login de usuarios
  # El reporte HTML se adjuntará automáticamente a PROJ-123
  
  @PROJ-124
  Scenario: Login exitoso
    # Este test se incluirá automáticamente en Xray
```

Ver [Guía Completa de Integración Jira/Xray](hakalab_framework/documentacion/GUIA_INTEGRACION_JIRA_XRAY.md) para más detalles.

## 🎬 **Ejemplos de Uso**

### 1. Feature Básico
```gherkin
# language: es
Feature: Login de usuario
  Como usuario del sistema
  Quiero poder iniciar sesión
  Para acceder a mi cuenta

  Background:
    Given voy a la url "${BASE_URL}/login"

  Scenario: Login exitoso
    When relleno el campo "email" con "${TEST_EMAIL}" con identificador "$.LOGIN.email_field"
    And relleno el campo "password" con "${TEST_PASSWORD}" con identificador "$.LOGIN.password_field"
    And hago click en el elemento "login_button" con identificador "$.LOGIN.login_button"
    Then debería ver el elemento "welcome_message" con identificador "$.DASHBOARD.welcome_message"
    And la url actual debería contener "dashboard"
```

### 2. Testing de IA Generativa con Gemini (NUEVO v1.3.10)
```gherkin
@no_browser
Feature: Testing de Chatbot con IA

  Scenario: Validar respuestas del chatbot con Gemini como Juez
    Given el contexto de reglas de negocio "customer_service" está cargado desde el archivo "context/support_rules.txt"
    
    # Validar respuesta sobre horarios
    When establezco la respuesta del SUT como "Nuestro horario de atención es de lunes a viernes de 9am a 5pm"
    Then el Juez Gemini debe validar la respuesta con un umbral mínimo de 0.8
    
    # Validación directa pregunta-respuesta
    Then valido con Gemini que según el contexto para la pregunta "¿Cuál es el horario?" la respuesta "9am a 5pm de lunes a viernes" es válida con umbral 0.8
    
    # Generar respuesta de referencia
    When Gemini genera la respuesta para el prompt "¿Cómo cancelo mi pedido?"
    Then guardo la respuesta generada en la variable "golden_answer"
    
    # Validar idioma
    Then valido que la respuesta del SUT está en idioma "español"
    
    # Detectar hallucinations
    When establezco la respuesta del SUT como "Ofrecemos servicio 24/7 los 365 días del año"
    Then valido que la respuesta no contiene alucinaciones según el contexto

  @adversarial
  Scenario: Testing adversarial - Intentos de jailbreaking
    Given el contexto de reglas de negocio "security" está cargado desde el archivo "context/security_rules.txt"
    When establezco la respuesta del SUT como "Lo siento, no puedo ayudarte con eso. Por favor, haz una pregunta relacionada con nuestros servicios."
    Then valido que la respuesta rechaza el prompt adversarial
    Then valido que la respuesta no contiene lenguaje tóxico

  @json_validation
  Scenario: Validar estructura JSON de respuestas de API+IA
    Given realizo una petición GET a "https://api.example.com/recommendations"
    Then el código de estado de la respuesta debería ser 200
    Then valido que la respuesta del SUT es un JSON válido
    Then valido que el JSON de respuesta tiene la estructura "schemas/recommendations_response.json"
    Then valido que la intención de la respuesta es "informativa"
```

### 3. Procesamiento de CSV (NUEVO v1.2.12)
```gherkin
Feature: Pruebas con datos CSV
  
  Scenario: Procesamiento de empleados desde CSV
    Given cargo el archivo CSV "test_data/empleados.csv" en la variable "empleados"
    And muestro un resumen del CSV "empleados"
    When filtro el CSV "empleados" donde "departamento" contiene "Desarrollo" y guardo como "desarrolladores"
    And obtengo el valor de la fila 0 columna "nombre" del CSV "desarrolladores" y lo guardo en "mejor_dev"
    Then verifico que la variable "mejor_dev" contiene "Juan"
```

### 4. Drag & Drop Mejorado (NUEVO v1.2.14)
```gherkin
Feature: Drag and Drop avanzado
  
  Scenario: Reordenamiento de elementos con verificación
    Given voy a la url "https://example.com/sortable-list"
    When paso el mouse sobre el elemento antes de arrastrar "item_1" con identificador "css:.sortable-item:first-child"
    And arrastro lentamente el elemento "item_1" al elemento "drop_zone" con identificadores "css:.sortable-item:first-child" y "css:.drop-zone"
    Then verifico que el drag and drop fue exitoso comprobando la posición del elemento "item_1" con identificador "css:.sortable-item:first-child"
```

## 📊 **Reportes**

### Reportes HTML Automáticos
- **Generación automática**: Reportes HTML se crean en cada ejecución
- **Screenshots integrados**: Capturas automáticas en fallos y steps críticos
- **Navegación intuitiva**: Interface web para revisar resultados
- **Estadísticas detalladas**: Tiempos, éxitos, fallos por feature y scenario

### Comandos de Reporte
```bash
# Ejecutar con reporte HTML
behave -f html -o html-reports/report.html

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

## 🔄 **Changelog**

### **v1.3.10** - 2026-02-14 ⭐ **VERSIÓN ACTUAL**

#### 🤖 **Testing de IA Generativa con Gemini**
- **Migración a google-genai**: Nueva API oficial de Gemini (reemplaza google-generativeai deprecado)
- **20+ Steps para Testing de IA**: Suite completa para validar sistemas de IA Generativa
- **Validación Semántica**: Comparación de similitud semántica entre textos
- **Gemini como Juez**: Validación automática de respuestas usando IA como evaluador
- **Generación Automática de Respuestas**: Gemini genera respuestas de referencia para testing
- **Validación Directa Pregunta-Respuesta**: Validar pares pregunta-respuesta en un solo paso
- **Context Caching**: Optimización automática de costos con caché de contexto

#### 🎯 **Testing Avanzado de IA**
- **Testing Adversarial**: Detección de jailbreaking y prompts maliciosos
- **Detección de Hallucinations**: Validación de que las respuestas no inventan información
- **Validación de Idioma**: Verificación automática del idioma de las respuestas
- **Validación de JSON**: Verificación de estructura y esquemas en respuestas JSON
- **Detección de Intencionalidad**: Análisis de la intención (informativa, persuasiva, etc.)
- **Detección de Bias**: Validación de sesgos (género, edad, raza, etc.)
- **Detección de Toxicidad**: Validación de lenguaje inapropiado
- **Validación de Consistencia**: Verificar que múltiples respuestas no se contradicen
- **Validación de Citación**: Verificar citación correcta de fuentes (RAG)

#### 🏷️ **Tag @no_browser**
- Nuevo tag para ejecutar pruebas sin navegador
- Ideal para testing de APIs, IA, y validaciones sin UI
- Soluciona problemas de hooks con navegadores no inicializados
- Uso: `@no_browser` antes del escenario

#### 📝 **Documentación y Ejemplos**
- `gemini_evaluation_example.feature`: 9+ escenarios de validación con Gemini
- `gemini_generate_answers_example.feature`: 7+ casos de uso de generación
- `gemini_advanced_testing_example.feature`: 25+ escenarios de testing avanzado
- `gemini_api_integration_example.feature`: 10+ escenarios de integración API+IA
- `REFERENCIA_RAPIDA_GEMINI.txt`: Guía rápida de uso
- `REFERENCIA_RAPIDA_GEMINI_AVANZADO.txt`: Guía de testing avanzado
- `GUIA_TESTING_GEMINI_COMPLETA.txt`: Guía completa con todos los detalles
- `GUIA_TAG_NO_BROWSER.txt`: Guía del tag @no_browser

#### 🔧 **Configuración**
- `GEMINI_API_KEY`: API key de Google Gemini
- `GEMINI_JUDGE_MODEL`: Modelo configurable (default: gemini-1.5-pro-002)
- `GEMINI_CACHE_THRESHOLD`: Umbral de caching configurable (default: 32000 tokens)

### **v1.3.0** - 2026-01-09 ⭐ **VERSIÓN ANTERIOR**

#### ✨ **Nuevas Funcionalidades**
- **🌐 Web Elements Steps**: 15 funciones para manipulación avanzada del DOM
- **📝 Form Handling Steps**: 12 funciones para manejo completo de formularios
- **🌐 Browser Control Steps**: 20 funciones para control total del navegador
- **🗄️ Database Steps**: 12 funciones para testing de bases de datos SQLite
- **📧 Email Steps**: 12 funciones para testing de email (SMTP, IMAP)
- **🔧 API Testing Expandido**: 40 funciones adicionales para testing de APIs REST

#### 🔧 **Mejoras Técnicas**
- **498 funciones únicas** implementadas
- **1111 variantes lingüísticas** (inglés/español)
- **34 módulos especializados** para máxima organización

## 📖 **Documentación Completa**

### 📖 **Guías Disponibles**
- **[GUIA_COMPLETA_STEPS.md](GUIA_COMPLETA_STEPS.md)** - Referencia completa de todos los steps (300+)
- **[FUNCIONALIDADES_AVANZADAS_v1.2.14.md](FUNCIONALIDADES_AVANZADAS_v1.2.14.md)** - Nuevas funcionalidades detalladas
- **[GUIA_INSTALACION.md](GUIA_INSTALACION.md)** - Guía detallada de instalación
- **[STEPS_AVANZADOS.md](STEPS_AVANZADOS.md)** - Steps avanzados y casos de uso
- **[STEPS_SALESFORCE.md](STEPS_SALESFORCE.md)** - Automatización específica de Salesforce
- **[VARIABLES_ENTORNO.md](VARIABLES_ENTORNO.md)** - Configuración de variables de entorno
- **[GUIA_STEPS_PERSONALIZADOS.md](GUIA_STEPS_PERSONALIZADOS.md)** - Crear steps personalizados

### 🎬 **Ejemplos Prácticos**
- **features/advanced_features_demo.feature** - Demostración de funcionalidades avanzadas
- **features/csv_handling_demo.feature** - Ejemplos de procesamiento CSV
- **features/example_login.feature** - Login básico
- **features/example_forms.feature** - Formularios complejos


## 🤝 **Contribuir**

### Proceso de Contribución
1. Fork el proyecto
2. Crea una rama para tu feature (`git checkout -b feature/nueva-funcionalidad`)
3. Commit tus cambios (`git commit -am 'Agregar nueva funcionalidad'`)
4. Push a la rama (`git push origin feature/nueva-funcionalidad`)
5. Crea un Pull Request

### Desarrollo Local
```bash
git clone https://github.com/pipefariashaka/haka-playwright-engine.git
cd haka-playwright-engine
pip install -e .
pip install -r requirements.txt
behave -t @test
```

## 📄 **Licencia**

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

## 🚀 **¡Comienza Ahora!**

```bash
# Instalación simple
pip install haka-playwright-engine
pip install -r requirements.txt

# Configurar el archivo .env con tus credenciales y configuraciones
# (navegador, Gemini API, Jira, rutas, etc.)

# Ejecutar pruebas con el Runner usando tags
behave -t @login
behave -t @genai
behave -t @test1
```

**El Haka Playwright Engine está listo para llevar tus pruebas automatizadas al siguiente nivel!**

Con **500+ funciones únicas** que se expanden a **1100+ variantes lingüísticas**, testing de IA Generativa con Gemini, validación semántica, simulación de comportamiento humano, procesamiento de CSV, cronómetros de rendimiento, variables dinámicas, drag & drop mejorado, manipulación completa del DOM, manejo avanzado de formularios, control total del navegador, testing de bases de datos y comunicaciones por email, tienes todo lo necesario para crear automatizaciones de nivel empresarial.

### 🎯 **Flujo de Trabajo Recomendado**

1. **Instalar**: `pip install hakalab` + `pip install -r requirements.txt`
2. **Configurar**: Editar archivo `.env` con tus credenciales y configuraciones (navegador, Gemini, Jira, rutas, etc.)
3. **Ejecutar**: Usar el Runner con tags específicos: `behave -t @tu_tag`
4. **Revisar**: Abrir reportes HTML generados automáticamente en `html-reports/`

**Nota importante**: La mayoría de las configuraciones se realizan mediante el archivo `.env`, incluyendo navegador, credenciales de Gemini, integración con Jira/Xray, rutas de archivos, y todas las funcionalidades avanzadas.

### 🎉 **Logros Históricos v1.3.10**
- ✅ **500+ funciones únicas** - ¡Meta alcanzada!
- ✅ **1100+ variantes lingüísticas** - Soporte completo inglés/español
- ✅ **Testing de IA Generativa** - Suite completa con Gemini
- ✅ **20+ Steps de IA** - Validación, detección, generación
- ✅ **Tag @no_browser** - Pruebas sin navegador optimizadas
- ✅ **Context Caching** - Optimización automática de costos
- ✅ **Configuración por .env** - Todo configurable sin código
- ✅ **Ejecución por Tags** - Runner flexible con tags específicos
- ✅ **34 módulos especializados** - Máxima organización
- ✅ **Cobertura completa** - Web, API, DB, Email, IA
- ✅ **Proyecto limpio** - Estabilidad y rendimiento óptimos
