Skip to content

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:

  1. It reads stack.test_framework from qa-stack.yaml.
  2. It looks for the adapters/<test_framework>/ folder inside the skill.
  3. If it finds a README.md, it loads its conventions and uses its templates and scripts.
  4. If it only finds a STUB.md (adapter not implemented), it stops with the message Adapter <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) share lib/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 that parse-results.sh expects. Otherwise, NEO can'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