@ciach/playwright-private-reporter

Jenkins-first Playwright reporting utilities.

What it gives you

• A withPrivateReporter() config wrapper for Playwright projects.
• A PrivateReporter implementation that emits run.json, failures.json, and health.json.
• A generateReport CLI that creates summary.md and a themeable static summary.html suitable for Jenkins HTML Publisher.
• JSON schemas and examples for Jenkins + Playwright adoption.

Installation

Add the package to a Playwright repo:

npm install --save-dev @ciach/playwright-private-reporter @playwright/test

If your CI image does not already include browsers, install them as part of setup:

npx playwright install --with-deps

Consumer quick start

1. Wrap your Playwright config

import { defineConfig } from '@playwright/test';
import { withPrivateReporter } from '@ciach/playwright-private-reporter';

export default withPrivateReporter(
  defineConfig({
    testDir: './tests',
    use: {
      trace: 'retain-on-failure',
      screenshot: 'only-on-failure',
      video: 'retain-on-failure',
    },
  }),
  {
    projectName: 'payments-ui',
    outputDir: 'artifacts',
    summaryTheme: 'modern',
    enableHistoryDiff: true,
  },
);

See the full example in examples/playwright.config.ts.

2. Run Playwright locally

npx playwright test
npx playwright show-report

Local runs keep developer-friendly terminal/html reporters. CI adds blob + JUnit + the private reporter automatically.

3. Generate the Jenkins artifacts in CI

Run tests first:

npx playwright test

Merge sharded blob reports into HTML:

npx playwright merge-reports --reporter html ./all-blob-reports

Generate the private summary artifacts:

npx playwright-private-reporter-generate

4. Publish from Jenkins

Use the example pipeline in examples/Jenkinsfile to:

• publish JUnit XML,
• publish artifacts/internal-report/summary.html,
• publish the merged playwright-report/index.html, and
• archive traces, screenshots, videos, blob zips, and XML.

Output files

After a CI run, expect these artifacts:

• blob-report/
• playwright-report/
• artifacts/test-results/
• junit/results.xml
• artifacts/internal-report/run.json
• artifacts/internal-report/failures.json
• artifacts/internal-report/health.json
• artifacts/internal-report/summary.md
• artifacts/internal-report/summary.html

Themes and custom templates

The HTML summary renderer is presentation-only. The Playwright reporter still writes JSON first, and generateReport() turns that data into HTML later.

Built-in themes:

• classic: compact version of the original summary.
• modern: richer default with visual hierarchy, cards, collapsible failure groups, and improved artifact navigation.

Set a built-in theme in config or when calling generateReport():

withPrivateReporter(defineConfig({}), {
  projectName: 'payments-ui',
  summaryTheme: 'modern',
});

For full control, point summaryTemplatePath at a local .js, .mjs, or .cjs module that exports either default or renderSummary(context).

withPrivateReporter(defineConfig({}), {
  projectName: 'payments-ui',
  summaryTemplatePath: './reporting/summary-template.mjs',
});

The renderer receives title, theme, runSummary, failuresSummary, diff, and artifactLinks.

See examples/summary-templates.md for the full template guide and the three ready-to-copy examples. You can also import the built-ins from the package and wrap them:

import { renderModernSummaryHtml } from '@ciach/playwright-private-reporter';

If you invoke the standalone CLI directly, you can also override presentation with env vars:

PRIVATE_REPORT_SUMMARY_THEME=modern \
PRIVATE_REPORT_SUMMARY_TEMPLATE_PATH=./reporting/summary-template.mjs \
npx playwright-private-reporter-generate

How to test this package in this repo right now

From the repository root:

npm run check:schemas
npm run check:examples
npm run test:private-reporter

What those do:

• check:schemas parses the JSON schemas.
• check:examples verifies the example/docs files exist.
• test:private-reporter builds the package and runs the node-based tests for:
  • withPrivateReporter() reporter injection,
  • PrivateReporter artifact generation, and
  • generateReport history-diff summary generation.

Smoke test in a consumer repo

Once installed in an actual Playwright project:

1. add withPrivateReporter(...) to your playwright.config.ts,
2. run npx playwright test,
3. confirm junit/results.xml and artifacts/internal-report/*.json exist,
4. merge blob reports if you shard on CI, and
5. run npx playwright-private-reporter-generate to produce summary.md and summary.html.

Publishing

From the repository root:

npm --workspace @ciach/playwright-private-reporter test
npm publish --workspace @ciach/playwright-private-reporter --access public

prepack runs the full test suite before npm creates the publish tarball, so npm publish ships freshly built artifacts.

Example files

• Playwright config example: examples/playwright.config.ts
• Jenkins pipeline example: examples/Jenkinsfile
• Template guide: examples/summary-templates.md
• Template example: examples/summary-template.cjs
• Template example: examples/summary-template-minimal.cjs
• Template example: examples/summary-template-ops.cjs
• Architecture/build spec: ../../docs/playwright-private-reporter-build-spec.md