Saltar a contenido

Configurar Lippia

Estado del adapter: ✅ Completo. Lo usan lippia-neo-generate-test-suite (para escribir los .feature y los step definitions) y lippia-neo-run-and-heal (para ejecutarlos con Maven y repararlos).

Valor en qa-stack.yaml test_framework: lippia
Lenguaje java
Qué es Lippia Core Framework (io.lippia:core): Cucumber 4 (Gherkin), TestNG, Selenium 3 para web y Spring RestTemplate para API
Tipos de app web, api e hybrid
Autenticación basic_auth o token de API, siempre por variables de entorno (no hay equivalente a google_sso)
Carpeta de tests por defecto tests/lippia/ (es la raíz del módulo Maven)

Los templates y scripts reales de Lippia viven en la biblioteca compartida lib/lippia/ del repositorio de skills. Los adapters de cada skill solo delegan en ella.


1. Qué necesitás instalado

A diferencia de Playwright, no hay un solo comando que instale todo: son cinco cosas independientes.

Herramienta Versión Cómo verificarlo Notas
JDK 8 o superior java -version Lippia compila para 1.8, pero se ejecuta sin problemas en 11, 17 o 21. Si java no está en el PATH, agregá <JDK>/bin o definí JAVA_HOME
Maven 3.6 o superior mvn -version Si no está en el PATH, agregá <maven>/bin
Acceso al Nexus de Crowdar — mvn dependency:resolve dentro de la carpeta de tests io.lippia:core se descarga de ahí. Requiere red corporativa o VPN, según la política vigente
Google Chrome (o Chromium) real Estable Que esté instalado en la máquina No alcanza con el Chromium que descarga Playwright. ChromeDriver no hace falta instalarlo: Lippia lo descarga solo
Bash (Git Bash o WSL en Windows) — bash --version Los scripts lib/lippia/scripts/*.sh no funcionan desde cmd.exe ni PowerShell

Repositorios de Nexus que usa el proyecto:

https://nexus-v3-repositories.automation.crowdaronline.com/repository/maven-releases/
https://nexus-v3-repositories.automation.crowdaronline.com/repository/maven-snapshots/

Para las releases de lectura no hace falta configurar credenciales en ~/.m2/settings.xml. Si tu Nexus pide autenticación, agregalas ahí.


2. qa-stack.yaml de ejemplo

stack:
  test_framework: lippia
  language: java
  app_type: web               # web | api | hybrid
  auth: basic_auth
  pipeline_provider: gitlab

environment:
  base_url: https://techstore-staging.com
  app_version: 1.0.0-SNAPSHOT
  os: Ubuntu 22.04

paths:
  user_stories_storage:
    type: local
    cloud_provider_mcp: null
    local_path: user-stories/
  test_plans_dir: test-plans/
  tests_dir: tests/lippia/    # raíz del módulo Maven (acá va el pom.xml)
  reports_dir: target/cucumber-reports/
  scripted_dir: execution/
  exploratory_dir: exploration/
  env_file: .env.tests
  lippia_config_path: tests/lippia/src/test/resources/config.properties   # solo para Lippia

commands:
  run_tests: null             # usa el run.sh del adapter → mvn clean test
  install_deps: null          # usa mvn dependency:resolve

paths.lippia_config_path aparece solo cuando el framework es Lippia. lippia-neo-bootstrap-stack busca el config.properties en el repositorio y solo te pregunta la ruta si no lo encuentra (nunca lo crea). Si todavía no existe, lippia-neo-generate-test-suite lo genera desde la plantilla.

Classpath de Maven: Lippia carga config.properties como recurso del classpath (src/test/resources/), no desde cualquier ruta. Si elegís una ruta fuera de un <testResource> declarado en pom.xml, tenés que agregar uno que apunte ahí. Si no, Lippia no encuentra el archivo.


3. Estructura del proyecto

Todo vive directamente bajo paths.tests_dir, que es la raíz del módulo Maven:

tests/lippia/                                  ← paths.tests_dir
├── pom.xml                                    ← si no existe, se crea desde la plantilla
└── src/
    ├── main/java/pages/                       ← Page Objects (si hubo exploración previa)
    │   └── CarritoPage.java
    └── test/
        ├── java/
        │   ├── runners/TestNGRunner.java      ← runner Cucumber + TestNG
        │   └── steps/
        │       ├── CommonSteps.java           ← Background y login, uno por proyecto
        │       └── <US-ID>Steps.java          ← pasos de cada historia
        └── resources/
            ├── features/
            │   └── US-002/
            │       ├── tc-01-agregar-producto.feature
            │       └── tc-02-crear-orden.api.feature   ← caso de API
            ├── testng.xml
            └── config.properties

Si el proyecto no tiene pom.xml, testng.xml, config.properties, TestNGRunner.java o CommonSteps.java, lippia-neo-generate-test-suite los crea desde las plantillas de lib/lippia/templates/.


4. Configurar pom.xml y config.properties

pom.xml

Si arrancás desde la plantilla (lib/lippia/templates/pom-template.xml), ya viene todo configurado. Si el proyecto ya tenía su propio pom.xml, revisá que tenga:

Qué Por qué
Dependencia io.lippia:core (versión 3.3.0.3 o superior) Es el framework
Los repositorios de Nexus de Crowdar (crowdar-releases, crowdar-snapshots) Sin ellos Maven no encuentra Lippia
Un perfil Maven qa run.sh se ejecuta con -Pqa por defecto
El plugin JSON de Cucumber en cucumber.options parse-results.sh lee target/cucumber-reports/results.json. Sin ese archivo, no puede leer los resultados

El bloque de cucumber.options que se necesita:

<properties>
    <cucumber.options>
        --plugin json:target/cucumber-reports/results.json
        --plugin pretty
        --glue steps
        --glue com.crowdar.bdd.cukes.hooks
        classpath:features
    </cucumber.options>
</properties>

config.properties

Los valores más importantes de la plantilla:

Propiedad Para qué Valores
crowdar.projectType Tipo de proyecto o navegador WEB_CHROME, WEB_FIREFOX, WEB_EDGE, API, DATABASE, GENERIC
crowdar.driver.setup.strategy Cómo se consigue el driver del navegador vacío = se descarga solo · LOCAL = driver ya instalado en el PATH · GRID = Selenium Grid
crowdar.driverHub URL del Selenium Hub Solo si la estrategia es GRID
crowdar.capabilities Archivo de capabilities del navegador chromeCapabilities.json
crowdar.element.wait y demás timeouts Tiempos de espera, en segundos 30 por defecto
crowdar.extent.environment Ambiente que aparece en el reporte staging, dev o prod

Las credenciales nunca van en config.properties. Se cargan siempre desde variables de entorno.

Evitá escribir una ruta absoluta a chrome.exe en chromeCapabilities.json (goog:chromeOptions.binary), salvo que sea imprescindible (por ejemplo, una imagen Docker con Chrome en una ruta no estándar). Una ruta de tu máquina no funciona en otro entorno ni en CI.

Modo headless: para ejecutar sin ventana (por ejemplo en CI), el perfil Maven tiene que configurar --headless en las capabilities de Chrome.


5. Credenciales y variables de entorno

El adapter de Lippia toma los datos del entorno de la terminal y se los pasa a Maven como propiedades (-DAPP_URL=..., -DQA_USER=...). En el código, los steps los leen con System.getenv("NOMBRE").

Variable Obligatoria Para qué
APP_URL Sí (tests web) URL base de la aplicación
QA_USER Sí (con basic_auth) Usuario de prueba
QA_PASSWORD Sí (con basic_auth) Contraseña de prueba
BASE_API_URL Solo tests de API URL base de la API
API_TOKEN Si la API usa token Token Bearer
QA_ENV No (por defecto staging) Ambiente, se pasa como -Dtest.environment

Definilas en la misma terminal donde trabaja el asistente, antes de ejecutar la suite:

export APP_URL="https://techstore-staging.com"
export QA_USER="usuario-de-prueba"
export QA_PASSWORD="contraseña-de-prueba"
# solo si app_type es api o hybrid:
export BASE_API_URL="https://api.techstore-staging.com"
export API_TOKEN="token-de-prueba"

⚠️ Diferencia con .env.tests: para basic_auth, lippia-neo-bootstrap-stack genera .env.tests con las claves APP_USER y APP_PASSWORD, que son las que usa Playwright. El adapter de Lippia no lee ese archivo y espera QA_USER / QA_PASSWORD / APP_URL. Si solo completás .env.tests, los tests de Lippia fallan en el login.

check-env.sh avisa si falta alguna de las tres obligatorias, pero no frena la ejecución. Los tests después fallan en el Background.


6. Qué genera NEO

  • Un .feature por caso de prueba (tc-<NN>-<slug>.feature; los de API terminan en .api.feature), en src/test/resources/features/<US-ID>/.
  • Pasos en español, para que coincidan con el plan de pruebas.
  • Etiquetas en cada escenario: @<US-ID> (para filtrar por historia), @tc<NN> (por caso) y @smoke o @regression.
  • El login en el Background, que no se repite en cada escenario.
  • Selectores en este orden: id, name, data-qa / data-testid, XPath por texto visible y, como último recurso, clase CSS. Si no se conoce un selector, queda By.xpath("TODO") con un comentario.
  • Esperas explícitas (WebDriverWait o las de webActionManager), nunca Thread.sleep().
app_type Plantillas que usa
web feature-template.feature + stepdef-web-template.java
api api-feature-template.feature + stepdef-api-template.java
hybrid Las dos, en archivos separados (tc-NN.feature y tc-NN.api.feature)

7. Cómo lo ejecuta lippia-neo-run-and-heal

El run.sh del adapter (que delega en lib/lippia/scripts/run.sh):

  1. Ejecuta check-env.sh: verifica Java y Maven (si falta alguno, sale con código 2) y avisa si faltan variables.
  2. Verifica que exista pom.xml en tests_dir.
  3. Resuelve dependencias con mvn dependency:resolve, salvo que SKIP_INSTALL=true.
  4. Entra a tests_dir y ejecuta mvn clean test -P<perfil> con el plugin JSON de Cucumber y las variables de entorno.
  5. Deja el resultado en target/cucumber-reports/results.json.
Variable Por defecto Para qué
QA_TESTS_DIR paths.tests_dir Raíz del módulo Maven (donde está pom.xml)
CUCUMBER_TAGS vacío (todos) Filtrar escenarios por etiqueta: @smoke, @US-002, @tc01
CUCUMBER_OPTIONS vacío Opciones extra para Cucumber
LIPPIA_PROFILE qa Perfil Maven
QA_ENV staging Ambiente de ejecución
SKIP_INSTALL false true para no resolver dependencias en cada ejecución

Lippia no filtra por carpeta. A diferencia de Playwright, no se puede ejecutar "solo esta carpeta". Para ejecutar un subconjunto se usan las etiquetas (CUCUMBER_TAGS="@US-002"). Si un plan pide filtrar por carpeta, lippia-neo-run-and-heal lo ignora y lo deja anotado.

Cuando repara, NEO trabaja sobre los step definitions en Java y los .feature, no sobre los Page Objects. Las fallas de infraestructura (api_error, por ejemplo HTTP 5xx o conexión rechazada) y las de configuración (environment, por ejemplo una variable no definida) no se reparan: se escalan.


8. Publicar los resultados en LTM

Además de dejar el resultado en target/cucumber-reports/results.json, run.sh puede publicar la ejecución en Lippia Test Manager (LTM) con el plugin de LTM del framework, mientras corre la suite. Se publica el resultado (qué escenarios pasaron y cuáles fallaron), no los casos de prueba.

Viene apagado. Se activa con QA_RESULTS_EXPORT=ltm en la ejecución que se quiere publicar.

Publicá solo la ejecución final

Cada ejecución con el export activo crea un Run nuevo en LTM. Por eso lippia-neo-run-and-heal no lo activa en las iteraciones en las que repara tests: se publica una ejecución final, cuando la suite quedó como se quiere reportar. Si la variable ya viene definida en el entorno, igual corre y lo deja anotado en escalation_notes.

En el proyecto de tests (si arrancaste desde las plantillas de lib/lippia/templates/, ya está):

Qué De dónde sale
Dependencia io.lippia.report:ltm-cucumber4-adapter 2.0.1 pom-template.xml
Clase reporters.TestManagerReporter en src/test/java/reporters/ testmanagerreporter-template.java
test-manager.screenshots en config.properties config-template.properties (DISABLED en proyectos de API)
JDK 15 o superior al ejecutar (probado con 21) Con JDK 11 el plugin falla al arrancar

En LTM:

  1. Un proyecto. Su código (el recuadro debajo del título, por ejemplo EXP222) es el que se usa; el nombre no sirve.
  2. Un access token: menú Access tokens → New → Generate.
  3. Un repositorio vinculado al proyecto. El repo y la rama de la ejecución tienen que coincidir con ese repo; si no, LTM rechaza el Run sin dar detalle. Para vincularlo, LTM pide antes una credencial de GitLab o GitHub.
Variable Obligatoria Por defecto
QA_RESULTS_EXPORT Sí, ltm para activar Vacío = no publica
TEST_MANAGER_API_HOST Sí — (ej. https://test.testmanager.lippia.io)
TEST_MANAGER_PROJECT_CODE Sí —
TEST_MANAGER_ACCESS_TOKEN Sí —
TEST_MANAGER_RUN_NAME No NEO <QA_ENV> <fecha>
TEST_MANAGER_REPOSITORY_URL No El remote origin del repo, en HTTPS y sin credenciales
TEST_MANAGER_REPOSITORY_BRANCH No La rama del CI o la rama actual de git

El token va solo en el env file del proyecto o en las variables del CI, nunca en qa-stack.yaml ni en el repositorio. run.sh nunca lo muestra en el log.

Si el export falla, run.sh termina con código 2 y lippia-neo-run-and-heal lo escala como un problema de configuración, sin tocar los tests:

Lo que ves Qué hacer
faltan variables: ... Cargar las variables que nombra el mensaje en el env file o en el CI
el export a LTM necesita JDK 15 o superior Ejecutar con JDK 15+ (recomendado 21)
export a LTM activo y no se ejecutó ningún escenario LTM rechazó el Run: revisar el código del proyecto, el token y que el repo y la rama coincidan con el repo vinculado en LTM

9. Checklist rápido

java -version
mvn -version
ls "/c/Program Files/Google/Chrome/Application/chrome.exe"   # Chrome instalado (ruta default en Windows)
echo "$APP_URL $QA_USER"                                    # variables definidas
cd tests/lippia && mvn dependency:resolve                   # acceso al Nexus de Crowdar

Si las cuatro cosas (JDK, Maven, acceso al Nexus y Chrome) están resueltas, lippia-neo-generate-test-suite y lippia-neo-run-and-heal se ejecutan de punta a punta sin intervención manual.


10. Problemas comunes (y qué hacer)

Lo que ves Por qué puede pasar Qué hacer
Java no encontrado / Maven no encontrado No están instalados o no están en el PATH Instalar o agregar <JDK>/bin y <maven>/bin al PATH (o definir JAVA_HOME)
No se encontró pom.xml en 'tests/lippia/' El módulo Maven todavía no existe o tests_dir apunta a otro lado Generar la suite con lippia-neo-generate-test-suite o corregir paths.tests_dir
Maven no puede descargar io.lippia:core No hay acceso al Nexus de Crowdar Conectarse a la red corporativa o VPN; si el Nexus pide usuario, cargarlo en ~/.m2/settings.xml
No se generó el archivo results.json Falta el plugin JSON en cucumber.options del pom.xml Agregar el bloque de la sección 4
Todos los tests fallan en el Background Faltan APP_URL, QA_USER o QA_PASSWORD en el entorno Exportarlas (sección 5); completar .env.tests no alcanza
Error de sesión de ChromeDriver No hay un Chrome real instalado, o la máquina no tiene internet la primera vez Instalar Chrome estable; la primera ejecución necesita internet para descargar el driver
Lippia no encuentra config.properties Está fuera de un <testResource> del pom.xml Moverlo a src/test/resources/ o declarar el <testResource>
Los scripts no se ejecutan en Windows Se ejecutan desde PowerShell o cmd.exe Usar Git Bash o WSL