reporting-labs 0.6.10 → 0.6.12

package/README.md

@@ -305,8 +305,6 @@ Every option is optional. `npx reporting-labs init` writes them all, with commen
 | `project` | – | `{ name, version, team, url }` shown under the title |
 | `metadata` | `{}` | Chips in the header, e.g. `{ env: 'staging', build: '#1842' }`. `build` labels the run in the trend; in CI the run number is used when it is not set. The environment name is also read from the process environment and wins over `env` here: `ENV`, `TEST_ENV`, `APP_ENV`, `TARGET_ENV` and friends, or any variable ending in `_ENV` / `_ENVIRONMENT` (`OPENCART_ENV`), so a config that says `local` still labels CI reports `dev`, `qa`, `stage` |
 | `envVar` | – | Name of the variable that holds the environment name, when the detection cannot guess it |
-
-**Runtime overrides.** `REPORTING_LABS_METADATA_<KEY>` sets a header chip from the environment (`REPORTING_LABS_METADATA_ENV=qa`, `REPORTING_LABS_METADATA_RELEASE=2.3`) and `REPORTING_LABS_TITLE`, `_THEME`, `_PALETTE`, `_ACCENT`, `_LOGO` the matching option; they win over the config. The env chip resolves in this order: `REPORTING_LABS_METADATA_ENV`, the variable `envVar` names, the conventional names (`ENV`, `TEST_ENV`, `APP_ENV`, `TARGET_ENV`, `CI_ENVIRONMENT_NAME`, anything ending in `_ENV`), then `metadata.env` in the config.
 | `env` | – | Extra rows on the Environment card |
 | `links` | `{}` | Turn meta keys into links. `{id}` is replaced by the value. An object `{ url, display }` builds the URL from several fields of an object passed to `meta()`, see below |
 | `maskKeys` | `[]` | Extra keys to mask as `****` |
@@ -330,11 +328,14 @@ Every option is optional. `npx reporting-labs init` writes them all, with commen
 | `embedVideos` | `false` | Videos inside the HTML too (bigger file, no folder issues) |
 | `emitJson` | `true` | Also write `report.json` alongside `index.html` (used by `merge`) |
 | `jsonFile` | `'report.json'` | File name of the JSON blob |
+| `pdf` | `true` | Also write `report.pdf` (light theme, print-ready), printed by Playwright's Chromium or an installed Chrome / Edge, whatever browser the tests ran on. `false` turns it off; `{ file: 'run.pdf' }` renames it; `{ chromePath }` (or `CHROME_PATH`) names the browser. The Export PDF button in the report works either way |
 | `embedFonts` | `true` | Bundle the fonts (~140 KB) so it looks the same offline |
 | `announce` | `true` | Print the report path after the run |
 | `open` | `'on-failure'` | Open the report in the browser after the run: `'on-failure'`, `'always'` or `'never'`. Never opens in CI |
 | `warnMissingMeta` | `true` | After the run, list the tests that have no `meta()` in the console, so nobody on the team forgets |
 
+**Runtime overrides.** `REPORTING_LABS_METADATA_<KEY>` sets a header chip from the environment (`REPORTING_LABS_METADATA_ENV=qa`, `REPORTING_LABS_METADATA_RELEASE=2.3`) and `REPORTING_LABS_TITLE`, `_THEME`, `_PALETTE`, `_ACCENT`, `_LOGO` the matching option; they win over the config. The env chip resolves in this order: `REPORTING_LABS_METADATA_ENV`, the variable `envVar` names, the conventional names (`ENV`, `TEST_ENV`, `APP_ENV`, `TARGET_ENV`, `CI_ENVIRONMENT_NAME`, anything ending in `_ENV`), then `metadata.env` in the config.
+
 If your reporter list differs between CI and local, add the same line to both:
 
 ```ts
@@ -606,7 +607,7 @@ Your Slack step can then read `results.json` for pass / fail counts and top fail
 - **Each run replaces the report.** The old report stays until the new run finishes. Archive the folder if you want to keep an old one.
 - **Videos on macOS.** If the report is in Downloads, Desktop or Documents and you open it as a file, Chrome may not be allowed to read the `assets/` folder (the player shows a clear message). Allow Chrome under System Settings → Privacy & Security → Files and Folders, move the project elsewhere, or set `embedVideos: true`.
 - **Keyboard.** `j` / `k` next and previous test, `f` failed only, `/` search, `1`–`5` switch views, `Esc` close.
-- **Print.** A print stylesheet is included, so "Save as PDF" works.
+- **PDF.** `report.pdf` is written next to the report, and the Export PDF button in the header saves the same print-ready copy from the browser.
 - **Themes.** Light and dark follow the OS. The toggle in the header remembers your choice.
 
 ## Java teams
@@ -617,12 +618,42 @@ The same report, from Java: `dev.reportinglabs` on Maven Central, for TestNG and
 
 The same report, from Python: `pip install reporting-labs` ([PyPI](https://pypi.org/project/reporting-labs/)). A pytest plugin that turns on the moment it is installed, with zero-code support for Playwright and Selenium, and a Robot Framework listener (one row per test, keywords as steps). Source: [reporting-labs-python](https://github.com/naveenautomationlabs/reporting-labs-python). Guides: [reportinglabs.dev/get-started/python](https://reportinglabs.dev/get-started/python).
 
+## WebdriverIO
+
+The same report, from a WebdriverIO suite (Mocha, Jasmine or Cucumber): one row per test, WebDriver commands as steps, a screenshot on failure, failure clusters and the PDF export. WebdriverIO runs a reporter per spec, so reportingLabs writes a part per runner and stitches them together in `onComplete`:
+
+```ts
+// wdio.conf.ts
+import ReportingLabsReporter, { reportingLabsComplete } from 'reporting-labs/wdio';
+
+export const config = {
+  reporters: ['spec', [ReportingLabsReporter, { outputFolder: 'reporting-labs' }]],
+  async onComplete() {
+    await reportingLabsComplete({ outputFolder: 'reporting-labs', title: 'Web E2E' });
+  },
+};
+```
+
+Guide: [reportinglabs.dev/get-started/webdriverio](https://reportinglabs.dev/get-started/webdriverio).
+
 ## Roadmap
 
-- WebdriverIO, Cypress, Jest/Vitest and JUnit XML adapters
+- Cypress, Jest/Vitest and JUnit XML adapters
 - AI summary of failures (bring your own API key)
 - Hosted history dashboard across branches and projects
 
+## Security & privacy
+
+reportingLabs is a library that runs inside your own test run. There is no reportingLabs server, account, API key, telemetry or licence check.
+
+- **Nothing is sent anywhere.** The reporter makes no network requests of its own; its only traffic is the traffic your tests already make. An opened report makes no external requests either: fonts, scripts and the logo are embedded, so it works offline and behind a firewall. The only exceptions are opt-in (`embedFonts: false`, a logo given as an `https://` URL) or need a click (CI, commit and issue links).
+- **Everything stays on your machine:** the report folder (`reporting-labs/` by default) holds `index.html`, `report.json`, `report.pdf` and `assets/`, plus the run history `reporting-labs.history.json` next to your project. Nothing is written anywhere else. Whoever can read your test artifacts can read the report; deleting them deletes the data.
+- **Secrets are masked before anything is written:** passwords, tokens, cookies, auth headers, API keys, JWTs and card numbers in logs, API bodies and headers, test data, errors and step titles. With Playwright, a value passed to `fill()` shows in the step title unless it is a known secret, so read test passwords from environment variables (masked by default) or list them in `maskValues`. The WebdriverIO reporter masks values typed into password fields.
+- **Screenshots, videos and traces are not masked.** They are images and recordings of the application, so run tests against test data, or turn them off for suites that show real personal data.
+- **No runtime dependencies;** `@playwright/test` is an optional peer, the one your project already has. No install or post-install scripts. MIT licensed.
+
+Full details for security reviewers and client projects, including what is read, what is written and what to tell a client: [reportinglabs.dev/security-privacy](https://reportinglabs.dev/security-privacy). To report a vulnerability, open an issue saying you have a security report (no details) and a private channel will be arranged.
+
 ## License
 
 MIT © Naveen Automation Labs

package/dist/explain.d.ts

@@ -2,7 +2,7 @@
  * Turns a raw Playwright error message into a short, plain-language explanation.
  * Rule based, no network, no AI. The original message is always kept next to it.
  */
-export type ErrorKind = 'not-found' | 'ambiguous' | 'not-visible' | 'blocked' | 'disabled' | 'detached' | 'wrong-element' | 'assertion' | 'visual' | 'navigation' | 'network' | 'api' | 'test-timeout' | 'hook-timeout' | 'closed' | 'script' | 'file' | 'thrown';
+export type ErrorKind = 'not-found' | 'ambiguous' | 'not-visible' | 'blocked' | 'disabled' | 'detached' | 'wrong-element' | 'assertion' | 'visual' | 'navigation' | 'network' | 'api' | 'test-timeout' | 'hook-timeout' | 'closed' | 'crashed' | 'script' | 'file' | 'thrown';
 export interface ErrorExplain {
     kind: ErrorKind;
     /** Short label for a badge, e.g. "Element not found". */

package/dist/explain.js

@@ -21,6 +21,7 @@ const LABELS = {
     'test-timeout': 'Test timed out',
     'hook-timeout': 'Hook timed out',
     'closed': 'Browser closed early',
+    'crashed': 'Browser crashed',
     'script': 'Error in test code',
     'file': 'File not found',
     'thrown': 'Test threw an error',
@@ -51,6 +52,9 @@ function explainError(raw) {
         const where = action ? ` It was stuck in ${action}` + (locator ? ` on ${locator}` : '') + '.' : '';
         return out('test-timeout', `The whole test took longer than ${secs(ms)}.${where}`, 'Find the slow step in the Steps list below. Raise timeout in playwright.config.ts only if the flow is really that long.', { timeoutMs: ms, action, locator });
     }
+    // ── The browser process died (memory, too many workers): infrastructure, not the app or the test ──
+    if (/Target crashed|Page crashed|page has crashed|Renderer process crashed|tab crashed|session deleted because of page crash|chrome not reachable|Browsing context has been discarded/i.test(msg))
+        return out('crashed', 'The browser crashed while the test was running.', 'Not a bug in the app or the test: the browser process died, usually from memory pressure or too many parallel workers. Re-run it; if it keeps happening, lower workers or give the machine more memory.', { action });
     // ── Strict mode ──────────────────────────────────────────────────────────
     m = msg.match(/strict mode violation: (.+?) resolved to (\d+) elements/s);
     if (m)

package/dist/pdf.d.ts

@@ -0,0 +1,14 @@
+export interface PdfResult {
+    ok: boolean;
+    reason?: string;
+}
+/** Render the report's print layout to a PDF. Best-effort, never throws: a failure here must not fail
+ *  the run — the HTML report and its Export PDF button remain.
+ *  1. the Chromium that Playwright ships, when `@playwright/test` and its browser are installed;
+ *  2. an installed Chrome, Edge or Chromium, headless with --print-to-pdf (the report builds its print
+ *     layout itself on `?rl-print`). Edge ships with Windows, so this covers suites that run on Firefox
+ *     or WebKit, and WebdriverIO projects that have no Playwright at all.
+ *  `chromePath` (or the CHROME_PATH variable) names the browser explicitly and skips the search. */
+export declare function writeReportPdf(htmlFile: string, pdfFile: string, chromePath?: string): Promise<PdfResult>;
+/** Any Chromium-based browser can print the report: Chrome, Edge or Chromium. */
+export declare function findChrome(): string | undefined;

package/dist/pdf.js

@@ -0,0 +1,149 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeReportPdf = writeReportPdf;
+exports.findChrome = findChrome;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const url_1 = require("url");
+/** Render the report's print layout to a PDF. Best-effort, never throws: a failure here must not fail
+ *  the run — the HTML report and its Export PDF button remain.
+ *  1. the Chromium that Playwright ships, when `@playwright/test` and its browser are installed;
+ *  2. an installed Chrome, Edge or Chromium, headless with --print-to-pdf (the report builds its print
+ *     layout itself on `?rl-print`). Edge ships with Windows, so this covers suites that run on Firefox
+ *     or WebKit, and WebdriverIO projects that have no Playwright at all.
+ *  `chromePath` (or the CHROME_PATH variable) names the browser explicitly and skips the search. */
+async function writeReportPdf(htmlFile, pdfFile, chromePath) {
+    try {
+        fs.unlinkSync(pdfFile);
+    }
+    catch { /* none yet */ } // never leave a previous run's PDF next to this report
+    const explicit = chromePath || process.env.CHROME_PATH;
+    let firstError = '';
+    if (!explicit) {
+        try {
+            const { chromium } = await import('@playwright/test');
+            const browser = await chromium.launch();
+            try {
+                const page = await browser.newPage();
+                await page.goto((0, url_1.pathToFileURL)(htmlFile).href, { waitUntil: 'load' });
+                await page.evaluate(() => window.reportingLabsPreparePrint?.());
+                await page.pdf({ path: pdfFile, printBackground: true, preferCSSPageSize: true });
+            }
+            finally {
+                await browser.close();
+            }
+            if (written(pdfFile))
+                return { ok: true };
+        }
+        catch (e) {
+            firstError = String(e.message).split('\n')[0];
+        }
+    }
+    const chrome = explicit && isFile(explicit) ? explicit : findChrome();
+    if (!chrome) {
+        return { ok: false, reason: explicit ? `browser not found at ${explicit}` : 'no Chrome, Edge or Chromium found (set pdf: { chromePath }, or pdf: false to silence)' };
+    }
+    try {
+        (0, child_process_1.spawnSync)(chrome, ['--headless', '--no-sandbox', '--disable-gpu', '--no-pdf-header-footer',
+            '--virtual-time-budget=8000', '--run-all-compositor-stages-before-draw',
+            '--print-to-pdf=' + pdfFile, (0, url_1.pathToFileURL)(htmlFile).href + '?rl-print=1'], { stdio: 'ignore', timeout: 120000 });
+    }
+    catch (e) {
+        return { ok: false, reason: String(e.message).split('\n')[0] };
+    }
+    return written(pdfFile) ? { ok: true } : { ok: false, reason: firstError || `${path.basename(chrome)} did not write the PDF` };
+}
+function written(f) {
+    try {
+        return fs.statSync(f).size > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function isFile(f) {
+    try {
+        return fs.statSync(f).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function which(name) {
+    const exts = process.platform === 'win32' ? ['.exe', ''] : [''];
+    for (const dir of (process.env.PATH || '').split(path.delimiter)) {
+        if (!dir)
+            continue;
+        for (const ext of exts) {
+            const p = path.join(dir, name + ext);
+            try {
+                fs.accessSync(p, fs.constants.X_OK);
+                if (isFile(p))
+                    return p;
+            }
+            catch { /* next */ }
+        }
+    }
+    return undefined;
+}
+/** Any Chromium-based browser can print the report: Chrome, Edge or Chromium. */
+function findChrome() {
+    const candidates = [];
+    if (process.platform === 'darwin') {
+        candidates.push('/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', '/Applications/Chromium.app/Contents/MacOS/Chromium', '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge');
+    }
+    else if (process.platform === 'win32') {
+        for (const base of [process.env.ProgramFiles, process.env['ProgramFiles(x86)'], process.env.LOCALAPPDATA]) {
+            if (!base)
+                continue;
+            candidates.push(path.join(base, 'Google', 'Chrome', 'Application', 'chrome.exe'), path.join(base, 'Microsoft', 'Edge', 'Application', 'msedge.exe'));
+        }
+    }
+    for (const c of candidates)
+        if (isFile(c))
+            return c;
+    for (const name of ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', 'chrome',
+        'microsoft-edge', 'microsoft-edge-stable', 'msedge']) {
+        const p = which(name);
+        if (p)
+            return p;
+    }
+    for (const c of ['/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser', '/snap/bin/chromium'])
+        if (isFile(c))
+            return c;
+    return undefined;
+}

package/dist/reporter.d.ts

@@ -20,6 +20,8 @@ export default class ReportingLabsReporter implements Reporter {
     private pushOutput;
     onBegin(config: FullConfig, suite: Suite): void;
     onEnd(result: FullResult): Promise<void>;
+    /** report.pdf next to the HTML; see writeReportPdf for which browser prints it. Never fails the run. */
+    private writePdf;
     /** One short list of tests that carry no meta() at all, so the whole team keeps the report useful. */
     private printMissingMeta;
     /** Open the report in the default browser, like Playwright's HTML reporter. Never in CI. */
@@ -61,3 +63,15 @@ export default class ReportingLabsReporter implements Reporter {
  * it differently; this finds it without being told. Undefined when nothing fits.
  */
 export declare function detectEnvName(env: NodeJS.ProcessEnv, envVar?: string): string | undefined;
+export declare function ciRunLabel(env: NodeJS.ProcessEnv): string | undefined;
+export declare function ciLink(env: NodeJS.ProcessEnv): {
+    name: string;
+    url?: string;
+} | null;
+export declare function gitInfo(cwd: string, env: NodeJS.ProcessEnv): {
+    sha?: string;
+    author?: string;
+    subject?: string;
+    branch?: string;
+    url?: string;
+};

package/dist/reporter.js

@@ -34,6 +34,9 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectEnvName = detectEnvName;
+exports.ciRunLabel = ciRunLabel;
+exports.ciLink = ciLink;
+exports.gitInfo = gitInfo;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
@@ -41,6 +44,7 @@ const child_process_1 = require("child_process");
 const template_1 = require("./template");
 const mask_1 = require("./mask");
 const explain_1 = require("./explain");
+const pdf_1 = require("./pdf");
 const DEFAULT_EMBED_LIMIT = 2 * 1024 * 1024;
 /** Attach steps created by log() and the automatic API capture; the data shows in its own section, so hide the step. */
 function isInternalAttach(s) {
@@ -240,8 +244,19 @@ class ReportingLabsReporter {
             this.printMissingMeta(tests);
             console.log('');
         }
+        if (this.options.pdf !== false)
+            await this.writePdf(file);
         this.maybeOpen(file, result);
     }
+    /** report.pdf next to the HTML; see writeReportPdf for which browser prints it. Never fails the run. */
+    async writePdf(htmlFile) {
+        const pdfOpt = typeof this.options.pdf === 'object' ? this.options.pdf : {};
+        const pdfFile = path.join(this.outDir, pdfOpt.file || 'report.pdf');
+        const r = await (0, pdf_1.writeReportPdf)(htmlFile, pdfFile, pdfOpt.chromePath);
+        if (this.options.announce === false)
+            return;
+        console.log(r.ok ? `  reporting-labs: PDF written to ${path.relative(process.cwd(), pdfFile)}\n` : `  reporting-labs: PDF skipped — ${r.reason}\n`);
+    }
     /** One short list of tests that carry no meta() at all, so the whole team keeps the report useful. */
     printMissingMeta(tests) {
         if (this.options.warnMissingMeta === false)