Skip to content

Configure Lippia

Adapter status: ✅ Complete. It is used by lippia-neo-generate-test-suite (to write the .feature files and step definitions) and lippia-neo-run-and-heal (to run them with Maven and fix them).

Value in qa-stack.yaml test_framework: lippia
Language java
What it is Lippia Core Framework (io.lippia:core): Cucumber 4 (Gherkin), TestNG, Selenium 3 for web, and Spring RestTemplate for API
App types web, api, and hybrid
Authentication basic_auth or API token, always through environment variables (there is no equivalent to google_sso)
Default tests folder tests/lippia/ (it is the root of the Maven module)

The actual Lippia templates and scripts live in the shared library lib/lippia/ in the skills repository. Each skill's adapters simply delegate to it.


1. What you need installed

Unlike Playwright, there isn't a single command that installs everything: there are five independent things.

Tool Version How to check it Notes
JDK 8 or higher java -version Lippia compiles for 1.8, but it runs without problems on 11, 17, or 21. If java isn't on the PATH, add <JDK>/bin or set JAVA_HOME
Maven 3.6 or higher mvn -version If it isn't on the PATH, add <maven>/bin
Access to the Crowdar Nexus — mvn dependency:resolve inside the tests folder io.lippia:core is downloaded from there. It requires the corporate network or VPN, depending on the current policy
A real Google Chrome (or Chromium) Stable It must be installed on the machine The Chromium that Playwright downloads is not enough. You don't need to install ChromeDriver: Lippia downloads it on its own
Bash (Git Bash or WSL on Windows) — bash --version The lib/lippia/scripts/*.sh scripts don't work from cmd.exe or PowerShell

Nexus repositories used by the project:

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

For read-only access to releases, you don't need to configure credentials in ~/.m2/settings.xml. If your Nexus requires authentication, add them there.


2. Sample qa-stack.yaml

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/    # root of the Maven module (pom.xml goes here)
  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   # Lippia only

commands:
  run_tests: null             # uses the adapter's run.sh → mvn clean test
  install_deps: null          # uses mvn dependency:resolve

paths.lippia_config_path appears only when the framework is Lippia. lippia-neo-bootstrap-stack looks for config.properties in the repository and only asks you for the path if it can't find it (it never creates it). If it doesn't exist yet, lippia-neo-generate-test-suite generates it from the template.

Maven classpath: Lippia loads config.properties as a classpath resource (src/test/resources/), not from any arbitrary path. If you choose a path outside a <testResource> declared in pom.xml, you have to add one that points there. Otherwise, Lippia can't find the file.


3. Project structure

Everything lives directly under paths.tests_dir, which is the root of the Maven module:

tests/lippia/                                  ← paths.tests_dir
├── pom.xml                                    ← if it doesn't exist, it is created from the template
└── src/
    ├── main/java/pages/                       ← Page Objects (if there was a previous exploration)
    │   └── CarritoPage.java
    └── test/
        ├── java/
        │   ├── runners/TestNGRunner.java      ← Cucumber + TestNG runner
        │   └── steps/
        │       ├── CommonSteps.java           ← Background and login, one per project
        │       └── <US-ID>Steps.java          ← steps for each user story
        └── resources/
            ├── features/
            │   └── US-002/
            │       ├── tc-01-agregar-producto.feature
            │       └── tc-02-crear-orden.api.feature   ← API case
            ├── testng.xml
            └── config.properties

If the project doesn't have pom.xml, testng.xml, config.properties, TestNGRunner.java, or CommonSteps.java, lippia-neo-generate-test-suite creates them from the templates in lib/lippia/templates/.


4. Configure pom.xml and config.properties

pom.xml

If you start from the template (lib/lippia/templates/pom-template.xml), everything is already configured. If the project already had its own pom.xml, check that it has:

What Why
The io.lippia:core dependency (version 3.3.0.3 or higher) It's the framework
The Crowdar Nexus repositories (crowdar-releases, crowdar-snapshots) Without them Maven can't find Lippia
A Maven profile qa run.sh runs with -Pqa by default
The Cucumber JSON plugin in cucumber.options parse-results.sh reads target/cucumber-reports/results.json. Without that file, it can't read the results

The cucumber.options block you need:

<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

The most important values in the template:

Property What it's for Values
crowdar.projectType Project type or browser WEB_CHROME, WEB_FIREFOX, WEB_EDGE, API, DATABASE, GENERIC
crowdar.driver.setup.strategy How the browser driver is obtained empty = downloaded automatically · LOCAL = driver already installed on the PATH · GRID = Selenium Grid
crowdar.driverHub Selenium Hub URL Only if the strategy is GRID
crowdar.capabilities Browser capabilities file chromeCapabilities.json
crowdar.element.wait and the other timeouts Wait times, in seconds 30 by default
crowdar.extent.environment Environment shown in the report staging, dev, or prod

Credentials never go in config.properties. They are always loaded from environment variables.

Avoid writing an absolute path to chrome.exe in chromeCapabilities.json (goog:chromeOptions.binary), unless it's essential (for example, a Docker image with Chrome in a non-standard path). A path from your machine won't work in another environment or in CI.

Headless mode: to run without a window (for example in CI), the Maven profile has to set --headless in the Chrome capabilities.


5. Credentials and environment variables

The Lippia adapter takes the data from the terminal environment and passes it to Maven as properties (-DAPP_URL=..., -DQA_USER=...). In the code, the steps read them with System.getenv("NOMBRE").

Variable Required What it's for
APP_URL Yes (web tests) Base URL of the application
QA_USER Yes (with basic_auth) Test user
QA_PASSWORD Yes (with basic_auth) Test password
BASE_API_URL API tests only Base URL of the API
API_TOKEN If the API uses a token Bearer token
QA_ENV No (default staging) Environment, passed as -Dtest.environment

Set them in the same terminal where the assistant is working, before running the suite:

export APP_URL="https://techstore-staging.com"
export QA_USER="test-user"
export QA_PASSWORD="test-password"
# only if app_type is api or hybrid:
export BASE_API_URL="https://api.techstore-staging.com"
export API_TOKEN="token-de-prueba"

⚠️ Difference from .env.tests: for basic_auth, lippia-neo-bootstrap-stack generates .env.tests with the keys APP_USER and APP_PASSWORD, which are the ones Playwright uses. The Lippia adapter doesn't read that file and expects QA_USER / QA_PASSWORD / APP_URL. If you only fill in .env.tests, the Lippia tests fail at login.

check-env.sh warns you if any of the three required variables is missing, but it doesn't stop the run. The tests then fail in the Background.


6. What NEO generates

  • One .feature per test case (tc-<NN>-<slug>.feature; API ones end in .api.feature), in src/test/resources/features/<US-ID>/.
  • Steps in Spanish, so they match the test plan.
  • Tags on each scenario: @<US-ID> (to filter by user story), @tc<NN> (by case), and @smoke or @regression.
  • Login in the Background, so it isn't repeated in every scenario.
  • Selectors in this order: id, name, data-qa / data-testid, XPath by visible text and, as a last resort, CSS class. If a selector isn't known, it is left as By.xpath("TODO") with a comment.
  • Explicit waits (WebDriverWait or the ones in webActionManager), never Thread.sleep().
app_type Templates it uses
web feature-template.feature + stepdef-web-template.java
api api-feature-template.feature + stepdef-api-template.java
hybrid Both, in separate files (tc-NN.feature and tc-NN.api.feature)

7. How lippia-neo-run-and-heal runs it

The adapter's run.sh (which delegates to lib/lippia/scripts/run.sh):

  1. Runs check-env.sh: checks Java and Maven (if either is missing, it exits with code 2) and warns if variables are missing.
  2. Checks that pom.xml exists in tests_dir.
  3. Resolves dependencies with mvn dependency:resolve, unless SKIP_INSTALL=true.
  4. Goes into tests_dir and runs mvn clean test -P<perfil> with the Cucumber JSON plugin and the environment variables.
  5. Leaves the result in target/cucumber-reports/results.json.
Variable Default What it's for
QA_TESTS_DIR paths.tests_dir Root of the Maven module (where pom.xml is)
CUCUMBER_TAGS empty (all) Filter scenarios by tag: @smoke, @US-002, @tc01
CUCUMBER_OPTIONS empty Extra options for Cucumber
LIPPIA_PROFILE qa Maven profile
QA_ENV staging Execution environment
SKIP_INSTALL false true to skip resolving dependencies on every run

Lippia doesn't filter by folder. Unlike Playwright, you can't run "just this folder". To run a subset, you use tags (CUCUMBER_TAGS="@US-002"). If a plan asks to filter by folder, lippia-neo-run-and-heal ignores it and makes a note of it.

When fixing, NEO works on the Java step definitions and the .feature files, not on the Page Objects. Infrastructure failures (api_error, for example HTTP 5xx or connection refused) and configuration failures (environment, for example an undefined variable) aren't fixed: they are escalated.


8. Publish the results to LTM

Besides leaving the result in target/cucumber-reports/results.json, run.sh can publish the run to Lippia Test Manager (LTM) with the framework's LTM plugin, while the suite runs. What gets published is the result (which scenarios passed and which failed), not the test cases.

It's off by default. You turn it on with QA_RESULTS_EXPORT=ltm in the run you want to publish.

Publish only the final run

Every run with the export on creates a new Run in LTM. That's why lippia-neo-run-and-heal doesn't turn it on in the iterations where it fixes tests: you publish one final run, once the suite is the way you want to report it. If the variable is already set in the environment, it still runs and notes it in escalation_notes.

In the test project (if you started from the templates in lib/lippia/templates/, it's already there):

What Where it comes from
Dependency io.lippia.report:ltm-cucumber4-adapter 2.0.1 pom-template.xml
Class reporters.TestManagerReporter in src/test/java/reporters/ testmanagerreporter-template.java
test-manager.screenshots in config.properties config-template.properties (DISABLED in API projects)
JDK 15 or higher at runtime (tested with 21) With JDK 11 the plugin fails on startup

In LTM:

  1. A project. Its code (the box under the title, for example EXP222) is what you use; the name doesn't work.
  2. An access token: Access tokens → New → Generate menu.
  3. A repository linked to the project. The run's repo and branch must match that repo; otherwise LTM rejects the Run without details. To link it, LTM first asks for a GitLab or GitHub credential.
Variable Required Default
QA_RESULTS_EXPORT Yes, ltm to turn it on Empty = doesn't publish
TEST_MANAGER_API_HOST Yes — (e.g. https://test.testmanager.lippia.io)
TEST_MANAGER_PROJECT_CODE Yes —
TEST_MANAGER_ACCESS_TOKEN Yes —
TEST_MANAGER_RUN_NAME No NEO <QA_ENV> <date>
TEST_MANAGER_REPOSITORY_URL No The repo's remote origin, in HTTPS and without credentials
TEST_MANAGER_REPOSITORY_BRANCH No The CI branch or the current git branch

The token goes only in the project's env file or in the CI variables, never in qa-stack.yaml or in the repository. run.sh never shows it in the log.

If the export fails, run.sh ends with code 2 and lippia-neo-run-and-heal escalates it as a configuration problem, without touching the tests:

What you see What to do
faltan variables: ... Load the variables named in the message in the env file or in the CI
el export a LTM necesita JDK 15 o superior Run with JDK 15+ (21 recommended)
export a LTM activo y no se ejecutó ningún escenario LTM rejected the Run: check the project code, the token, and that the repo and branch match the repo linked in LTM

9. Quick checklist

java -version
mvn -version
ls "/c/Program Files/Google/Chrome/Application/chrome.exe"   # Chrome installed (default path on Windows)
echo "$APP_URL $QA_USER"                                    # variables set
cd tests/lippia && mvn dependency:resolve                   # access to the Crowdar Nexus

If all four things (JDK, Maven, Nexus access, and Chrome) are in place, lippia-neo-generate-test-suite and lippia-neo-run-and-heal run end to end without manual intervention.


10. Common problems (and what to do)

What you see Why it may happen What to do
Java no encontrado / Maven no encontrado They aren't installed or aren't on the PATH Install them or add <JDK>/bin and <maven>/bin to the PATH (or set JAVA_HOME)
No se encontró pom.xml en 'tests/lippia/' The Maven module doesn't exist yet, or tests_dir points somewhere else Generate the suite with lippia-neo-generate-test-suite or fix paths.tests_dir
Maven can't download io.lippia:core There's no access to the Crowdar Nexus Connect to the corporate network or VPN; if the Nexus requires a user, add it in ~/.m2/settings.xml
No se generó el archivo results.json The JSON plugin is missing from cucumber.options in pom.xml Add the block from section 4
All tests fail in the Background APP_URL, QA_USER, or QA_PASSWORD are missing from the environment Export them (section 5); filling in .env.tests isn't enough
ChromeDriver session error There's no real Chrome installed, or the machine has no internet the first time Install stable Chrome; the first run needs internet to download the driver
Lippia can't find config.properties It's outside a <testResource> in pom.xml Move it to src/test/resources/ or declare the <testResource>
The scripts don't run on Windows They're being run from PowerShell or cmd.exe Use Git Bash or WSL