Merv-Local + Cucumber (Java) guide

Introduction

Cucumber runs BDD scenarios in Java. Merv-Local hooks into Cucumber via org.teche.merv.client.plugin.MervCucumberHandler and writes rich HTML/JSON reports under merv.report.folder — no central server required.

Using Cucumber-js (Node.js)? See the Merv-Local + Cucumber-js guide for merv-client/cucumber-formatter and Playwright hooks.

You will learn
  • How to add merv-client-api to Maven or Gradle
  • Minimum merv.properties for local mode
  • How to register the Cucumber plugin and bind Selenium (optional)
  • How to record data, validation, and info steps
  • Where suite HTML and the dashboard live after a run

Add dependency

Add MERV to your project (use the latest version from Maven Central when available):

Maven (pom.xml)

<dependency>
  <groupId>io.github.techelliiptica</groupId>
  <artifactId>merv-client-api</artifactId>
  <version>4.0.0</version>
</dependency>

Gradle

dependencies {
  testImplementation "io.github.techelliiptica:merv-client-api:4.0.0"
}

Configure merv.properties

Place merv.properties in your project root (next to pom.xml — the directory where you run mvn test).

Sample Configuration

merv.local=true
merv.regression_suite=Your Regression Suite Name
merv.report.folder=./merv-reports

Download sample merv.properties

Common properties

Property Role
merv.local true — Merv-Local: write HTML/JSON reports on disk under merv.report.folder (no cloud API).
false — Merv-Server: send suites, cases, and steps to the MERV cloud API (set merv.server, API key, and hierarchy as well).
merv.report.folder Root for timestamped run folders and index.html dashboard.
merv.regression_suite Suite title in JSON and HTML.
merv.execution.parallel true — parallel scenarios share one suite folder safely.
false — single-threaded run (default for most suites).
merv.screenshot true (or legacy on / yes) — capture a PNG after each Gherkin step when a WebDriver is bound via MervCucumberHandler.setAutomationToolObject(...).
false — no automatic step screenshots (smaller report folders).

Register Cucumber plugin

Register the MERV Cucumber plugin so execution events are captured:

@CucumberOptions(
  plugin = {
    "org.teche.merv.client.plugin.MervCucumberHandler"
  }
)

If you use Cucumber 7+ with JUnit Platform, configure the same plugin in your platform properties.

Bind automation (optional)

When merv.screenshot=on, bind your driver in hooks so screenshots and step context are captured:

WebDriverContext.setDriver(driver);
MervCucumberHandler.setAutomationToolObject(AutomationTool.SELENIUM, driver);

Plugin steps in tests

Use the unified reporter API (same for Cucumber, TestNG, and JUnit 5):

MervReporter.validation("Verify total", expected, actual);
MervReporter.testdata("Payload", requestJson);
MervReporter.info("Reached checkout page");

Run your suite

mvn test

Gradle:

./gradlew test

Run your Cucumber suite normally. MERV generates local report artifacts during execution.

Viewing Merv reports

After a run, reports live under {merv.report.folder} (for example ./merv-reports/). Open paths through a local web server — not via file:// in the file manager.

merv-reports/ index.html # Dashboard (all runs) 15-05-2026 14-23-41 Merv-Report/ json/merv-report.json # Suite + testcase data html/merv-report.html # Final suite report html/merv-report-live.html # Live report during run

Open with a web server

Merv-Local reports load JSON and charts with fetch. Browsers often block that on file:// URLs. Use your IDE’s static server (or any local HTTP server) so the address bar shows http://localhost:….

  1. Install the Live Server extension.
  2. Right-click merv-reports/index.html and choose Open with Live Server.
  3. Open {runFolder}/html/merv-report-live.html on the same server while tests run.

Other editors and CI

Any local static server works: npx serve merv-reports or python3 -m http.server --directory merv-reports, then open http://localhost:…/index.html.

What’s next

← Back to Documentation