fumadocs-test-reports 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shenxianovo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# fumadocs-test-reports
+
+Framework-native test report presenters and shared React UI primitives for Fumadocs.
+
+## Quick start
+
+```tsx
+import { parseTUnitReport } from 'fumadocs-test-reports/tunit';
+import { TUnitReport, TUnitReportLink } from 'fumadocs-test-reports/tunit/ui';
+import input from './run.tunit-report.json';
+
+const report = parseTUnitReport(input);
+
+<TUnitReport report={report} />;
+<TUnitReportLink report={report} href="/docs/reports/run" />;
+```
+
+Install the package in your Fumadocs application:
+
+```sh
+pnpm add fumadocs-test-reports
+```
+
+React 19.2+ and Fumadocs UI 16.16.2+ are peer dependencies. The parser entry does not import React or Fumadocs UI.
+
+Import the stylesheet after your Fumadocs styles:
+
+```css
+@import 'fumadocs-test-reports/css/preset.css';
+```
+
+## Architecture
+
+During 0.x development, changes replace the current API and data model directly. Deprecated APIs and version-dependent compatibility branches are not retained.
+
+```text
+TUnit JSON → parse → TUnit native fields → TUnit presenter → shared UI primitives
+```
+
+Each framework owns its parser, native types and presenter. Shared UI primitives accept display props, such as text, a visual tone or a duration. Future presenters can combine these primitives with their framework-specific traces, steps or artifacts.
+
+Public entries:
+
+- `/tunit`: `parseTUnitReport`, `TUnitParseError` and native `TUnit*` types.
+- `/tunit/ui`: `TUnitReport` and `TUnitReportLink`.
+- `/ui`: `StatusBadge`, `Duration`, `ErrorDetail` and `StdoutPanel`.
+- `/css/preset.css`: report-specific layout and status styles using Fumadocs theme variables.
+
+## Native TUnit data
+
+`parseTUnitReport` accepts decoded `.tunit-report.json` sidecar JSON, schema version 1. It validates the fields consumed by the presenter, then returns the input object unchanged. The caller owns file reads, network requests and routing.
+
+Names and values remain native: `assemblyName`, `groups[].tests`, `displayName`, `output`, `errorOutput`, `exception.innerException`, `retryAttempt`, `spanId` and `parentSpanId`. Unknown fields, arbitrary status strings and explicit null values remain present. The parser adds no fields, defaults or status mappings.
+
+The minimum shape contains `schemaVersion`, `assemblyName`, `groups` and each group's `className` and `tests`. A test requires `id`, `displayName` and `status`. Metadata and optional payloads are checked when supplied. Invalid known fields, duplicate test IDs or unsupported schema versions throw `TUnitParseError`; its `path` identifies the JSON field.
+
+The presenter reads TUnit's supplied `summary` counters. For minimal reports without these counters, it derives display counts from the native tests. Retries remain attempt history within a test. Timestamp text is displayed as supplied, and duration values are milliseconds.
+
+`TUnitReport` provides search, native outcome filters, details, output, retry attempts and a TUnit trace timeline. `selectedTestId` and `onTestSelect` let the host implement permalinks. `TUnitReportLink` embeds a link to the same native report in a document.
+
+The presenter reuses Fumadocs Tabs, Accordion, Card, CodeBlock, Callout and button variants. Custom styles cover the test list, metrics, status badges and trace bars. Native components provide tab keyboard navigation, disclosure controls and code-copy buttons.
+
+Report layout uses container queries: test columns and metrics adapt to the report's available width, including space consumed by a host sidebar or table of contents. Match your Fumadocs layout with its corresponding page components. Spacious and Glass also require their layout styles, imported as `fumadocs-ui/css/generated/spacious.css` or `fumadocs-ui/css/generated/glass.css`.
+
+Use the host's `<DocsPage full>` for a dedicated report page. Spacious's native page width is 760 px by default; `full` sets the limit to 1200 px, while the report adapts to the available space inside it.
+
+Flux in `@fumadocs/base-ui@16.16.2` has a page-container width issue: its centred outer layout can shrink the page when content uses inline-size containment. The workspace example applies a dependency patch that adds `w-full` to Flux's native `main`; it keeps the native page limits and alignment. This patch is not included in the published report package. A host using this affected Flux version needs the same dependency fix. Other demonstrated layouts use their native page configuration directly.
+
+Both support `locale="en"` (default) and `locale="zh"`. Fumadocs layouts and Next.js routing belong to the host application.
+
+## Shared UI primitives
+
+```tsx
+import { StatusBadge, Duration, ErrorDetail, StdoutPanel } from 'fumadocs-test-reports/ui';
+
+<StatusBadge status="failed" tone="danger" />;
+<Duration value={42} />;
+<ErrorDetail message="Expected 400, received 200" stack="at example.test.ts:12" />;
+<StdoutPanel content="Connection refused" title="Standard error" />;
+```
+
+`StatusBadge` displays the caller's text with a visual tone. The presenter decides what a native status means. `Duration` treats a missing or null value as unknown and displays a recorded zero as zero. Error and output components render plain, escaped text; the presenter owns exception nesting and retry semantics.
+
+This version implements TUnit. Additional frameworks will have their own native parsers and presenters. Dashboard, history and cross-framework search are future features.
+
+References: [TUnit's native report model](https://github.com/thomhurst/TUnit/blob/main/src/TUnit.Engine/Reporters/Html/HtmlReportDataModel.cs), [its sidecar writer](https://github.com/thomhurst/TUnit/blob/main/src/TUnit.Engine/Reporters/Aggregation/ReportDataJson.cs), and [Fumadocs OpenAPI's package layout](https://github.com/fuma-nama/fumadocs/tree/dev/packages/openapi).
+
+## Local release
+
+Run the workspace checks from the repository root:
+
+```sh
+pnpm test --run
+pnpm types:check
+pnpm build
+pnpm lint
+pnpm lint:format
+```
+
+Review the public package from `packages/test-reports`:
+
+```sh
+npm publish --dry-run --ignore-scripts
+```
+
+`pnpm pack` rebuilds the package through `prepack`. Published files are limited to `dist`, `css`, the package README, license and manifest. Example reports and test fixtures stay in the repository.
+
+After logging in to npm, publish from `packages/test-reports`:
+
+```sh
+pnpm publish --access public --no-git-checks
+```
+
+The manifest specifies the public npm registry. Publishing requires npm account access and any authentication challenge configured for that account.

package/css/preset.css

@@ -0,0 +1,300 @@
+.ftr-report,
+.ftr-summary,
+.ftr-ui {
+  color: var(--color-fd-foreground);
+  font-size: 0.875rem;
+  line-height: 1.6;
+}
+.ftr-report {
+  width: 100%;
+  min-width: 0;
+  container: ftr-report / inline-size;
+}
+.ftr-run-heading {
+  margin-bottom: 1.25rem;
+}
+.ftr-run-heading h2 {
+  font-size: 1.25rem;
+  font-weight: 600;
+  overflow-wrap: anywhere;
+}
+.ftr-run-meta {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.375rem 1rem;
+  color: var(--color-fd-muted-foreground);
+  font-size: 0.75rem;
+  margin-top: 0.5rem;
+}
+.ftr-metrics {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  border: 1px solid var(--color-fd-border);
+  border-radius: 0.75rem;
+  background: var(--color-fd-card);
+  margin-bottom: 1.5rem;
+  overflow: hidden;
+}
+.ftr-metrics > div {
+  padding: 1rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+  border-inline-end: 1px solid var(--color-fd-border);
+}
+.ftr-metrics > div:last-child {
+  border-inline-end: 0;
+}
+.ftr-metrics span,
+.ftr-metrics small {
+  color: var(--color-fd-muted-foreground);
+  font-size: 0.75rem;
+}
+.ftr-metrics strong {
+  font-size: 1.5rem;
+  font-weight: 600;
+}
+.ftr-toolbar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+  margin-bottom: 0.75rem;
+}
+.ftr-toolbar h3,
+.ftr-detail-heading h3 {
+  font-size: 1rem;
+  font-weight: 600;
+}
+.ftr-toolbar input {
+  font: inherit;
+  border: 1px solid var(--color-fd-border);
+  padding: 0.5rem 0.75rem;
+  border-radius: 0.5rem;
+  background: var(--color-fd-background);
+  color: inherit;
+  width: min(100%, 300px);
+}
+.ftr-toolbar input:focus-visible {
+  outline: 2px solid var(--color-fd-ring);
+  outline-offset: 2px;
+}
+.ftr-filters {
+  display: flex;
+  gap: 0.25rem;
+  flex-wrap: wrap;
+  margin-bottom: 1rem;
+}
+.ftr-filters small {
+  opacity: 0.7;
+  margin-inline-start: 0.375rem;
+}
+.ftr-workspace {
+  display: grid;
+  grid-template-columns: minmax(250px, 0.9fr) minmax(300px, 1.1fr);
+  border: 1px solid var(--color-fd-border);
+  border-radius: 0.75rem;
+  overflow: hidden;
+}
+.ftr-list {
+  border-inline-end: 1px solid var(--color-fd-border);
+  max-height: 700px;
+  overflow: auto;
+}
+.ftr-group {
+  padding: 0.75rem 1rem;
+  background: var(--color-fd-card);
+  border-bottom: 1px solid var(--color-fd-border);
+  font-size: 0.75rem;
+}
+.ftr-group small {
+  display: block;
+  color: var(--color-fd-muted-foreground);
+  overflow-wrap: anywhere;
+}
+.ftr-test {
+  width: 100%;
+  justify-content: start;
+  align-items: center;
+  text-align: start;
+  gap: 0.625rem;
+  padding: 0.875rem;
+  border-radius: 0;
+  border-bottom: 1px solid var(--color-fd-border);
+}
+.ftr-test[aria-pressed='true'] {
+  background: var(--color-fd-accent);
+  box-shadow: inset 2px 0 var(--color-fd-primary);
+}
+.ftr-test-name {
+  flex: 1;
+  min-width: 0;
+  overflow-wrap: anywhere;
+  font-size: 0.8125rem;
+}
+.ftr-test > small {
+  white-space: nowrap;
+  color: var(--color-fd-muted-foreground);
+  font-size: 0.75rem;
+}
+.ftr-badge {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+  font-size: 0.75rem;
+  font-weight: 500;
+  padding: 0.125rem 0.5rem;
+  border-radius: 0.375rem;
+  white-space: nowrap;
+  border: 1px solid color-mix(in srgb, var(--ftr-tone) 40%, transparent);
+  background: color-mix(in srgb, var(--ftr-tone) 10%, transparent);
+  color: var(--color-fd-foreground);
+}
+.ftr-tone-success {
+  --ftr-tone: var(--color-fd-success);
+}
+.ftr-tone-danger {
+  --ftr-tone: var(--color-fd-error);
+}
+.ftr-tone-neutral {
+  --ftr-tone: var(--color-fd-muted-foreground);
+}
+.ftr-tone-info {
+  --ftr-tone: var(--color-fd-info);
+}
+.ftr-detail {
+  min-width: 0;
+}
+.ftr-detail-heading {
+  padding: 1rem;
+}
+.ftr-detail-heading h3 {
+  overflow-wrap: anywhere;
+  margin: 0.5rem 0;
+}
+.ftr-detail-heading > small {
+  color: var(--color-fd-muted-foreground);
+}
+.ftr-detail-tabs {
+  margin: 0;
+  border-radius: 0;
+  border-inline: 0;
+  border-bottom: 0;
+}
+.ftr-fields {
+  display: grid;
+  grid-template-columns: 85px minmax(0, 1fr);
+  gap: 0.75rem;
+  font-size: 0.75rem;
+  margin: 0;
+}
+.ftr-fields dt {
+  color: var(--color-fd-muted-foreground);
+  overflow-wrap: anywhere;
+}
+.ftr-fields dd {
+  margin: 0;
+  overflow-wrap: anywhere;
+}
+.ftr-field {
+  display: contents;
+}
+.ftr-codeblock code {
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  padding-inline: 1rem;
+}
+.ftr-error-message {
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+.ftr-output,
+.ftr-attempts {
+  max-height: 600px;
+  overflow: auto;
+}
+.ftr-attempt {
+  padding: 0.75rem 0;
+  border-bottom: 1px solid var(--color-fd-border);
+}
+.ftr-attempt h4 {
+  display: flex;
+  gap: 0.625rem;
+  align-items: center;
+  font-weight: 500;
+}
+.ftr-traces {
+  max-height: 600px;
+  overflow: auto;
+}
+.ftr-span-heading {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  gap: 0.25rem 0.625rem;
+  width: 100%;
+  text-align: start;
+  font-size: 0.75rem;
+}
+.ftr-span-heading > span {
+  overflow-wrap: anywhere;
+}
+.ftr-span-heading > small {
+  color: var(--color-fd-muted-foreground);
+}
+.ftr-track {
+  grid-column: 1 / -1;
+  display: block;
+  height: 5px;
+  border-radius: 3px;
+  background: var(--color-fd-muted);
+  margin: 0.375rem 0;
+  overflow: hidden;
+}
+.ftr-track span {
+  display: block;
+  height: 100%;
+  min-width: 2px;
+  background: var(--color-fd-primary);
+  opacity: 0.6;
+  border-radius: 3px;
+}
+.ftr-empty {
+  padding: 1rem;
+  color: var(--color-fd-muted-foreground);
+  font-size: 0.875rem;
+}
+.ftr-summary-footer {
+  display: flex;
+  gap: 0.75rem;
+  justify-content: space-between;
+  align-items: center;
+  margin-top: 0.75rem;
+}
+@container ftr-report (max-width: 850px) {
+  .ftr-workspace {
+    grid-template-columns: minmax(0, 1fr);
+  }
+  .ftr-list {
+    border-inline-end: 0;
+    border-bottom: 1px solid var(--color-fd-border);
+    max-height: 350px;
+  }
+}
+@container ftr-report (max-width: 600px) {
+  .ftr-metrics {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+  .ftr-metrics > div:nth-child(2) {
+    border-inline-end: 0;
+  }
+  .ftr-metrics > div:nth-child(-n + 2) {
+    border-bottom: 1px solid var(--color-fd-border);
+  }
+  .ftr-toolbar {
+    align-items: stretch;
+    flex-direction: column;
+  }
+  .ftr-toolbar input {
+    width: 100%;
+  }
+}

package/dist/tunit/index.d.ts

@@ -0,0 +1,3 @@
+import { TUnitAttempt, TUnitException, TUnitKeyValue, TUnitReport, TUnitReportSummary, TUnitSpan, TUnitTestGroup, TUnitTestResult } from "./types.js";
+import { TUnitParseError, parseTUnitReport } from "./parse.js";
+export { type TUnitAttempt, type TUnitException, type TUnitKeyValue, TUnitParseError, type TUnitReport, type TUnitReportSummary, type TUnitSpan, type TUnitTestGroup, type TUnitTestResult, parseTUnitReport };

package/dist/tunit/index.js

@@ -0,0 +1,2 @@
+import { TUnitParseError, parseTUnitReport } from "./parse.js";
+export { TUnitParseError, parseTUnitReport };

package/dist/tunit/parse.d.ts

@@ -0,0 +1,9 @@
+import { TUnitReport } from "./types.js";
+//#region src/tunit/parse.d.ts
+export declare class TUnitParseError extends Error {
+  readonly path: string;
+  constructor(path: string, message: string);
+}
+/** Validate decoded sidecar JSON and return its native structure unchanged. */
+export declare function parseTUnitReport(input: unknown): TUnitReport;
+//#endregion

package/dist/tunit/parse.js

@@ -0,0 +1,180 @@
+//#region src/tunit/parse.ts
+var TUnitParseError = class extends Error {
+	constructor(path, message) {
+		super(`${path}: ${message}`);
+		this.path = path;
+		this.name = "TUnitParseError";
+	}
+};
+function object(value, path) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new TUnitParseError(path, "expected an object");
+	return value;
+}
+function text(value, path, required = false) {
+	if (value == null && !required) return;
+	if (typeof value !== "string") throw new TUnitParseError(path, "expected a string");
+}
+function nonempty(value, path) {
+	text(value, path, true);
+	if (!value.trim()) throw new TUnitParseError(path, "expected a non-empty string");
+}
+function number(value, path, required = false, integer = false) {
+	if (value == null && !required) return;
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || integer && !Number.isSafeInteger(value)) throw new TUnitParseError(path, integer ? "expected a non-negative safe integer" : "expected a finite non-negative number");
+}
+function timestamp(value, path) {
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new TUnitParseError(path, "expected finite epoch milliseconds");
+}
+function strings(value, fields, path) {
+	for (const field of fields) text(value[field], `${path}.${field}`);
+}
+function list(value, path, validate, required = false) {
+	if (value == null && !required) return;
+	if (!Array.isArray(value)) throw new TUnitParseError(path, "expected an array");
+	value.forEach((item, index) => validate(item, `${path}[${index}]`));
+}
+function summary(value, path) {
+	if (value == null) return;
+	const s = object(value, path);
+	for (const field of [
+		"total",
+		"passed",
+		"failed",
+		"skipped",
+		"cancelled",
+		"timedOut",
+		"flaky"
+	]) number(s[field], `${path}.${field}`, true, true);
+}
+function exception(value, path, depth = 0) {
+	if (value == null) return;
+	if (depth > 32) throw new TUnitParseError(path, "exception nesting exceeds 32 levels");
+	const e = object(value, path);
+	strings(e, [
+		"type",
+		"message",
+		"stackTrace"
+	], path);
+	exception(e.innerException, `${path}.innerException`, depth + 1);
+}
+function keyValue(value, path) {
+	const kv = object(value, path);
+	text(kv.key, `${path}.key`, true);
+	text(kv.value, `${path}.value`, true);
+}
+function attempt(value, path) {
+	const a = object(value, path);
+	nonempty(a.status, `${path}.status`);
+	number(a.durationMs, `${path}.durationMs`);
+	strings(a, [
+		"exceptionType",
+		"exceptionMessage",
+		"stackTrace"
+	], path);
+}
+function test(value, path) {
+	const t = object(value, path);
+	for (const field of [
+		"id",
+		"displayName",
+		"status"
+	]) nonempty(t[field], `${path}.${field}`);
+	strings(t, [
+		"methodName",
+		"className",
+		"startTime",
+		"endTime",
+		"output",
+		"errorOutput",
+		"filePath",
+		"sourceRelativePath",
+		"skipReason",
+		"traceId",
+		"spanId"
+	], path);
+	number(t.durationMs, `${path}.durationMs`);
+	for (const field of [
+		"lineNumber",
+		"endLineNumber",
+		"retryAttempt"
+	]) number(t[field], `${path}.${field}`, false, true);
+	exception(t.exception, `${path}.exception`);
+	list(t.categories, `${path}.categories`, (item, p) => text(item, p, true));
+	list(t.customProperties, `${path}.customProperties`, keyValue);
+	list(t.attempts, `${path}.attempts`, attempt);
+	list(t.additionalTraceIds, `${path}.additionalTraceIds`, nonempty);
+}
+function span(value, path) {
+	const s = object(value, path);
+	for (const field of [
+		"traceId",
+		"spanId",
+		"name"
+	]) nonempty(s[field], `${path}.${field}`);
+	strings(s, [
+		"parentSpanId",
+		"spanType",
+		"source",
+		"kind",
+		"status",
+		"statusMessage"
+	], path);
+	timestamp(s.startTimeMs, `${path}.startTimeMs`);
+	number(s.durationMs, `${path}.durationMs`, true);
+	list(s.tags, `${path}.tags`, keyValue);
+	list(s.events, `${path}.events`, (value, p) => {
+		const e = object(value, p);
+		nonempty(e.name, `${p}.name`);
+		timestamp(e.timestampMs, `${p}.timestampMs`);
+		list(e.tags, `${p}.tags`, keyValue);
+	});
+	list(s.links, `${path}.links`, (value, p) => {
+		const link = object(value, p);
+		nonempty(link.traceId, `${p}.traceId`);
+		nonempty(link.spanId, `${p}.spanId`);
+	});
+}
+/** Validate decoded sidecar JSON and return its native structure unchanged. */
+function parseTUnitReport(input) {
+	const r = object(input, "$");
+	if (r.schemaVersion !== 1) throw new TUnitParseError("$.schemaVersion", "expected supported TUnit schema version 1");
+	nonempty(r.assemblyName, "$.assemblyName");
+	strings(r, [
+		"publicationGeneration",
+		"machineName",
+		"timestamp",
+		"tunitVersion",
+		"operatingSystem",
+		"runtimeVersion",
+		"filter",
+		"commitSha",
+		"branch",
+		"pullRequestNumber",
+		"repositorySlug",
+		"artifactUrl"
+	], "$");
+	number(r.totalDurationMs, "$.totalDurationMs");
+	summary(r.summary, "$.summary");
+	const ids = /* @__PURE__ */ new Set();
+	list(r.groups, "$.groups", (value, path) => {
+		const g = object(value, path);
+		nonempty(g.className, `${path}.className`);
+		text(g.namespace, `${path}.namespace`);
+		summary(g.summary, `${path}.summary`);
+		list(g.tests, `${path}.tests`, (value, p) => {
+			test(value, p);
+			const id = value.id;
+			if (ids.has(id)) throw new TUnitParseError(`${p}.id`, `duplicate result id ${id}`);
+			ids.add(id);
+		}, true);
+	}, true);
+	list(r.spans, "$.spans", span);
+	if (r.sourceLinks != null) {
+		const links = object(r.sourceLinks, "$.sourceLinks");
+		for (const field of ["lineUrl", "rangeUrl"]) text(links[field], `$.sourceLinks.${field}`, true);
+		text(links.rawUrl, "$.sourceLinks.rawUrl");
+	}
+	return input;
+}
+//#endregion
+export { TUnitParseError, parseTUnitReport };