🚀 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.5.0

Lo nuevo en esta versión

• Haka MCP: servidor Model Context Protocol integrado — el catálogo de steps, features, POMs y reportes del proyecto quedan disponibles como tools dentro de cualquier asistente de IA (Kiro, Claude Desktop, Cursor). Incluye navegación con estado (experimental): abrir un navegador real, capturar selectores verificados y generar escenarios @borrador desde el chat.
• haka-steps corregido: ahora busca en el catálogo real de +1600 steps (antes usaba una lista de 13 ejemplos hardcodeados y no encontraba nada).
• haka-run corregido: ya no falla con ModuleNotFoundError cuando el binario behave no está en el venv.
• haka-ui: nuevo alias homologado del comando hakalab-ui.
• Guía CLI completa (GUIA_HAKA_CLI.md): documentación de los 12 comandos del framework con todas sus opciones.

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

Funcionalidades Avanzadas

• ** 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)

# 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:

# 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]

# Salesforce API + frontdoor.jsp
pip install "haka-playwright-engine[salesforce]"

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

Consulta hakalab_framework/documentacion/GUIA_SALESFORCE_FRONTDOOR.md para configuración, steps, seguridad y límites de MFA, y GUIA_SALESFORCE_JWT_BEARER.md para el procedimiento de habilitación en la org paso a paso.

Ejemplo mínimo para varios usuarios Salesforce por ambiente:

SF_API_ENABLED=true
SF_LOGIN_MODE=frontdoor
SF_API_AUTH_MODE=oauth_jwt_bearer
SF_API_DOMAIN=test

# Una sola Connected App con firma digital sirve a todos los perfiles.
SF_OAUTH_CLIENT_ID=<consumer_key>
SF_OAUTH_TOKEN_URL=https://mi-org--sit.sandbox.my.salesforce.com/services/oauth2/token
SF_JWT_PRIVATE_KEY_PATH=/ruta/segura/haka_sf.key

# Cada perfil entra como su propio usuario mediante el claim sub del JWT.
SF_PERFIL_UAT1_JWT_USERNAME=usuario.uat1@empresa.com.sit
SF_PERFIL_SIT1_JWT_USERNAME=usuario.sit1@empresa.com.sit

oauth_jwt_bearer conserva la identidad de cada perfil y es el flujo válido para frontdoor, porque el token mantiene contexto de usuario. oauth_client_credentials queda para escenarios de API sin navegador: su token pertenece al usuario Ejecutar como de la app y no abre sesión en la UI. La llave privada nunca se versiona; en CI se entrega como secreto en SF_JWT_PRIVATE_KEY.

En un feature se selecciona el perfil con Given inicio sesión con el usuario "UAT1". La sesión del mismo perfil se reutiliza dentro del proceso; los workers paralelos son aislados y deben usar usuarios separados si modifican datos concurrentemente.

Instalación Manual con requirements.txt

Si prefieres usar archivos requirements:

# 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

# 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) para configuración completa.

Instalación en Modo Desarrollo

# 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)

# 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

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

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

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)

# 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)

# 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)

# 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)

# 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)

# 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)

# 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

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

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

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)

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

# === JIRA + XRAY CLOUD ===
# JiraConfigPlugin aplica jira_config.json cuando JIRA_ENABLED=true.
JIRA_ENABLED=true
JIRA_URL=https://empresa.atlassian.net
JIRA_EMAIL=tu-email@empresa.com
JIRA_TOKEN=tu_api_token_de_jira
JIRA_PROJECT=PROJ
JIRA_COMMENT_MESSAGE=Reporte QA

# Xray Cloud es el único flujo Xray disponible.
XRAY_ENABLED=true
XRAY_AUTH_METHOD=client_credentials
XRAY_CLIENT_ID=tu_client_id_xray
XRAY_CLIENT_SECRET=tu_client_secret_xray
XRAY_BASE_URL=https://xray.cloud.getxray.app
# Opcional: tipos Jira con nombres localizados.
XRAY_TEST_ISSUE_TYPE=Test
XRAY_TEST_EXECUTION_ISSUE_TYPE=Test Execution
XRAY_TEST_PLAN_ISSUE_TYPE=Test Plan

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

🔗 Jira configurado + Xray Cloud

Jira y Xray Cloud funcionan de forma independiente o conjunta mediante el sistema de plugins; no existe un flujo Xray clásico.

• JiraConfigPlugin se habilita con JIRA_ENABLED=true y jira_config.json. Aplica adjuntos/comentarios a configuracion.tipos_adjuntos, actualiza campos por tipo y puede crear/vincular Bugs según la configuración.
• XrayCloudPlugin se habilita con XRAY_ENABLED=true. Actualiza los Test Runs y adjunta el HTML a los Test, Test Execution y Test Plan verificados en Jira.
• Ambos consultan Jira para resolver el tipo real de cada key antes de actuar. El orden de los tags nunca determina su rol.

📋 Uso de tags por tipo real

@EJ-1 @EJ-2 @EJ-3
Feature: Login de usuarios
  # EJ-1: Historia; EJ-2: Test Execution; EJ-3: Test Plan.
  # Los tres tipos se confirman mediante Jira.

  @EJ-4
  Scenario: Login exitoso
    # EJ-4 debe resolver como Test real para actualizar su Test Run en Xray.

Consulta la guía de Xray Cloud y configura las reglas Jira en jira_config.json.

🎬 Ejemplos de Uso

1. Feature Básico

# 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)

@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)

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)

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

# 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.4.29 - 2026-08-03 ⭐ VERSIÓN ACTUAL

🔧 Haka UI — Fix de empaquetado para PyPI

• Corregido el empaquetado del frontend dist para distribución via pip install haka-playwright-engine.
• Eliminado modo DEV del comando hakalab-ui.
• Búsqueda robusta del frontend en instalaciones normales y editables.

v1.4.28 - 2026-08-03

🖥️ Haka UI — Interfaz gráfica local para gestión de proyectos

• Nueva interfaz web local lanzada con hakalab-ui desde cualquier proyecto. FastAPI backend + Vite/React frontend empaquetados con el framework.
• Dashboard: Resumen del proyecto con gráficos donut y barras de la última ejecución (pass/fail/skipped).
• Features viewer: Vista por escenarios individuales (cards), Scenario Builder visual con catálogo de +700 pasos, selector de localizadores desde JSON POM, tabla de Examples editable, toggle Scenario/Outline.
• Page Objects editor: Visualización y edición de JSON POMs con CRUD completo.
• Runner: Selector de tags con buscador (por tag, feature o scenario), selector de navegador, modo headless, flujo de ejecución modal y salida en tiempo real con status por escenario.
• Reportes viewer: Reportes agrupados por ejecución, resumen JSON visual con detalle por step, visor HTML iframe, screenshots de pasos fallidos.
• Config editor: ~120 variables del .env con secciones colapsables, tooltips, booleans como select, sección "Integración con Test Managers".
• Integraciones: Editores visuales para Jira, Cassini, CI/CD y configuración de reportes (logos con upload a base64, color pickers).
• Sidebar colapsable con logo personalizable y versionado del engine.
• SPA routing completo: navegación directa por URL sin 404.
• Catálogo de pasos: Parseado en runtime desde la documentación del framework, siempre sincronizado con la versión instalada.

v1.4.27 - 2026-07-30

📸 Cassini — Screenshot por paso (evidencia por sub-paso)

• Ahora la integración con Cassini captura una evidencia por cada step Gherkin del escenario (no solo una general): tras ejecutarse cada paso se toma una captura y se adjunta a ese sub-paso.
• En Cassini cada sub-paso muestra su propia miniatura (con lightbox) junto a su estado. La captura del escenario reutiliza la del último paso, sin capturas extra.
• Se controla con el mismo flag CASSINI_SCREENSHOTS (por defecto activado; false lo desactiva por completo). Cambio retrocompatible.

v1.4.26 - 2026-07-30

🧩 Cassini — Paso a paso por escenario

• La integración con Cassini ahora reporta el detalle paso a paso (steps Gherkin) de cada escenario: por cada step se envía su keyword, nombre, estado, duración y, para los fallidos, la aserción o excepción.
• En Cassini cada escenario se muestra como un colapsable con su paso a paso, estado por step, evidencia y detalle de errores. La captura sigue siendo por escenario. Cambio retrocompatible, sin configuración nueva.

v1.4.25 - 2026-07-30

☁️ Salesforce — Consultas SOQL e integridad de objetos por API

• Nuevos pasos para consultar y validar la integridad de objetos de Salesforce (SOQL, campos, picklists, tipos de registro) vía API, sin navegador.
• Reutilizan tu perfil ya configurado (SF_PERFIL_<NOMBRE>_*): Given inicializo la API de Salesforce para el usuario "UAT1". No requieren variables ni API keys nuevas.

v1.4.24 - 2026-07-30

🐛 Fix — Reporte HTML: estado de escenarios y resumen

• Corregido un caso (visto en pruebas de API con Scenario Outline) en el que los escenarios aparecían como passed aun con un step fallido y el resumen "Scenarios" quedaba en 0/0/0.
• El reporte ahora deriva el estado de escenarios y features desde sus steps al generarse y recomputa el resumen, por lo que el HTML/JSON quedan correctos aunque el hook after_scenario no se ejecute. Incluye soft assertions y propaga el mensaje de error del step fallido.

v1.4.23 - 2026-07-29

🖼️ Screenshots en WebP

• Las capturas (web y mobile) ahora se guardan en WebP, reduciendo mucho su peso frente a PNG y manteniendo transparencia. Sin configuración.
• La conversión se hace con Pillow (ya incluido) con cadena de fallback WebP → PNG → JPG, para nunca perder el screenshot.

📱 Mobile — Abrir apps del dispositivo

• Nuevos pasos para abrir una app concreta del emulador/dispositivo por package/bundle id (abro la aplicación móvil con paquete "..."), por nombre visible desde el launcher (abro la aplicación "..." desde el dispositivo), o lanzando una actividad específica (lanzo la actividad "..." del paquete "...").
• Pasos para terminar una app por su id y verificar que está instalada.
• Nuevos métodos en AppiumManager: open_app, start_activity, open_app_by_name.

v1.4.21 - 2026-07-17

🤖 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_HAKA_CLI.md - Los 12 comandos del framework (haka-init, haka-run, haka-steps, haka-agent...) con todas sus opciones
• GUIA_HAKA_AGENT.md - Discovery automatizado: explorar una app y generar POMs, features y documentación
• GUIA_HAKA_MCP.md - Servidor MCP: el proyecto (steps, features, POMs, reportes) como tools dentro de tu asistente de IA
• CATALOGO_COMPLETO_STEPS.md - Los 1265 steps del framework, generados desde el código: si no está acá, no existe
• GUIA_TOOLTIPS_Y_PUNTERO.md - Tooltips (6 formas distintas), hover robusto y puntero interceptado
• GUIA_COMPLETA_STEPS.md - Referencia completa de todos los steps (300+)
• FUNCIONALIDADES_AVANZADAS_v1.2.14.md - Nuevas funcionalidades detalladas
• GUIA_INSTALACION.md - Guía detallada de instalación
• STEPS_AVANZADOS.md - Steps avanzados y casos de uso
• STEPS_SALESFORCE.md - Automatización específica de Salesforce
• VARIABLES_ENTORNO.md - Configuración de variables de entorno
• 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

🤖 Discovery Automatizado — Haka Agent

El comando haka-agent recorre una aplicación web, entiende qué hace, y genera documentación funcional, localizadores verificados y escenarios BDD ejecutables.

A diferencia de un generador basado solo en IA, el agente ejecuta primero y escribe el test después: cada acción se ejecuta en un navegador real, su efecto se observa comparando el estado antes y después, y recién entonces se sintetiza el escenario. Los selectores se prueban contra el DOM antes de escribirse en el POM.

# Agotar las casuísticas de una pantalla (sin enviar formularios)
haka-agent exhaustive --url https://miapp.com/formulario --dry-run

# Partir de una pantalla detrás de login y pasos previos:
# navegás a mano en tu Chrome y el agente adopta esa pestaña
haka-agent exhaustive --cdp-url http://localhost:9222 --dry-run

# Mapear la aplicación completa sin modificar nada
haka-agent explore --url https://miapp.com --read-only --autonomous

# Completar un objetivo concreto
haka-agent flow --url https://miapp.com --goal "crear un pedido nuevo"

# Detectar cambios respecto de una corrida anterior
haka-agent regression --url https://miapp.com --baseline discovery/graph.json

Genera tres artefactos: json_poms/ con selectores verificados y fallbacks, features/generated/ con escenarios etiquetados @verificado o @derivado según si se ejecutaron realmente, y discovery/ con la documentación funcional, el grafo de navegación y capturas.

Consulta la guía de Haka Agent para el detalle de los cuatro modos, opciones, modos de seguridad y flujo de trabajo recomendado.

🔴 Grabar desde tu navegador — Haka Engine Connector

El agente explora solo; el conector graba lo que vos hacés. Es una extensión de Chrome que captura tu interacción en tu propio navegador, con tu sesión ya iniciada, y genera el feature y el POM. No abre un navegador limpio ni te pide volver a loguearte, así que podés empezar a grabar a mitad de un flujo largo.

pip install 'haka-playwright-engine[connector]'

cd /ruta/a/tu/proyecto
haka-connector --path .

Después, en Chrome: abrís la extensión, elegís el proyecto que encontró sondeando los puertos locales, le das un nombre a la pantalla y grabás. Alt+clic sobre cualquier elemento agrega una validación.

El reparto de responsabilidades es lo que lo hace confiable: la extensión verifica en la página real que cada selector matchee un solo elemento (es la única que está dentro del DOM con tu sesión), y el servidor decide el ranking, las claves del POM y el texto de los steps reutilizando ElementIndex y ArtifactGenerator. Si ningún selector resulta único, el paso se omite con aviso en vez de dejar un localizador ambiguo que falle de forma intermitente meses después.

Funciona dentro de iframes: agrega los cambio al iframe por src que contiene y regreso al frame padre donde hacen falta.

El servidor escucha solo en 127.0.0.1, el proyecto se fija al arrancar (la ruta que venga en la petición se ignora), el CORS acepta únicamente orígenes chrome-extension:// y con --token auto se puede exigir un secreto compartido.

La extensión se distribuye por separado, en su propio repositorio. Las pruebas del servidor están en tests/connector/.

🖥️ Interfaz Gráfica — Haka UI

El framework incluye una interfaz web local para gestionar visualmente tu proyecto de pruebas. Se lanza con un solo comando y no requiere instalación adicional.

Lanzamiento

# Desde el directorio de tu proyecto (con el framework instalado)
haka-ui

# Opciones disponibles
haka-ui --port 9000          # Cambiar puerto (default: 8787)
haka-ui --path /ruta/proyecto # Apuntar a otro proyecto
haka-ui --no-browser          # No abrir navegador automáticamente

hakalab-ui sigue disponible como alias por compatibilidad, pero haka-ui es el comando recomendado (homologado con haka-init, haka-run, haka-agent, etc.).

Se abre automáticamente en http://localhost:8787.

Módulos disponibles

Scenario Builder

El Scenario Builder permite construir escenarios de forma visual:

• Catálogo de pasos: +700 pasos del framework organizados por categoría (Web, API, Mobile, GenAI, etc.) con buscador integrado
• Pasos reutilizados: Muestra pasos ya usados en otros features con badge de uso
• Selector de localizadores (POM): Botón "POM" que abre un modal para elegir localizadores existentes de JSON POMs o crear nuevos
• Edición inline: Cada paso tiene botón de edición (✎) para corregir texto sin re-agregar
• Tipo de escenario: Toggle entre Scenario y Scenario Outline
• Tabla de Examples: Crear/editar headers y filas, agregar columnas, eliminar filas — todo visual
• Reordenar pasos: Botones ↑↓ para mover pasos de posición

Características de la interfaz

• Sidebar colapsable: Click en el toggle para reducir a solo iconos (56px)
• Logo personalizable: Imagen en frontend/public/logo.png
• Dark theme: Paleta oscura (#0A0E1A) con acentos cyan (#00D4FF)
• SPA routing: Navegación directa por URL (ej: localhost:8787/features)
• Sin dependencias externas de UI: Iconos SVG inline, sin librerías de componentes

Requisitos

El comando hakalab-ui requiere fastapi y uvicorn instalados en el entorno:

pip install fastapi uvicorn

Si instalaste el framework con pip install haka-playwright-engine, ya los tienes.

🔌 Haka MCP — el proyecto dentro de tu asistente de IA

Servidor MCP que expone tu proyecto Haka (features, catálogo de steps, POMs, reportes) como herramientas que cualquier asistente compatible — Kiro, Claude Desktop, Cursor, etc. — puede invocar directamente durante una conversación, sin que tengas que salir del chat a correr comandos de CLI.

pip install haka-playwright-engine

El SDK MCP se instala automáticamente en Python 3.10+ como parte de las dependencias base. Registralo en el mcp.json de tu asistente apuntando al proyecto:

{
  "mcpServers": {
    "haka-engine": {
      "command": "haka-mcp",
      "cwd": "/ruta/a/tu-proyecto-de-pruebas"
    }
  }
}

Con eso el asistente puede, sin que se lo tengas que explicar cada vez:

Sobre la licencia: run_tests no reimplementa nada — llama al mismo runner.run_tests que usa haka-run, que dispara behave, que corre el hook de arranque del framework que valida la licencia. Si el proyecto no tiene una licencia válida configurada, la ejecución se bloquea exactamente igual que si hubieras corrido haka-run a mano; no hay forma de usar el MCP para saltarse esa validación. El resto de las tools son de solo lectura y no la disparan, igual que hoy no la disparan haka-steps o haka-validate.

Navegación con estado (EXPERIMENTAL): un segundo grupo de tools (browser_open, browser_navigate, browser_snapshot, browser_click, browser_fill, browser_select_option, browser_check, browser_save_selectors, browser_draft_scenario, browser_close) mantiene un navegador vivo entre llamadas, reutilizando los mismos módulos de Haka Agent (ElementIndex verifica cada selector contra el DOM real, ActionExecutor observa el efecto de cada acción). Se marca experimental a propósito: cualquier .feature que se llegue a escribir con browser_draft_scenario queda con tag @borrador y necesita revisión humana, porque el criterio de qué probar lo decidió el asistente sin contexto de negocio. Detalle completo en la guía.

Consulta la guía de Haka MCP para el detalle de cada tool, sus parámetros y ejemplos de uso.

🤝 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

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

📦 Publicación en PyPI

El script publish_to_pypi.py automatiza el proceso de publicación:

# Publicar en PyPI (genera wheel puro Python py3-none-any)
python3 publish_to_pypi.py

El build genera un wheel puro Python (py3-none-any) compatible con todas las plataformas. La compilación con Cython está desactivada por defecto para evitar problemas de RECORD en PyPI.

Build con Cython (opcional)

Si necesitas compilar módulos sensibles con Cython (ofuscación de código):

# Activar compilación Cython explícitamente
HAKA_USE_CYTHON=1 python3 -m build

Esto genera un wheel platform-specific con extensiones .so/.pyd compiladas. Solo usar para distribución privada, no para PyPI público.

Requisitos para publicar

pip install build twine

Archivo ~/.pypirc con credenciales configuradas para el repositorio haka-playwright-engine.

📄 Licencia

Software propietario. Copyright © 2024-2026 HAKA LAB SpA, Santiago de Chile. Todos los derechos reservados.

Este no es software libre ni de código abierto. Su uso requiere una licencia vigente otorgada por HAKA LAB SpA y se activa mediante credenciales nominativas (HAKA_LICENSE_EMAIL y HAKA_LICENSE_KEY). Están prohibidas la redistribución, la modificación y la elusión del mecanismo de validación de licencia sin autorización previa y por escrito.

Ver el archivo LICENSE para los términos completos. Para licenciamiento: felipe.farias@hakalab.com

🚀 ¡Comienza Ahora!

# 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