Custom report — hand-built suites, tests & steps

Introduction

Use a custom report when your automation is not wired through Cucumber, Cucumber-js, TestNG, JUnit, or the Playwright reporter — but you still want MERV suites, testcases, plugin-style steps, validation rows, test data, info lines, and screenshots in the same HTML dashboard or Merv App.

When to use a custom report

• Standalone scripts, CLI tools, or batch jobs that run checks outside a test framework
• Prototypes and spikes before adopting a full Cucumber / Playwright integration
• Hybrid pipelines that already have pass/fail logic but need MERV HTML or cloud storage
• Microservice or API checks where you control suite/test/step structure in code

Automated setup (doctor)

For JavaScript / TypeScript projects, install core and run the core doctor. It creates or fills missing merv.* keys and a sample custom-report script without wiping unrelated settings.

npm install merv-client
npx merv-client doctor setup
npx merv-client doctor setup --typescript

Then run the generated script (or your own) and open the dashboard with npx merv show-report. Prefer manual setup below for full control.

Manual setup

Skip doctor and configure by hand: add merv.properties, then follow the language examples (Java / JS / TS) to call MervReport.open() (or Java MervClient) yourself.

merv.properties

Place merv.properties at the project root (directory you run from).

Sample Configuration (Merv-Local)

merv.local=true
merv.report.folder=./merv-reports/
merv.regression_suite=Custom Report Suite
merv.emailable.html=false

Download sample merv.properties

Common properties

Sample Configuration (Merv-Server)

merv.local=false
merv.server=https://merv.online/api/v1
merv.api_key=merv_your_api_key
merv.parent_hierarchy=your-hierarchy-uuid
merv.regression_suite=Custom Report Suite

Server setup: Merv-Server user guide. MervReport (npm) reads the same file for local or server mode.

API overview

Examples by language

After the JS client split, custom reports use only merv-client (core). You do not install merv-client-playwright or merv-client-cucumber for this path. Those packages are for Playwright Test and Cucumber-js adapters.

Each tab shows a full custom-report flow: open suite → create test → add steps → finalize.

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

import org.teche.merv.client.MervClient;
import org.teche.merv.client.dto.*;
import org.teche.merv.client.exception.MervClientException;
import org.teche.merv.client.utils.MervSuiteBootstrap;
import org.teche.merv.client.utils.TestCaseBuilder;
import org.teche.merv.client.utils.TestStepBuilder;

import java.io.File;
import java.util.Properties;
import java.util.UUID;

public class CustomMervReport {
  public static void main(String[] args) throws Exception {
    try (MervClient client = MervClient.fromConfig()) {
      Properties props = new Properties();
      props.load(new java.io.FileInputStream("merv.properties"));

      UUID suiteId = MervSuiteBootstrap.resolveSuiteId(
          client, props, "Custom Report Suite");

      TestCaseResponse testCase = client.createTestCase(
          TestCaseBuilder.create()
              .testcaseName("Checkout API")
              .description("POST /checkout with valid cart")
              .testSuiteId(suiteId)
              .status(TestCaseStatus.INPROGRESS)
              .build());

      UUID caseId = testCase.getId();

      // Info / prerequisite step
      client.createTestStep(TestStepBuilder.create()
          .testcaseId(caseId)
          .teststepName("Environment")
          .stepType("information")
          .prereq("Using staging tenant STG-42")
          .status("PASSED")
          .build());

      // Test data step
      TestStepResponse dataStep = client.createTestStep(
          TestStepBuilder.create()
              .testcaseId(caseId)
              .teststepName("Request body")
              .stepType("testdata")
              .testdata("{\"cartId\":\"cart-991\",\"currency\":\"USD\"}")
              .status("PASSED")
              .build());

      // Validation step
      TestStepResponse validationStep = client.createTestStep(
          TestStepBuilder.create()
              .testcaseId(caseId)
              .teststepName("HTTP status")
              .stepType("assertion")
              .expected("200")
              .actual("200")
              .status("PASSED")
              .build());

      // Screenshot attachment on a step
      client.uploadFile(validationStep.getId(),
          new File("screenshots/checkout-response.png"),
          "Checkout response UI");

      client.updateTestCaseStatus(caseId, TestCaseStatus.PASSED);
    }
  }
}

npm install merv-client
# Optional automated setup:
npx merv-client doctor setup

import { MervReport, MervReportFile } from 'merv-client';

const report = await MervReport.open();

await report.createTest(
  'Checkout API',
  'POST /checkout with valid cart'
);

await report.info('Using staging tenant STG-42');

await report.testdata(
  'Request body',
  JSON.stringify({ cartId: 'cart-991', currency: 'USD' })
);

// Optional: attach a file as test data (create fixtures/checkout-payload.json first)
await report.testdata(
  'Payload file',
  new MervReportFile('./fixtures/checkout-payload.json')
);

await report.validation('HTTP status', '200', '200');

// Optional: viewport PNG when a Playwright page is bound (see Screenshots)
await report.validation('Page title', 'Checkout', 'Checkout', true);

await report.finalize();

console.log('Report written under merv.report.folder');

npm install merv-client
npm install -D typescript tsx @types/node
# Optional automated setup:
npx merv-client doctor setup --typescript

import { MervReport, MervReportFile } from 'merv-client';

async function runCustomReport(): Promise<void> {
  const report = await MervReport.open();

  await report.createTest(
    'Checkout API',
    'POST /checkout with valid cart',
  );

  await report.info('Using staging tenant STG-42');

  await report.testdata(
    'Request body',
    JSON.stringify({ cartId: 'cart-991', currency: 'USD' }),
  );

  // Optional: create fixtures/checkout-payload.json first, or omit this call
  await report.testdata(
    'Payload file',
    new MervReportFile('./fixtures/checkout-payload.json'),
  );

  await report.validation('HTTP status', '200', '200');
  await report.validation('Page title', 'Checkout', 'Checkout', true);

  await report.finalize();
}

runCustomReport().catch((err: unknown) => {
  console.error(err);
  process.exit(1);
});

Step types

Call createTest once per logical testcase. Add as many steps as you need before starting the next test or calling finalize().

Screenshots & file attachments

JavaScript / TypeScript — Playwright page bound

When a Playwright page is bound via MervPlaywright.setAutomationToolObject(AutomationTool.PLAYWRIGHT, page) (from merv-client), validation(step, expected, actual, true) captures a viewport PNG into the run folder (local) or uploads it (server). You may use the playwright package for the browser without installing merv-client-playwright.

import { chromium } from 'playwright';
import { AutomationTool, MervPlaywright, MervReport } from 'merv-client';

const browser = await chromium.launch();
const page = await browser.newPage();
MervPlaywright.setAutomationToolObject(AutomationTool.PLAYWRIGHT, page);

const report = await MervReport.open();
await report.createTest('UI check', 'Home');
await page.goto('https://example.com');
await report.validation('Title', 'Example Domain', await page.title(), true);
await report.finalize();

MervPlaywright.clear();
await browser.close();

JavaScript / TypeScript — copy PNG from disk (local)

For scripts without Playwright, use the lower-level MervExplicitLocalReport API:

import { MervExplicitLocalReport } from 'merv-client';

const run = MervExplicitLocalReport.open();
const shot = run.copyScreenshotFromFile('/tmp/checkout.png', 'checkout-step');

run.addTestCase({
  testcaseName: 'Checkout flow',
  status: 'PASSED',
  startTime: new Date().toISOString(),
  endTime: new Date().toISOString(),
  executionMachine: 'ci-runner-01',
  testSteps: [{
    teststepName: 'Confirm order',
    stepType: 'ASSERTION',
    status: 'PASSED',
    expected: 'Order confirmed',
    actual: 'Order confirmed',
    screenshots: shot ? [shot] : [],
  }],
});
run.finalize();

Java — server upload

After createTestStep, call client.uploadFile(stepId, file, description) to attach PNG or other files to that step in the Merv App.

View reports

• Merv-Local — run merv show-report (opens http://127.0.0.1:6174/) or serve {merv.report.folder}/index.html (see open dashboard)
• Merv-Server — browse suites at merv.online/app

Troubleshooting

← Back to documentation