merv-client

MERV (Metrics Engine for Reports & Visualization) — JavaScript/TypeScript client for Playwright: rich Merv-Local HTML/JSON reports compatible with the MERV ecosystem (same contract as the Java merv-client), optional action screenshots, and plugin-style validation/data steps aligned with MervPlaywrightHandler on the JVM.

Why this package?

| Capability | Description | |------------|-------------| | Playwright reporter | Writes json/merv-report.json, live suite HTML, and refreshes the report dashboard under merv.report.folder. | | Java-parity steps | MervPlaywrightHandler + attach pipeline merge custom rows with Playwright’s own steps per testcase. | | Standalone reporting | MervReport.open() emits the same folder layout without registering the reporter (no TestInfo.attach pipeline). | | merv.properties | Same configuration style as the Java client (report path, suite title, screenshots, debug noise, extra step types). |

Installation

npm install -D merv-client

Peer dependency: @playwright/test ≥ 1.40.0

Runtime: Node.js ≥ 18

Quick start (Playwright reporter)

1. Add merv.properties next to package.json:

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

2. Register the reporter using the /playwright-reporter subpath (avoids double-loading @playwright/test when Playwright parses playwright.config):

// playwright.config.ts
import { defineConfig } from '@playwright/test';

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

3. Run tests and open merv-reports/index.html (and the latest run folder under it).

Keep import from '@playwright/test' (Option A)

Use MERV’s wrapped test, MervPlaywrightHandler, and plugin-step screenshots while specs still say @playwright/test. Full step-by-step instructions (JavaScript and TypeScript) are in FRAMEWORK_INTEGRATION.md §4a.

Checklist (JavaScript .spec.js):

| Step | File | Action | |------|------|--------| | 1 | tests/support/playwright-test-bridge.js | export * from 'merv-client/playwright-test'; | | 2 | playwright.config.js | reporter: [['merv-client/playwright-reporter', {}]] | | 3 | jsconfig.json | paths: @playwright/test → bridge (valid JSON, no comments) | | 4 | package.json | "imports": { "@playwright/test": "./tests/support/playwright-test-bridge.js" } | | 5 | tests/*.spec.js | import { test, expect, MervPlaywrightHandler } from '@playwright/test'; | | 6 | Verify | npx playwright test --list then npm test |

// tests/example.spec.js
import { expect, test, MervPlaywrightHandler } from '@playwright/test';

test('demo', async ({ page }, testInfo) => {
  const merv = new MervPlaywrightHandler(testInfo);
  await merv.data('Order Id', '12349893', true);
  await page.goto('/');
});

Do not import MervPlaywrightHandler from merv-client while test comes from stock @playwright/test — plugin steps and screenshots will not work.

Other wiring (direct merv-client import, extendTestWithMervScreenshots) is in FRAMEWORK_INTEGRATION.md §4.

Choosing how you record tests

| Approach | When to use | |----------|-------------| | Reporter only | Playwright-native steps in MERV JSON/HTML; no action screenshots. Import test from @playwright/test. | | Reporter + screenshots (Option A) | Same imports (@playwright/test) via path alias + bridge; see Screenshots with Option A. | | MervPlaywrightHandler | You want full testcase rows including Java-style addValidationStep / addDataStep / info merged into the same testcase as Playwright steps. Requires the MERV reporter and the usual worker attach wiring (see integration guide). | | MervReport | You want to write MERV output explicitly (scripts, or Playwright without the reporter). No plugin attach process — calls createTest, steps, then finalize(). |

Package entry points

| Import path | Purpose | |-------------|---------| | merv-client | Main API: reporter export, MervReport, MervPlaywrightHandler, extendTestWithMervScreenshots, helpers (formatMervStepTitle, …). | | merv-client/playwright-reporter | Only for playwright.config reporter: [...] — prefer this over importing the default reporter from the root in config. (merv-client/reporter is a deprecated alias.) | | merv-client/playwright-test | Wrapped test / expect (same surface as Playwright) for screenshot + plugin integration. |

Configuration reference (short)

See FRAMEWORK_INTEGRATION.md for the full table and examples.

| Property | Role | |----------|------| | merv.report.folder | Root for timestamped run folders (default ./merv-reports/). | | merv.regression_suite | Suite title in JSON/HTML. | | merv.screenshot=true | Enables wrapped page fixture for viewport screenshots after common actions (when using the wrapped test). | | merv.debug=true or debug=true | Include hooks, fixtures, and all step categories in the report. | | merv.report.extra_step_types | Allow tagged test.step types when debug is off (e.g. VALIDATION_STEP). | | merv.plugin_assertion_soft=true | Record failed validation steps without failing the Playwright test (optional). |

Documentation index

| Document | Contents | |----------|----------| | FRAMEWORK_INTEGRATION.md | Full setup: properties, reporter, MervReport, path-alias shim, screenshots, MervPlaywright, checklist. | | CHANGELOG.md | Version history. | | CONTRIBUTING.md | Building from source and PR expectations. | | docs/PUBLISHING.md | npm publish steps for maintainers. |

Related (Java / repo root): merv-client/LOCAL_REPORTS_CONTEXT.md — JSON contract for local dashboards.

Migrating from @techelliptica/merv-client-js

If you previously depended on the scoped name only in docs or local file: links, switch to the published package:

npm uninstall @techelliptica/merv-client-js  # if present
npm install -D merv-client

Replace every import and reporter path:

• @techelliptica/merv-client-js → merv-client
• @techelliptica/merv-client-js/reporter → merv-client/playwright-reporter
• @techelliptica/merv-client-js/playwright-test → merv-client/playwright-test

The Git repository folder remains merv-client-js/ inside the MERV monorepo; only the npm package name is merv-client.

Building from source

git clone https://github.com/techelliiptica/merv.git
cd merv/merv-client-js
npm install
npm run build
npm run typecheck

License

Apache License 2.0 — see LICENSE.

Copyright contributors and TechElliptica as described in the MERV repository.