REFERENCIA RÁPIDA: ELEMENTLOCATOR
==================================

USO INCORRECTO (NO HACER)
--------------------------

ESTO NO FUNCIONA - locate_element no existe:

from hakalab_framework.core.element_locator import locate_element

@step('mi step')
def mi_step(context):
    element = locate_element(context.page, "selector")  # ERROR


USO CORRECTO
------------

1. ElementLocator ya está disponible en el contexto

from behave import step

@step('hago click en "{identifier}"')
def click_elemento(context, identifier):
    # ElementLocator ya está en context.element_locator
    element = context.element_locator.find(context.page, identifier)
    element.click()


2. Métodos disponibles

Método 1: find() - Retorna elemento Playwright listo para usar
element = context.element_locator.find(context.page, "$.LOGIN.button")
element.click()

Método 2: get_element() - Alias de find()
element = context.element_locator.get_element(context.page, "$.LOGIN.button")
element.fill("texto")

Método 3: get_locator() - Solo retorna el selector string
selector = context.element_locator.get_locator("$.LOGIN.button")
element = context.page.locator(selector)


3. Formato de identificadores

CORRECTO - Formato $.ARCHIVO.elemento:
"$.LOGIN.username_field"
"$.PRODUCTS.add_to_cart_button"
"$.CHECKOUT.submit_order"

INCORRECTO:
"LOGIN.username_field"  # Falta $.
"username_field"        # Falta $.ARCHIVO


4. Ejemplo completo correcto

from behave import step
from hakalab_framework.core.screenshot_manager import take_screenshot

@step('completo el login con usuario "{usuario}" y password "{password}"')
def completar_login(context, usuario, password):
    """Ejemplo completo de uso correcto del ElementLocator."""
    try:
        page = context.page
        locator = context.element_locator
        
        # Usar find() para obtener elementos
        username_field = locator.find(page, "$.LOGIN.username_field")
        username_field.fill(usuario)
        
        password_field = locator.find(page, "$.LOGIN.password_field")
        password_field.fill(password)
        
        submit_button = locator.find(page, "$.LOGIN.submit_button")
        submit_button.click()
        
        print(f"✓ Login completado para usuario: {usuario}")
        
    except Exception as e:
        take_screenshot(context, "error_login")
        raise AssertionError(f"Error en login: {str(e)}")


ESTRUCTURA DE ARCHIVOS JSON
----------------------------

Los archivos JSON deben estar en la carpeta configurada en JSON_POMS_PATH:

Archivo: json_poms/LOGIN.json
{
  "username_field": "#username",
  "password_field": "#password",
  "submit_button": "button[type='submit']",
  "error_message": ".error-message"
}

Uso:
Para acceder a username_field del archivo LOGIN.json:
element = context.element_locator.find(context.page, "$.LOGIN.username_field")


CONFIGURACIÓN
-------------

En tu archivo .env:
# Carpeta donde están los archivos JSON con selectores
JSON_POMS_PATH=json_poms


FALLBACKS AUTOMÁTICOS (NUEVO)
------------------------------

Puedes definir selectores con fallbacks para mayor robustez.
Si el selector principal falla, el framework prueba automáticamente los fallbacks.

Archivo: json_poms/LOGIN.json
{
  "username_field": "#username",
  "password_field": "#password",
  
  "submit_button": {
    "selector": "button[type='submit']",
    "fallbacks": [
      "#login-button",
      "//button[contains(text(), 'Login')]",
      "button.btn-primary"
    ]
  }
}

Uso (igual que siempre):
element = context.element_locator.find(context.page, "$.LOGIN.submit_button")
element.click()

Cómo funciona:
1. Intenta button[type='submit']
2. Si falla, intenta #login-button
3. Si falla, intenta //button[contains(text(), 'Login')]
4. Si falla, intenta button.btn-primary
5. Si todos fallan, lanza error con el último selector

Ventajas:
✅ Mayor robustez ante cambios en la UI
✅ Soporta múltiples versiones de la aplicación
✅ Automático - no cambias tus steps
✅ Reduce falsos negativos

Cuándo usar:
✅ Elementos que cambian frecuentemente
✅ Aplicaciones con múltiples versiones
✅ Testing cross-browser con diferencias de DOM
✅ Selectores inestables

Cuándo NO usar:
❌ Elementos estables que nunca cambian
❌ Cuando quieres detectar cambios en la UI
❌ Selectores únicos y confiables


RECURSOS
--------

- Ver archivo completo de ejemplo: features/steps/ejemplo_correcto.py
- Documentación completa: hakalab_framework/documentacion/GUIA_STEPS_PERSONALIZADOS.md
- Código fuente: hakalab_framework/core/element_locator.py


ERRORES COMUNES Y SOLUCIONES
-----------------------------

Error: "cannot import name 'locate_element'"

Causa: Intentar importar una función que no existe.

Solución: No importar nada. Usar context.element_locator directamente.

NO HACER:
from hakalab_framework.core.element_locator import locate_element

HACER:
from behave import step

@step('mi step')
def mi_step(context):
    element = context.element_locator.find(context.page, "$.FILE.element")


Error: "El identificador debe empezar con '$.'

Causa: Formato incorrecto del identificador.

Solución: Siempre usar formato $.ARCHIVO.elemento

NO HACER:
element = context.element_locator.find(context.page, "LOGIN.button")

HACER:
element = context.element_locator.find(context.page, "$.LOGIN.button")


Error: "Archivo JSON no encontrado"

Causa: El archivo JSON no existe en la carpeta JSON_POMS_PATH.

Solución: 
1. Verificar que existe el archivo: json_poms/ARCHIVO.json
2. Verificar la variable de entorno JSON_POMS_PATH en .env

En .env:
JSON_POMS_PATH=json_poms


Error: "Elemento no encontrado en el archivo"

Causa: El elemento no existe en el archivo JSON.

Solución: Verificar que el elemento existe en el JSON:

Archivo json_poms/LOGIN.json:
{
  "username_field": "#username",
  "password_field": "#password"
}

CORRECTO - elemento existe en JSON:
element = context.element_locator.find(context.page, "$.LOGIN.username_field")

ERROR - elemento no existe en JSON:
element = context.element_locator.find(context.page, "$.LOGIN.email_field")


TIPS
----

1. Siempre usar try/except para manejar errores
2. Capturar screenshots en caso de error
3. Usar logging con print() para seguimiento
4. Validar precondiciones antes de interactuar
5. Documentar cada step con docstrings claros


CHECKLIST PARA CREAR STEPS
---------------------------

- No importar locate_element (no existe)
- Usar context.element_locator directamente
- Formato de identificadores: $.ARCHIVO.elemento
- Archivos JSON existen en JSON_POMS_PATH
- Manejo de errores con try/except
- Screenshots en errores
- Logging informativo
- Documentación con docstrings


RESUMEN RÁPIDO
--------------

INCORRECTO:
from hakalab_framework.core.element_locator import locate_element
element = locate_element(context.page, "selector")

CORRECTO:
element = context.element_locator.find(context.page, "$.ARCHIVO.elemento")

El ElementLocator es una clase que ya está instanciada y disponible en context.element_locator.
No necesitas importar nada, solo usar los métodos disponibles:
- find(page, identifier) - Retorna elemento Playwright
- get_element(page, identifier) - Alias de find()
- get_locator(identifier) - Retorna solo el selector string

Todos los identificadores deben usar formato: $.ARCHIVO.elemento
Los archivos JSON deben estar en la carpeta configurada en JSON_POMS_PATH
