HAKALAB FRAMEWORK - AUTOMATIZACION DE PRUEBAS AVANZADA

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 e integración completa con Jira y Xray.

CARACTERISTICAS PRINCIPALES v1.2.23+

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.2.23+:
- Integración Jira/Xray: Integración completa con Jira y Xray Cloud para trazabilidad automática
- Flujo Optimizado Xray: Una sola llamada API crea Test Execution con todos los tests y actualiza estados
- 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

Integración Jira/Xray v1.2.23+:
- Adjunto Automático: Reportes HTML se adjuntan automáticamente a issues de Jira
- Test Executions: Creación automática de Test Executions en Xray con todos los tests
- Estados Automáticos: Mapeo automático de resultados (passed/failed/skipped)
- Vinculación HU: Test Executions se vinculan automáticamente a Historias de Usuario
- Control Granular: Variables de entorno para habilitar/deshabilitar integraciones
- Validación Automática: Solo procesa issues de tipo "Test" válidas
- Flujo Optimizado: Una sola llamada API para crear, adjuntar y actualizar estados

STEPS REALES DISPONIBLES EN EL FRAMEWORK

NAVIGATION STEPS - Navegación y URLs:
- voy a la url "https://example.com"
- recargo la página
- voy hacia atrás
- voy hacia adelante
- espero 3 segundos
- espero a que cargue la página
- abro una nueva pestaña
- cierro la pestaña actual
- cambio a la pestaña 1
- maximizo la ventana
- establezco el tamaño de ventana a 1920x1080

INTERACTION STEPS - Clicks, hover, formularios:
- hago click en el elemento "button_login" con identificador "id"
- hago doble click en el elemento "button" con identificador "css"
- hago click derecho en el elemento "menu" con identificador "xpath"
- paso el mouse sobre el elemento "dropdown" con identificador "class"
- relleno el campo "username" con "admin" con identificador "name"
- limpio el campo "email" con identificador "id"
- escribo "texto" en el campo "search" con identificador "css"
- selecciono la opción "España" del dropdown "country" con identificador "name"
- marco el checkbox "terms" con identificador "id"
- desmarco el checkbox "newsletter" con identificador "class"
- presiono la tecla "Enter"
- subo el archivo "test.pdf" al elemento "upload" con identificador "id"

ASSERTION STEPS - Verificaciones y validaciones:
- debería ver el texto "Bienvenido"
- no debería ver el texto "Error"
- el título de la página debería ser "Home"
- el título de la página debería contener "Dashboard"
- debería ver el elemento "welcome_message" con identificador "id"
- no debería ver el elemento "error_banner" con identificador "class"
- el elemento "title" debería contener el texto "Bienvenido" con identificador "css"
- el elemento "name" debería tener el texto exacto "Juan Pérez" con identificador "xpath"
- el campo "email" debería tener el valor "test@example.com" con identificador "name"
- el elemento "submit_button" debería estar habilitado con identificador "id"
- el elemento "loading" debería estar deshabilitado con identificador "class"
- el checkbox "terms" debería estar marcado con identificador "id"
- el checkbox "newsletter" no debería estar marcado con identificador "name"
- la url actual debería ser "https://example.com/dashboard"
- la url actual debería contener "dashboard"

CSV FILE STEPS - Manejo de archivos CSV:
- verifico que el archivo CSV "data/test.csv" existe
- verifico que el archivo CSV "data/large.csv" tiene un peso de al menos 1000 bytes
- cargo el archivo CSV "data/empleados.csv" en la variable "empleados"
- busco en el CSV "empleados" el valor "Desarrollo" en la columna "departamento"
- obtengo el valor de la fila 0 columna "nombre" del CSV "empleados" y lo guardo en "primer_empleado"
- filtro el CSV "empleados" donde "salario" contiene "75000" y guardo como "salarios_altos"
- verifico que el CSV "empleados" tiene 50 filas
- verifico que el CSV "empleados" contiene las columnas "nombre,email,departamento"
- exporto el CSV "empleados_filtrados" a "output/resultado.csv"
- muestro un resumen del CSV "empleados"
- busco en el CSV "empleados" múltiples valores "IT,Desarrollo,QA" en columna "departamento"
- ordeno el CSV "empleados" por columna "salario" de forma "descendente" y guardo como "ordenados"

TIMING STEPS - Control avanzado de tiempos:
- pauso 3 segundos
- espero 1500 milisegundos
- espero aleatoriamente entre 2 y 5 segundos
- espero hasta que el elemento "button.submit" sea visible
- espero hasta que el elemento "loading" desaparezca
- espero hasta que el elemento "input" esté habilitado
- espero hasta que el elemento "title" contenga el texto "Completado"
- espero hasta que la página termine de cargar
- espero hasta que no haya requests de red pendientes
- espero con timeout de 10 segundos hasta que "modal" sea visible
- establezco el timeout global en 30 segundos
- espero hasta que el elemento "status" tenga el atributo "class" con valor "success"
- espero hasta que haya 5 elementos "li.item"
- espero hasta que la URL contenga "dashboard"
- marco el tiempo de inicio como "carga_pagina"
- verifico que el cronómetro "carga_pagina" no exceda 10 segundos
- muestro el tiempo transcurrido del cronómetro "carga_pagina"
- espero hasta que el elemento "spinner" no esté en estado de carga
- espero progresivamente: "1,2,3,5"

ADVANCED INPUT STEPS - Interacción avanzada con campos:
- escribo gradualmente "Usuario de Prueba" en "input[name='username']" con 150ms entre caracteres
- escribo naturalmente "Comentario realista" en "textarea[name='comments']"
- limpio completamente el campo "input[name='email']"
- selecciono todo el texto en "input[name='search']" y lo borro
- borro 5 caracteres del final en "input[name='subject']"
- reemplazo el texto en "input[name='title']" con "Nuevo título"
- agrego " - Información adicional" al final del texto en "textarea[name='description']"
- inserto "URGENTE: " al inicio del campo "input[name='subject']"
- tecleo "Enter" en el campo "input[name='search']"
- tecleo combinación "Ctrl+A" en el campo "textarea[name='content']"
- enfoco el campo "input[name='email']"
- desenfocar el campo actual
- copio el contenido del campo "input[name='data']" al portapapeles
- pego el contenido del portapapeles en "textarea[name='paste_area']"
- escribo avanzado "test@example.com" y presiono Enter en "input[name='email']"
- selecciono el texto desde la posición 0 hasta 5 en "input[name='text']"
- escribo con velocidad "lenta" el texto "Mensaje importante" en "textarea[name='message']"
- simulo errores de escritura con texto "Automatización realista" en "input[name='search']"
- verifico que puedo escribir en el campo "input[name='editable']"
- limpio el campo "input[name='data']" usando "clear"
- escribo texto multilínea en "textarea[name='description']"

VARIABLE STEPS - Variables dinámicas:
- creo la variable "usuario_base" con valor "testuser"
- genero una variable "session_id" con texto aleatorio de 12 caracteres
- genero una variable "ticket_number" con número aleatorio entre 1000 y 9999
- genero una variable "timestamp" con timestamp actual
- genero una variable "fecha_hoy" con fecha actual en formato "%Y-%m-%d"
- concateno las variables "usuario_base" y "ticket_number" en la variable "usuario_completo"
- incremento la variable numérica "contador" en 1
- muestro el valor de la variable "session_id"
- verifico que la variable "email" contiene "@example.com"
- verifico que la variable "status" es igual a "success"
- obtengo el texto del elemento "h1.title" y lo guardo en la variable "titulo_pagina" con identificador "css"
- obtengo el atributo "href" del elemento "link" y lo guardo en la variable "url_destino" con identificador "id"
- muestro todas las variables actuales
- limpio todas las variables
- copio la variable "original" a "backup"

WAIT STEPS - Esperas específicas:
- espero a que el elemento "modal" sea visible con identificador "id"
- espero a que el elemento "loading" esté oculto con identificador "class"
- espero a que el elemento "button" esté habilitado con identificador "css"
- espero a que el elemento "status" contenga el texto "Completado" con identificador "xpath"
- espero a que la url de la página contenga "success"
- espero a que el título de la página sea "Proceso Completado"
- espero a que la red esté inactiva
- espero a que el contenido del DOM esté cargado
- espero a que el elemento "submit" sea clickeable con identificador "id"

SCROLL STEPS - Desplazamiento de página:
- hago scroll al elemento "footer" con identificador "id"
- hago scroll al inicio de la página
- hago scroll al final de la página
- hago scroll hacia abajo 500 píxeles
- hago scroll hacia arriba 300 píxeles
- hago scroll hacia la izquierda 200 píxeles
- hago scroll hacia la derecha 150 píxeles
- hago scroll del elemento "container" hacia abajo 100 píxeles con identificador "class"
- hago scroll del elemento "sidebar" hacia arriba 50 píxeles con identificador "id"

WINDOW STEPS - Ventanas y pestañas:
- cambio a la nueva ventana
- cierro la ventana actual
- cambio a la ventana con título "Configuración"
- cambio a la ventana con url que contiene "admin"
- acepto la alerta
- rechazo la alerta
- acepto la alerta con texto "Confirmado"
- obtengo el texto de la alerta y lo guardo en la variable "alert_message"
- cambio al frame "content" con identificador "id"
- cambio al contenido principal
- tomo una captura de pantalla y la guardo como "test_screenshot.png"
- tomo una captura del elemento "modal" y la guardo como "modal.png" con identificador "class"

DRAG DROP STEPS - Arrastrar y soltar (MEJORADOS v1.2.12):
- arrastro el elemento "item1" al elemento "target" con identificadores "id" y "class"
- arrastro el elemento "box" por desplazamiento x="100" y="50" con identificador "css"
- arrastro el elemento "slider" a las coordenadas x="200" y="300" con identificador "id"
- empiezo a arrastrar el elemento "draggable" con identificador "class"
- muevo el elemento arrastrado a las coordenadas x="150" y="250"
- suelto el elemento arrastrado
- paso el mouse sobre el elemento antes de arrastrar "item" con identificador "id"
- arrastro lentamente el elemento "source" al elemento "target" con identificadores "id" y "class"
- verifico que el drag and drop fue exitoso comprobando la posición del elemento "moved_item" con identificador "id"
- verifico que el elemento "item" está en la posición x="150" y="250" con identificador "id"
- arrastro el elemento "source" al elemento "target" usando API nativa con identificadores "id" y "class"
- realizo drag and drop avanzado desde "source" hasta "target" con identificadores "id" y "class"
- simulo drag and drop con HTML5 desde "source" hasta "target" con identificadores "id" y "class"
- arrastro y suelto el archivo "document.pdf" al elemento "dropzone" con identificador "id"

COMBOBOX STEPS - Selects y dropdowns:
- selecciono la opción "Opción 1" del combobox "dropdown" con identificador "id"
- selecciono la opción por valor "value1" del combobox "select" con identificador "name"
- selecciono la opción por índice "2" del combobox "options" con identificador "css"
- abro el dropdown "menu" con identificador "class"
- selecciono la opción "Madrid" del dropdown abierto
- escribo y selecciono "Barcelona" en el combobox buscable "city" con identificador "id"
- limpio la selección del combobox "country" con identificador "name"
- verifico que el combobox "status" tiene seleccionada la opción "Activo" con identificador "id"
- verifico que el combobox "categories" contiene las opciones "Cat1,Cat2,Cat3" con identificador "class"
- selecciono múltiples opciones "Op1,Op2,Op3" del multiselect "items" con identificador "id"
- navego las opciones del combobox con flechas y selecciono la opción "Target" de "selector" con identificador "css"

MODAL STEPS - Modales y diálogos:
- espero a que aparezca el modal "confirmation" con identificador "id"
- espero a que desaparezca el modal "loading" con identificador "class"
- cierro el modal "alert" haciendo click en el botón cerrar con identificador "css"
- cierro el modal presionando la tecla Escape
- cierro el modal haciendo click fuera
- verifico que el modal "dialog" es visible con identificador "id"
- verifico que el modal "popup" no es visible con identificador "class"
- verifico que el modal "confirm" tiene el título "Confirmar Acción" con identificador "id"
- hago click en el botón "Aceptar" del modal "dialog" con identificador de modal "id"
- relleno el campo "message" con "Texto de prueba" en el modal "form" con identificadores modal="id" campo="name"
- verifico que el modal "notification" contiene el texto "Éxito" con identificador "class"
- manejo la alerta del navegador con acción "accept"
- manejo la confirmación del navegador con acción "dismiss"
- manejo el prompt del navegador con texto "Respuesta" y acción "accept"
- espero a que aparezca cualquier modal
- verifico que no hay modales visibles
- tomo captura del modal "dialog" con identificador "id"

FILE STEPS - Upload, download y archivos:
- subo el archivo "documents/test.pdf" al elemento "upload" con identificador "id"
- subo múltiples archivos "file1.txt,file2.txt" al elemento "multi_upload" con identificador "class"
- inicio descarga haciendo click en el elemento "download_btn" con identificador "css"
- espero a que complete la descarga
- guardo la descarga como "report.pdf"
- verifico que existe el archivo descargado
- verifico que el nombre del archivo descargado es "data.xlsx"
- verifico que el tamaño del archivo descargado es mayor a "1000" bytes
- verifico que el archivo descargado contiene el texto "Total:"
- verifico que la descarga es JSON válido
- verifico que el JSON descargado contiene la clave "status" con valor "success"
- verifico que la descarga es CSV válido con "name,email,phone" columnas
- verifico que el CSV descargado tiene "100" filas
- extraigo y verifico que el ZIP contiene los archivos "data.csv,report.pdf"
- creo archivo de prueba "test.txt" con contenido "Contenido de prueba"
- elimino archivo de prueba "temp.txt"
- verifico que el archivo "output.txt" existe en el directorio "downloads"
- obtengo el tamaño del archivo "data.csv" y lo guardo en la variable "file_size"

TABLE STEPS - Tablas avanzadas:
- verifico que la tabla "users" tiene "10" filas con identificador "id"
- verifico que la tabla "data" tiene "5" columnas con identificador "class"
- hago click en la celda de la fila "2" columna "3" de la tabla "grid" con identificador "css"
- verifico que la celda de la fila "1" columna "2" contiene "Juan" en la tabla "employees" con identificador "id"
- ordeno la tabla "products" por la columna "Price" con identificador "class"
- filtro la tabla "items" por la columna "Category" con valor "Electronics" con identificador "id"
- selecciono la fila "3" en la tabla "records" con identificador "css"
- verifico que la fila "2" de la tabla "data" está seleccionada con identificador "id"
- obtengo el valor de la celda fila "1" columna "2" y lo guardo en la variable "cell_value" de la tabla "info" con identificador "class"
- verifico que la tabla "results" contiene una fila con valores "John,Doe,Manager" con identificador "id"
- edito la celda de la fila "1" columna "3" con valor "Nuevo valor" en la tabla "editable" con identificador "css"
- exporto los datos de la tabla "summary" y los guardo en la variable "table_data" con identificador "id"

KEYBOARD MOUSE STEPS - Interacciones avanzadas:
- pulso la tecla "F5"
- presiono la combinación de teclas "Ctrl+C"
- escribo el texto "Hola mundo" con retraso de "100" ms entre caracteres
- mantengo presionada la tecla "Shift" por "2" segundos
- hago click en las coordenadas x="100" y="200"
- hago doble click en las coordenadas x="150" y="250"
- hago click derecho en las coordenadas x="300" y="400"
- muevo el mouse a las coordenadas x="500" y="600"
- hago scroll con la rueda del mouse "down" por "3" pasos
- realizo gesto de mouse desde x="0" y="0" hasta x="100" y="100"
- simulo el atajo de teclado "Ctrl+S" en el elemento "editor" con identificador "id"
- selecciono todo el texto con Ctrl+A
- copio el texto seleccionado con Ctrl+C
- pego el texto con Ctrl+V
- corto el texto con Ctrl+X
- deshago la acción con Ctrl+Z
- rehago la acción con Ctrl+Y
- navego con la tecla Tab "3" veces
- navego con Shift+Tab "2" veces
- pulso la tecla Enter
- presiono la tecla Escape
- presiono la tecla Espacio
- presiono la tecla de flecha "down"
- escribo el texto "test" y presiono Enter
- limpio el campo actual con Ctrl+A y Delete
- simulo escritura humana con el texto "Mensaje natural" y retrasos aleatorios

SALESFORCE STEPS - Automatización de Salesforce:
- espero a que cargue Salesforce Lightning
- navego a la aplicación de Salesforce "Sales"
- navego al objeto de Salesforce "Account"
- creo un nuevo registro de Salesforce para el objeto "Contact"
- relleno el campo de Salesforce "FirstName" con "Juan"
- selecciono la opción "Hot" del picklist "Rating" de Salesforce
- busco y selecciono el lookup "Account" de Salesforce con "Acme Corp"
- guardo el registro de Salesforce
- verifico que el campo "Name" del registro de Salesforce contiene "Juan Pérez"
- hago click en la pestaña "Details" de Salesforce
- espero el mensaje toast de Salesforce "success"
- cierro los mensajes toast de Salesforce
- cambio a la vista clásica de Salesforce
- cambio a la vista Lightning de Salesforce
- abro el registro "001XX0000000001" de Salesforce para el objeto "Account"
- edito el registro de Salesforce
- elimino el registro de Salesforce
- busco en la búsqueda global de Salesforce con "Acme Corporation"

ENVIRONMENT STEPS - Variables de entorno:
- cargo las variables de entorno del archivo ".env.testing"
- establezco la variable de entorno "API_URL" con valor "https://api.test.com"
- obtengo variable de entorno "DATABASE_URL" y la guardo en variable "db_connection"
- verifico que existe la variable de entorno "SECRET_KEY"
- verifico que la variable de entorno "ENV" es igual a "production"
- navego a la URL de entorno "BASE_URL"
- relleno el campo "api_key" con la variable de entorno "API_TOKEN" usando identificador "id"
- uso credenciales de entorno para login con usuario "ADMIN_USER" y contraseña "ADMIN_PASS"
- hago click en el botón de login
- realizo login completo con credenciales de entorno "TEST_USER" y "TEST_PASS"
- imprimo todas las variables de entorno
- imprimo las variables de entorno que coinciden con el patrón "API"
- hago backup de la variable de entorno "ORIGINAL_URL" como "backup_url"
- restauro la variable de entorno "CURRENT_URL" desde el backup "backup_url"

JIRA XRAY STEPS - Integración con Jira y Xray:
- verifico la conexión con Jira
- verifico la configuración de Xray
- muestro información de la integración Jira/Xray
- verifico que la issue "PROD-123" existe en Jira
- verifico que el test "PROD-456" es de tipo Test en Jira
- agrego un comentario "Prueba completada" a la issue "PROD-123"
- adjunto el archivo "reports/report.html" a la issue "PROD-123"
- busco issues en Jira con JQL "project = PROD AND issuetype = Test"
- verifico que la búsqueda JQL encontró "5" issues
- creo un test execution "Pruebas de Login" en Xray
- agrego los tests "PROD-456,PROD-789" al test execution actual
- actualizo el estado del test "PROD-456" a "passed" en el test execution actual

DATA EXTRACTION STEPS - Extracción de datos:
- obtengo el texto del elemento "title" y lo guardo en la variable "page_title" con identificador "id"
- obtengo el valor del campo "email" y lo guardo en la variable "user_email" con identificador "name"
- obtengo el atributo "href" del elemento "link" y lo guardo en la variable "url" con identificador "css"
- obtengo la propiedad css "color" del elemento "button" y la guardo en la variable "btn_color" con identificador "class"
- obtengo la url actual y la guardo en la variable "current_page"
- obtengo el título de la página y lo guardo en la variable "page_name"
- cuento los elementos con identificador "css:.item" y guardo el conteo en la variable "item_count"
- verifico si el elemento "modal" es visible y guardo el resultado en la variable "is_modal_open" con identificador "id"
- verifico si el elemento "button" está habilitado y guardo el resultado en la variable "btn_enabled" con identificador "class"
- verifico si el checkbox "terms" está marcado y guardo el resultado en la variable "terms_accepted" con identificador "name"

ADVANCED STEPS - JavaScript y funciones avanzadas:
- ejecuto el javascript "window.scrollTo(0, 0)"
- ejecuto javascript "document.title" y guardo el resultado en la variable "js_title"
- tomo una captura de pantalla
- tomo una captura de pantalla con nombre "test_screenshot"
- arrastro el elemento "source" al elemento "target" con identificador origen "id" e identificador destino "class"
- establezco la cookie "session" con valor "abc123"
- obtengo la cookie "user_id" y la guardo en la variable "current_user"
- elimino la cookie "temp_data"
- limpio todas las cookies
- establezco el elemento de local storage "theme" con valor "dark"
- obtengo el elemento de local storage "preferences" y lo guardo en la variable "user_prefs"
- limpio el local storage
- establezco el elemento de session storage "cart" con valor "item1,item2"
- obtengo el elemento de session storage "session_id" y lo guardo en la variable "session"
- simulo la combinación de teclas "Alt+Tab"
- establezco la geolocalización del navegador a latitud 40.7128 y longitud -74.0060
- emulo el dispositivo "iPhone 12"

INSTALACION

Instalación desde PyPI (Recomendada)

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

Instalación de Versión Específica

pip install git+https://github.com/hakalab/hakalab-framework.git@v1.2.23
python -m playwright install

Instalación en Modo Desarrollo

git clone https://github.com/hakalab/hakalab-framework.git
cd hakalab-framework
pip install -e .
python -m playwright install

USO DEL FRAMEWORK

Configuración Inicial:
cp .env.example .env

Ejecutar Pruebas:
behave
behave --tags=@smoke
behave --tags=@login,@regression
behave features/example_login.feature
behave -f html -o html-reports/report.html
behave --no-capture
BROWSER=firefox behave
HEADLESS=true behave

Generar Reportes:
Los reportes HTML se generan automáticamente en html-reports/
open html-reports/report.html  # Mac
start html-reports/report.html # Windows
xdg-open html-reports/report.html # Linux

EJEMPLOS DE USO REALES

1. Feature Básico con Funcionalidades Reales

# language: es
Feature: Demostración de funcionalidades del framework
  Como tester automatizado
  Quiero usar las capacidades reales del framework
  Para crear pruebas funcionales

  Background:
    Given voy a la url "https://example.com/login"

  Scenario: Login con datos dinámicos y medición de rendimiento
    # Generar datos dinámicos
    When genero una variable "session_id" con texto aleatorio de 8 caracteres
    And genero una variable "timestamp" con timestamp actual
    And creo la variable "email" con valor "test_${session_id}@example.com"
    
    # Iniciar cronómetro
    And marco el tiempo de inicio como "login_process"
    
    # Entrada realista
    And escribo naturalmente "${email}" en "input[name='email']"
    And escribo gradualmente "password123" en "input[name='password']" con 100ms entre caracteres
    And hago click en el elemento "submit_button" con identificador "css:button[type='submit']"
    
    # Verificar tiempo de respuesta
    Then muestro el tiempo transcurrido del cronómetro "login_process"
    And verifico que el cronómetro "login_process" no exceda 5 segundos
    And debería ver el elemento "welcome_message" con identificador "id"

2. Procesamiento de Datos CSV Real

Feature: Pruebas con datos CSV
  
  Scenario: Procesamiento de empleados desde CSV
    # Cargar y analizar CSV
    Given cargo el archivo CSV "test_data/empleados.csv" en la variable "empleados"
    And muestro un resumen del CSV "empleados"
    And verifico que el CSV "empleados" tiene 50 filas
    
    # Filtrar datos específicos
    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_por_salario"
    
    # Usar datos en formulario
    And obtengo el valor de la fila 0 columna "nombre" del CSV "dev_por_salario" y lo guardo en "mejor_dev"
    And obtengo el valor de la fila 0 columna "email" del CSV "dev_por_salario" y lo guardo en "email_dev"
    
    # Llenar formulario con datos del CSV
    When voy a la url "https://example.com/employee-form"
    And escribo naturalmente "${mejor_dev}" en "input[name='name']"
    And relleno el campo "email" con "${email_dev}" con identificador "css:input[name='email']"
    
    Then verifico que la variable "mejor_dev" contiene "Juan"

3. Simulación de Comportamiento Humano Real

Scenario: Entrada de texto realista
  Given voy a la url "https://example.com/contact"
  
  # Escritura con diferentes velocidades
  When escribo con velocidad "lenta" el texto "Consulta importante" en "input[name='subject']"
  And escribo naturalmente "Este es un mensaje de prueba" en "textarea[name='message']"
  
  # Simulación de errores humanos
  And simulo errores de escritura con texto "Información adicional" en "textarea[name='details']"
  
  # Manipulación avanzada de texto
  And agrego " - Enviado automáticamente" al final del texto en "textarea[name='message']"
  And borro 5 caracteres del final en "input[name='subject']"
  
  # Esperas realistas
  And espero aleatoriamente entre 1 y 3 segundos
  And hago click en el elemento "submit_button" con identificador "css:button[type='submit']"

4. Page Object Models en JSON Real

// json_poms/LOGIN.json
{
  "email_field": "input[name='email']",
  "password_field": "input[name='password']",
  "login_button": "button[type='submit']",
  "error_message": ".alert-error",
  "welcome_message": "#welcome-banner",
  "forgot_password_link": "a[href*='forgot-password']"
}

# Usar elementos del JSON
When relleno el campo "email" con "user@example.com" con identificador "$.LOGIN.email_field"
And relleno el campo "password" con "password123" 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 "$.LOGIN.welcome_message"

5. Variables de Entorno y Configuración Real

# .env
BASE_URL=https://staging.example.com
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=admin123
API_KEY=abc123xyz789
BROWSER=chromium
HEADLESS=false
TIMEOUT=30000
SCREENSHOTS_DIR=screenshots
HTML_REPORTS_DIR=html-reports
VIDEO_RECORDING=false

Scenario: Login con credenciales de entorno
  Given cargo las variables de entorno del archivo ".env"
  When navego a la URL de entorno "BASE_URL"
  And realizo login completo con credenciales de entorno "ADMIN_EMAIL" y "ADMIN_PASSWORD"
  Then la url actual debería contener "dashboard"

6. Integración Completa con Jira y Xray (NUEVO v1.2.23+)

# Configuración en .env
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_ENABLED=true
XRAY_AUTHORIZATION_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZW5hbnQiOiIyNjI1MGIzNC04YTMyLTNiZWMtOGI1MC04MjljZGJkNmMwMDciLCJhY2NvdW50SWQiOiI1ZmIyOTFiYWRkMGM1OTAwNzU5MWVhOWYiLCJpc1hlYSI6ZmFsc2UsImlhdCI6MTc2Nzk3MTg2NSwiZXhwIjoxNzY4MDU4MjY1LCJhdWQiOiIzRUJBM0IyRjA2MEI0Q0Q3QjRFQzE4NzgwQ0M1MDBFNyIsImlzcyI6ImNvbS54cGFuZGl0LnBsdWdpbnMueHJheSIsInN1YiI6IjNFQkEzQjJGMDYwQjRDRDdCNEVDMTg3ODBDQzUwMEU3In0.7HStiUpL2C7edzUDALpPHFQfJOxn8WzD6DLT3BLxva0
XRAY_BASE_URL=https://xray.cloud.getxray.app

# Feature con integración automática
# language: es
@PROD-90
Feature: Prueba flujo correcto
  Como usuario del framework
  Quiero probar el flujo correcto de Xray
  Para verificar que se crea UN Test Execution con TODOS los tests

  @PROD-91
  Scenario: Primer test del flujo correcto
    When I go to the url "https://example.com"
    And I take a screenshot with name "flow1"

  @PROD-92
  Scenario: Segundo test del flujo correcto
    When I go to the url "https://httpbin.org"
    And I take a screenshot with name "flow2"

# Resultado automático:
# ✅ Reporte HTML adjuntado a issue PROD-90
# ✅ UN Test Execution creado (ej: PROD-144)
# ✅ TODOS los tests incluidos en UNA llamada: PROD-91, PROD-92
# ✅ Estados actualizados: PROD-91=passed, PROD-92=passed
# ✅ Test Execution vinculado a HU: PROD-144 → PROD-90

# Verificación manual de integración
Feature: Verificación de integración Jira/Xray
  
  Scenario: Validar configuración
    Given verifico la conexión con Jira
    And verifico la configuración de Xray
    When muestro información de la integración Jira/Xray
    And verifico que la issue "PROD-90" existe en Jira
    And verifico que el test "PROD-91" es de tipo Test en Jira
    Then busco issues en Jira con JQL "project = PROD AND issuetype = Test"
    And verifico que la búsqueda JQL encontró "10" issues

CONFIGURACION AVANZADA

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

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

# === 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 Y XRAY ===
JIRA_ENABLED=true                           # true=habilitar Jira, false=deshabilitar completamente
JIRA_URL=https://hakalab.atlassian.net
JIRA_EMAIL=felipe.farias@hakalab.com
JIRA_TOKEN=ATATT3xFfGF0DWFjw9A1O4PHPyHbOz0Ntqaj7-yWjwm0w5OernZnl0OtsXfxK1sd9foBaPKUY90WLSCseC8OS5dHmqWaV0PKTOqDKj_SIq4R_n-HHUVBzb0dRCUS2Hwv6ZjQE6LS02dc5vLNYQZuxS941J6bwRyJSgMF28ZMyrjzciCjtDSWm7k=1E898852
JIRA_PROJECT=PROD                           # Clave del proyecto (ej: PROJ, TEST, QA)
JIRA_COMMENT_MESSAGE=Reporte prueba de QA   # Mensaje para comentarios
XRAY_ENABLED=true                          # true=habilitar Xray, false=solo Jira
XRAY_TEST_PLAN=                            # Opcional: Test Plan para asociar executions
XRAY_AUTHORIZATION_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZW5hbnQiOiIyNjI1MGIzNC04YTMyLTNiZWMtOGI1MC04MjljZGJkNmMwMDciLCJhY2NvdW50SWQiOiI1ZmIyOTFiYWRkMGM1OTAwNzU5MWVhOWYiLCJpc1hlYSI6ZmFsc2UsImlhdCI6MTc2Nzk3MTg2NSwiZXhwIjoxNzY4MDU4MjY1LCJhdWQiOiIzRUJBM0IyRjA2MEI0Q0Q3QjRFQzE4NzgwQ0M1MDBFNyIsImlzcyI6ImNvbS54cGFuZGl0LnBsdWdpbnMueHJheSIsInN1YiI6IjNFQkEzQjJGMDYwQjRDRDdCNEVDMTg3ODBDQzUwMEU3In0.7HStiUpL2C7edzUDALpPHFQfJOxn8WzD6DLT3BLxva0
XRAY_BASE_URL=https://xray.cloud.getxray.app

# === DEBUG Y DESARROLLO ===
HAKALAB_SHOW_STEPS=false     # Mostrar carga de steps
DEBUG_MODE=false             # Modo debug
SLOW_MO=0                    # Delay entre acciones (ms)

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

DOCUMENTACION COMPLETA

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 (NUEVO v1.2.23+)
- FUNCIONALIDADES_AVANZADAS_v1.2.12.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

Guías NotebookLM (Formato TXT):
- GUIA_COMPLETA_STEPS_NotebookLM.txt - Referencia completa optimizada para IA
- GUIA_INTEGRACION_JIRA_XRAY_NotebookLM.txt - Integración Jira/Xray para IA (NUEVO v1.2.23+)
- GUIA_INSTALACION_NotebookLM.txt - Instalación optimizada para IA
- README_NotebookLM.txt - Este archivo, optimizado para procesamiento IA

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

CHANGELOG

v1.2.23+ - 2026-01-09 (INTEGRACIÓN JIRA/XRAY)

Nuevas Funcionalidades Principales:
- Integración Completa con Jira: Adjunto automático de reportes HTML a issues de Jira
- Integración Optimizada con Xray Cloud: Creación automática de Test Executions con flujo optimizado
- Flujo Xray Optimizado: Una sola llamada API crea Test Execution, adjunta todos los tests y actualiza estados
- Vinculación Automática: Test Executions se vinculan automáticamente a Historias de Usuario
- Control Granular: Variables de entorno para habilitar/deshabilitar integraciones independientemente
- Steps Específicos: 12+ steps para gestión manual de Jira y Xray
- Validación Automática: Solo procesa issues de tipo "Test" válidas en Xray

Integración Jira/Xray Detallada:
- Adjunto automático de reportes HTML a issues de Jira basado en tags del feature
- Creación automática de Test Executions en Xray con todos los tests del feature
- Mapeo automático de estados: passed/failed/skipped
- Vinculación automática de Test Execution a Historia de Usuario del feature
- Flujo optimizado: Una sola llamada API para crear, adjuntar y actualizar
- Autenticación directa con token de Xray Cloud
- Logs detallados del proceso de integración
- Manejo robusto de errores y validaciones

Variables de Entorno Nuevas:
- JIRA_ENABLED: Control maestro de integración con Jira
- JIRA_URL, JIRA_EMAIL, JIRA_TOKEN, JIRA_PROJECT: Configuración de Jira
- JIRA_COMMENT_MESSAGE: Mensaje personalizable para comentarios
- XRAY_ENABLED: Control de integración con Xray
- XRAY_AUTHORIZATION_TOKEN: Token directo de Xray Cloud
- XRAY_BASE_URL: URL base de Xray Cloud API
- XRAY_TEST_PLAN: Test Plan opcional para asociar executions

Archivos Nuevos:
- hakalab_framework/integrations/jira_integration.py - Integración completa con Jira
- hakalab_framework/integrations/xray_integration.py - Integración optimizada con Xray Cloud
- hakalab_framework/integrations/behave_hooks.py - Hooks automáticos para Behave
- hakalab_framework/steps/jira_xray_steps.py - Steps específicos para Jira/Xray
- test_jira_connection.py - Script de prueba de conexión con Jira
- test_xray_connection.py - Script de prueba de conexión con Xray
- GUIA_INTEGRACION_JIRA_XRAY.md - Guía completa de integración
- GUIA_INTEGRACION_JIRA_XRAY_NotebookLM.txt - Guía optimizada para IA

Archivos Actualizados:
- features/environment.py - Hooks automáticos de Jira/Xray integrados
- .env y .env.example - Variables de configuración de Jira/Xray
- README.md y README_NotebookLM.txt - Documentación actualizada

v1.2.12 - 2026-01-06 (VERSIÓN ANTERIOR)

Nuevas Funcionalidades:
- Manejo Avanzado de CSV: 15+ steps para procesamiento completo de archivos CSV
- Variables Dinámicas: 20+ steps para generación y manipulación automática de variables
- Control de Tiempos: 15+ steps para cronómetros, esperas inteligentes y medición de rendimiento
- Entrada Avanzada: 25+ steps para simulación de escritura humana y manipulación sofisticada de texto
- Drag & Drop Mejorado: Sistema completamente rediseñado con múltiples métodos de fallback

Mejoras Técnicas:
- Sistema de variables completamente rediseñado con resolución automática
- Integración completa con pandas para procesamiento de datos CSV
- Cronómetros de alta precisión para medición de rendimiento
- Simulación realista de comportamiento humano con errores y delays variables
- Drag & Drop robusto con mouse down/up, timing delays y verificación de posición

Mejoras Específicas de Drag & Drop v1.2.12:
- Secuencias mouse down/up apropiadas con timing delays (100-500ms)
- Método de arrastre lento con 20 pasos incrementales para elementos sensibles
- Hover antes de arrastrar para activar elementos que requieren interacción previa
- API nativa de Playwright como método primario con fallback manual
- Simulación HTML5 drag & drop con JavaScript completamente funcional con soporte CSS y XPath (v1.2.20)
- Verificación automática de posición después del drag & drop
- Manejo robusto de errores con múltiples métodos de retry
- Soporte para arrastre por coordenadas específicas y desplazamientos relativos

Archivos Nuevos:
- hakalab_framework/steps/csv_file_steps.py - Procesamiento de CSV
- hakalab_framework/steps/timing_steps.py - Control avanzado de tiempos
- hakalab_framework/steps/advanced_input_steps.py - Entrada sofisticada
- hakalab_framework/steps/variable_steps.py - Variables dinámicas

Archivos Mejorados:
- hakalab_framework/steps/drag_drop_steps.py - Drag & drop completamente rediseñado

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/your-org/hakalab-framework.git
cd hakalab-framework
pip install -e .
python -m pytest tests/
behave features/

Crear Steps Personalizados:
# En tu archivo custom_steps.py
from behave import step

@step('mi step personalizado con "{parametro}"')
def mi_step_personalizado(context, parametro):
    """Descripción de mi step personalizado"""
    # Tu lógica aquí
    print(f"Ejecutando step con parámetro: {parametro}")

LICENCIA

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

SOPORTE Y COMUNIDAD

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 hakalab-framework
- 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

RECONOCIMIENTOS

Tecnologías Utilizadas:
- Playwright - Automatización web moderna
- Behave - Framework BDD para Python
- Pandas - Procesamiento de datos CSV
- Jinja2 - Templates para reportes HTML

Contribuidores:
- Equipo Hakalab - Desarrollo y mantenimiento principal
- Comunidad Open Source - Contribuciones y feedback

COMIENZA AHORA

# Instalación rápida
pip install git+https://github.com/hakalab/hakalab-framework.git
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