@reportforge/playwright-pdf 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,272 @@
+import { Reporter, FullConfig, Suite, TestCase, TestResult, FullResult } from '@playwright/test/reporter';
+
+type TemplateId = 'minimal' | 'detailed' | 'executive';
+/**
+ * License plan. Subscription is the only product — every active license is the
+ * same plan. The "no license" case is represented by the absence of a
+ * LicenseInfo (LicenseClient.resolve() returns null), not by a sentinel plan.
+ */
+type LicensePlan = 'subscription';
+interface ReporterOptions {
+    /**
+     * Output file path. Supports tokens: {date}, {branch}, {status}.
+     * @default 'playwright-report/{date}-report.pdf'
+     */
+    outputFile?: string;
+    /**
+     * PDF report template(s) to use. Pass a single string or an array to
+     * generate multiple PDFs in one run. When an array is given, the template
+     * name is appended to each output filename automatically:
+     *   outputFile: 'reports/{date}-report.pdf'
+     *   template: ['detailed', 'executive']
+     * →  reports/2026-04-28-report-detailed.pdf
+     *    reports/2026-04-28-report-executive.pdf
+     *
+     * - minimal:   clean white layout, developer-focused, fast
+     * - detailed:  full QA report with defect log and requirements traceability
+     * - executive: cover page, KPI dashboard, charts for stakeholders
+     * @default 'minimal'
+     */
+    template?: TemplateId | TemplateId[];
+    /**
+     * ReportForge license key. Falls back to RF_LICENSE_KEY environment variable.
+     * If omitted (or invalid / inactive), the reporter logs a warning and skips
+     * PDF generation — your Playwright tests still run normally.
+     */
+    licenseKey?: string;
+    /**
+     * Path to a logo image (PNG, JPG, or SVG) to embed in the report header.
+     * Supports both absolute and relative paths.
+     */
+    logo?: string;
+    /**
+     * Primary brand colour (hex). Used for headers and accent bars.
+     * @default '#CC785C'
+     */
+    primaryColor?: string;
+    /**
+     * Accent brand colour (hex). Used for highlights and badges.
+     * @default '#3F7D58'
+     */
+    accentColor?: string;
+    /**
+     * Text to render as a diagonal watermark overlay on every page.
+     * Example: 'CONFIDENTIAL', 'DRAFT'
+     */
+    watermark?: string;
+    /**
+     * Password to protect the generated PDF (Enterprise tier).
+     * Requires qpdf to be installed on the system.
+     */
+    pdfPassword?: string;
+    /**
+     * Custom title for the report cover and header.
+     * @default 'Playwright Test Report'
+     */
+    reportTitle?: string;
+    /**
+     * Project or application name. Inferred from package.json if absent.
+     */
+    projectName?: string;
+    /**
+     * Open the generated PDF automatically after generation (local use only).
+     * @default false
+     */
+    open?: boolean;
+    /**
+     * Full path to a Chrome/Chromium executable.
+     * Falls back to PUPPETEER_EXECUTABLE_PATH env, then system Chrome discovery.
+     */
+    puppeteerExecutablePath?: string;
+    /**
+     * Base URL for the ReportForge licensing server. Overrides the default
+     * (https://reportforge.org) during local development and tests.
+     * Also configurable via REPORTFORGE_SERVER_URL env var.
+     */
+    serverUrl?: string;
+    /**
+     * Compression preset for screenshots embedded into the PDF.
+     *   - 'auto'     — picks based on test / failure volume (default)
+     *   - 'none'     — pass-through (original PNG, largest)
+     *   - 'balanced' — JPEG q85, max 1400px wide
+     *   - 'max'      — JPEG q70, max 1000px wide (smallest)
+     * @default 'auto'
+     */
+    compressionLevel?: 'auto' | 'none' | 'balanced' | 'max';
+    /**
+     * Whether to embed Playwright screenshots into the PDF.
+     * When false, failure entries still appear (title, error, stack trace)
+     * but without screenshot images — useful for exec-audience reports or
+     * reducing file size when visual evidence is not needed.
+     * Applies to all three templates.
+     * @default true
+     */
+    includeScreenshots?: boolean;
+    /**
+     * Maximum number of failure entries rendered inline in the PDF.
+     * Overflow is written to a sibling `{basename}-failures.json` sidecar file
+     * and a banner is shown above the failures section. If omitted, the cap
+     * is derived from `compressionLevel`.
+     */
+    maxInlineFailures?: number;
+    /**
+     * Soft cap on final PDF size in megabytes. If the generated PDF exceeds
+     * this, the report is re-rendered once with the 'max' compression preset.
+     * Set to 0 to disable the cap. Defaults to 8 MB (email-friendly).
+     * @default 8
+     */
+    maxFileSizeMb?: number;
+    /**
+     * Merge N Playwright JSON shard report files into a single PDF.
+     * Accepts a path/glob string or an array of paths/globs.
+     *
+     * Workflow:
+     * 1. Run each shard with `--reporter=json` to produce JSON output files.
+     * 2. After all shards finish, run a Playwright invocation with this reporter
+     *    configured and `shardResults` pointing at the JSON files — the live run
+     *    may have zero tests.
+     *
+     * Known limitation: timed-out tests are counted as failures in shard mode
+     * (Playwright JSON stats do not distinguish timedOut from failed).
+     *
+     * @example
+     * shardResults: 'results/shard-*.json'
+     * @example
+     * shardResults: ['results/shard-1.json', 'results/shard-2.json']
+     */
+    shardResults?: string | string[];
+    /**
+     * Webhook notification channels. Post a pass/fail summary after each run.
+     * Each channel must have `enabled: true` to fire (default is `false`).
+     * `on` controls the trigger: `'always'` (default), `'failure'`, or `'success'`.
+     */
+    notify?: {
+        slack?: {
+            url: string;
+            on?: 'always' | 'failure' | 'success';
+            enabled?: boolean;
+        };
+        teams?: {
+            url: string;
+            on?: 'always' | 'failure' | 'success';
+            enabled?: boolean;
+        };
+        discord?: {
+            url: string;
+            on?: 'always' | 'failure' | 'success';
+            enabled?: boolean;
+        };
+    };
+    /**
+     * Path to the history JSON file. Defaults to
+     * `~/.reportforge/{projectKey}/history.json` where `projectKey` is derived
+     * from the raw `outputFile` string. Set explicitly to share history across
+     * machines or to place the file inside the repo (e.g. `.reportforge/history.json`).
+     */
+    historyFile?: string;
+    /**
+     * Maximum number of runs to keep in the history file. Older runs are pruned
+     * on append.
+     * @default 10
+     */
+    historySize?: number;
+    /**
+     * Show the pass-rate sparkline and delta badge in the `detailed` template.
+     * Set to `false` to disable history tracking entirely.
+     * @default true
+     */
+    showTrend?: boolean;
+}
+
+/**
+ * The resolved license for the current reporter run.
+ *
+ * The mere existence of a LicenseInfo means the subscription is active —
+ * "no license" is represented by `LicenseClient.resolve()` returning null,
+ * not by a sentinel plan or `valid: false` flag.
+ *
+ * `source` surfaces how the license was obtained so the reporter can log
+ * actionable diagnostics:
+ *   - 'jwt-online'  → freshly activated/refreshed against the server
+ *   - 'jwt-cache'   → served from ~/.reportforge/license.json (offline)
+ */
+interface LicenseInfo {
+    plan: LicensePlan;
+    source: 'jwt-online' | 'jwt-cache';
+    expiry: Date;
+    key: string;
+    machinesUsed?: number;
+    machineLimit?: number;
+}
+
+/**
+ * PdfReporter — Playwright custom reporter that generates professional PDF reports.
+ *
+ * Usage in playwright.config.ts:
+ * ```ts
+ * reporter: [
+ *   ['@reportforge/playwright-pdf', {
+ *     template: 'detailed',
+ *     outputFile: 'reports/{date}-{branch}-report.pdf',
+ *     logo: './assets/logo.png',
+ *     primaryColor: '#CC785C',
+ *   }]
+ * ]
+ * ```
+ *
+ * The reporter automatically reads `RF_LICENSE_KEY` from the environment.
+ * You can also pass it explicitly via the `licenseKey` option — useful when
+ * the key comes from a non-standard source.
+ *
+ * Pass an array to generate one PDF per template in a single run:
+ * ```ts
+ * reporter: [
+ *   ['@reportforge/playwright-pdf', {
+ *     template: ['detailed', 'executive'],
+ *     outputFile: 'reports/{date}-report.pdf',
+ *   }]
+ * ]
+ * ```
+ *
+ * An active ReportForge subscription is required. Without a valid license the
+ * reporter logs a single-line warning and skips PDF generation — your
+ * Playwright tests still run normally.
+ */
+declare class PdfReporter implements Reporter {
+    private readonly options;
+    private readonly cwd;
+    private readonly licenseClient;
+    private readonly dataCollector;
+    private readonly pdfGenerator;
+    constructor(rawOptions?: ReporterOptions);
+    onBegin(config: FullConfig, suite: Suite): void;
+    onTestEnd(test: TestCase, result: TestResult): void;
+    onEnd(result: FullResult): Promise<void>;
+    private _collectData;
+    private _appendTrend;
+    private _buildReportData;
+    printsToStdio(): boolean;
+    private resolveLicense;
+    private resolveProjectName;
+    private openPdf;
+}
+
+/**
+ * Returns the options object unchanged, but typed as `ReporterOptions`.
+ * Use this in `playwright.config.ts` to get full IntelliSense on all
+ * reporter properties:
+ *
+ * ```ts
+ * import { defineReporterConfig } from '@reportforge/playwright-pdf';
+ *
+ * reporter: [
+ *   ['@reportforge/playwright-pdf', defineReporterConfig({
+ *     template: 'detailed',
+ *     outputFile: 'reports/{date}-report.pdf',
+ *   })]
+ * ]
+ * ```
+ */
+declare function defineReporterConfig(options: ReporterOptions): ReporterOptions;
+
+export { type LicenseInfo, type LicensePlan, PdfReporter, type ReporterOptions, type TemplateId, PdfReporter as default, defineReporterConfig };