Configure Cypress
Adapter status: ✅ Complete. Cypress is a valid value of stack.test_framework: lippia-neo-bootstrap-stack detects it, lippia-neo-generate-test-suite generates the suite from its templates, and lippia-neo-run-and-heal runs and repairs it.
| Piece | Does it support Cypress? |
|---|---|
List of valid frameworks in STACK.md and in qa-stack.yaml |
✅ playwright, cypress, lippia, and pytest |
Automatic detection in lippia-neo-bootstrap-stack |
✅ When package.json includes cypress. If it also includes @playwright/test, it asks you which one to use |
lippia-neo-generate-test-suite (adapters/cypress/) |
✅ README and 9 templates |
lippia-neo-run-and-heal (adapters/cypress/) |
✅ run.sh and parse-results.sh, with scoping by folder and by file |
lippia-neo-find-existing-tests and lippia-neo-find-ui-tests-by-code-diff |
❌ Not yet: they return not_found with a warning |
lippia-neo-repair-selectors-by-diff |
❌ Not yet: it stops with a warning, without repairing anything |
CI jobs from lippia-neo-bootstrap-ci |
❌ They don't install the Cypress dependencies yet (see section 9) |
Value in qa-stack.yaml |
test_framework: cypress |
| Language | javascript or typescript (if there is a tsconfig.json or cypress.config.ts) |
| What it uses | Cypress + @badeball/cypress-cucumber-preprocessor (scenarios in Gherkin) |
| App types | web, api, and hybrid |
| Authentication | basic_auth or api_token. google_sso has no automatic solution (see section 4) |
| Tests folder | paths.tests_dir, which for Cypress is also the root of the Cypress project (e.g. tests/cypress/) |
1. What you need installed
| Tool | Version | How to check it |
|---|---|---|
| Node.js | 18 or higher | node -v |
cypress |
The one in package.json |
npx cypress version |
@badeball/cypress-cucumber-preprocessor |
The one in package.json |
Listed in package.json |
A bundler for the preprocessor: @bahmutov/cypress-esbuild-preprocessor (the one the template uses) or @cypress/webpack-preprocessor |
— | Listed in package.json |
dotenv |
— | Listed in package.json |
| Bash (Git Bash or WSL on Windows) | — | bash --version |
npm install -D cypress @badeball/cypress-cucumber-preprocessor @bahmutov/cypress-esbuild-preprocessor dotenv
For the skills that browse the application live (
lippia-neo-run-manual-testing,lippia-neo-reproduce-bug),NEOuses the Playwright MCP, regardless of the testing framework. If you're going to use those skills, configure it too (see Playwright MCP setup).
2. Sample qa-stack.yaml
stack:
test_framework: cypress
language: javascript
app_type: web
auth: basic_auth
pipeline_provider: github
environment:
base_url: https://techstore-staging.com
app_version: 2.4.1
os: Windows 11
paths:
user_stories_storage:
type: local
cloud_provider_mcp: null
local_path: user-stories/
test_plans_dir: test-plans/
tests_dir: tests/cypress/ # root of the Cypress project: cypress.config.js goes here
reports_dir: test-results/reports/
scripted_dir: execution/
exploratory_dir: exploration/
env_file: .env.tests
commands:
run_tests: null # uses the adapter's run.sh → npx cypress run --project <tests_dir>
install_deps: null
3. Configure the Cypress project
Unlike Playwright, cypress.config.js does not go at the root of the repository: it goes at the root of paths.tests_dir, because the adapter runs Cypress with --project <tests_dir>.
cypress.config.js
// tests/cypress/cypress.config.js
const { defineConfig } = require('cypress');
const createBundler = require('@bahmutov/cypress-esbuild-preprocessor');
const { addCucumberPreprocessorPlugin } = require('@badeball/cypress-cucumber-preprocessor');
const { createEsbuildPlugin } = require('@badeball/cypress-cucumber-preprocessor/esbuild');
require('dotenv').config({ path: '.env.tests' }); // = paths.env_file
module.exports = defineConfig({
screenshotsFolder: 'screenshots', // required: parse-results.sh looks for the screenshots here
videosFolder: 'videos',
e2e: {
baseUrl: 'https://techstore-staging.com', // = environment.base_url
specPattern: 'e2e/features/**/*.feature',
supportFile: 'support/e2e.js',
async setupNodeEvents(on, config) {
await addCucumberPreprocessorPlugin(on, config);
on('file:preprocessor', createBundler({ plugins: [createEsbuildPlugin(config)] }));
return config;
},
env: {
APP_USER: process.env.APP_USER, // only the keys that match stack.auth
APP_PASSWORD: process.env.APP_PASSWORD,
},
},
});
| What | Why |
|---|---|
screenshotsFolder: 'screenshots' and videosFolder: 'videos' |
parse-results.sh rebuilds the screenshot path for each failure assuming those folders |
specPattern: 'e2e/features/**/*.feature' |
So Cypress finds the .feature files that NEO generates |
require('dotenv').config(...) + env block |
Cypress doesn't load .env on its own: you have to read .env.tests and expose the variables. In the tests they are used with Cypress.env('APP_USER') |
.cypress-cucumber-preprocessorrc.json
Enables the JSON report that lippia-neo-run-and-heal reads (one file per feature):
{
"json": { "enabled": true, "output": "reports/json/[name].json" },
"html": { "enabled": true, "output": "reports/cucumber-report.html" },
"stepDefinitions": ["e2e/step_definitions/**/*.js"],
"filterSpecs": true,
"omitFiltered": true
}
If your project already had this file with the JSON in a different folder, don't move it: set that folder in the
CYPRESS_JSON_OUTPUTvariable (see section 6).
4. Authentication
basic_auth and api_token
Fill in the values in .env.tests and expose them in the env block of cypress.config.js. The steps read them with Cypress.env('NOMBRE') and never write them as literals:
Given('el usuario está autenticado', () => {
loginPage.visit();
loginPage.login(Cypress.env('APP_USER'), Cypress.env('APP_PASSWORD'));
});
google_sso — known limitation
Cypress has no equivalent to Playwright's storageState, and the real Google login gets blocked by bot detection, 2FA, or captcha. If you set auth: google_sso with Cypress:
lippia-neo-generate-test-suitedoes not generate an automatic session mechanism: it leaves aTODOin the login step and a warning in its output.lippia-neo-run-and-healdoes not validate anything about the session before running: login failures show up as regular failures (probablyenvironment).
Possible alternatives: cy.session() with a programmatic login against an internal endpoint that doesn't go through Google, or use basic_auth / api_token if the app has an alternative login for testing.
5. What NEO generates
tests/cypress/ ← paths.tests_dir (root of the Cypress project)
├── cypress.config.js
├── .cypress-cucumber-preprocessorrc.json
├── support/e2e.js ← support file
├── e2e/
│ ├── features/US-002/
│ │ ├── tc-001-agregar-producto.feature ← one .feature per test case
│ │ └── tc-002-carrito-vacio.feature
│ ├── step_definitions/ ← steps (includes the common login steps, only once)
│ └── pages/ ← Page Objects (CarritoPage.js, LoginPage.js…)
├── reports/json/ ← output read by lippia-neo-run-and-heal
└── screenshots/ videos/ ← automatic evidence of failures
Rules the generated tests follow:
- Imports always from
@badeball/cypress-cucumber-preprocessor, never from the plaincucumberpackage (it has a different API and is incompatible). - Selectors, in this order:
data-cy,data-testid,id/name, visible text (cy.contains) and, as a last resort, CSS class. If a selector isn't known, it is left ascy.get('TODO')with a comment. - Page Objects: selectors are encapsulated in
e2e/pages/and never left loose in the steps. - Waits use the automatic retry of
.should(...), never fixed pauses likecy.wait(2000).cy.wait('@alias')only on a namedcy.intercept. - Network mocks with
cy.intercept().
6. How lippia-neo-run-and-heal runs it
The adapter's run.sh:
- Checks that
node_modules, Cypress, andcypress.config.js(or.ts) exist insidetests_dir. If anything is missing, it exits with code2. - Runs
npx cypress run --project <tests_dir>with the appropriate filters. parse-results.shreads the JSON files inreports/json/and rebuilds the screenshot path for each failure.
| Variable | Default | What it's for |
|---|---|---|
QA_TESTS_DIR |
Required | Root of the Cypress project (paths.tests_dir). It is always a single folder |
QA_CUCUMBER_TAGS |
empty | Filter by tag: @smoke, @US-002, "@US-002 and not @wip" |
QA_CUCUMBER_SPEC |
empty | Run only certain .feature files: comma-separated globs (e.g. e2e/features/US-002/**/*.feature) |
QA_EXCLUDE_DIRS |
empty | Subfolders of e2e/features/ to exclude, separated by spaces |
CYPRESS_FLAGS |
empty | Extra flags, for example --browser firefox |
CYPRESS_CONFIG |
empty | Use a different config file (--config-file) |
CYPRESS_JSON_OUTPUT |
reports/json |
JSON report folder, relative to QA_TESTS_DIR |
When a playbook narrows down the run, lippia-neo-run-and-heal translates its options like this (QA_TESTS_DIR never changes):
lippia-neo-run-and-heal option |
Becomes |
|---|---|
config.target_tests |
QA_CUCUMBER_SPEC with each test's path, comma-separated |
config.include_dirs |
QA_CUCUMBER_SPEC with e2e/features/<folder>/**/*.feature for each folder |
config.exclude_dirs |
QA_EXCLUDE_DIRS with the names of the e2e/features/ subfolders |
Cypress runs in headless mode by default with
cypress run, so you don't need any extra flag for CI.
trace_pathis always empty: Cypress has no equivalent to the Playwright trace. The screenshot for each failure is located using Cypress's naming convention; if it isn't found, it stays empty, and that is not an error.
7. Quick checklist
node -v
npx cypress version
ls tests/cypress/cypress.config.js tests/cypress/.cypress-cucumber-preprocessorrc.json
grep -n "screenshotsFolder" tests/cypress/cypress.config.js
QA_TESTS_DIR=tests/cypress QA_CUCUMBER_TAGS=@smoke bash <path-to-adapter>/run.sh
8. Common problems (and what to do)
| What you see | Why it may happen | What to do |
|---|---|---|
QA_TESTS_DIR debe apuntar al project root de Cypress |
The Cypress project folder wasn't specified | Set QA_TESTS_DIR to paths.tests_dir |
No se encontró cypress.config.js/ts en '<tests_dir>' |
The config is at the root of the repository instead of in tests_dir |
Move or create cypress.config.js inside tests_dir |
Cypress no encontrado |
The package isn't installed | npm install -D cypress |
| No results show up after running | The preprocessor doesn't have the JSON report enabled or writes it to a different folder | Check .cypress-cucumber-preprocessorrc.json or set CYPRESS_JSON_OUTPUT |
screenshot_path empty in failures |
screenshotsFolder was changed to a different folder |
Go back to screenshotsFolder: 'screenshots' |
| Steps aren't found ("step implementation missing") | It was imported from cucumber instead of @badeball/cypress-cucumber-preprocessor, or stepDefinitions points to a different folder |
Fix the import or the stepDefinitions glob |
lippia-neo-bootstrap-stack asks you which framework to use |
package.json includes both cypress and @playwright/test |
Choose the one the suite will be generated with |
lippia-neo-find-existing-tests always returns not_found |
The existing-coverage search doesn't support Cypress yet | It's a current limitation (see the table at the top) |
9. Current limitations
| What | What happens with Cypress | Alternative |
|---|---|---|
Searching for existing coverage (lippia-neo-find-existing-tests, lippia-neo-find-ui-tests-by-code-diff) |
They return status: not_found with a warning, without checking the .feature files |
Tell lippia-neo-run-and-heal which folders to run with include_dirs |
Repairing selectors from a diff (lippia-neo-repair-selectors-by-diff) |
It stops with a warning, without touching the tests | Run lippia-neo-run-and-heal: it repairs broken selectors while running the suite |
CI jobs (lippia-neo-bootstrap-ci) |
The install step has no branch for Cypress. On GitHub and Bitbucket it is treated as playwright (it runs npm install and installs the Playwright browsers); on GitLab and Jenkins it installs nothing |
Manually add the Cypress installation to the generated job (npm ci and npx cypress install) |