Merv-Local + Playwright guide

Introduction

Playwright Test is an end-to-end framework for modern web apps. Merv-Local adds rich HTML/JSON reports, a run dashboard, and Java-style plugin steps on top of your existing Playwright project via the merv-client npm package.

Installing merv-client

Inside your Playwright project root (where package.json and playwright.config live):

npm install -D merv-client merv-client-playwright @playwright/test

Automated setup (doctor)

After install, run the Playwright doctor. It creates or heals MERV wiring (merv.properties, reporter entry, bridge/jsconfig) without wiping unrelated project settings.

# Install first (required on every machine)
npm install -D merv-client-playwright

# Then run doctor
npx merv-client-playwright doctor setup
npx merv-client-playwright doctor setup --typescript

# Windows alternatives if npx bin is not found
npm exec -- merv-client-playwright doctor setup
node node_modules/merv-client-playwright/dist/cli.js doctor setup

• Fills missing merv.* keys only (keeps your other properties)
• Adds merv-client-playwright/reporter to playwright.config without replacing other options
• Creates / corrects the test bridge and safe jsconfig/tsconfig merges when needed

Then run tests and open the dashboard with npx merv show-report. Prefer manual setup below if you want every file edited by hand.

Manual setup

Skip doctor and configure MERV yourself: create merv.properties, register the reporter, then optionally Option A / plugin steps.

package.json — align Playwright versions (important)

as merv-client using the same version of Playwright as your project, you need to align the versions in your package.json in order to avoid conflicts. You can do this by pinning @playwright/test at the project root and add npm overrides so nested merv-client dependencies resolve the same packages.

{
  "devDependencies": {
    "@playwright/test": "1.59.1",
    "merv-client": "^4.0.22"
  },
  "overrides": {
    "merv-client": {
      "@playwright/test": "$@playwright/test",
      "playwright": "$playwright",
      "playwright-core": "$playwright-core"
    }
  }
}

After editing, run npm install and confirm with npm ls @playwright/test playwright-core — all entries should show one version. Restart the TypeScript server in your IDE. This will ensure that merv-client uses the same version of Playwright as your project.

What’s installed

Merv does not replace Playwright. After you configure the reporter and run tests, each execution creates a timestamped folder under user defined folder for merv.report.folder key in merv.properties file:

playwright.config stays your central Playwright configuration (browsers, timeouts, projects). Add one reporter entry for Merv alongside list or the built-in HTML reporter — use ['merv-client/playwright-reporter', {}] (see Register the reporter).

Testcase tags are filled automatically: any @word in the test title becomes a tag (e.g. Verify Login @login with @abc → @login, @abc). When the title or Playwright project name contains chromium, the browser tag chrome is added for consolidated and KPI filters.

Configure merv.properties

Create merv.properties next to package.json. The reporter and test wrapper read it from the project root (or an ancestor directory).

Sample Configuration

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

Download sample merv.properties

Common properties

Register the reporter

In playwright.config.js or playwright.config.ts, register Merv in the reporter array using the dedicated subpath merv-client/playwright-reporter — not the root merv-client package. Playwright loads config before your tests run; the subpath loads only the reporter entry point and avoids pulling in the wrapped test shim (which can trigger “Requiring @playwright/test second time” warnings).

Reporter entry (required)

reporter: [
  ['list'],
  ['merv-client/playwright-reporter', {}],
],

Full playwright.config example

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

export default defineConfig({
  testDir: './tests',
  reporter: [
    ['list'],
    ['merv-client/playwright-reporter', {}],
  ],
  use: {
    // baseURL, trace, screenshot, …
  },
});

Running your tests

Run from the directory that contains merv.properties. By default Playwright runs headless; Merv writes JSON and refreshes reports as tests complete.

npx playwright test

With only the reporter registered, you can keep import { test, expect } from '@playwright/test' — the report shows Playwright API and expect steps. For plugin steps and screenshots, use the wrapped test (see below).

Viewing Merv reports

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

• index.html — dashboard: suite grid, KPI charts, consolidated views
• {runFolder}/html/merv-report.html — final suite report for one run
• {runFolder}/html/merv-report-live.html — live suite view while tests run (polls json/merv-report.json)

Open with a web server

npx merv show-report
npx merv-client show-report
npm run show-report

# Explicit folder / options
npx merv show-report ./merv-reports
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

Opens http://127.0.0.1:6174/ (dashboard). Also available: http://127.0.0.1:6174/merv-logs.html (Merv-Logs). Stop with Ctrl+C.

Other editors and CI

Any local 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 the merv-reports folder as an artifact and serve it from your pipeline’s report viewer or object storage with HTTP access.

Add Custom Step and Screenshot Types

To add Custom Steps and many other merv feature to make your tests more readable and maintainable. Recommended for large suites: keep Playwright-style imports, but resolve them to Merv’s wrapped test via a one-time bridge, Pick your project language below.

my-project/
├── tsconfig.json                 ← no @playwright/test alias
├── playwright.config.ts
├── pages/
├── tests/
│   ├── tsconfig.json             ← bridge alias + extends root
│   ├── support/playwright-test-bridge.ts
│   └── *.spec.ts
└── merv.properties

playwright.config still registers merv-client/playwright-reporter in reporter: [] — do not import the reporter from root merv-client in config. For TypeScript, set tsconfig: './tests/tsconfig.json' in config and keep the @playwright/test bridge alias in tests/tsconfig.json only (see TypeScript tab above).

Adding Custom Steps in Reports

Use MervPlaywrightHandler with Playwright’s testInfo to add explicit rows merged into the same testcase as Playwright steps.

import { expect, test, MervPlaywrightHandler } from '@playwright/test';

test('checkout', async ({ page }, testInfo) => {
  const merv = new MervPlaywrightHandler(testInfo);

  await merv.data('Request', JSON.stringify({ sku: 'SKU-1' }));
  await merv.validation('Cart total', '$42.00', '$42.00', true);
  await merv.info('Environment: staging');

  await page.goto('/cart');
  await expect(page.getByRole('heading')).toBeVisible();
});

More Configuration

In order to implement these configurations, we need to implement bridge setup properly as mentioned in the previous section

Debug mode

By default each testcase shows Playwright API actions and expect steps. To include hooks, fixtures, and every test.step category:

merv.debug=true

Screenshots

for custom steps — pass true as the last argument:

await merv.data('Order Id', '12349893', true);
await merv.validation('Status', '200', '200', true);

In plaugin manner, in merv.properties, it will add screenshot automatically after each locator/page action and after each expect matcher :

merv.screenshot=true

Captures a viewport PNG after each locator/page action and after each expect matcher (pass or fail). Requires wrapped test and expect from merv-client/playwright-test.

Soft plugin failure

Record a failed validation in the report without failing the Playwright test:

merv.plugin_assertion_soft=true

Chai assertions

If your suite uses Chai (expect / assert) as well as Playwright’s built-in expect, MERV reports both:

Install Chai in the project (npm i -D chai). With MERV’s wrapped test, leave merv.chai=true (default) so Chai is hooked automatically. Or install manually:

import chai from 'chai';
import { installMervChai } from 'merv-client/chai';

installMervChai(chai);
export const { expect, assert } = chai;

Both step types sit under the assertion category in merv.step.allowed. Do not wrap the same check in both libraries — you would get two rows for one logical assertion. Set merv.chai=false to turn Chai reporting off.

MervReport (explicit)

For a full custom-report guide (no Playwright reporter) with Java, JavaScript, and TypeScript tabs, see Custom report guide.

Use MervReport when you want the same folder layout and JSON contract without registering the Playwright reporter — for scripts or hand-built testcase rows.

Setup

1. Keep merv.properties at the project root.
2. import { MervReport } from 'merv-client';
3. const report = MervReport.open(); — creates a new run folder.

Report object

const report = await MervReport.open();
await report.createTest('Login API', 'POST /auth with valid user');
await report.testdata('Request body', JSON.stringify({ user: 'a@b.com' }));
await report.validation('Status code', '200', '200');
await report.validation('Title', 'Home', 'Home', true); // optional screenshot
await report.info('Using staging tenant');
await report.finalize();

Custom steps on MervReport: info, testdata (string or new MervReportFile(path)), and validation (with optional screenshot flag).

Step object

Each step row in JSON includes teststepName, stepType, status, optional expected / actual, testdata, screenshots, and errorMessage when applicable.

Troubleshooting

← Back to Documentation