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.propertiesas a classpath resource (src/test/resources/), not from any arbitrary path. If you choose a path outside a<testResource>declared inpom.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.exeinchromeCapabilities.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
--headlessin 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: forbasic_auth,lippia-neo-bootstrap-stackgenerates.env.testswith the keysAPP_USERandAPP_PASSWORD, which are the ones Playwright uses. The Lippia adapter doesn't read that file and expectsQA_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
.featureper test case (tc-<NN>-<slug>.feature; API ones end in.api.feature), insrc/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@smokeor@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 asBy.xpath("TODO")with a comment. - Explicit waits (
WebDriverWaitor the ones inwebActionManager), neverThread.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):
- Runs
check-env.sh: checks Java and Maven (if either is missing, it exits with code2) and warns if variables are missing. - Checks that
pom.xmlexists intests_dir. - Resolves dependencies with
mvn dependency:resolve, unlessSKIP_INSTALL=true. - Goes into
tests_dirand runsmvn clean test -P<perfil>with the Cucumber JSON plugin and the environment variables. - 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-healignores 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:
- A project. Its code (the box under the title, for example
EXP222) is what you use; the name doesn't work. - An access token: Access tokens → New → Generate menu.
- 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.yamlor in the repository.run.shnever 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 |