flake-ledger 0.0.0-stage → 0.1.1

package/bin/flake-ledger.mjs

@@ -0,0 +1,385 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync } from 'node:fs';
+import { scanRuns, ScanError } from '../lib/scan.mjs';
+import {
+  FLAKY_CLASSIFICATIONS,
+  flakyTests,
+  formatExplain,
+  formatTable,
+  toJson,
+} from '../lib/report.mjs';
+
+const VERSION = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+).version;
+
+const USAGE = `flake-ledger: rank flaky tests from JUnit XML across CI runs
+
+Usage:
+  flake-ledger scan <runs-dir> [options]
+  flake-ledger explain <runs-dir> <test-id> [--json]
+  flake-ledger --help
+  flake-ledger --version
+
+Scan options:
+  --json, -j              print machine-readable JSON instead of a table
+  --top N                 show only the N highest-ranked tests
+  --quarantine <file>     write the ids of flaky tests, one per line
+  --fail-on <rate>        exit 1 when a flaky test's unstable rate is >= rate
+  --min-runs <n>          only fail on tests seen in at least n runs (default: 1)
+  --group-by <mode>       auto (default), file, or parent
+
+Layout:
+  runs/<run-id>/<shard>.xml merges every XML in that run directory (shards)
+  runs/<run-id>.xml         each XML directly under runs-dir is its own run
+  runs/shard-1.xml          explicit shard names directly under runs-dir merge
+  runs/run-3-shard-1/*.xml  shard-named run directories merge into run-3
+
+MVP features:
+  - scan recursively parses every JUnit XML, merges sharded files, and
+    collapses repeated attempts into one record per classname::name.
+  - Classifies cross-run flake, passed-on-retry (Surefire flakyFailure /
+    rerunFailure, retry attributes, repeated testcases), always-failing, and
+    stable.
+  - Prints a table ranked by a 95% Wilson lower bound on unstable rate, with
+    --json and --top N for machines.
+  - --quarantine <file> writes flaky-only test ids; explain prints the per-run
+    timeline with file paths and failure messages.
+  - --fail-on <rate> --min-runs <n> makes CI exit 1 when a flaky test crosses
+    the threshold; the default stays report-only.
+`;
+
+class CliError extends Error {
+  constructor(message, code = 2) {
+    super(message);
+    this.name = 'CliError';
+    this.code = code;
+  }
+}
+
+class HelpRequest extends Error {}
+class VersionRequest extends Error {}
+
+function requireValue(argv, index, option, inline) {
+  if (inline !== undefined) {
+    if (inline === '') throw new CliError(`option ${option} needs a value`);
+    return { value: inline, index };
+  }
+  const value = argv[index + 1];
+  if (value === undefined || value.startsWith('-')) {
+    throw new CliError(`option ${option} needs a value`);
+  }
+  return { value, index: index + 1 };
+}
+
+function integerValue(value, option, minimum) {
+  if (!/^\d+$/.test(String(value))) throw new CliError(`option ${option} needs an integer`);
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < minimum) {
+    throw new CliError(`option ${option} must be >= ${minimum}`);
+  }
+  return parsed;
+}
+
+function rateValue(value, option) {
+  const raw = String(value).trim();
+  let parsed;
+  if (raw.endsWith('%')) parsed = Number(raw.slice(0, -1)) / 100;
+  else parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    throw new CliError(`option ${option} needs a rate between 0 and 1 (or a percentage)`);
+  }
+  if (parsed > 1 && parsed <= 100) parsed /= 100;
+  if (parsed > 1) throw new CliError(`option ${option} needs a rate between 0 and 1`);
+  return parsed;
+}
+
+function splitOption(arg) {
+  const equals = arg.indexOf('=');
+  if (equals === -1) return { name: arg, inline: undefined };
+  return { name: arg.slice(0, equals), inline: arg.slice(equals + 1) };
+}
+
+function parseGroupBy(value) {
+  const mode = String(value).toLowerCase();
+  if (mode === 'auto' || mode === 'dir' || mode === 'directory') return 'auto';
+  if (mode === 'file' || mode === 'each-file') return 'file';
+  if (mode === 'parent' || mode === 'folder') return 'parent';
+  throw new CliError('option --group-by must be auto, file, or parent');
+}
+
+function parseScanArgs(argv) {
+  const options = {
+    json: false,
+    top: null,
+    quarantine: null,
+    failOn: null,
+    minRuns: 1,
+    groupBy: 'auto',
+  };
+  const positionals = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--') {
+      positionals.push(...argv.slice(index + 1));
+      break;
+    }
+    if (arg === '-h' || arg === '--help') throw new HelpRequest();
+    if (arg === '-v' || arg === '--version') throw new VersionRequest();
+    if (!arg.startsWith('-') || arg === '-') {
+      positionals.push(arg);
+      continue;
+    }
+
+    const { name, inline } = splitOption(arg);
+    if (name === '--json' || name === '-j') {
+      if (inline !== undefined) throw new CliError('option --json does not take a value');
+      options.json = true;
+    } else if (name === '--top') {
+      const consumed = requireValue(argv, index, name, inline);
+      index = consumed.index;
+      options.top = integerValue(consumed.value, name, 0);
+    } else if (name === '--quarantine') {
+      const consumed = requireValue(argv, index, name, inline);
+      index = consumed.index;
+      options.quarantine = consumed.value;
+    } else if (name === '--fail-on') {
+      const consumed = requireValue(argv, index, name, inline);
+      index = consumed.index;
+      options.failOn = rateValue(consumed.value, name);
+    } else if (name === '--min-runs') {
+      const consumed = requireValue(argv, index, name, inline);
+      index = consumed.index;
+      options.minRuns = integerValue(consumed.value, name, 0);
+    } else if (name === '--group-by') {
+      const consumed = requireValue(argv, index, name, inline);
+      index = consumed.index;
+      options.groupBy = parseGroupBy(consumed.value);
+    } else {
+      throw new CliError(`unknown option ${arg}`);
+    }
+  }
+
+  if (positionals.length !== 1) {
+    throw new CliError('scan needs exactly one <runs-dir>');
+  }
+  options.runsDir = positionals[0];
+  return options;
+}
+
+function parseExplainArgs(argv) {
+  const options = { json: false, groupBy: 'auto' };
+  const positionals = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--') {
+      positionals.push(...argv.slice(index + 1));
+      break;
+    }
+    if (arg === '-h' || arg === '--help') throw new HelpRequest();
+    if (arg === '-v' || arg === '--version') throw new VersionRequest();
+    if (!arg.startsWith('-') || arg === '-') {
+      positionals.push(arg);
+      continue;
+    }
+
+    const { name, inline } = splitOption(arg);
+    if (name === '--json' || name === '-j') {
+      if (inline !== undefined) throw new CliError('option --json does not take a value');
+      options.json = true;
+    } else if (name === '--group-by') {
+      const consumed = requireValue(argv, index, name, inline);
+      index = consumed.index;
+      options.groupBy = parseGroupBy(consumed.value);
+    } else if (name === '--top') {
+      // Accepted for symmetry with scan; explain always prints one test.
+      const consumed = requireValue(argv, index, name, inline);
+      index = consumed.index;
+      integerValue(consumed.value, name, 0);
+    } else {
+      throw new CliError(`unknown option ${arg}`);
+    }
+  }
+
+  if (positionals.length !== 2) {
+    throw new CliError('explain needs a <runs-dir> and a test id');
+  }
+  options.runsDir = positionals[0];
+  options.query = positionals[1];
+  return options;
+}
+
+function printWarnings(warnings) {
+  for (const warning of warnings) {
+    process.stderr.write(`warning: ${warning.message}\n`);
+  }
+}
+
+function writeQuarantine(file, ids) {
+  const body = ids.length > 0 ? `${ids.join('\n')}\n` : '';
+  writeFileSync(file, body, 'utf8');
+}
+
+function runScan(options) {
+  const result = scanRuns(options.runsDir, { groupBy: options.groupBy });
+  printWarnings(result.warnings);
+
+  const shown = options.top === null ? result.tests : result.tests.slice(0, options.top);
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(toJson(result, { tests: shown, version: VERSION }), null, 2)}\n`);
+  } else if (result.files.length === 0) {
+    process.stdout.write(`No JUnit XML files found under ${result.runsDir}.\n`);
+  } else if (result.tests.length === 0) {
+    process.stdout.write(
+      `No testcases found in ${result.files.length} XML file${
+        result.files.length === 1 ? '' : 's'
+      } under ${result.runsDir}.\n`,
+    );
+  } else {
+    process.stdout.write(
+      `${formatTable(shown, {
+        totals: result.totals,
+        totalTests: result.tests.length,
+      })}\n`,
+    );
+  }
+
+  let exitCode = 0;
+  if (options.quarantine) {
+    const ids = flakyTests(result.tests).map((test) => test.id);
+    try {
+      writeQuarantine(options.quarantine, ids);
+      process.stderr.write(
+        `wrote ${ids.length} flaky test id${ids.length === 1 ? '' : 's'} to ${options.quarantine}\n`,
+      );
+    } catch (error) {
+      process.stderr.write(`flake-ledger: cannot write quarantine file: ${error.message}\n`);
+      exitCode = 2;
+    }
+  }
+
+  if (options.failOn !== null) {
+    const offending = result.tests.filter(
+      (test) =>
+        FLAKY_CLASSIFICATIONS.has(test.classification) &&
+        test.eligibleRuns >= options.minRuns &&
+        test.unstableRate >= options.failOn,
+    );
+    if (offending.length > 0) {
+      for (const test of offending) {
+        process.stderr.write(
+          `flaky: ${test.id} unstable in ${test.unstableRuns}/${test.eligibleRuns} runs ` +
+            `(${(test.unstableRate * 100).toFixed(1)}%) >= ${(options.failOn * 100).toFixed(1)}%\n`,
+        );
+      }
+      process.stderr.write(
+        `flake-ledger: ${offending.length} flaky test${
+          offending.length === 1 ? '' : 's'
+        } crossed --fail-on ${options.failOn}\n`,
+      );
+      if (exitCode === 0) exitCode = 1;
+    }
+  }
+
+  return exitCode;
+}
+
+function findTest(result, query) {
+  const exact = result.tests.find((test) => test.id === query);
+  if (exact) return { test: exact, matches: [exact] };
+
+  const matches = result.tests.filter(
+    (test) =>
+      test.name === query ||
+      test.classname === query ||
+      test.id.endsWith(`::${query}`) ||
+      test.id.includes(query),
+  );
+  return { test: matches.length === 1 ? matches[0] : null, matches };
+}
+
+function runExplain(options) {
+  const result = scanRuns(options.runsDir, { groupBy: options.groupBy });
+  printWarnings(result.warnings);
+  const { test, matches } = findTest(result, options.query);
+  if (!test) {
+    if (matches.length === 0) {
+      process.stderr.write(`flake-ledger: no test matched ${JSON.stringify(options.query)}\n`);
+    } else {
+      process.stderr.write(
+        `flake-ledger: ${JSON.stringify(options.query)} matched ${matches.length} tests:\n` +
+          matches
+            .slice(0, 20)
+            .map((match) => `  ${match.id}`)
+            .join('\n') +
+          `${matches.length > 20 ? '\n  ...' : ''}\n`,
+      );
+    }
+    return 1;
+  }
+
+  if (options.json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          tool: 'flake-ledger',
+          version: VERSION,
+          runsDir: result.runsDir,
+          test,
+          warnings: result.warnings,
+        },
+        null,
+        2,
+      )}\n`,
+    );
+  } else {
+    process.stdout.write(`${formatExplain(test)}\n`);
+  }
+  return 0;
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  const command = argv[0];
+  if (command === '--help' || command === '-h' || command === 'help') {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  if (command === '--version' || command === '-v') {
+    process.stdout.write(`${VERSION}\n`);
+    return 0;
+  }
+
+  try {
+    if (command === 'scan') return runScan(parseScanArgs(argv.slice(1)));
+    if (command === 'explain') return runExplain(parseExplainArgs(argv.slice(1)));
+    throw new CliError(`unknown command ${JSON.stringify(command)}; try --help`);
+  } catch (error) {
+    if (error instanceof HelpRequest) {
+      process.stdout.write(USAGE);
+      return 0;
+    }
+    if (error instanceof VersionRequest) {
+      process.stdout.write(`${VERSION}\n`);
+      return 0;
+    }
+    if (error instanceof ScanError) {
+      process.stderr.write(`flake-ledger: ${error.message}\n`);
+      return 2;
+    }
+    if (error instanceof CliError) {
+      process.stderr.write(`flake-ledger: ${error.message}\n`);
+      return error.code;
+    }
+    throw error;
+  }
+}
+
+process.exitCode = main();

package/examples/README.md

@@ -0,0 +1,102 @@
+# flake-ledger example
+
+Five CI runs, one JUnit XML report per run, checked in so you can see the ledger
+without installing anything first. The reports are small but exercise the
+interesting cases: a test that failed and passed on retry, two tests that failed
+in some runs and passed in others, a stable test, and a skipped test.
+
+## Run it
+
+From the repository root:
+
+```sh
+npm run example
+```
+
+or directly:
+
+```sh
+node examples/demo.mjs
+```
+
+The script runs the real CLI against `examples/runs`, prints four steps, and
+exits nonzero if any of the numbers below stop matching. It has no
+dependencies and does not write outside a temporary directory.
+
+You can also run the commands yourself:
+
+```sh
+node bin/flake-ledger.mjs scan examples/runs
+node bin/flake-ledger.mjs explain examples/runs 'com.example.CheckoutTest::appliesCoupon'
+node bin/flake-ledger.mjs scan examples/runs --json --top 3
+```
+
+## What is in the fixture
+
+```text
+examples/runs/
+  run-01/results.xml
+  run-02/results.xml
+  run-03/results.xml
+  run-04/results.xml
+  run-05/results.xml
+```
+
+Each file is a separate run because it sits in its own directory. Every run has
+the same five tests:
+
+| Test | Runs | Attempts | Unstable | Pass-on-retry | Classification |
+| --- | ---: | ---: | ---: | ---: | --- |
+| `com.example.LoginTest::rejectsExpiredToken` | 5 | 5 | 2 | 0 | cross-run flake |
+| `com.example.SearchTest::filtersByPrice` | 5 | 5 | 2 | 0 | cross-run flake |
+| `com.example.CheckoutTest::appliesCoupon` | 5 | 7 | 2 | 2 | passed-on-retry |
+| `com.example.CartTest::addsItem` | 5 | 5 | 0 | 0 | stable |
+| `com.example.ReportTest::exportsCsv` | 5 | 5 | 0 | 0 | skipped |
+
+`run-01` and `run-03` contain Surefire-style `<flakyFailure>` evidence for
+`CheckoutTest::appliesCoupon`: the report records the failed attempt and the
+pass that followed it. That is why the test has seven attempts across five runs
+and stays visible after the run went green.
+
+## What to look for
+
+`scan` ranks by a 95% Wilson lower bound on the unstable rate, so the two
+cross-run flakes and the passed-on-retry test all score `0.118` from `2/5`
+unstable runs, and the stable/skipped tests score `0.000`:
+
+```text
+TEST ID                                     RUNS  ATTEMPTS  UNSTABLE  PASS-ON-RETRY  FAILED  RATE   SCORE  CLASS
+com.example.LoginTest::rejectsExpiredToken  5     5         2         0              2       40.0%  0.118  cross-run flake
+com.example.SearchTest::filtersByPrice      5     5         2         0              2       40.0%  0.118  cross-run flake
+com.example.CheckoutTest::appliesCoupon     5     7         2         2              0       40.0%  0.118  passed-on-retry
+com.example.CartTest::addsItem              5     5         0         0              0       0.0%   0.000  stable
+com.example.ReportTest::exportsCsv          5     5         0         0              0       0.0%   0.000  skipped
+
+5 runs, 5 tests, 27 attempts, 5 XML files.
+```
+
+`explain` shows why `appliesCoupon` is not just a passing test. Run it yourself
+to see the per-run timeline, including the failed attempt, its assertion
+message, and the retried pass.
+
+The demo's third step writes the quarantine list and applies the CI gate:
+
+```sh
+node bin/flake-ledger.mjs scan examples/runs \
+  --quarantine flaky.txt --fail-on 0.2 --min-runs 5
+```
+
+Three tests cross 20%, so the command exits 1; `flaky.txt` contains their ids.
+Without `--fail-on` the same scan is report-only and exits 0.
+
+## Use your own reports
+
+Point the CLI at the directory where your CI downloads JUnit XML. The first
+directory below the path is treated as one run:
+
+```sh
+node bin/flake-ledger.mjs scan path/to/runs
+```
+
+If your reports are flat files or sharded differently, see the layouts in the
+main [README](../README.md#input-layout) and use `--group-by`.

package/examples/demo.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+// Run the real flake-ledger CLI against the five-run JUnit fixture in
+// examples/runs and check the numbers the README claims.
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const bin = path.join(repoRoot, 'bin', 'flake-ledger.mjs');
+const runsDir = path.join(repoRoot, 'examples', 'runs');
+const runsArg = 'examples/runs';
+
+function quote(part) {
+  return /^[A-Za-z0-9_./:=@%+-]+$/.test(part) ? part : JSON.stringify(part);
+}
+
+function display(args) {
+  return ['node bin/flake-ledger.mjs', ...args.map(quote)].join(' ');
+}
+
+function run(args) {
+  const result = spawnSync(process.execPath, [bin, ...args], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+  });
+  if (result.error) throw result.error;
+  return result;
+}
+
+function check(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function show(title, args, result, options = {}) {
+  console.log(`\n${title}`);
+  console.log(`$ ${display(args)}`);
+  if (options.stdout !== false) process.stdout.write(result.stdout);
+  if (options.stderr !== false) process.stderr.write(result.stderr);
+}
+
+const temporary = mkdtempSync(path.join(tmpdir(), 'flake-ledger-example-'));
+const quarantineFile = path.join(temporary, 'flaky.txt');
+
+try {
+  console.log('flake-ledger runnable example');
+  console.log(`fixtures: ${runsArg} (5 CI runs, one JUnit XML report per run)`);
+  console.log('This runs the checked-in CLI, not a mock.');
+
+  // 1. The ranked ledger.
+  const scanArgs = ['scan', runsArg];
+  const scan = run(scanArgs);
+  check(scan.status === 0, `scan exited ${scan.status}: ${scan.stderr}`);
+  show('1. Rank every test across the five runs', scanArgs, scan);
+  check(
+    scan.stdout.includes(
+      'com.example.CheckoutTest::appliesCoupon     5     7         2         2              0       40.0%  0.118  passed-on-retry',
+    ),
+    'scan table is missing the passed-on-retry row',
+  );
+  check(
+    scan.stdout.includes('5 runs, 5 tests, 27 attempts, 5 XML files.'),
+    'scan totals changed',
+  );
+
+  // 2. The timeline that produced the score.
+  const explainArgs = [
+    'explain',
+    runsArg,
+    'com.example.CheckoutTest::appliesCoupon',
+  ];
+  const explain = run(explainArgs);
+  check(explain.status === 0, `explain exited ${explain.status}: ${explain.stderr}`);
+  show("2. Show one test's per-run timeline", explainArgs, explain);
+  check(
+    explain.stdout.includes('run run-01  passed-on-retry  2 attempts'),
+    'explain is missing the run-01 retry',
+  );
+  check(
+    explain.stdout.includes('#1 failed') &&
+      explain.stdout.includes('expected 10% discount, got 0') &&
+      explain.stdout.includes('#2 passed') &&
+      explain.stdout.includes('(retried)'),
+    'explain is missing the failed-then-passed attempt pair',
+  );
+
+  // 3. The CI gate: write the quarantine list and fail on a crossed threshold.
+  const gateArgs = [
+    'scan',
+    runsArg,
+    '--quarantine',
+    quarantineFile,
+    '--fail-on',
+    '0.2',
+    '--min-runs',
+    '5',
+  ];
+  const gate = run(gateArgs);
+  check(gate.status === 1, `gate should exit 1, got ${gate.status}: ${gate.stderr}`);
+  show('3. Gate CI on the same ledger', gateArgs, gate, { stdout: false });
+  console.log(`exit code 1 (expected: three flaky tests crossed --fail-on 0.2)`);
+
+  const quarantined = readFileSync(quarantineFile, 'utf8').trimEnd().split('\n');
+  console.log('\nquarantine file (temporary):');
+  console.log(quarantined.join('\n'));
+  check(
+    quarantined.join('\n') ===
+      [
+        'com.example.LoginTest::rejectsExpiredToken',
+        'com.example.SearchTest::filtersByPrice',
+        'com.example.CheckoutTest::appliesCoupon',
+      ].join('\n'),
+    'quarantine list changed',
+  );
+
+  // 4. Machine-readable totals, and the classifications behind the table.
+  const jsonArgs = ['scan', runsArg, '--json'];
+  const json = run(jsonArgs);
+  check(json.status === 0, `scan --json exited ${json.status}: ${json.stderr}`);
+  console.log('\n4. Check the machine-readable ledger');
+  console.log(`$ ${display(jsonArgs)}`);
+  const ledger = JSON.parse(json.stdout);
+  console.log(`totals: ${JSON.stringify(ledger.totals)}`);
+  check(
+    JSON.stringify(ledger.totals) ===
+      JSON.stringify({ files: 5, runs: 5, tests: 5, attempts: 27 }),
+    `unexpected totals: ${JSON.stringify(ledger.totals)}`,
+  );
+
+  const byId = new Map(ledger.tests.map((test) => [test.id, test]));
+  const checkout = byId.get('com.example.CheckoutTest::appliesCoupon');
+  check(checkout, 'checkout test is missing from JSON');
+  check(checkout.classification === 'passed-on-retry', 'checkout is not passed-on-retry');
+  check(checkout.runs === 5 && checkout.attempts === 7, 'checkout run/attempt counts changed');
+  check(checkout.passedOnRetryRuns === 2, 'checkout retry count changed');
+  check(
+    byId.get('com.example.LoginTest::rejectsExpiredToken').classification === 'cross-run flake',
+    'login test is not a cross-run flake',
+  );
+  check(
+    byId.get('com.example.SearchTest::filtersByPrice').classification === 'cross-run flake',
+    'search test is not a cross-run flake',
+  );
+  check(byId.get('com.example.CartTest::addsItem').classification === 'stable', 'cart test is not stable');
+  check(byId.get('com.example.ReportTest::exportsCsv').classification === 'skipped', 'report test is not skipped');
+
+  console.log(`\nAll checks passed. The ledger above comes from ${runsArg}.`);
+  console.log('Try editing a fixture (or point the CLI at your own runs) and run this again.');
+} catch (error) {
+  console.error(`\nexample failed: ${error.message}`);
+  process.exitCode = 1;
+} finally {
+  rmSync(temporary, { recursive: true, force: true });
+}

package/examples/runs/run-01/results.xml

@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<testsuites>
+  <testsuite name="com.example.CheckoutTest" timestamp="2026-01-05T10:00:00">
+    <testcase classname="com.example.CheckoutTest" name="appliesCoupon">
+      <flakyFailure message="expected 10% discount, got 0">
+        <stackTrace>org.opentest4j.AssertionFailedError: expected 10% discount, got 0
+  at CheckoutTest.appliesCoupon(CheckoutTest.java:42)</stackTrace>
+      </flakyFailure>
+    </testcase>
+  </testsuite>
+  <testsuite name="com.example.LoginTest" timestamp="2026-01-05T10:00:00">
+    <testcase classname="com.example.LoginTest" name="rejectsExpiredToken">
+      <failure message="expected 401, got 200">
+        <stackTrace>org.opentest4j.AssertionFailedError: expected 401, got 200</stackTrace>
+      </failure>
+    </testcase>
+  </testsuite>
+  <testsuite name="com.example.SearchTest" timestamp="2026-01-05T10:00:00">
+    <testcase classname="com.example.SearchTest" name="filtersByPrice"/>
+  </testsuite>
+  <testsuite name="com.example.CartTest" timestamp="2026-01-05T10:00:00">
+    <testcase classname="com.example.CartTest" name="addsItem"/>
+  </testsuite>
+  <testsuite name="com.example.ReportTest" timestamp="2026-01-05T10:00:00">
+    <testcase classname="com.example.ReportTest" name="exportsCsv">
+      <skipped message="CSV export not configured"/>
+    </testcase>
+  </testsuite>
+</testsuites>

package/examples/runs/run-02/results.xml

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<testsuites>
+  <testsuite name="com.example.CheckoutTest" timestamp="2026-01-05T10:10:00">
+    <testcase classname="com.example.CheckoutTest" name="appliesCoupon"/>
+  </testsuite>
+  <testsuite name="com.example.LoginTest" timestamp="2026-01-05T10:10:00">
+    <testcase classname="com.example.LoginTest" name="rejectsExpiredToken"/>
+  </testsuite>
+  <testsuite name="com.example.SearchTest" timestamp="2026-01-05T10:10:00">
+    <testcase classname="com.example.SearchTest" name="filtersByPrice">
+      <failure message="expected price 10, got 12">
+        <stackTrace>org.opentest4j.AssertionFailedError: expected price 10, got 12</stackTrace>
+      </failure>
+    </testcase>
+  </testsuite>
+  <testsuite name="com.example.CartTest" timestamp="2026-01-05T10:10:00">
+    <testcase classname="com.example.CartTest" name="addsItem"/>
+  </testsuite>
+  <testsuite name="com.example.ReportTest" timestamp="2026-01-05T10:10:00">
+    <testcase classname="com.example.ReportTest" name="exportsCsv">
+      <skipped message="CSV export not configured"/>
+    </testcase>
+  </testsuite>
+</testsuites>