reporting-labs 0.2.0 → 0.3.0

package/README.md

@@ -169,6 +169,7 @@ Run it two or three times to see the history features (new vs known failures, fl
 
 ### Test detail: the error, the steps, the proof
 
+- **What went wrong, in plain words.** Above every error the report says what happened and what to check first: "Element not found: `#checkout` was not on the page within 5s", "Element covered by another element: a `<div class=overlay>` was on top", "Site unreachable", "Test timed out", "Assertion failed: expected "90", got "100"". Playwright's own message stays right below it, untouched. The same label shows in Needs attention and groups the Failure clusters.
 - **Expected vs received** side by side with the difference highlighted.
 - Error **location** (opens in VS Code), Playwright's **code snippet**, full message and stack.
 - **Steps** with a bar per step showing its share of the test time. Given/When/Then titles are styled as Gherkin.
@@ -224,7 +225,7 @@ Every option is optional. `npx reporting-labs init` writes them all, with commen
 | Option | Default | What it does |
 |---|---|---|
 | `title` | `'Test report'` | Title in the header |
-| `logo` | – | Path, URL or data URI of your logo |
+| `logo` | – | Your logo next to the title: `'logo.png'` (a file next to the config, embedded in the report) or an https URL |
 | `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 |
 | `env` | – | Extra rows on the Environment card |
@@ -232,7 +233,7 @@ Every option is optional. `npx reporting-labs init` writes them all, with commen
 | `maskKeys` | `[]` | Extra keys to mask as `****` |
 | `dimensions` | `['priority','severity','feature','owner']` | Meta keys that get charts and filters |
 | `dimensionOrder` | P0…P4, blocker…trivial | Sort order per dimension |
-| `widgets` | all on | Hide cards: `{ tags: false, timeline: false, ... }` |
+| `widgets` | all on | Hide cards: `{ tags: false, timeline: false, ... }`. Failure clusters and the Trend chart are always shown |
 | `sections` | `[]` | Extra HTML below the summary, e.g. release notes |
 | `history` | `{ enabled: true, keep: 30 }` | Run history file; `file` sets a custom path |
 | `palette` | `'lab'` | `'lab'` (blue), `'ocean'`, `'ember'`, `'mono'` |

package/bin/config-template.txt

@@ -9,7 +9,7 @@ const config: ReportingLabsOptions = {
 
   // ── Look ─────────────────────────────────────────────────────────────────────
   title: 'My app – regression',                       // shown in the header
-  // logo: 'https://example.com/logo.svg',            // path, URL or data URI; shown next to the title
+  // logo: 'logo.png',                               // your logo next to the title: a file next to this config (embedded), or an https URL
   // palette: 'lab',                                  // 'lab' (blue, default) | 'ocean' | 'ember' | 'mono'; viewers can switch
   // accent: '#7C3AED',                               // your brand color instead of the palette accent
   // theme: 'auto',                                   // 'auto' (follows OS, default) | 'light' | 'dark'
@@ -54,6 +54,7 @@ const config: ReportingLabsOptions = {
   // },
 
   // ── Widgets on the overview (hide what you do not need) ──────────────────────
+  // Failure clusters and the Trend chart are always shown.
   // widgets: {
   //   runStrip: true,        // pass/fail strip under the header
   //   outcome: true,         // outcome ring

package/dist/explain.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 interface ErrorExplain {
+    kind: ErrorKind;
+    /** Short label for a badge, e.g. "Element not found". */
+    label: string;
+    /** One plain sentence about what happened. */
+    summary: string;
+    /** What to check first. */
+    hint?: string;
+    /** The locator involved, when Playwright printed one. */
+    locator?: string;
+    /** The Playwright call that failed, e.g. locator.click or page.goto. */
+    action?: string;
+    /** The expect matcher, e.g. toHaveText. */
+    matcher?: string;
+    timeoutMs?: number;
+    url?: string;
+}
+export declare function explainError(raw: string): ErrorExplain | undefined;

package/dist/explain.js

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.explainError = explainError;
+const LABELS = {
+    'not-found': 'Element not found',
+    'ambiguous': 'Selector matches several elements',
+    'not-visible': 'Element not visible',
+    'blocked': 'Element covered by another element',
+    'disabled': 'Element disabled',
+    'detached': 'Element disappeared',
+    'wrong-element': 'Wrong element type',
+    'assertion': 'Assertion failed',
+    'visual': 'Screenshot mismatch',
+    'navigation': 'Page did not load',
+    'network': 'Site unreachable',
+    'api': 'API call failed',
+    'test-timeout': 'Test timed out',
+    'hook-timeout': 'Hook timed out',
+    'closed': 'Browser closed early',
+    'script': 'Error in test code',
+    'file': 'File not found',
+    'thrown': 'Test threw an error',
+};
+const secs = (ms) => (ms >= 1000 ? (ms / 1000).toFixed(ms % 1000 ? 1 : 0) + 's' : ms + 'ms');
+const short = (s, n = 120) => (s.length > n ? s.slice(0, n - 1) + '…' : s);
+function pick(msg, re) { const m = msg.match(re); return m ? m[1] : undefined; }
+function explainError(raw) {
+    const msg = (raw || '').replace(/\u001b\[[0-9;]*m/g, '').trim();
+    if (!msg)
+        return undefined;
+    const first = msg.split('\n')[0].trim();
+    const out = (kind, summary, hint, extra = {}) => ({ kind, label: LABELS[kind], summary, hint, ...extra });
+    // Common pieces Playwright prints
+    const locator = pick(msg, /(?:waiting for|Locator:\s*|resolved to \d+ elements?:?\s*|locator\(['"]|)(locator\([^\n]*?\))(?:\s|$)/m) ?? pick(msg, /(?:waiting for|Locator:\s*)\s*(getBy\w+\([^\n]*?\)(?:\.\w+\([^\n]*?\))*)/m);
+    const timeoutMs = Number(pick(msg, /(?:Timeout|timeout of|Timed out)\s+(\d+)ms/i) ?? 0) || undefined;
+    const action = pick(first, /^(?:Error: |TimeoutError: )?([a-zA-Z]+\.[a-zA-Z]+):/);
+    const url = pick(msg, /(?:navigating to|at)\s+"?(https?:\/\/[^\s"]+)/);
+    // ── Whole-test and hook timeouts ─────────────────────────────────────────
+    let m = msg.match(/"(beforeAll|beforeEach|afterAll|afterEach)" hook timeout of (\d+)ms exceeded/);
+    if (m)
+        return out('hook-timeout', `The ${m[1]} hook took longer than ${secs(Number(m[2]))}.`, 'Look at what the hook does (login, seeding data, starting a server). Raise the hook timeout only if that work really needs more time.', { timeoutMs: Number(m[2]) });
+    m = msg.match(/Test timeout of (\d+)ms exceeded(?: while (?:running|tearing down) "(\w+)" hook)?/);
+    if (m) {
+        const ms = Number(m[1]);
+        if (m[2])
+            return out('hook-timeout', `The ${m[2]} hook did not finish within the test timeout of ${secs(ms)}.`, 'Check the steps in the hook. A slow login or a waiting call is the usual cause.', { timeoutMs: ms });
+        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 });
+    }
+    // ── Strict mode ──────────────────────────────────────────────────────────
+    m = msg.match(/strict mode violation: (.+?) resolved to (\d+) elements/s);
+    if (m)
+        return out('ambiguous', `${short(m[1].trim())} matched ${m[2]} elements, Playwright needs exactly one.`, 'Make the selector more specific, or pick one with .first(), .nth(i) or a filter such as { hasText }.', { locator: m[1].trim() });
+    // ── Assertions (expect) ──────────────────────────────────────────────────
+    m = msg.match(/expect\((?:locator|page|received|value)\)\.(\w+)(?:\(\w*\))?/) ?? msg.match(/waiting for expect\((?:locator|page)\)\.(\w+)/);
+    if (m || /^Error: expect\(/.test(first) || /^Error: Timed out \d+ms waiting for expect/.test(first)) {
+        const matcher = m ? m[1] : undefined;
+        const expected = pick(msg, /^Expected(?:[^:\n]{0,40})?:[ \t]*(.+)$/m)?.trim();
+        const received = pick(msg, /^Received(?:[^:\n]{0,40})?:[ \t]*(.+)$/m)?.trim();
+        const notFound = /element\(s\) not found|locator resolved to 0 elements|not found/i.test(msg) && !/unexpected value/i.test(msg);
+        const base = { matcher, locator, timeoutMs };
+        if (matcher === 'toHaveScreenshot' || /Screenshot comparison failed|pixels \(ratio [\d.]+ of all image pixels\) are different/.test(msg)) {
+            const px = pick(msg, /(\d+) pixels \(ratio ([\d.]+)/);
+            return out('visual', px ? `The page looks different from the baseline: ${px} pixels changed.` : 'The page looks different from the baseline screenshot.', 'Open the visual comparison below. If the new look is intended, update the baseline with --update-snapshots.', base);
+        }
+        if (notFound && locator)
+            return out('not-found', `${locator} was not on the page${timeoutMs ? ' within ' + secs(timeoutMs) : ''}, so ${matcher ?? 'the check'} could not run.`, 'Check the selector, and whether the element is inside an iframe, behind a login, or only shown after a click.', base);
+        if (matcher === 'toBeVisible' || (matcher === 'toBeHidden')) {
+            const want = matcher === 'toBeVisible' ? 'visible' : 'hidden';
+            return out(matcher === 'toBeVisible' ? 'not-visible' : 'assertion', `${locator ?? 'The element'} was expected to be ${want}${timeoutMs ? ' within ' + secs(timeoutMs) : ''} but was ${received ?? (want === 'visible' ? 'hidden' : 'visible')}.`, want === 'visible' ? 'The element may still be loading, be hidden by CSS, or sit inside a closed menu or dialog.' : 'Something kept the element on screen. Check the step that should hide it.', base);
+        }
+        if (matcher && /^(toHaveURL)$/.test(matcher))
+            return out('assertion', `The page URL was ${received ?? 'different'}, expected ${expected ?? 'another URL'}.`, 'The navigation may not have happened yet, or it went to a different page (a redirect, a login screen, an error page).', base);
+        if (matcher && /^(toHaveCount)$/.test(matcher))
+            return out('assertion', `${locator ?? 'The selector'} matched ${received ?? 'a different number of'} elements, expected ${expected ?? 'another count'}.`, 'The list may not have finished loading, or the selector also matches other elements.', base);
+        if (matcher && /^(toBeEnabled|toBeDisabled|toBeChecked|toBeEditable|toBeFocused|toBeEmpty|toBeAttached|toBeInViewport)$/.test(matcher))
+            return out('assertion', `${locator ?? 'The element'} was not in the expected state (${matcher.replace(/^toBe/, '').toLowerCase()})${received ? ': it was ' + received : ''}.`, 'Check the step before this one. The element may still be loading or waiting on a previous action.', base);
+        if (expected !== undefined && received !== undefined) {
+            const what = matcher && /text/i.test(matcher) ? 'text' : matcher && /value/i.test(matcher) ? 'value' : matcher && /attribute/i.test(matcher) ? 'attribute' : matcher && /title/i.test(matcher) ? 'title' : matcher && /class/i.test(matcher) ? 'class' : 'value';
+            const who = locator ? locator + ' had the wrong ' + what : 'The ' + what + ' was wrong';
+            return out('assertion', `${who}: expected ${short(expected, 80)}, got ${short(received, 80)}.`, /^["']/.test(expected) && /^["']/.test(received) && expected.toLowerCase() === received.toLowerCase() ? 'Only the letter case differs. Use toHaveText with { ignoreCase: true } if that is fine.' : 'Compare expected and received below. A copy change, a data change or a timing issue are the usual causes.', base);
+        }
+        return out('assertion', `${matcher ? 'expect().' + matcher + '()' : 'An expect()'} did not pass${locator ? ' for ' + locator : ''}.`, 'See the full message below for the expected and received values.', base);
+    }
+    // ── Navigation and network ───────────────────────────────────────────────
+    m = msg.match(/net::(ERR_[A-Z_]+)|NS_ERROR_([A-Z_]+)|Could not connect to server|ECONNREFUSED|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|ECONNRESET|certificate|ERR_CERT/i);
+    if (m) {
+        const code = (m[1] || m[2] || m[0]).toUpperCase();
+        const reason = /REFUSED/.test(code) ? 'nothing is listening on that address' : /NOT_RESOLVED|ENOTFOUND|EAI_AGAIN/.test(code) ? 'the host name could not be resolved' : /CERT/i.test(code) ? 'the TLS certificate was rejected' : /TIMED_OUT|ETIMEDOUT/.test(code) ? 'the connection timed out' : /RESET|ABORTED/.test(code) ? 'the connection was dropped' : 'the connection failed';
+        if (action && /^apiRequestContext\./.test(action))
+            return out('api', `The API request could not be sent: ${reason} (${code}).`, 'Check the base URL and that the API is up. In CI, check that the service started before the tests.', { action, url });
+        return out('network', `The browser could not reach ${url ?? 'the site'}: ${reason} (${code}).`, 'Check baseURL, that the app is running, and VPN or proxy settings. In CI, make sure the web server starts before the tests.', { action, url });
+    }
+    if (action && /^apiRequestContext\./.test(action)) {
+        if (/Request timed out|Timeout \d+ms exceeded/.test(msg))
+            return out('api', `The API request did not answer${timeoutMs ? ' within ' + secs(timeoutMs) : ' in time'}.`, 'The API may be slow or hanging. Check its logs, or raise the request timeout.', { action, url, timeoutMs });
+        if (/Request context disposed/.test(msg))
+            return out('api', 'The API request was made after its request context was closed.', 'Make sure request.dispose() or the end of the test does not run before this call.', { action });
+        return out('api', `The API call ${action} failed: ${short(first.replace(/^Error: /, ''))}`, 'See the full message below and the API tab for the request.', { action, url });
+    }
+    if (action && /^(page|frame)\.(goto|reload|goBack|goForward|waitForURL|waitForLoadState|waitForNavigation)$/.test(action)) {
+        if (/Timeout \d+ms exceeded|Navigation timeout/i.test(msg))
+            return out('navigation', `${url ?? 'The page'} did not finish loading within ${timeoutMs ? secs(timeoutMs) : 'the timeout'}.`, 'The app may be slow, stuck on a request, or redirecting in a loop. Try waitUntil: "domcontentloaded" if the page keeps long-running requests open.', { action, url, timeoutMs });
+        if (/interrupted by another navigation/.test(msg))
+            return out('navigation', 'The page navigated somewhere else while this navigation was in progress.', 'A redirect or a click started another navigation. Wait for the final URL instead.', { action, url });
+        return out('navigation', `${action} failed: ${short(first.replace(/^(Error|TimeoutError): /, ''))}`, 'See the full message below.', { action, url });
+    }
+    if (/Navigation timeout of \d+ms exceeded|page\.waitForNavigation/.test(msg))
+        return out('navigation', `The page did not finish loading within ${timeoutMs ? secs(timeoutMs) : 'the timeout'}.`, 'The app may be slow or stuck on a request. Check the Network tab in a trace.', { url, timeoutMs });
+    // ── Closed / detached ────────────────────────────────────────────────────
+    if (/Target page, context or browser has been closed|Target closed|Browser has been closed|Browser closed|browser has disconnected|Page closed|Context closed/i.test(msg))
+        return out('closed', 'The browser or page was closed before this step could run.', 'A previous step closed it, the test ended early, or the browser crashed. Look at the step just before this one.', { action });
+    if (/Execution context was destroyed|most likely because of a navigation/.test(msg))
+        return out('detached', 'The page navigated away while this step was running.', 'Wait for the navigation to finish (for example await page.waitForURL) before touching the page.', { action, locator });
+    if (/not attached to the DOM|element was detached|Element is not attached/i.test(msg))
+        return out('detached', `${locator ?? 'The element'} was removed from the page while Playwright was using it.`, 'The UI re-rendered the element. Re-locate it after the change, or wait for the update to finish.', { action, locator });
+    // ── Action timeouts on a locator: not found / not visible / blocked / disabled ──
+    if (action && /Timeout \d+ms exceeded/.test(msg)) {
+        const base = { action, locator, timeoutMs };
+        const t = timeoutMs ? ' for ' + secs(timeoutMs) : '';
+        if (/intercepts pointer events/.test(msg)) {
+            const by = pick(msg, /\n\s*-?\s*(<[^>]+>)[^\n]*intercepts pointer events/);
+            return out('blocked', `${locator ?? 'The element'} was there, but ${by ? by + ' ' : 'another element '}was covering it, so the ${action.split('.')[1]} never landed.`, 'A modal, cookie banner, toast or loading overlay is on top. Close it first, or wait for it to disappear.', base);
+        }
+        if (/element is not visible/.test(msg))
+            return out('not-visible', `${locator ?? 'The element'} exists but stayed hidden${t}.`, 'It may be inside a closed menu, collapsed section or hidden tab, or hidden by CSS. Open the container first.', base);
+        if (/element is not enabled|is disabled/.test(msg))
+            return out('disabled', `${locator ?? 'The element'} stayed disabled${t}.`, 'A form may be invalid or still loading. Fill the required fields or wait for the button to enable.', base);
+        if (/element is outside of the viewport/.test(msg))
+            return out('not-visible', `${locator ?? 'The element'} was outside the visible area${t}.`, 'Scroll it into view, or check for a fixed layout that keeps it off screen.', base);
+        if (/not an? <input>|not an <input>|Element is not an/.test(msg))
+            return out('wrong-element', `${locator ?? 'The element'} is not the kind of element this action works on.`, 'For example fill() needs an <input> or <textarea>. Check the selector points at the right element.', base);
+        if (/waiting for/.test(msg) && !/locator resolved to/.test(msg))
+            return out('not-found', `${locator ?? 'The element'} was not on the page${timeoutMs ? ' within ' + secs(timeoutMs) : ''}, so ${action} could not run.`, 'Check the selector. The element may be inside an iframe, behind a login, or only shown after another step.', base);
+        if (/waiting for element to be visible, enabled and stable/.test(msg))
+            return out('not-visible', `${locator ?? 'The element'} was found but never became ready (visible, enabled and stable)${timeoutMs ? ' within ' + secs(timeoutMs) : ''}.`, 'The element may be animating, hidden, or disabled. Wait for the animation or the loading state to finish.', base);
+        return out('not-found', `${action} did not complete${timeoutMs ? ' within ' + secs(timeoutMs) : ''}${locator ? ' on ' + locator : ''}.`, 'See the call log below for what Playwright was waiting on.', base);
+    }
+    if (action && /Element is not an? <input>|not an <input>/.test(msg))
+        return out('wrong-element', `${locator ?? 'The element'} is not the kind of element this action works on.`, 'For example fill() needs an <input> or <textarea>. Check the selector.', { action, locator });
+    if (action && /did not find some options|Option .* not found/.test(msg))
+        return out('assertion', `selectOption could not find the requested option${locator ? ' in ' + locator : ''}.`, 'Check the option value or label. Options may load later than the select element.', { action, locator });
+    // ── Files and code errors ────────────────────────────────────────────────
+    if (/ENOENT: no such file or directory/.test(msg)) {
+        const f = pick(msg, /open '([^']+)'|'([^']+)'/) ?? pick(msg, /directory, \w+ '([^']+)'/);
+        return out('file', `A file the test needs is missing${f ? ': ' + f : ''}.`, 'Check the path, and that the file is committed or generated before the run (a download, a fixture, a baseline screenshot).');
+    }
+    m = first.match(/^(TypeError|ReferenceError|SyntaxError|RangeError): (.+)$/);
+    if (m) {
+        const hint = /is not a function/.test(m[2]) ? 'A method is being called on the wrong object, or a helper was not imported.' : /Cannot read propert|of undefined|of null/.test(m[2]) ? 'Something was undefined at that point: an API response, a fixture, a page object field.' : /is not defined/.test(m[2]) ? 'A variable or import is missing.' : /JSON/.test(m[2]) ? 'The response was not valid JSON. It may be an HTML error page.' : 'This is a bug in the test or a helper, not in the app.';
+        return out('script', `${m[1]} in the test code: ${short(m[2])}`, hint);
+    }
+    if (/^Error: (.+)/.test(first) && !/^Error: (locator|page|frame|browser|expect|apiRequestContext)/.test(first))
+        return out('thrown', short(first.replace(/^Error: /, '')), 'The test (or a helper) threw this error on purpose or via a failed check. The stack trace below points at the line.');
+    return out('thrown', short(first), 'See the full message and stack trace below.');
+}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import ReportingLabsReporter from './reporter';
-export type { ReportingLabsOptions, ApiCall } from './types';
+export type { ReportingLabsOptions, ApiCall, ErrorExplainData } from './types';
+export { explainError } from './explain';
 export { ReportingLabsReporter };
 export { meta, log, testData, api, recordApi } from './meta';
 export default ReportingLabsReporter;

package/dist/index.js

@@ -3,9 +3,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.recordApi = exports.api = exports.testData = exports.log = exports.meta = exports.ReportingLabsReporter = void 0;
+exports.recordApi = exports.api = exports.testData = exports.log = exports.meta = exports.ReportingLabsReporter = exports.explainError = void 0;
 const reporter_1 = __importDefault(require("./reporter"));
 exports.ReportingLabsReporter = reporter_1.default;
+var explain_1 = require("./explain");
+Object.defineProperty(exports, "explainError", { enumerable: true, get: function () { return explain_1.explainError; } });
 var meta_1 = require("./meta");
 Object.defineProperty(exports, "meta", { enumerable: true, get: function () { return meta_1.meta; } });
 Object.defineProperty(exports, "log", { enumerable: true, get: function () { return meta_1.log; } });

package/dist/reporter.d.ts

@@ -31,6 +31,8 @@ export default class ReportingLabsReporter implements Reporter {
     private metaKeys;
     /** Pull meta values (priority, owner, story, epic...) from annotations and tags. */
     private extractMeta;
+    /** A local image file (path relative to the config) is embedded as a data URI so the report stays self-contained. URLs and data URIs pass through. */
+    private resolveLogo;
     private rel;
     private serializeError;
     private outcome;

package/dist/reporter.js

@@ -39,6 +39,7 @@ const os = __importStar(require("os"));
 const child_process_1 = require("child_process");
 const template_1 = require("./template");
 const mask_1 = require("./mask");
+const explain_1 = require("./explain");
 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) {
@@ -167,7 +168,7 @@ class ReportingLabsReporter {
             globalOutput: this.globalOutput,
             shard: this.config.shard ? { current: this.config.shard.current, total: this.config.shard.total } : undefined,
             options: {
-                logo: this.options.logo,
+                logo: this.resolveLogo(this.options.logo),
                 accent: this.options.accent,
                 theme: this.options.theme ?? 'auto',
                 palette: this.options.palette ?? 'lab',
@@ -329,12 +330,33 @@ class ReportingLabsReporter {
         }
         return meta;
     }
+    /** A local image file (path relative to the config) is embedded as a data URI so the report stays self-contained. URLs and data URIs pass through. */
+    resolveLogo(logo) {
+        if (!logo || /^(https?:|data:)/i.test(logo))
+            return logo;
+        const base = this.config.configFile ? path.dirname(this.config.configFile) : this.config.rootDir;
+        const file = path.resolve(base, logo);
+        if (!fs.existsSync(file)) {
+            console.warn(`reporting-labs: logo not found at ${file}`);
+            return undefined;
+        }
+        const mime = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.svg': 'image/svg+xml', '.gif': 'image/gif', '.webp': 'image/webp', '.ico': 'image/x-icon' };
+        const type = mime[path.extname(file).toLowerCase()];
+        if (!type) {
+            console.warn(`reporting-labs: logo ${logo} is not a png, jpg, svg, gif or webp file`);
+            return undefined;
+        }
+        return `data:${type};base64,${fs.readFileSync(file).toString('base64')}`;
+    }
     rel(file) {
         const base = this.config.configFile ? path.dirname(this.config.configFile) : this.config.rootDir;
         return path.relative(base, file).split(path.sep).join('/');
     }
     serializeError(e) {
         const out = { message: stripAnsi(e.message ?? e.value ?? '') };
+        const why = (0, explain_1.explainError)(out.message);
+        if (why)
+            out.explain = why;
         if (e.stack)
             out.stack = stripAnsi(e.stack);
         if (e.snippet)

package/dist/template.js

@@ -473,6 +473,7 @@ html,body{-webkit-font-smoothing:antialiased}
 .hdr h1,.hdr .proj-blk h1{color:#fff;font-size:20px;font-weight:600;letter-spacing:-.01em;line-height:1.2}
 .hdr .proj-blk .sub,.hdr .proj-blk .sub a,.hdr .when{color:rgba(255,255,255,.78)}
 .hdr .logo{width:42px;height:42px;border-radius:11px;flex:none;box-shadow:0 0 0 1px rgba(255,255,255,.35),0 6px 16px -6px rgba(0,0,0,.45)} .hdr .logo svg{width:42px;height:42px;display:block;border-radius:11px}
+.hdr img.logo.brand{width:auto;max-width:180px;height:42px;object-fit:contain;border-radius:8px;background:#fff;padding:4px;box-sizing:border-box}
 .hdr img{height:32px;border-radius:6px}
 .hdr .chip{background:rgba(255,255,255,.12);border:1px solid rgba(255,255,255,.22);color:rgba(255,255,255,.85);border-radius:999px;padding:4px 9px}
 .hdr .chip b{color:#fff}
@@ -603,7 +604,7 @@ html,body{-webkit-font-smoothing:antialiased}
 .attn2 td:first-child{border-radius:6px 0 0 6px} .attn2 td:last-child{border-radius:0 6px 6px 0}
 .attn2 .pr{width:96px;white-space:nowrap;font-size:12.5px;line-height:1.35} .attn2 .pr .dot{display:inline-block;width:8px;height:8px;border-radius:50%;margin-right:7px}
 .attn2 .pr span{font-weight:600;color:var(--ink)} .attn2 .pr small{display:block;color:var(--ink-3);font-size:11.5px;padding-left:15px}
-.attn2 .tt .n{font-weight:500;color:var(--ink);line-height:1.35} .attn2 .tt .s{font-size:12px;color:var(--ink-3);margin-top:2px} .attn2 .tt .s b.new{color:var(--fail);font-weight:600}
+.attn2 .tt .n{font-weight:500;color:var(--ink);line-height:1.35} .attn2 .tt .s{font-size:12px;color:var(--ink-3);margin-top:2px} .attn2 .tt .s b.new{color:var(--fail);font-weight:600} .attn2 .tt .s .rsn{color:var(--ink-2)}
 .attn2 .ow{text-align:right;color:var(--ink-3);font-size:12.5px;white-space:nowrap;width:1%;padding-top:10px}
 .attn-foot{margin-top:auto;padding-top:12px;border-top:1px solid var(--line)} .attn-foot button{font-size:12.5px;font-weight:500;color:var(--accent-2)} .attn-foot button:hover{text-decoration:underline}
 .clu2{list-style:none;margin:0;padding:0}
@@ -619,6 +620,12 @@ html,body{-webkit-font-smoothing:antialiased}
 .note{padding:10px 14px;border-radius:8px;margin-bottom:10px;border:1px solid var(--line)} .note.ok{background:var(--pass-bg);color:var(--ink)} .note.warn{background:var(--flaky-bg);color:var(--flaky-ink)}
 .badge.xfail{background:var(--flaky-bg);color:var(--flaky-ink)}
 .errwrap+.errwrap{margin-top:14px}
+.why{border:1px solid var(--line);border-left:3px solid var(--fail);border-radius:0 var(--radius) var(--radius) 0;padding:10px 14px;margin-bottom:10px;background:var(--surface)}
+.why-c{font-size:12.5px;color:var(--ink);margin-bottom:2px;line-height:1.4} .why-c .why-k{margin-right:2px}
+.why-l{display:flex;align-items:center;gap:8px;margin-bottom:4px} .why-k{font-size:12px;font-weight:600;color:var(--fail)} .why-a{font:11.5px var(--mono);color:var(--ink-3)}
+.why-s{font-size:var(--fs);color:var(--ink);line-height:1.45} .why-h{font-size:12.5px;color:var(--ink-2);margin-top:4px;line-height:1.45}
+.why.assertion,.why.visual{border-left-color:#C77D14} .why.assertion .why-k,.why.visual .why-k{color:#9A6A00}
+.why.script,.why.thrown,.why.file{border-left-color:var(--ink-3)} .why.script .why-k,.why.thrown .why-k,.why.file .why-k{color:var(--ink-2)}
 .errloc{font-family:var(--mono);color:var(--ink-3);margin-bottom:6px} .errloc a{color:var(--accent-2);text-decoration:none} .errloc a:hover{text-decoration:underline}
 .snip{margin:10px 0 0;background:var(--surface-2);border:1px solid var(--line);border-radius:8px;padding:10px 12px;font-family:var(--mono);line-height:1.55;white-space:pre;overflow:auto;color:var(--ink-2)}
 /* ---------- triage extras: history, diff, export, env, heatmap ---------- */
@@ -725,7 +732,7 @@ app.append(h('div',{class:'band'}, stripe(), header(), nav()),
   h('div',{class:'view','data-view':'tests'}, main()),
   h('div',{class:'view','data-view':'failures'}, h('div',{class:'view-pad'}, failuresView())),
   h('div',{class:'view','data-view':'api'}, h('div',{class:'view-pad'}, apiView())),
-  h('div',{class:'view','data-view':'timeline'}, h('div',{class:'view-pad'}, timelineView())));
+  hasTimelineView()? h('div',{class:'view','data-view':'timeline'}, h('div',{class:'view-pad'}, timelineView())) : null);
 select(state.selected || firstInteresting(), true);
 showView(state.view);
 window.addEventListener('keydown', e=>{
@@ -740,13 +747,14 @@ window.addEventListener('keydown', e=>{
 /* ---------- header ---------- */
 function setHash(){ const p=new URLSearchParams(); if(state.view!=='overview') p.set('view',state.view); if(state.selected&&state.view==='tests') p.set('t',state.selected); const hs=p.toString(); history.replaceState(null,'',hs?'#'+hs:location.pathname+location.search); }
 function showView(v){
+  if(!document.querySelector('.view[data-view='+v+']')) v='overview';
   state.view=v; document.querySelectorAll('.view').forEach(el=>el.classList.toggle('on',el.dataset.view===v));
   document.querySelectorAll('.nav button[data-view]').forEach(b=>b.setAttribute('aria-selected',b.dataset.view===v));
   setHash(); try{window.scrollTo(0,0);}catch(e){}
 }
 function nav(){
   const s=data.stats, f=s.failed+s.timedOut+s.interrupted, apiN=data.tests.reduce((a,t)=>a+t.results.reduce((b,r)=>b+r.api.length,0),0);
-  const tabs=[['overview','Overview',null],['tests','Tests',s.total],['failures','Failures',f+s.flaky,f>0],['api','API',apiN],['timeline','Timeline',null]].filter(t=>t[0]!=='api'||apiN>0);
+  const tabs=[['overview','Overview',null],['tests','Tests',s.total],['failures','Failures',f+s.flaky,f>0],['api','API',apiN],['timeline','Timeline',null]].filter(t=>(t[0]!=='api'||apiN>0)&&(t[0]!=='timeline'||hasTimelineView()));
   return h('nav',{class:'nav'}, h('div',{}, tabs.map(([v,l,n,bad])=>h('button',{'data-view':v,'aria-selected':state.view===v,onclick:()=>showView(v)}, l, n!=null?h('span',{class:'cnt'+(bad?' bad':'')},n):null))));
 }
 function failuresView(){
@@ -780,8 +788,12 @@ function apiView(){
         h('td',{class:'u',title:c.url},c.url), h('td',{}, h('span',{class:'sc '+cls,style:'font:12px var(--mono);font-weight:600;color:'+(cls==='bad'?'var(--fail)':cls==='warn'?'var(--flaky-ink)':'var(--pass)')},st||'—')), h('td',{class:'t'},c.duration!=null?ms(c.duration):'—'), h('td',{class:'t',title:t.title},t.title)); })))));
 }
 function timelineView(){
-  return h('div',{class:'grid'}, h('div',{class:'card w12'}, h('h2',{},'Timeline by worker'), timeline()), h('div',{class:'card w6'}, h('h2',{},'Workers'), workers()), h('div',{class:'card w6'}, h('h2',{},'Duration spread'), histogram()));
+  const W=data.options.widgets, cards=[];
+  if(W.timeline!==false) cards.push(h('div',{class:'card w12'}, h('h2',{},'Timeline by worker'), timeline()), h('div',{class:'card w6'}, h('h2',{},'Workers'), workers()));
+  if(W.durations!==false) cards.push(h('div',{class:W.timeline!==false?'card w6':'card w12'}, h('h2',{},'Duration spread'), histogram()));
+  return h('div',{class:'grid'}, cards);
 }
+function hasTimelineView(){ return data.options.widgets.timeline!==false || data.options.widgets.durations!==false; }
 function stripe(){
   const s=data.stats, f=s.failed+s.timedOut+s.interrupted, tot=s.total||1;
   return h('div',{class:'stripe','aria-hidden':'true'}, [['passed',s.passed],['flaky',s.flaky],['failed',f],['skipped',s.skipped]].filter(x=>x[1]).map(([k,n])=>h('i',{style:'width:'+(n/tot*100)+'%;background:'+colorOf(k)})));
@@ -808,10 +820,11 @@ function header(){
     [['lab','Blue'],['ocean','Ocean'],['ember','Ember'],['mono','Mono']].map(([v,l])=>h('option',{value:v,selected:html.getAttribute('data-palette')===v},l)));
   const copy = h('button',{class:'btn',onclick:e=>copyText(summaryMarkdown(),e.currentTarget,'Copied for Slack')}, 'Copy summary');
   return h('header',{class:'hdr'},
-    data.options.logo ? h('img',{src:data.options.logo,alt:''}) : h('div',{class:'logo',title:'Generated by reportingLabs','aria-label':'reportingLabs'}, document.getElementById('rl-logo').content.cloneNode(true)),
+    data.options.logo ? h('img',{class:'logo brand',src:data.options.logo,alt:''}) : h('div',{class:'logo',title:'Generated by reportingLabs','aria-label':'reportingLabs'}, document.getElementById('rl-logo').content.cloneNode(true)),
     data.options.project ? h('div',{class:'proj-blk'}, h('h1',{}, data.title),
       h('div',{class:'sub'}, [data.options.project.name, data.options.project.version?'v'+data.options.project.version:null, data.options.project.team].filter(Boolean).join(' · '),
-        data.options.project.url? [' · ', h('a',{href:data.options.project.url,target:'_blank',rel:'noopener'}, data.options.project.url.replace(/^https?:\/\//,''))] : null))
+        data.options.project.url? [' · ', h('a',{href:data.options.project.url,target:'_blank',rel:'noopener'}, data.options.project.url.replace(/^https?:\/\//,''))] : null),
+      data.options.project.description? h('div',{class:'sub desc'}, data.options.project.description) : null)
     : h('h1',{}, data.title),
     h('div',{class:'hmeta'}, Object.entries(data.metadata).map(([k,v])=>h('span',{class:'chip'}, k+' ', h('b',{},v)))),
     h('div',{class:'spacer'}),
@@ -950,7 +963,7 @@ function csvCell(v){ v=v==null?'':String(v); return /[",\n]/.test(v)? '"'+v.repl
 function failureRows(){
   const bad=data.tests.filter(t=>isFail(t.outcome)||t.outcome==='flaky').sort((a,b)=>rank(a)-rank(b));
   return bad.map(t=>{ const r=t.results[t.results.length-1], e=r&&r.errors[0], si=sinceInfo(t);
-    return { title:t.title, suite:t.path.join(' > '), file:t.file, line:t.line, project:t.project, outcome:label[t.outcome], since:si?(si.kind==='new'?'new':runLabel(si.since)):'', priority:t.meta.priority||'', severity:t.meta.severity||'', owner:t.meta.owner||'', feature:t.meta.feature||'', story:t.meta.story||t.meta.issue||'', epic:t.meta.epic||'', attempts:t.results.length, duration_ms:Math.round(t.duration), error:e?e.message.split('\n')[0]:'', tags:t.tags.join(' ') }; });
+    return { title:t.title, suite:t.path.join(' > '), file:t.file, line:t.line, project:t.project, outcome:label[t.outcome], since:si?(si.kind==='new'?'new':runLabel(si.since)):'', priority:t.meta.priority||'', severity:t.meta.severity||'', owner:t.meta.owner||'', feature:t.meta.feature||'', story:t.meta.story||t.meta.issue||'', epic:t.meta.epic||'', attempts:t.results.length, duration_ms:Math.round(t.duration), reason:e&&e.explain?e.explain.label:'', why:e&&e.explain?e.explain.summary:'', error:e?e.message.split('\n')[0]:'', tags:t.tags.join(' ') }; });
 }
 function exportCsv(){ const rows=failureRows(); if(!rows.length) return; const cols=Object.keys(rows[0]); download(fileStem()+'-failures.csv', [cols.join(','), ...rows.map(r=>cols.map(c=>csvCell(r[c])).join(','))].join('\n'), 'text/csv'); }
 function exportJson(){ const rows=failureRows().map(r=>{ const t=data.tests.find(x=>x.title===r.title&&x.project===r.project&&x.file===r.file); const res=t&&t.results[t.results.length-1]; return Object.assign({}, r, {errorFull:res&&res.errors[0]?res.errors[0].message:''}); });
@@ -969,7 +982,12 @@ function tokenDiff(a,b){
   const join=(arr,cls)=>{ const out=[]; for(const [t,d] of arr){ const last=out[out.length-1]; if(last&&last.d===d) last.t+=t; else out.push({t,d}); } return out.map(x=>x.d?h('mark',{class:cls},x.t):x.t); };
   return {a:join(A,'del'), b:join(B,'ins')};
 }
-function errorView(e){ return h('div',{class:'errwrap'}, errorWhere(e), errorBody(e), e.snippet? h('pre',{class:'snip'}, e.snippet) : null); }
+function errorView(e){ return h('div',{class:'errwrap'}, whyView(e.explain), errorWhere(e), errorBody(e), e.snippet? h('pre',{class:'snip'}, e.snippet) : null); }
+function whyView(x){
+  if(!x) return null;
+  return h('div',{class:'why '+x.kind}, h('div',{class:'why-l'}, h('span',{class:'why-k'},x.label), x.action? h('code',{class:'why-a'},x.action):null),
+    h('div',{class:'why-s'},x.summary), x.hint? h('div',{class:'why-h'},x.hint):null);
+}
 function errorWhere(e){
   if(!e.location) return null;
   const l=e.location, txt=l.file+':'+l.line+(l.column?':'+l.column:'');
@@ -1041,7 +1059,7 @@ function hero(){
   else delta=ok? 'Nothing to worry about.' : failed+' failed'+(s.flaky?', '+s.flaky+' flaky':'')+(s.skipped?', '+s.skipped+' skipped':'');
   return h('button',{class:'pill kpi hero','aria-pressed':state.status==='all','data-k':'all',title:'Show all tests',onclick:()=>{state.status='all';refresh();showView('tests');}},
     spark(hseries(e=>{ const rn=e.total-e.skipped; return rn?Math.round(e.passed/rn*100):0; }),'#fff'),
-    ring,
+    data.options.widgets.outcome!==false? ring : null,
     h('div',{class:'body'},
       h('div',{class:'l'}, ok? 'All passed' : 'Pass rate'),
       h('div',{class:'v'}, s.passed, h('small',{}, 'of '+ran+' ran')),
@@ -1067,6 +1085,7 @@ function attention(limit){
   const sub=(t,projects)=>{ const parts=[t.file.split('/').pop()];
     if(data.projects.length>1) parts.push(projects.length>1? projects.length+' projects' : projects[0]);
     const si=sinceInfo(t); if(si) parts.push(si.kind==='new'? h('b',{class:'new'},'new this run') : 'failing since '+runLabel(si.since));
+    const le=t.results[t.results.length-1]&&t.results[t.results.length-1].errors[0]; if(le&&le.explain) parts.push(h('span',{class:'rsn',title:le.explain.summary},le.explain.label));
     else if(t.outcome==='flaky') parts.push('passed on retry '+t.results.length);
     const out=[]; parts.forEach((x,k)=>{ if(k) out.push(' · '); out.push(x); }); return out; };
   const tbl=h('table',{class:'attn2'}, h('tbody',{}, rows.map(({t,projects})=>h('tr',{tabindex:'0',onclick:()=>select(t.id),onkeydown:e=>{ if(e.key==='Enter') select(t.id); }},
@@ -1121,7 +1140,7 @@ function errorSignature(msg){
 }
 function failureClusters(){
   const m=new Map();
-  for(const t of data.tests){ if(!isFail(t.outcome)) continue; const r=t.results[t.results.length-1]; const e=r&&r.errors[0]; const sig=errorSignature(e?e.message:'(no error message)'); const c=m.get(sig)||{sig,sample:e?e.message.split('\n').slice(0,2).join('\n'):'(no error message)',tests:[]}; c.tests.push(t); m.set(sig,c); }
+  for(const t of data.tests){ if(!isFail(t.outcome)) continue; const r=t.results[t.results.length-1]; const e=r&&r.errors[0]; const x=e&&e.explain; const sig=x&&!/^(thrown|script)$/.test(x.kind)? x.kind+'|'+(x.locator||x.url||'')+'|'+(x.matcher||x.action||'') : errorSignature(e?e.message:'(no error message)'); const c=m.get(sig)||{sig,sample:e?e.message.split('\n').slice(0,2).join('\n'):'(no error message)',why:e&&e.explain?e.explain:null,tests:[]}; c.tests.push(t); m.set(sig,c); }
   return [...m.values()].sort((a,b)=>b.tests.length-a.tests.length);
 }
 function clustersView(cl){
@@ -1131,7 +1150,7 @@ function clustersView(cl){
     const who=[]; names.forEach(([title,ts],k)=>{ if(k) who.push(h('span',{class:'sep'},'·')); who.push(h('button',{onclick:()=>select(ts[0].id),title:ts.map(t=>t.project).join(', ')}, title, data.projects.length>1&&ts.length>1? h('small',{},' ×'+ts.length) : null)); });
     if(extra>0) who.push(h('span',{class:'sep'},'·'), h('span',{class:'ex'},'+'+extra+' more'));
     return h('li',{}, h('span',{class:'n'}, c.tests.length, h('small',{},c.tests.length===1?'test':'tests')),
-      h('div',{class:'b'}, h('div',{class:'msg',title:c.sample}, c.sample.split('\n')[0]), h('div',{class:'who'}, who)));
+      h('div',{class:'b'}, c.why? h('div',{class:'why-c'}, h('span',{class:'why-k'},c.why.label), ' ', c.why.summary) : null, h('div',{class:'msg',title:c.sample}, c.sample.split('\n')[0]), h('div',{class:'who'}, who)));
   }));
 }
 function trend(){

package/dist/types.d.ts

@@ -1,7 +1,7 @@
 export interface ReportingLabsOptions {
     /** Report title shown in the header. Default: "Test report" */
     title?: string;
-    /** Path or data-URI of a logo image. Optional. */
+    /** Your logo: a file path relative to the config (e.g. 'logo.png', embedded into the report), an https URL, or a data URI. */
     logo?: string;
     /** Override the palette accent with your brand color, e.g. '#7C3AED'. Default: the palette's own accent (royal blue for `lab`). */
     accent?: string;
@@ -148,6 +148,17 @@ export interface EnvRow {
     href?: string;
 }
 export type Status = 'passed' | 'failed' | 'skipped' | 'flaky' | 'timedOut' | 'interrupted';
+export interface ErrorExplainData {
+    kind: string;
+    label: string;
+    summary: string;
+    hint?: string;
+    locator?: string;
+    action?: string;
+    matcher?: string;
+    timeoutMs?: number;
+    url?: string;
+}
 export interface ErrorData {
     message: string;
     stack?: string;
@@ -156,7 +167,8 @@ export interface ErrorData {
         file: string;
         line: number;
         column: number;
-    };
+    }; /** Plain-language reading of the message, rule based. The message itself is always kept. */
+    explain?: ErrorExplainData;
 }
 export interface StepData {
     title: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reporting-labs",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "reportingLabs – beautiful, customizable single-file HTML test reports. One line of config. Playwright adapter included, more runners on the way.",
   "keywords": [
     "test-report",