donobu 5.26.0 → 5.27.0

package/dist/esm/reporter/markdown.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Donobu Markdown Reporter for Playwright.
+ *
+ * Writes a Markdown summary of the run to disk. Pairs with the
+ * GitHub Actions step-summary pattern: the CI job just cats the file into
+ * `$GITHUB_STEP_SUMMARY`.
+ *
+ * @usage
+ * ```ts
+ * // playwright.config.ts
+ * reporter: [
+ *   ['donobu/reporter/markdown', { outputFile: 'test-results/report.md' }],
+ * ],
+ * ```
+ *
+ * During an auto-heal rerun (`DONOBU_AUTO_HEAL_ACTIVE=1`) the reporter skips
+ * file writes. It always merges its output entry into the shared state file
+ * so the orchestrator knows to regenerate the markdown from the merged report.
+ */
+import type { FullResult, Reporter, TestCase, TestResult } from '@playwright/test/reporter';
+export interface DonobuMarkdownReporterOptions {
+    /** Path to write the Markdown report. Defaults to `test-results/report.md`. */
+    outputFile?: string;
+}
+export default class DonobuMarkdownReporter implements Reporter {
+    private readonly options;
+    private readonly resultsByTest;
+    constructor(options?: DonobuMarkdownReporterOptions);
+    onTestEnd(test: TestCase, result: TestResult): void;
+    onEnd(_result: FullResult): Promise<void>;
+    printsToStdio(): boolean;
+}
+//# sourceMappingURL=markdown.d.ts.map

package/dist/esm/reporter/markdown.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * @fileoverview Donobu Markdown Reporter for Playwright.
+ *
+ * Writes a Markdown summary of the run to disk. Pairs with the
+ * GitHub Actions step-summary pattern: the CI job just cats the file into
+ * `$GITHUB_STEP_SUMMARY`.
+ *
+ * @usage
+ * ```ts
+ * // playwright.config.ts
+ * reporter: [
+ *   ['donobu/reporter/markdown', { outputFile: 'test-results/report.md' }],
+ * ],
+ * ```
+ *
+ * During an auto-heal rerun (`DONOBU_AUTO_HEAL_ACTIVE=1`) the reporter skips
+ * file writes. It always merges its output entry into the shared state file
+ * so the orchestrator knows to regenerate the markdown from the merged report.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = require("fs");
+const path_1 = require("path");
+const buildReport_1 = require("./buildReport");
+const renderMarkdown_1 = require("./renderMarkdown");
+const stateFile_1 = require("./stateFile");
+class DonobuMarkdownReporter {
+    constructor(options = {}) {
+        this.resultsByTest = new Map();
+        this.options = options;
+    }
+    onTestEnd(test, result) {
+        const existing = this.resultsByTest.get(test);
+        if (existing) {
+            existing.push(result);
+        }
+        else {
+            this.resultsByTest.set(test, [result]);
+        }
+    }
+    async onEnd(_result) {
+        const outputFile = (0, path_1.resolve)(this.options.outputFile ?? 'test-results/report.md');
+        const outputDir = (0, path_1.dirname)(outputFile);
+        const autoHealActive = process.env.DONOBU_AUTO_HEAL_ACTIVE === '1';
+        const report = (0, buildReport_1.buildDonobuReport)(this.resultsByTest);
+        (0, stateFile_1.mergeStateFileEntry)(process.env.PLAYWRIGHT_JSON_OUTPUT_DIR, report, {
+            markdown: { outputFile },
+        });
+        if (autoHealActive) {
+            return;
+        }
+        const markdown = (0, renderMarkdown_1.renderMarkdown)(report);
+        (0, fs_1.mkdirSync)(outputDir, { recursive: true });
+        (0, fs_1.writeFileSync)(outputFile, markdown, 'utf8');
+        console.error(`Donobu Markdown report written to ${outputFile}`);
+    }
+    printsToStdio() {
+        return false;
+    }
+}
+exports.default = DonobuMarkdownReporter;
+//# sourceMappingURL=markdown.js.map

package/dist/esm/reporter/merge.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Pure in-memory merge of two `DonobuReport`s.
+ *
+ * Combines the initial Playwright run and an auto-heal rerun into a single
+ * report that carries both attempts and annotates any test whose outcome
+ * flipped from failing → passing as `self-healed`. The result is destined for
+ * the HTML renderer (and, for back-compat, the on-disk Playwright JSON that
+ * downstream dashboards consume).
+ *
+ * This module intentionally owns zero I/O. Callers load the reports off disk,
+ * call `mergeReports`, then persist / relocate attachments / re-render as
+ * needed. Keeping the merge pure makes it trivial to test and reason about.
+ */
+import type { DonobuReport, HealedTestDescriptor } from './model';
+export interface MergeReportsParams {
+    /** Pre-loaded initial report, or null when the initial run produced none. */
+    initialReport: DonobuReport | null;
+    /** Pre-loaded heal-run report, or null when the heal run produced none. */
+    healReport: DonobuReport | null;
+    /** Tests the orchestrator declared healed — used when the heal report
+     *  doesn't expose them under a matching key (e.g. filter rewrites). */
+    healedTests: HealedTestDescriptor[];
+    /** Whether the heal rerun exited cleanly. */
+    healSucceeded: boolean;
+    /** Recorded in the merged report metadata for triage auto-discovery. */
+    triageRunDir?: string;
+    /** Recorded in the merged report metadata purely for provenance. */
+    initialReportSourcePath?: string;
+    healReportSourcePath?: string;
+}
+export declare function mergeReports(params: MergeReportsParams): DonobuReport | null;
+export declare function buildTestKey(file?: string, projectName?: string, title?: string): string;
+//# sourceMappingURL=merge.d.ts.map

package/dist/esm/reporter/merge.js

@@ -0,0 +1,229 @@
+"use strict";
+/**
+ * @fileoverview Pure in-memory merge of two `DonobuReport`s.
+ *
+ * Combines the initial Playwright run and an auto-heal rerun into a single
+ * report that carries both attempts and annotates any test whose outcome
+ * flipped from failing → passing as `self-healed`. The result is destined for
+ * the HTML renderer (and, for back-compat, the on-disk Playwright JSON that
+ * downstream dashboards consume).
+ *
+ * This module intentionally owns zero I/O. Callers load the reports off disk,
+ * call `mergeReports`, then persist / relocate attachments / re-render as
+ * needed. Keeping the merge pure makes it trivial to test and reason about.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeReports = mergeReports;
+exports.buildTestKey = buildTestKey;
+function mergeReports(params) {
+    const { initialReport, healReport } = params;
+    if (!initialReport && !healReport) {
+        return null;
+    }
+    // Clone so we never mutate either input.
+    const combined = JSON.parse(JSON.stringify(initialReport ?? healReport));
+    const initialIndex = indexReport(initialReport);
+    const combinedIndex = indexReport(combined);
+    const healIndex = indexReport(healReport);
+    const healedKeys = new Set();
+    if (healReport) {
+        const processedHealEntries = new Set();
+        const processHealEntry = (healEntry) => {
+            const key = buildTestKey(healEntry.suite.file, healEntry.test.projectName, healEntry.test.title);
+            let combinedEntry = (healEntry.test.testId
+                ? combinedIndex.byId.get(healEntry.test.testId)
+                : undefined) ??
+                combinedIndex.byKey.get(key) ??
+                null;
+            if (!combinedEntry) {
+                combinedEntry = insertTestIntoReport(combined, healEntry);
+                if (healEntry.test.testId) {
+                    combinedIndex.byId.set(healEntry.test.testId, combinedEntry);
+                }
+                combinedIndex.byKey.set(key, combinedEntry);
+            }
+            const originalEntry = (healEntry.test.testId
+                ? initialIndex.byId.get(healEntry.test.testId)
+                : undefined) ??
+                initialIndex.byKey.get(key) ??
+                null;
+            const combinedTest = combinedEntry.test;
+            if (healEntry.test.results?.length) {
+                combinedTest.results = [
+                    ...(combinedTest.results ?? []),
+                    ...healEntry.test.results,
+                ];
+            }
+            if (healEntry.test.status !== undefined) {
+                combinedTest.status = healEntry.test.status;
+            }
+            if (healEntry.test.outcome !== undefined) {
+                combinedTest.outcome = healEntry.test.outcome;
+            }
+            const originalStatus = originalEntry
+                ? getFinalResultStatus(originalEntry.test)
+                : undefined;
+            const healStatus = getFinalResultStatus(healEntry.test);
+            if (healStatus === 'passed' &&
+                originalStatus &&
+                originalStatus !== 'passed') {
+                combinedTest.annotations = combinedTest.annotations ?? [];
+                if (!combinedTest.annotations.some((annotation) => annotation.type === 'self-healed')) {
+                    combinedTest.annotations.push({
+                        type: 'self-healed',
+                        description: 'Automatically healed by Donobu auto-heal rerun after applying treatment plan.',
+                    });
+                }
+                combinedTest.donobuStatus = 'healed';
+                healedKeys.add(key);
+            }
+        };
+        const iterateEntries = (entries) => {
+            for (const [, healEntry] of entries) {
+                if (processedHealEntries.has(healEntry)) {
+                    continue;
+                }
+                processedHealEntries.add(healEntry);
+                processHealEntry(healEntry);
+            }
+        };
+        iterateEntries(healIndex.byId);
+        iterateEntries(healIndex.byKey);
+    }
+    if (params.healSucceeded && healedKeys.size === 0) {
+        params.healedTests.forEach((descriptor) => {
+            // Descriptors must arrive with `testCase.file` already normalized to the
+            // same form that suite.file has in the reports — the caller owns path
+            // normalization because it has access to the CWD the run was launched in.
+            const key = buildTestKey(descriptor.testCase.file, descriptor.testCase.projectName, descriptor.testCase.title);
+            const entry = combinedIndex.byKey.get(key);
+            if (entry) {
+                entry.test.annotations = entry.test.annotations ?? [];
+                if (!entry.test.annotations.some((annotation) => annotation.type === 'self-healed')) {
+                    entry.test.annotations.push({
+                        type: 'self-healed',
+                        description: 'Automatically healed by Donobu auto-heal rerun after applying treatment plan.',
+                    });
+                }
+                entry.test.donobuStatus = 'healed';
+                healedKeys.add(key);
+            }
+        });
+    }
+    combined.stats = computeReportStats(combined);
+    const mergedMetadata = {
+        ...(combined.metadata ?? {}),
+        donobuMergedReport: true,
+        mergedAtIso: new Date().toISOString(),
+        sources: {
+            initial: params.initialReportSourcePath ?? null,
+            autoHeal: params.healReportSourcePath ?? null,
+        },
+        ...(params.triageRunDir ? { triageRunDir: params.triageRunDir } : {}),
+        donobuHealedTests: Array.from(healedKeys.values()),
+    };
+    combined.metadata = mergedMetadata;
+    return combined;
+}
+// Playwright does not reliably expose stable IDs across reports; fall back to
+// a composite key. Exported so the orchestrator can build matching keys for
+// heal descriptors when needed.
+function buildTestKey(file, projectName, title) {
+    return [file ?? 'unknown-file', projectName ?? 'default', title ?? '']
+        .map((segment) => segment.toString())
+        .join('::');
+}
+function getFinalResultStatus(test) {
+    if (!test) {
+        return undefined;
+    }
+    return test.results?.at?.(-1)?.status ?? test.status;
+}
+function indexReport(report) {
+    const byId = new Map();
+    const byKey = new Map();
+    if (!report?.suites) {
+        return { byId, byKey };
+    }
+    report.suites.forEach((suite) => {
+        suite.specs?.forEach((spec) => {
+            spec.tests?.forEach((test) => {
+                const entry = { suite, spec, test };
+                if (test.testId) {
+                    byId.set(test.testId, entry);
+                }
+                const key = buildTestKey(suite.file, test.projectName, test.title);
+                byKey.set(key, entry);
+            });
+        });
+    });
+    return { byId, byKey };
+}
+function insertTestIntoReport(report, entry) {
+    const suites = report.suites ?? [];
+    let suite = suites.find((candidate) => candidate.file === entry.suite.file);
+    if (!suite) {
+        suite = JSON.parse(JSON.stringify(entry.suite));
+        suite.specs = [];
+        report.suites = [...suites, suite];
+    }
+    let spec = suite.specs.find((candidate) => candidate.title === entry.spec.title);
+    if (!spec) {
+        spec = JSON.parse(JSON.stringify(entry.spec));
+        spec.tests = [];
+        suite.specs.push(spec);
+    }
+    const testClone = JSON.parse(JSON.stringify(entry.test));
+    spec.tests.push(testClone);
+    return { suite, spec, test: testClone };
+}
+function computeReportStats(report) {
+    let expected = 0;
+    let unexpected = 0;
+    let skipped = 0;
+    let flaky = 0;
+    let total = 0;
+    let duration = 0;
+    if (!report?.suites) {
+        return report?.stats ?? {};
+    }
+    report.suites.forEach((suite) => {
+        suite.specs?.forEach((spec) => {
+            spec.tests?.forEach((test) => {
+                total += 1;
+                const finalResult = test.results?.at(-1);
+                if (finalResult?.duration) {
+                    duration += finalResult.duration;
+                }
+                const status = finalResult?.status ?? test.status;
+                switch (status) {
+                    case 'passed':
+                        expected += 1;
+                        break;
+                    case 'skipped':
+                        skipped += 1;
+                        break;
+                    case 'flaky':
+                        flaky += 1;
+                        break;
+                    case 'failed':
+                    case 'timedOut':
+                    case 'interrupted':
+                        unexpected += 1;
+                        break;
+                    default:
+                        unexpected += 1;
+                }
+            });
+        });
+    });
+    return {
+        expected,
+        unexpected,
+        flaky,
+        skipped,
+        duration,
+        total,
+    };
+}
+//# sourceMappingURL=merge.js.map

package/dist/esm/reporter/model.d.ts

@@ -0,0 +1,101 @@
+/**
+ * @fileoverview Canonical Donobu test-report model.
+ *
+ * This is the single in-memory / on-disk shape shared between the reporter,
+ * the auto-heal orchestrator, the merge step, and the HTML renderer. It is a
+ * Playwright-JSON superset with explicit Donobu fields: downstream tools that
+ * only understand Playwright JSON continue to work because unknown fields are
+ * ignored.
+ *
+ * The file is intentionally loose about the inner Playwright shape (`unknown`
+ * at the boundary, `any` inside the renderer) — the goal here is to give every
+ * consumer one type to import and one filename to look for on disk, not to
+ * retype the whole Playwright reporter surface.
+ */
+/**
+ * Filename the reporter writes into each run's Playwright output directory.
+ * The auto-heal orchestrator looks for this file (in both the initial run's
+ * output dir and the heal-run's staging dir) to drive the merge + re-render.
+ *
+ * Internal contract only — not a public artifact and not guaranteed to stay
+ * stable across Donobu versions.
+ */
+export declare const DONOBU_REPORT_STATE_FILENAME = ".donobu-report-state.json";
+/**
+ * Per-format output record written by each Donobu reporter into the shared
+ * state file. The auto-heal orchestrator reads this map after merging two
+ * runs and re-renders whichever formats the user has configured, landing each
+ * result at the same path the reporter originally chose.
+ */
+export interface DonobuReportOutputs {
+    html?: {
+        outputFile: string;
+    };
+    markdown?: {
+        outputFile: string;
+    };
+    /**
+     * Slack-specific configuration is read from environment variables
+     * (`DONOBU_SLACK_WEBHOOK_URL`, `DONOBU_REPORT_URL`) — see the `slack.ts`
+     * reporter docs — so the only thing tracked per-output is where the
+     * payload was written.
+     */
+    slack?: {
+        outputFile: string;
+    };
+}
+export interface DonobuReportMetadata {
+    /** True on reports that are the result of merging an initial + heal run. */
+    donobuMergedReport?: boolean;
+    mergedAtIso?: string;
+    sources?: {
+        initial?: string | null;
+        autoHeal?: string | null;
+    };
+    /** Absolute path to the triage run directory that produced the plans/evidence. */
+    triageRunDir?: string;
+    /** Composite keys (`file::projectName::title`) of tests that auto-heal repaired. */
+    donobuHealedTests?: string[];
+    /**
+     * Per-format output paths recorded by each configured Donobu reporter. The
+     * orchestrator iterates this to regenerate every output after the auto-heal
+     * merge.
+     */
+    donobuOutputs?: DonobuReportOutputs;
+    [key: string]: unknown;
+}
+/**
+ * Donobu's canonical test-report shape. Produced by the reporter, merged by
+ * `mergeReports`, rendered by `renderHtml`. Suites / specs / tests / results
+ * are left as `unknown[]` here and walked with `any` inside the renderer —
+ * the renderer already tolerates the full breadth of Playwright's JSON.
+ *
+ * Triage data (treatment plans, failure evidence) is loaded separately and
+ * passed alongside a `DonobuReport` to the renderer — it is not part of the
+ * serialized model.
+ */
+export interface DonobuReport {
+    suites?: unknown[];
+    stats?: unknown;
+    config?: unknown;
+    errors?: unknown[];
+    metadata?: DonobuReportMetadata;
+    [key: string]: unknown;
+}
+/**
+ * A test the orchestrator has designated as healed (used to annotate the
+ * merged report when the heal-run didn't expose the test under a matching key).
+ *
+ * `TPlan` is generic so callers that have a stronger type for the treatment
+ * plan (e.g. a Zod-inferred type) can preserve it; the merge step itself only
+ * reads `testCase`, so `unknown` is a safe default for the model's boundary.
+ */
+export interface HealedTestDescriptor<TPlan = unknown> {
+    plan: TPlan;
+    testCase: {
+        title?: string;
+        file?: string;
+        projectName?: string;
+    };
+}
+//# sourceMappingURL=model.d.ts.map

package/dist/esm/reporter/model.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * @fileoverview Canonical Donobu test-report model.
+ *
+ * This is the single in-memory / on-disk shape shared between the reporter,
+ * the auto-heal orchestrator, the merge step, and the HTML renderer. It is a
+ * Playwright-JSON superset with explicit Donobu fields: downstream tools that
+ * only understand Playwright JSON continue to work because unknown fields are
+ * ignored.
+ *
+ * The file is intentionally loose about the inner Playwright shape (`unknown`
+ * at the boundary, `any` inside the renderer) — the goal here is to give every
+ * consumer one type to import and one filename to look for on disk, not to
+ * retype the whole Playwright reporter surface.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DONOBU_REPORT_STATE_FILENAME = void 0;
+/**
+ * Filename the reporter writes into each run's Playwright output directory.
+ * The auto-heal orchestrator looks for this file (in both the initial run's
+ * output dir and the heal-run's staging dir) to drive the merge + re-render.
+ *
+ * Internal contract only — not a public artifact and not guaranteed to stay
+ * stable across Donobu versions.
+ */
+exports.DONOBU_REPORT_STATE_FILENAME = '.donobu-report-state.json';
+//# sourceMappingURL=model.js.map

package/dist/{cli/playwright-json-to-html.d.ts → esm/reporter/render.d.ts}

@@ -1,18 +1,13 @@
-#!/usr/bin/env node
 /**
- * @fileoverview Playwright JSON Report to HTML Report Converter
+ * @fileoverview Donobu HTML report renderer.
  *
- * Converts Playwright JSON test reports (optionally enriched with Donobu triage
- * data) into a polished, self-contained HTML report for test writers, maintainers,
- * and debuggers.
- *
- * @usage
- * ```bash
- * npm exec playwright-json-to-html report.json -o report.html
- * npm exec playwright-json-to-html report.json --triage-dir ./donobu-triage/run-id/ -o report.html
- * cat merged-report.json | npx playwright-json-to-html --triage-dir ./triage/ -o report.html
- * ```
+ * Pure library that turns a `DonobuReport` (Playwright-JSON superset with
+ * optional triage data) into a self-contained HTML document. No filesystem
+ * writes, no CLI arg parsing, no environment variable reads — callers (the
+ * reporter and the auto-heal orchestrator) own I/O.
  */
+import type { DonobuReport } from './model';
+export declare function stripAnsi(str: string): string;
 interface TreatmentPlanRecord {
     generatedAtIso?: string;
     plan: {
@@ -145,6 +140,6 @@ export interface TriageData {
     evidence: FailureEvidenceRecord[];
 }
 export declare function loadTriageData(triageDir: string): TriageData;
-export declare function generateHtml(jsonData: any, triage: TriageData, outputDir: string | null): string;
+export declare function renderHtml(report: DonobuReport, triage: TriageData, outputDir: string | null): string;
 export {};
-//# sourceMappingURL=playwright-json-to-html.d.ts.map
+//# sourceMappingURL=render.d.ts.map