Configure the adapters
This section explains how to set up your project's testing framework so NEO can use it: what you need to install, what goes in qa-stack.yaml, which configuration files the project needs, and how to check that everything is working.
There is one guide per framework. k6 and JMeter are performance frameworks (load testing against an API): they are configured with the performance block of qa-stack.yaml and used by the performance skills, not by the functional-suite skills (lippia-neo-generate-test-suite, lippia-neo-run-and-heal, lippia-neo-bootstrap-ci), which stop with framework_not_supported_by_this_skill when they meet them. The rest of this page (general steps, run.sh, parse-results.sh) describes the functional frameworks.
| Framework | Language | Adapter status | Guide |
|---|---|---|---|
| Playwright | JavaScript / TypeScript | ✅ Complete | Configure Playwright |
| playwright-bdd | JavaScript / TypeScript (Playwright + Gherkin, run with bddgen + playwright test) |
✅ Complete | Configure playwright-bdd |
| playwright-cucumberjs | JavaScript / TypeScript (Playwright + Gherkin, run with cucumber-js) | ✅ Complete | Configure playwright-cucumberjs |
| Lippia | Java (Maven + Cucumber + TestNG + Selenium) | ✅ Complete | Configure Lippia |
| Cypress | JavaScript / TypeScript (Cypress + Cucumber) | ✅ Complete (with limitations in the coverage search and in CI; see its guide) | Configure Cypress |
| k6 | JavaScript (performance) | ✅ Complete (load testing; does not use the functional-suite skills) | Configure k6 |
| JMeter | Java (performance) | ✅ Complete (load testing; does not use the functional-suite skills) | Configure JMeter |
| Pytest | Python | ⛔ STUB: documented but not implemented; the skills stop | Configure Pytest |
1. What is an adapter?
NEO is designed to work with any testing framework. The skills describe what needs to be done ("generate one test for each case in the plan", "run the suite and fix whatever fails"), but they don't know by heart how to do that in each framework.
That translation is done by the adapter: a set of files (conventions, templates, and scripts) that teaches the skill how to write, run, and read the results of a specific framework.
An analogy: the skill is an appliance and the adapter is the plug adapter. The appliance always does the same thing; the plug adapter changes depending on the country (the framework) where you plug it in.
Each adapter provides:
| Piece | What it's for | Example in Playwright |
|---|---|---|
Conventions (README.md) |
The framework's rules: how to name files, which selectors to prefer, how to handle login, how to wait | "One .spec.js per test case; prefer getByRole over CSS classes" |
| Templates | The base each test is generated from (tests are never written from scratch) | spec-template.spec.js, api-spec-template.spec.js |
Run script (run.sh) |
How to run the suite | npx playwright test |
Results script (parse-results.sh) |
Converts the framework's report into a common format the skill understands | Reads test-results/results.json |
2. How does NEO choose which adapter to use?
Everything comes from a single field in the qa-stack.yaml file, which lives at the root of the test repository:
stack:
test_framework: playwright # playwright | playwright-bdd | playwright-cucumberjs | cypress | lippia | pytest | k6 | jmeter
When a skill needs the framework, it always follows these steps:
- It reads
stack.test_frameworkfromqa-stack.yaml. - It looks for the
adapters/<test_framework>/folder inside the skill. - If it finds a
README.md, it loads its conventions and uses its templates and scripts. - If it only finds a
STUB.md(adapter not implemented), it stops with the messageAdapter <framework> en estado STUB. Ver <skill_root>/adapters/<framework>/STUB.md para contribuir.
In the case of Lippia, besides the adapter folder, the skills read the shared library
lib/lippia/in the skills repository, where the actual templates and scripts live. The two Gherkin runners (playwright-bdd and playwright-cucumberjs) sharelib/gherkin/: the data guidelines, each runner's data helper, and the data lint.
Skills that use adapters
| Skill | What it takes from the adapter |
|---|---|
lippia-neo-generate-test-suite |
Conventions and templates to write the tests |
lippia-neo-run-and-heal |
run.sh to run the suite and parse-results.sh to read the results |
lippia-neo-run-manual-testing and lippia-neo-reproduce-bug |
The ability to drive a real browser, which is provided by the Playwright MCP (see Configure the MCPs) |
lippia-neo-ci-bootstrap |
It doesn't use a framework adapter: it uses a CI provider adapter (GitHub, GitLab, Bitbucket), chosen by stack.pipeline_provider |
3. General steps (they apply to any framework)
Step 1 — Install what the framework requires
Each guide has its own list (Node.js, Java, Maven, browsers…). Do this before asking the assistant for anything: if a tool is missing, the adapter scripts stop before running a single test.
Step 2 — Generate qa-stack.yaml with lippia-neo-bootstrap-stack
Ask the assistant:
Set up the project for QA with lippia-neo-bootstrap-stack
The lippia-neo-bootstrap-stack skill detects the framework by looking at the repository. The first matching row wins: Gherkin projects also include @playwright/test, so they are checked first.
| If it finds… | It deduces |
|---|---|
package.json with playwright-bdd |
test_framework: playwright-bdd (and typescript if there is a tsconfig.json) |
package.json with @cucumber/cucumber plus @playwright/test or playwright |
test_framework: playwright-cucumberjs. If it also includes playwright-bdd, it asks you which one to use |
package.json with @playwright/test (and none of the above) |
test_framework: playwright (and typescript if there is a tsconfig.json) |
package.json with cypress |
test_framework: cypress (and typescript if there is a tsconfig.json or cypress.config.ts). If it also includes @playwright/test, it asks you which one to use |
pom.xml or build.gradle with cucumber / lippia |
test_framework: lippia, language: java |
pyproject.toml / setup.cfg / requirements.txt with pytest |
test_framework: pytest, language: python |
Whatever it can't deduce (app type, authentication, environment URL, version, operating system, and the folders where each thing is stored) it asks you. If you prefer to put it together by hand, each guide includes a complete sample qa-stack.yaml.
Step 3 — Configure the framework project
Each framework needs its configuration file to include certain things so NEO can read the results. For example, the JSON report must be enabled. This is detailed in each guide.
Step 4 — Add the test environment credentials
Credentials are never written in the tests. lippia-neo-bootstrap-stack creates a .env.tests file (kept out of git) with empty keys based on the authentication type, and you fill in the values by hand:
stack.auth |
Keys generated in .env.tests |
|---|---|
basic_auth |
APP_USER, APP_PASSWORD |
api_token |
API_TOKEN_MANAGER, API_TOKEN_VIEWER |
google_sso |
None: the session is saved in a browser state file (see the Playwright guide) |
none |
None |
If app_type is api or hybrid, API_BASE_URL is added as well.
Watch out with Lippia: the Lippia adapter reads different variables (
APP_URL,QA_USER,QA_PASSWORD) and takes them from the terminal environment, not from.env.tests. This is explained in its guide.
Step 5 — Verify
Ask the assistant to run the suite with lippia-neo-run-and-heal. Each guide has a quick checklist with the commands to confirm the environment is ready.
4. What all adapters have in common
Where the tests are written
Always directly in paths.tests_dir from qa-stack.yaml. If you accepted the default value from lippia-neo-bootstrap-stack, that folder already includes the framework name (tests/playwright/, tests/playwright-bdd/, tests/cypress/, tests/lippia/…). If you chose your own folder (for example e2e/), it is used as is. The skills never add a subfolder named after the framework.
Replace the run command (commands)
If your project runs its tests with a special command, you can replace the one the adapter uses:
commands:
run_tests: null # null = use the adapter's run.sh
install_deps: null # null = use the default install (npm ci, mvn dependency:resolve…)
| When to replace it | Example |
|---|---|
| You want to run a single browser or a different reporter | npx playwright test --project=chromium |
You use yarn or pnpm instead of npm |
install_deps: pnpm install --frozen-lockfile |
| Your Maven project uses a different profile | run_tests: mvn test -Pqa |
If you replace
run_tests, make sure the command still generates the JSON report thatparse-results.shexpects. Otherwise,NEOcan't read the results.
What each exit code means
| Code | Meaning | What lippia-neo-run-and-heal does |
|---|---|---|
0 |
All tests passed | Finishes green |
1 (or anything other than 0 and 2) |
Some tests are failing | Analyzes each failure and tries to fix it |
2 |
Environment or configuration failure (a tool is missing, there is no pom.xml, the report wasn't generated…) |
Doesn't try to fix anything: it tells you what's missing |
The scripts are bash
The run.sh and parse-results.sh scripts in every adapter are bash scripts. On Windows they must run on Git Bash or WSL; they don't work if you call them directly from cmd.exe or PowerShell.
5. Common problems (and what to do)
| What you see | Why it may happen | What to do |
|---|---|---|
Adapter <framework> en estado STUB |
The chosen framework doesn't have an implemented adapter yet (today: Pytest) | See the Pytest guide for alternatives |
The skill says it can't find qa-stack.yaml |
The bootstrap was never run in that repository | Run lippia-neo-bootstrap-stack (or the New Project Bootstrap playbook) |
| The tests are generated, but the framework "can't find any tests" | The framework configuration points to a different folder or extension | Check testDir / specPattern / testMatch according to your framework's guide |
run.sh doesn't start on Windows |
It's being run from PowerShell or cmd.exe |
Use Git Bash or WSL |
| All tests fail at login | The credentials are missing from .env.tests (or from the environment, for Lippia) |
Fill in the variables from Step 4 |