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

merv.properties

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

Merv-Local (on-disk HTML)

merv.local=true
merv.report.folder=./merv-reports/
merv.regression_suite=Custom Report Suite
merv.execution.parallel=false

Merv-Server (cloud)

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

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

<dependency>
  <groupId>io.github.techelliptica</groupId>
  <artifactId>merv-client-api</artifactId>
  <version>4.0.0</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

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' })
);

// Attach a file as test data (read from disk)
await report.testdata(
  'Payload file',
  new MervReportFile('./fixtures/checkout-payload.json')
);

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

// Optional: capture screenshot when a Playwright page is bound
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

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' }),
  );

  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.setPage(page), validation(step, expected, actual, true) captures a viewport PNG into the run folder (local) or uploads it (server).

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 — open {merv.report.folder}/index.html via a local web server (see open dashboard)
• Merv-Server — browse suites at merv.online/app

Troubleshooting

← Back to documentation