Documentation

This page focuses on Merv-Local: how report folders, merv-report.json, suite HTML, and the index.html dashboard fit together — including every consolidated view and KPI area. Implementation contracts for contributors live in merv-client/LOCAL_REPORTS_CONTEXT.md in the repo.

What Merv-Local is

Merv-Local writes execution results under a configurable report root on your machine. Each run gets its own timestamped folder. There is no requirement to run the MERV API or UI for these reports to work: the local dashboard (index.html), suite HTML, and Chart.js KPIs all read the same merv-report.json snapshots your test runner (Cucumber, TestNG, JUnit 5, Playwright via merv-client, etc.) produces when integrated with merv-client.

After each meaningful write (or when a run finishes), the client calls MervReportsIndexHtmlWriter.write(reportRoot) so index.html stays in sync with folders on disk. That is how new runs appear in the suite grid and how consolidated and KPI views pick up new data.

Folder layout on disk

Let reportRoot be the directory from MervConfig.getReportFolder() (usually set via merv.report.folder in merv.properties). Typical layout:

Run folder names are commonly like dd-MM-yyyy HH-mm-ss Merv-Report (Cucumber); other integrations should still use the same single segment folder name and the same html/, json/, and optional screenshots/ layout so the dashboard can find them.

JSON as source of truth

Every consumer — suite HTML, live HTML, index.html cards, consolidated views, and KPI scripts — ultimately depends on fields inside each run’s merv-report.json. At a high level the document includes:

• Run metadata — e.g. running (boolean) for in-flight vs completed, optional lastActivityMillis for stale/aborted-style detection, optional exportDate for display in live UI.
• testSuite — title plus a testCases array.
• Each test case — at minimum testcaseName and status (PASSED, FAILED, SKIPPED, IN_PROGRESS, etc.), and ideally failureReason, tags, startTime / endTime, executionMachine, and a testSteps array (step names, statuses, expected/actual, screenshots, timing).

If a framework omits optional fields, keep names and statuses accurate so pass/fail/skip counts, KPIs, and navigation still behave. Exact field parity with Cucumber is defined alongside MervCucumberHandler.generateJsonReport in the client source; align new runners with LOCAL_REPORTS_CONTEXT.md.

Per-run suite reports (merv-report-live.html / merv-report.html)

These pages are the drill-down for a single execution folder. They are generated from the same branding and escaping helpers as the rest of Merv-Local HTML (org.teche.merv.client.report.html). Typical behaviour:

• Sidebar — scenarios with pass / fail / skip / in-progress chips; search and filters.
• Summary — counts, pie chart, collapsible summary block.
• Failure reasons — grouped messages with links into related cases and screenshot thumbnails where available.
• Run timing — suite start, end, and duration.
• Case detail — status, duration, machine, tags, error text, test steps with status pills, step-level duration (gap from previous step end), screenshots, optional log excerpts.
• Step semantics — steps after a hard failure are shown as SKIP; genuinely in-flight steps use IN PROGRESS styling.
• Screenshot strip — optional “movie” of step images in order.
• Live trend — in the live HTML view, a throughput chart can show pass/fail activity in time buckets while the suite runs.

From index.html, each suite card links to merv-report.html when the run has finished, or merv-report-live.html while it is still in progress.

index.html local dashboard

Open {reportRoot}/index.html in a browser (file URL or a static file server). The page is a single-page layout with a left sidebar (branding, Merv-Local label, navigation) and a main area that switches between three primary views:

1. Test Suites — default; lists runs and the live execution chart.
2. Consolidated Report — three internal subtabs (below).
3. KPIs — Chart.js analytics driven by the same JSON snapshots, with a configurable build scope.

The top bar includes a search field that filters suite cards by folder name, suite title, and visible tags.

Test Suites view (how it works)

When at least one run folder exists, this view shows two stacked regions:

Live execution chart

A Chart.js time-series chart titled by the selected time window (defaults to the last hour). Preset ranges include 1 hour, 6 hours, 1 day, 1 week, 2 weeks, 1 month, plus Custom (datetime from / to with Apply). The chart aggregates all runs currently listed on the page: green area = test cases completed (pass outcomes) per minute, red line = fail completions per minute. The UI notes that it reflects cases finished per minute, not starts. While you develop, the chart can poll periodically (about every five seconds) so in-progress runs contribute new points without reloading the whole page.

Suite cards grid

Each card corresponds to one run folder. The writer reads that folder’s JSON (and presence of final HTML) to fill:

• Title and folder path — suite title from JSON and the on-disk folder name.
• Status badge — Completed when merv-report.html exists, otherwise In progress (live report path).
• Counts — total, pass, fail, and skip (skip segment hidden when count is zero).
• Meta strip — environment, release, sprint when present in JSON.
• Donut — quick pass/fail/skip proportion for that run.
• Tag pills — aggregated tags from cases in that run (used for search and for KPI tag filtering).
• Timestamp — last modified time and a human-readable “relative” ago string.
• Actions — View Cases (and open in new tab), plus Delete when the optional local delete integration is available.

The first card is marked as the latest run for quick visual emphasis. Cards expose a data-json path so browser scripts can fetch JSON when building consolidated and KPI datasets.

Consolidated Report (all subtabs)

The consolidated view merges every merv-report.json under reportRoot (subject to the same discovery rules as the index writer). It answers “how is this testcase or tag behaving across runs?” without opening each folder. There is a search control for filtering consolidated rows. Three subtabs:

1 — TestCase Summary (TestCase View)

One logical row per test case name aggregated across runs:

• Current status — outcome of the newest execution that included that name.
• Last five runs — compact status history chips.
• Last passed / last failed — timestamps for triage.
• Total pass / total fail — cumulative counts over discovered history.

Rows can expand to show per-run or per-suite breakdowns and links where the HTML supports deep navigation.

2 — Tag / Group Based Summary

Groups cases by tags (for Cucumber-driven JSON, these are scenario tags). A scenario with multiple tags appears under each relevant tag section. Clicking a tag can drive filtering in the consolidated search so you can focus a slice such as @smoke or @regression.

3 — Failure Summary

Lists failure reasons from the latest execution per testcase. When a test starts passing again, it drops out of this summary automatically, so the tab acts as a “current failures only” triage board. Rows may expand for detail depending on stored failure text in JSON.

KPIs (all sections and how they work)

The KPI view is entirely client-side: embedded JavaScript reads the same JSON files, applies your scope, then updates DOM counters and Chart.js canvases.

Build scope and tag filter

• Builds in KPI charts — dropdown: last 20, 30, 50, all builds, or Custom… with a numeric “last N builds” and Apply. Runs are ordered by recency; “build” here means one run folder snapshot.
• Tag filter — optional Tag select under “Custom Setting” limits KPI inputs to cases that carry that tag. The chosen tag is persisted in localStorage as merv.kpi.tag so refreshes keep your filter.
• Status line — a small status area can reflect how many snapshots were loaded after scope changes.

Test execution summary

Aggregates over the scoped runs:

• Cards — total test cases, passed, failed, skipped, and overall pass %.
• Doughnut chart — outcome mix for the scoped set.
• Stacked bar chart — pass vs fail (and skip semantics per implementation) per execution so you can compare recent runs side by side.

Execution Time & Performance

Uses start/end times on test cases inside each JSON file, plus one duration per run folder for suite-level stats:

• Total suite execution time — summed or rolled up across scoped runs per implementation logic in the dashboard script.
• Average test case execution time — mean duration per case over the data in scope.
• Suite duration P95 / P99 — percentile bands across run-level durations to highlight noisy pipeline timing.
• Charts — suite duration by run; chart of slowest cases by max duration observed per testcase name.
• Slow test cases list — ordered list of heaviest scenarios (collapsible section in the UI) for optimisation backlogs.

Flaky Test Detection

Surfaces tests that have both passed and failed at least once within the current KPI scope. The table includes failed-run counts, passed-run counts, a stability ratio (passes ÷ (passes + fails)), and pass/fail flips. Copy explains that retries are not stored in JSON; failed runs act as a proxy so stability is an approximation from stored outcomes only.

Trend Analysis (build-wise)

Three aligned time-series charts (oldest run on the left, newest on the right):

• Pass % over time — per-build pass rate.
• Failures per build — failure counts per run.
• Execution time trend — duration trend across runs.

The sidebar duplicates quick links to scroll directly to Pass % over time, Failures per build, and Execution time trend anchors inside the KPI panel for long pages.

Refreshing the index and deleting runs

Whenever run folders are added, finished, or removed, the on-disk index.html should be regenerated by calling MervReportsIndexHtmlWriter.write(reportRoot) from the runner (Cucumber hook, TestNG listener, etc.). If you delete folders manually, rerun that writer or trigger the same path your integration uses; otherwise cards and KPIs may reference missing JSON.

Optional ReportsDeleteServer (see merv-client sources) integrates with the dashboard so the Delete action on a card can remove a run folder and refresh the index safely.

Framework setup guides (Merv-Local)

Step-by-step integration pages on this site:

Other in-repo documentation

Reference material elsewhere in the MERV monorepo (not limited to local HTML):

API documentation and forum

For the central MERV REST API (users, suites, cases, steps, hierarchy, API keys, files), see API Documentation. Interactive docs: http://<api-host>:7777/swagger-ui.html when the API is running. Postman collections live under postman/.

To report defects or ask questions, use the Forum / Defects page. Forum database fields are described in merv-website/DATABASE_FIELDS.md.

Merv documentation → Cucumber + Local → API Documentation → Forum / Raise a defect →