perf(html-report): parallel report serialization + optimized hot writers (-26% end-of-session time)

[thomhurst]

Summary

The default-on HTML report (and its JSON sidecar) is built after the last test finishes. That work is on the critical path of every run and is included in the process wall clock. At 10,000 tests it took ~350 ms. This PR cuts it by about a quarter without changing report content.

1. Parallel array serialization. New ParallelJsonArrayWriter splits a large JSON array into slices.
   • Each slice is written by its own Utf8JsonWriter into its own SegmentedBufferWriter on a separate thread. The thread pool is otherwise idle at this point.
   • The slices are appended to the output in order. The bytes are identical to writing the elements sequentially.
   • Used for the HTML tests array (≥ 1,000 tests per slice), the sidecar groups array (≥ 8 groups per slice) and the sidecar spans array (≥ 2,000 spans per slice). Smaller arrays are written sequentially, exactly as before.
   • The sidecar is serialized concurrently with the HTML. Once the HTML path got faster, the sidecar would have become the critical path, so it is parallelised too.
2. AggressiveOptimization on the per-element writers. Affected methods: HtmlReportGenerator.WriteTest/WriteSpan, ReportDataJson.WriteTest/WriteSpan, HtmlReporter.BuildReportData/ExtractTestResult. These run once per process over every test. Without it, their loops executed as unoptimized tier-0 code for the whole job, because tier-up is delayed while other methods are still being JIT-compiled. The attribute is under #if NET, so netstandard2.0 is unchanged.

SegmentedBufferWriter gains a WriteTo(IBufferWriter<byte>) overload for the splice. The new file is source-linked into TUnit.Reporting.Tool alongside the serializers.

Benchmark

Bare scenario from meziantou's benchmark, 10,000 tests, net10.0. I timed each phase inside the process with the same temporary instrumentation in both builds. The builds ran interleaved, 10 runs each; values are medians in ms:

Phase	main	this PR
BuildReportData	98	72
HTML JSON serialization	149	99
gzip + base64 (unchanged)	63	63
Reporter total (session finishing → sidecar written)	348	258

Not changed here: gzip is now the largest sequential piece. CompressionLevel.Fastest would take it from 57 ms to 15 ms on this payload, but the compressed report grows from 1.26 MB to 2.08 MB. That is a size/speed trade-off for you to decide, so I left the level alone.

Test plan

• New ParallelJsonArrayWriterTests: parallel output is byte-identical to sequential output, with 0, 1, 7 and 10,000 elements and various slice sizes
• TUnit.UnitTests: SegmentedBufferWriterTests (6), ReportDataJsonTests (11), ReportDataMergerTests (9), HtmlReporterTruncateOutputTests (7)
• TUnit.Engine.Tests: HtmlReport* (66 passed, 1 skipped), *HtmlReportCliTests (5 passed, 1 skipped), ReportingSettingsTests (1 passed, 1 skipped)
• TUnit.Engine (all TFMs) and TUnit.Reporting.Tool build

Summary by CodeRabbit

• Performance
  • Large JSON arrays in HTML and aggregated reports are now serialized in parallel, which can speed up report generation while preserving output order.
  • Smaller arrays continue to use serial serialization.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-28T16:27:02.284258Z	52e9463	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: a3d56b24-0f10-41eb-987e-9b311c75767f

📥 Commits

Reviewing files that changed from the base of the PR and between 3c57e2f and 52e9463.

📒 Files selected for processing (7)

• src/TUnit.Engine/Reporters/Aggregation/ParallelJsonArrayWriter.cs
• src/TUnit.Engine/Reporters/Aggregation/ReportDataJson.cs
• src/TUnit.Engine/Reporters/Aggregation/SegmentedBufferWriter.cs
• src/TUnit.Engine/Reporters/Html/HtmlReportGenerator.cs
• src/TUnit.Engine/Reporters/Html/HtmlReporter.cs
• src/TUnit.Reporting.Tool/TUnit.Reporting.Tool.csproj
• tests/TUnit.UnitTests/ParallelJsonArrayWriterTests.cs

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 2 remain after this review.

---

📝 Walkthrough

Walkthrough

Report data and HTML report serialization now use parallel array writing for configured array sizes. The writer serializes index slices into separate buffers and appends them in order. SegmentedBufferWriter can append written bytes to an IBufferWriter.

Changes

Parallel report serialization

Layer / File(s)	Summary
Parallel array writer and buffer output src/TUnit.Engine/Reporters/Aggregation/ParallelJsonArrayWriter.cs, src/TUnit.Engine/Reporters/Aggregation/SegmentedBufferWriter.cs, src/TUnit.Reporting.Tool/TUnit.Reporting.Tool.csproj, tests/TUnit.UnitTests/ParallelJsonArrayWriterTests.cs	ParallelJsonArrayWriter writes directly for fewer than two slices. Otherwise, it serializes index ranges concurrently and appends their buffers in order. SegmentedBufferWriter adds an IBufferWriter overload. The tool links the writer source, and tests compare parallel output with sequential output.
Aggregation report serialization src/TUnit.Engine/Reporters/Aggregation/ReportDataJson.cs	ReportDataJson uses parallel array writing for groups and spans, with minimum slice sizes of 8 groups and 2,000 spans. It extracts group serialization into WriteGroup and adds NET-conditional optimization attributes to WriteTest and WriteSpan.
HTML report test serialization src/TUnit.Engine/Reporters/Html/HtmlReportGenerator.cs, src/TUnit.Engine/Reporters/Html/HtmlReporter.cs	HtmlReportGenerator flattens grouped tests and writes the tests array through ParallelJsonArrayWriter, with a minimum slice size of 1,000 tests. It uses shared compact writer options. Both HTML reporting files add NET-conditional optimization attributes to specified methods.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Refactor

Sequence Diagram(s)

sequenceDiagram
  participant ReportDataJson
  participant ParallelJsonArrayWriter
  participant SliceBuffers
  participant IBufferWriter
  ReportDataJson->>ParallelJsonArrayWriter: WriteElements with element callback
  ParallelJsonArrayWriter->>SliceBuffers: Serialize index ranges concurrently
  ParallelJsonArrayWriter->>IBufferWriter: Flush before appending slice output
  SliceBuffers->>IBufferWriter: Append written bytes in range order with commas

Loading

Merge Risk: ⚪ Minimal · up to 52e94

The inspected serialization paths preserve report output, and no actionable issue remains before merge.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 52e94

The report serializers retain their existing output boundaries and ordered content, with no identified new security exposure. Parallel work can delay cancellation, and end-to-end runtime behavior remains unverified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The independently affected scope is report generation within a test session and the linked reporting tool. The inspected change adds no externally callable serializer or new service dependency.

Trust Boundaries and Controls

• observed — Slice writers skip structural validation, but the inspected production callbacks use fixed JSON element writers. The enclosing writer is flushed before ordered splicing and closes each array next.

Resilience and Maintainability Implications

• observed — A failed slice does not hand its partial buffer to the caller: slice buffers are disposed, serializer failure propagates, and the inspected sidecar lifecycle disposes abandoned results.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 37.50% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 24 functions across 6 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main changes: parallel HTML report serialization and optimization of hot writers. It matches the pull request objectives and is concise enough for a history entry.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 37.50% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 24 functions across 6 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{A rabbit taps out slices in a row,
While little buffers gather below.
Commas hop between each part,
Tests check every quoted dart.
Groups and spans join the stream,
Neat JSON completes the dream.}

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Review: perf(html-report): parallel report serialization + optimized hot writers

Solid, well-reasoned perf work. The splice technique in ParallelJsonArrayWriter (each slice written by its own Utf8JsonWriter with SkipValidation = true into a separate SegmentedBufferWriter, then spliced back with manually-inserted commas) is a legitimate trick, and it's correctly implemented:

• Slice boundaries use (long)count * slice / sliceCount to avoid overflow and keep boundaries exact, so no elements are dropped or duplicated.
• writer.Flush() before splicing raw bytes into buffer is necessary and present — without it, whatever the outer Utf8JsonWriter still had buffered internally (e.g. the "tests":[ prefix) could land after the spliced slice bytes.
• The outer writer's "array still looks empty" state after the splice is intentional and correctly relied upon: the contract ("caller's next call must be WriteEndArray") is honored everywhere it's used, so no stray leading comma.
• All the dictionaries/arrays read inside the parallel closures (absStartByTestId, testWorker, spansByTrace, data.Groups, spans) are fully built before the Parallel.For starts and never mutated afterward, so the concurrent reads are safe. Each thread only writes to its own SegmentedBufferWriter/Utf8JsonWriter, so there's no shared mutable state across slices.
• Buffer disposal is correct on the exception path: the finally disposes whatever slice buffers got assigned, and the pre-existing catch { buffer.Dispose(); throw; } around the callers still cleans up the outer buffer.
• Threshold math (sliceCount = Math.Min(ProcessorCount, count / minElementsPerSlice)) matches the "below twice min runs sequential" comments, and single-core / small-array fallbacks correctly take the sequential path.
• ParallelJsonArrayWriterTests is a good test: it validates byte-identical output against the sequential path across 0/1/7/10,000 elements and multiple slice sizes, including the "never actually splits" case.

One gap worth closing: the parallel path is untested through the real serializers

ParallelJsonArrayWriterTests only exercises ParallelJsonArrayWriter.WriteElements directly with a synthetic writeElement callback — it never goes through ReportDataJson.Write or HtmlReportGenerator.SerializeReport with real ReportTestGroup/ReportTestResult/SpanData data. The thresholds are MinGroupsPerSlice = 8, MinTestsPerSlice = 1000, MinSpansPerSlice = 2000 (so sliceCount >= 2 needs ≥16 groups / ≥2000 tests / ≥4000 spans on multi-core CI runners), and none of the existing integration tests (ReportDataJsonTests, HtmlReporterTests, HtmlReportCliTests, HtmlReporterTruncateOutputTests) come close to those sizes — they all use a handful of tests/groups/spans. That means the actual production closures in HtmlReportGenerator (the flatTests tuple flattening + absStartByTestId/testWorker lookups inside the per-element closure) and in ReportDataJson (WriteGroup/WriteSpan dispatch) only ever run through the sequential branch in CI today. A bug specific to those closures (e.g. a captured-variable mistake, or a lookup that behaves differently under the parallel slicing) wouldn't be caught by the existing suite. Consider adding one integration-level test per serializer that generates ≥ the threshold count of tests/groups/spans (even synthetically) and asserts the output is well-formed / matches a sequential baseline, so the real production code path — not just the generic writer — is covered end-to-end.

Minor / defensive note

ParallelJsonArrayWriter.WriteElements splices slices with a literal ","u8 byte, which is only correct because every caller passes Indented = false. If options.Indented were ever true (not the case today, but nothing enforces it), the splice would produce invalid formatting since Utf8JsonWriter inserts newlines/indentation around commas in indented mode, not just the comma byte. Given the class doc already documents several other invariants the caller must uphold, it'd be worth adding Debug.Assert(!options.Indented) (or documenting it explicitly as a precondition) so a future caller passing indented options fails loudly instead of producing silently malformed JSON.

Nothing here blocks merging — the gap above is the only thing I'd actually ask to see addressed; the indentation note is a cheap guard to add if you're touching the file again.

[greptile-apps]

Confidence Score: 4/5

[Medium risk] Optimizes report serialization with parallel JSON writing.

The PR appears safe to merge, with non-blocking memory-efficiency and test-coverage improvements recommended.

Findings

1.  Higher peak report memory ▶
2.  Parallel path may go untested ▶

Summary

The PR parallelizes large HTML and sidecar JSON arrays, adds a buffer-to-buffer append overload, and applies optimization attributes to report hot paths.

• The slice-copy design increases transient pooled-memory use for large reports.
• The new tests do not guarantee that their parallel cases exercise slicing.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Report data] --> H[HTML serialization]
  A --> S[Sidecar serialization]
  H --> HS[Parallel test slices]
  S --> GS[Parallel group or span slices]
  HS --> HC[Copy slices into HTML buffer]
  GS --> SC[Copy slices into sidecar buffer]

Loading

_{Reviews (1) · Last reviewed commit: "perf(html-report): serialize large repor..."}