PlantUML Browser Rendering

PlantUML Browser Rendering

TestTrackingDiagrams can render PlantUML sequence diagrams entirely in the browser — no remote server, no IKVM package, and no Java installation required. This uses the official PlantUML TeaVM JavaScript engine, which compiles the full PlantUML Java codebase to JavaScript via TeaVM.

Because this runs the complete PlantUML engine, all features are supported — including the Teoz layout engine (!pragma teoz true), themes, all diagram types, and advanced sequence diagram features like parallel messages (&), nested boxes, and anchored durations.

---

Enabling Browser Rendering

Set PlantUmlRendering = PlantUmlRendering.BrowserJs on your ReportConfigurationOptions or DiagramsFetcherOptions:

Via ReportConfigurationOptions

new ReportConfigurationOptions
{
    PlantUmlRendering = PlantUmlRendering.BrowserJs,
    // ... other options
}

Via DiagramsFetcherOptions

var fetcher = DefaultDiagramsFetcher.GetDiagramsFetcher(new DiagramsFetcherOptions
{
    PlantUmlRendering = PlantUmlRendering.BrowserJs
});

The default value is DiagramFormat.PlantUml, so existing configurations continue to work without changes.

---

How It Works

1. During report generation, DefaultDiagramsFetcher runs the standard PlantUML text generation pipeline — the same pipeline used for server-side and IKVM rendering.
2. Instead of generating server URLs or rendering images, the raw PlantUML text is stored in the CodeBehind property of each DiagramAsCode, with ImgSrc left empty.
3. In the HTML report, each diagram is rendered as a <div> element with the raw PlantUML stored in a data-plantuml attribute:

   <div class="plantuml-browser" id="puml-0" data-plantuml="@startuml ...">Loading diagram...</div>

4. Two JavaScript files are loaded from the official PlantUML CDN:
   • viz-global.js (~1.4 MB) — the Graphviz layout engine
   • plantuml.js (~6.6 MB) — the PlantUML engine compiled to JavaScript
5. An IntersectionObserver watches each diagram element. When a diagram scrolls within 200px of the viewport, the observer triggers window.plantuml.render() to render it in-place as an inline SVG.

---

Lazy Rendering

Diagrams are lazily rendered using IntersectionObserver, equivalent to <img loading="lazy"> for traditional image-based diagrams. This is critical for large test suites:

• Diagrams outside the viewport are not rendered until the user scrolls near them
• Each diagram renders in approximately 300ms
• With 1,500 diagrams, only the visible ones render on page load — the rest render on demand as the user scrolls
• The rootMargin: '200px' setting pre-renders diagrams 200px before they enter the viewport, so they appear ready when scrolled into view

Without lazy rendering, 1,500 diagrams would block the browser's main thread for ~7 minutes on page load.

---

Comparison with Other Rendering Options

Aspect	PlantUml + Server (default)	PlantUml + Local	PlantUml + BrowserJs	Mermaid
Diagram syntax	PlantUML	PlantUML	PlantUML	Mermaid
Rendering	Server-side (remote URL)	In-process .NET via IKVM	Client-side (browser JavaScript)	Client-side (browser JavaScript)
HTML embedding	<img src="...">	<img src="...">	<div data-plantuml="..."> with IntersectionObserver	<pre class="mermaid">
External dependencies	PlantUML server	IKVM NuGet package	None (JS loaded from CDN on page open)	None (mermaid.js loaded from CDN on page open)
Teoz support	Yes	Yes	Yes	N/A
Themes	Yes	Yes	Yes	N/A (Mermaid has own themes)
Offline/self-contained	No (needs server)	Yes with Base64	Requires internet for CDN scripts	Requires internet for CDN scripts
Download cost	0 (images are pre-rendered)	0 (images are pre-rendered)	~8 MB JS on first page load (cached)	~1 MB JS on first page load (cached)
Lazy loading	<img loading="lazy">	<img loading="lazy">	IntersectionObserver	Mermaid.js renders all <pre> tags on startOnLoad
NuGet package needed	None	TestTrackingDiagrams.PlantUml.Ikvm	None	None

---

When to Use BrowserJs Rendering

Use PlantUmlRendering.BrowserJs when you want:

• No server dependency — Reports work without access to a PlantUML server (public or private)
• No IKVM overhead — No 30 MB NuGet package, no in-process Java rendering during test execution
• Full PlantUML feature set — Including Teoz, themes, and all diagram types, unlike Mermaid which uses a different syntax
• Local browsing — Open the HTML report file directly in a browser and diagrams render on the spot
• Fast test execution — Diagram rendering is deferred to report viewing time, not test execution time

Consider other options when:

• No internet at viewing time — The CDN scripts need to be fetched on first page load. Use PlantUmlRendering.Local with Base64Png/Base64Svg for fully offline reports
• You prefer Mermaid syntax — Use DiagramFormat.Mermaid for native GitHub/Azure DevOps rendering in Markdown
• You need pre-rendered images — Use PlantUmlRendering.Server or PlantUmlRendering.Local for <img> tags that don't require JavaScript
• CI summary rendering — Use CiSummaryPlantUmlRendering = PlantUmlRendering.NodeJs to render diagrams as inline base64 SVGs via Node.js, with no server dependency. See CI Summary Integration#nodejs-rendering

Note: PlantUmlRendering only applies when DiagramFormat = DiagramFormat.PlantUml. When DiagramFormat = DiagramFormat.Mermaid, PlantUmlRendering is silently ignored — diagrams are always rendered client-side by mermaid.js.

---

PlantUML Options That Still Apply

These configuration options work with PlantUmlRendering.BrowserJs because the same PlantUML text generation pipeline is used:

• PlantUmlTheme — Themes are embedded in the PlantUML text (!theme <name>) and applied by the browser engine
• SeparateSetup / HighlightSetup — Setup separation boxes are part of the PlantUML syntax
• FocusEmphasis / FocusDeEmphasis — Field highlighting is applied to the PlantUML text
• ExcludedHeaders — Header filtering happens during text generation
• All formatting processors (RequestPreFormattingProcessor, RequestPostFormattingProcessor, etc.)

PlantUML Options That Do Not Apply

These options are ignored when using PlantUmlRendering.BrowserJs:

Option	Reason
PlantUmlServerBaseUrl	No server is used — rendering happens in the browser
PlantUmlImageFormat	The browser engine always renders SVG
LocalDiagramRenderer	No local rendering — diagrams are rendered in the browser
LocalDiagramImageDirectory	No image files are produced

Note: LazyLoadDiagramImages is also not applicable in the traditional sense — lazy rendering is always enabled via IntersectionObserver and cannot be disabled for BrowserJs.

---

CI Summary Interactive HTML

The CI Summary Interactive HTML report (CiSummaryInteractive.html) also uses client-side PlantUML rendering with the same lazy IntersectionObserver approach. It uses the official PlantUML TeaVM JS engine from plantuml.github.io.

See CI Summary Integration for details on enabling CI summaries.

---

Teoz Layout Engine

The Teoz layout engine is a newer PlantUML layout engine that supports:

• Parallel messages — Use & to show messages sent simultaneously
• Nested boxes — Group participants in hierarchical boxes
• Anchors and durations — Label time spans between diagram events

To use Teoz, include the pragma in your PlantUML text. You can inject it globally using a formatting processor:

new ReportConfigurationOptions
{
    PlantUmlRendering = PlantUmlRendering.BrowserJs,
    RequestResponsePostProcessor = content => content  // your post-processing
}

Or use TrackingDiagramOverride.InsertPlantUml("!pragma teoz true") at the start of a test to enable it per-scenario. See Diagram Customisation#InsertPlantUml for details.

Teoz is fully supported by the browser engine because the complete PlantUML codebase is compiled to JavaScript.