Skip to content

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), NEO uses 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_OUTPUT variable (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-suite does not generate an automatic session mechanism: it leaves a TODO in the login step and a warning in its output.
  • lippia-neo-run-and-heal does not validate anything about the session before running: login failures show up as regular failures (probably environment).

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 plain cucumber package (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 as cy.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 like cy.wait(2000). cy.wait('@alias') only on a named cy.intercept.
  • Network mocks with cy.intercept().

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

The adapter's run.sh:

  1. Checks that node_modules, Cypress, and cypress.config.js (or .ts) exist inside tests_dir. If anything is missing, it exits with code 2.
  2. Runs npx cypress run --project <tests_dir> with the appropriate filters.
  3. parse-results.sh reads the JSON files in reports/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_path is 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)