Merv-Documentation

Introduction

Merv-Local turns your automated test runs into rich HTML and JSON reports on your machine — no central server required. Connect your runner (Cucumber, TestNG, JUnit 5, Playwright, …) once; open index.html to browse runs, KPIs, and consolidated testcase history.

Choose your framework

Pick Merv-Local or Merv-Server, then click your framework to open its guide.

What is Merv-Local?

Each test run writes a timestamped folder under your configured report root. Inside that folder, json/merv-report.json is the source of truth for pass/fail counts, steps, tags, and screenshots. The client also generates:

• index.html at the report root — suite grid, execution chart, consolidated views, KPIs
• html/merv-report.html — final suite report for one run
• html/merv-report-live.html — live suite view while tests are running

Configure runs with merv.properties (see below), then open the dashboard under merv.report.folder.

What’s on disk

Typical layout when merv.report.folder=./merv-reports/:

merv.properties

Merv reads merv.properties from your project root — the directory you run tests from (where pom.xml or package.json usually lives). Java runners load it at startup; Playwright resolves it from process.cwd() (or an ancestor folder).

Merv-Local properties

Set merv.local=true for on-disk HTML and JSON reports. On the Java client, omitting merv.local also selects local mode; set it explicitly so behaviour is clear.

Playwright-only (JavaScript / TypeScript)

Sample merv.properties (Merv-Local)

Minimal file for Cucumber, TestNG, JUnit 5, or Playwright with on-disk reports:

# --- Merv-Local (on-disk reports) ---
merv.local=true

# Where index.html and run folders are written
merv.report.folder=./merv-reports/

# Title on dashboard cards and suite reports
merv.regression_suite=My Regression Suite

# true if parallel threads share one suite folder
merv.execution.parallel=false

# Optional: driver screenshots (bind WebDriver/Page in hooks)
merv.screenshot=on

# Write interactive emailable-report.html when the suite finishes
merv.emailable.html=false

# Playwright / JS only — optional step category allowlist (info, hook, assertion, action)
# merv.step.allowed=info,assertion,action

# Playwright / Cucumber-js — record Chai expect/assert as ASSERTION (default on; needs chai installed)
# merv.chai=true

# Optional: sprint label in suite metadata
# merv.sprint=Sprint 12

# Optional: enable Delete on dashboard (start ReportsDeleteServer on this port)
# merv.reports.delete.port=9191

Download sample merv.properties

Place this file at the project root, wire your framework plugin or reporter, run tests, then open the dashboard (see Open the Merv dashboard).

Quick start

Every Merv-Local integration shares the same configuration file at the project root.

1. Add merv.properties

Use the sample Merv-Local file above.

2. Wire your test framework

Register the Merv plugin or reporter for your runner (Cucumber plugin, TestNG listener, JUnit extension, etc.). See the framework guides table below.

Playwright — register the reporter

In playwright.config.js or playwright.config.ts, add Merv using the merv-client/playwright-reporter subpath (not import from root merv-client in config):

import { defineConfig } from '@playwright/test';

export default defineConfig({
  reporter: [
    ['list'],
    ['merv-client/playwright-reporter', {}],
  ],
});

Details: Playwright guide — Register the reporter.

3. Run tests

# Java (Maven) — example
mvn test

# Playwright — example
npx playwright test

Open the Merv dashboard

After tests run, the Merv dashboard is index.html under your configured report root. Open it through a local web server so the browser uses http://localhost:… — not file:// from double-clicking the file in Finder or Explorer.

Report paths

Given merv.report.folder=./merv-reports/:

• merv-reports/index.html — main dashboard (suite grid, KPI charts, consolidated views, execution chart, tag search)
• merv-reports/merv-index-data.json — polled by the live dashboard while runs are in progress
• {runFolder}/html/merv-report.html — final suite report for one run (linked from each suite card)
• {runFolder}/html/merv-report-live.html — live suite view during the run (polls json/merv-report.json)
• {runFolder}/json/merv-report.json — source of truth for counts, steps, tags, and screenshots

Use a local web server

Commands to open the report

# From the project root (where merv.properties lives)
npx merv show-report

# Same command via the package binary / npm script (doctor often adds this)
npx merv-client show-report
npm run show-report

# Point at a specific report folder
npx merv show-report ./merv-reports
npx merv show-report /absolute/path/to/merv-reports

# Options
npx merv show-report --port 6174
npx merv show-report --host 127.0.0.1
npx merv show-report --host 0.0.0.0
npx merv show-report --no-open
npx merv show-report ./merv-reports --port 8080 --no-open

Java CLI (merv-client)

merv-client doctor setup
merv-client show-report
merv-client show-logs --host 0.0.0.0

Download: merv-client-download.html · JAR: /downloads/merv-client.jar

Use --host 0.0.0.0 when you need suite Share on your LAN (see Share, Download & emailable).

After the server starts, open these URLs:

• http://127.0.0.1:6174/ — dashboard (index.html)
• http://127.0.0.1:6174/merv-logs.html — Merv-Logs live console (see the Merv-Logs guide; or use the Merv-Logs link in the sidebar)
• http://127.0.0.1:6174/merv-tutor.html — Merv-Tutor step debugger (prefer npx merv-tutor open; see the Merv-Tutor guide)
• Suite cards on the dashboard link to {runFolder}/html/merv-report.html and live reports

Other editors and CI

Any static server works, for example npx serve merv-reports or python3 -m http.server --directory merv-reports, then open http://localhost:…/index.html. In CI, publish merv-reports as an artifact and serve it from your pipeline report viewer or object storage with HTTP access.

Dashboard views

On index.html you can:

• Test Suites — one card per run; links to live or final suite HTML; optional delete when the delete server is enabled
• Consolidated Report — testcase history and failure reasons across runs
• KPIs — pass/fail trends, flaky tests, duration charts (filter by tags where supported)
• Execution chart — pass/fail activity over a selected time range
• Tag search — filter suite cards and charts by Cucumber/Playwright tags

Live suite report

While a run is in progress, open {runFolder}/html/merv-report-live.html (from the dashboard Live link or your IDE browser). The page polls json/merv-report.json and refreshes steps and status without a full page reload. When the run finishes, use merv-report.html for the final suite view or return to index.html to compare runs.

Share, Download & emailable

Suite reports include Share and Download next to the suite title when you open them over HTTP (not file://). Share copies a LAN link while the report server is running. Download saves an interactive emailable-report.html and a full offline zip.

Open Share / Download guide →

Framework guides

Merv-Logs, Centralized logs & Merv-Tutor

Beyond framework reporters, MERV includes logging and teaching tools:

• Merv-Logs — MervLogger and import { console } from 'merv-client' on Java (merv-client-api) and JS/TS (merv-client). Open with npx merv show-logs. Doctor: setup-log, set console / unset console.
• Centralized logs — set merv.log.server so several projects forward into one shared Merv-Logs page (local write first, async ingest).
• Merv-Tutor — run npx merv-tutor script.js, then npx merv-tutor open for a line-by-line debugger with variables and console output (merv-tutor/latest.json + merv-tutor.html) — JavaScript / TypeScript only.

Install: Maven merv-client-api (Java logs); npm install merv-client (JS logs); add merv-tutor for the tutor CLI. Merv-Logs file sink defaults to on (merv.logger.file=true).

Merv-Server (send reports to the cloud)

If you want results in the MERV web app instead of local HTML folders, use Merv-Server: create an account, workspace, copy a Hierarchy ID, create an API key, and set merv.local=false in merv.properties. Full walkthrough: Merv-Server user guide.

Merv-Server guide →

Full Merv-Local documentation →