How to Use the Cypress Cucumber Preprocessor with HyperExecute

Short answer: install and configure the community @badeball/cypress-cucumber-preprocessor package, connect it to Cypress through the file:preprocessor event in setupNodeEvents, and confirm that Cypress can run a small .feature file locally. Then use the current Cypress-specific HyperExecute runner command and YAML keys from your LambdaTest documentation or account. This guide does not verify a current HyperExecute Cypress Cucumber schema or command, so it does not invent one or reuse Java/TestNG settings.

The preprocessor turns feature files into test files Cypress can serve to the browser. Existing Gherkin files often need little change when moving from WebDriver-based Cucumber, but step definitions must use Cypress commands instead of WebDriver operations.

1. Understand the pieces

Gherkin: human-readable scenarios in .feature files.
Cucumber preprocessor: the community package that connects those features and step definitions to Cypress.
Cypress Node event: the file:preprocessor hook receives a test file and returns the path to its processed output.
HyperExecute: LambdaTest’s cloud test execution platform. Its Cypress-specific runner details must come from current official documentation.

Cypress describes a preprocessor as “the plugin responsible for preparing a support file or a test file for the browser.” The Cypress API establishes where preprocessing is attached; it does not prove the current package-specific plugin call or bundler setup. Follow the maintained package README for those details.

2. Check versions and module format

Cypress lists @badeball/cypress-cucumber-preprocessor as a community plugin. Its catalog surfaced version 28.0.0, updated September 2026, with compatibility listed for Cypress ^13.0.0, ^14.0.0, selected 15.16–15.18 releases, and ^16.0.0. These ranges can change; check the plugin’s current peer requirements against the exact Cypress version in your lockfile before upgrading.

Check the project’s module format too. Cypress 15.17.0 and later determines whether a config loads as ESM or CommonJS using Node’s module rules before executing it. Use syntax matching your repository: for example, ESM imports and export default in an ESM config, or require and module.exports in CommonJS. A loading failure does not cause Cypress to retry the other format.

3. Install and configure the preprocessor

Install Cypress and @badeball/cypress-cucumber-preprocessor using the versions supported by the package’s current README.
Choose the package’s documented bundler integration and configure feature discovery and step-definition locations as its current instructions specify.
In cypress.config.*, register the package’s Node setup from setupNodeEvents and connect the selected bundler to on('file:preprocessor', ...).
Use the package’s documented support-file and feature-file layout; do not assume a folder convention without checking your version’s docs.
Run one feature locally before expanding the spec pattern.

Important: there is no safe universal copy-paste config here. The event API defines the preprocessor contract, but the package-specific setup call, bundler API, feature discovery settings, and ESM/CommonJS imports depend on the installed package version and bundler. Copy those exact pieces from the maintained preprocessor documentation and the Cypress Preprocessors API, rather than guessing.

What the event handler must do

The handler receives a source file, runs the configured transformation, writes the built file, and resolves with that output path only after writing is complete. Cypress treats resolution as the signal that the file can be served to the browser. Cypress may invoke the handler repeatedly for the same source path; avoid creating a new file watcher on each invocation, and clean up on the file’s close event when the chosen tooling requires it.

4. Adapt step definitions from WebDriver

Feature files can generally remain largely intact. The implementation behind each step changes because Cypress commands are queued and yield subjects rather than behaving like synchronous WebDriver calls. Use Cypress assertions and chaining in the step definitions.

import { Given, When, Then } from '@badeball/cypress-cucumber-preprocessor';

Given('I open the home page', () => {
  cy.visit('/');
});

When('I search for {string}', (term) => {
  cy.get('input[type="search"]').should('be.visible').type(term);
});

Then('the search field contains {string}', (term) => {
  cy.get('input[type="search"]').should('have.value', term);
});

This is an illustrative step-definition shape; confirm the import path and step API against your installed package version. Configure the application’s base URL through Cypress’s documented configuration or CLI mechanism. Do not carry over WebDriver calls such as driver navigation, element lookup, or explicit wait utilities unchanged.

Migration guidance from Cypress says feature files can stay largely as they are while step definitions are adapted to Cypress commands such as cy.visit and cy.get. See the Cypress migration guide.

5. Validate locally before using HyperExecute

Confirm Cypress opens the project with the intended config module format.
Run the smallest .feature spec explicitly and confirm it is discovered.
Check that each step resolves to exactly one intended definition.
Confirm the application URL and any required test data are available in the local environment.
Verify that a syntax or assertion failure points to useful source lines; bundler source-map configuration can affect code frames.
Run the same command in a clean checkout or CI-like environment so undeclared local dependencies are exposed.

6. Prepare the HyperExecute run without guessing its schema

The available HyperExecute material establishes the platform category and includes TestNG examples, but does not verify a current Cypress plus Cucumber YAML schema or runner command. Java/TestNG keys such as framework identifiers, Maven commands, feature-path keys, or tag filters are not evidence for Cypress configuration.

Open the current official HyperExecute documentation or account-provided Cypress instructions for your project.
Identify the documented Cypress runner command, YAML keys, runtime/browser setup, feature discovery configuration, environment-variable handling, and report collection.
Use only settings explicitly documented for Cypress. Keep package installation and Cypress config aligned with the locally validated project.
Start with one feature file and one browser configuration, then expand to the full suite and any documented parallelization.
Inspect the cloud job output for the actual command, discovered specs, browser/runtime versions, and uploaded reports.

Do not paste a generic Java/TestNG HyperExecute YAML into a Cypress project. When the Cypress-specific instructions are unavailable, ask LambdaTest support or consult your account’s current docs rather than filling in plausible-looking keys.

7. Bundler, discovery, and debugging considerations

Bundler choice: use one supported by the installed preprocessor version and follow its maintained integration guide. Do not mix configuration examples from different bundlers.
Spec discovery: ensure the Cypress spec pattern includes feature files in the location configured for the preprocessor, while excluding unrelated fixtures or generated output.
Source maps: configure source maps as recommended by the bundler so failures can map back to feature or step source. Cypress notes that third-party bundlers may need source-map configuration; inline maps can help provide code frames.
Experimental options: the package’s esbuild guidance describes prettySourceMaps as experimental and buggy. Do not enable it as a general fix.
Repeated preprocessing: Cypress can call the event for the same source more than once. Reuse or correctly dispose of watcher state to avoid excess processes and file handles.

8. Troubleshooting

Symptom	Likely cause	Fix
No feature specs are found	The Cypress spec pattern and preprocessor feature discovery settings do not agree, or the files are outside the configured location.	Check both settings against the package README and run a single feature by path.
“No step definition found”	The definition file is not in the package’s configured step path, its pattern does not match, or the expression differs from the feature step.	Verify the package’s step-definition conventions and make the expression match the Gherkin step exactly.
Config fails before Cypress starts	The config uses ESM syntax under CommonJS rules or vice versa, or an import cannot be resolved.	Match the config syntax to the repository’s Node module setup and verify dependencies are installed in the execution environment.
Processed file is missing or intermittently unavailable	The preprocessor promise resolved before the output was written.	Resolve only after the completed output path exists and is ready to serve.
Repeated builds or hanging processes	A new bundler watcher is created for each preprocessing call and not closed.	Reuse watchers where supported and clean them up on the file close lifecycle.
Stack trace points to generated code	Bundler source maps are missing or misconfigured.	Use the package and bundler’s documented source-map settings; avoid relying on the experimental pretty-map option as a production fix.
Works locally but not on HyperExecute	Runtime, browser, environment variables, working directory, spec discovery, or runner command differs.	Compare against the current Cypress-specific HyperExecute documentation and print or inspect the effective command and discovered specs.
TestNG or Maven keys are suggested for the job	Documentation for a different framework was applied to Cypress.	Use only HyperExecute values documented for Cypress; Java examples do not establish Cypress schema.

9. Performance, reliability, and cost

Preprocessing adds build work before a feature can run. Keep feature discovery narrow, avoid rebuilding watchers unnecessarily, and use the package’s supported caching or watch behavior if documented. Source maps improve debugging but can affect build output size or processing; follow the bundler guidance and measure in your own suite rather than assuming a speed gain.

Cloud execution adds environment and network variables. Pin compatible dependency versions in the lockfile, make test setup repeatable, and begin with a small feature to distinguish configuration failures from application failures. Parallel execution can reduce elapsed time only when the documented runner supports it and the suite’s data and application state are safe to run concurrently.

HyperExecute usage costs and plan limits are not established by the sources in this guide. Check current account pricing and execution limits directly before estimating a migration budget. The Cypress plugin is community software; its compatibility and maintenance status should be rechecked when upgrading Cypress.

10. Or skip the browser setup

If your goal is capturing a page image as part of a workflow rather than running browser assertions, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns PNG, JPEG, WebP, or PDF. See the API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie and consent banners are accepted like a visitor and removed before the shot, along with known newsletter popups and chat widgets; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers say which outcome occurred. Its MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The free plan includes 1,000 screenshots each month with no card; paid plans start at $5 for 3,000.

FAQ

Can I keep my existing Gherkin feature files?

Usually, they can remain largely as written. Review step wording only where the new Cypress definitions need a different interaction model.

Does this guide provide a verified HyperExecute YAML file?

No. The available research did not verify the current Cypress-specific schema or runner command, so use the current official project instructions for those values.

Do Java/TestNG HyperExecute examples apply to this setup?

No. They describe a different test stack and do not establish Cypress runner or feature-discovery settings.

Which versions should I install?

Choose versions whose peer requirements match, then verify the current compatibility range in the package README and Cypress plugin catalog before upgrading.