corp-v1-channel-architecture/references/docusaurus-drawio-browser-verification.md

Docusaurus Draw.io browser and connector verification

Use this after the production build when Architecture pages embed editable .drawio sources.

Resolve the real served route

Docusaurus serve respects baseUrl, and a document may override its apparent filename with frontmatter such as slug: /.

1. Read docusaurus.config.* for baseUrl and the Architecture plugin's routeBasePath.
2. Read each page's frontmatter before constructing browser URLs.
3. Build the URL as <origin><baseUrl><routeBasePath><document-slug>.
4. Treat unexpected 200, 302, or 404 responses as a routing-discovery problem first; do not infer that the desired document rendered merely because Docusaurus returned a page.

A Context source named context.mdx with slug: / normally renders at <baseUrl>/architecture/, not <baseUrl>/architecture/context/.

Reject authentication shells and unrelated HTTP 200 responses

An HTTP 200 from a deployed documentation URL is not proof that the Docusaurus route rendered. Reverse proxies and identity providers may return a login or access-denied shell with status 200 at every requested route.

Before using a deployed response as render evidence:

1. inspect the response body and script/style URLs for identity-provider or login-shell markers;
2. require at least one route-specific article heading or distinctive content marker;
3. if every route returns near-identical bytes or only authentication assets, classify the result as an authentication boundary—not a successful docs render;
4. do not search the login shell's generic HTML for diagram evidence or claim deployed-route verification;
5. report the limitation separately, retain exact-head build and local browser evidence, and use authenticated browser verification only when an approved credential path is available.

A local production build may prove artifact correctness, and equal Architecture tree IDs may justify carrying forward prior render evidence, but neither substitutes for a fresh deployed browser check. State those evidence dimensions separately.

Prove that the diagram rendered

Generic svg counts are insufficient because the Docusaurus shell and icons also use SVG.

For every edited diagram page:

• require the expected article heading;
• require the exact diagram title or another unique label from the imported .drawio source in the rendered article DOM;
• verify the required Architecture sidebar labels and nesting;
• collect browser console errors, uncaught page errors, and failed requests;
• record the HTTP status and route.

This couples browser evidence to the intended Draw.io source instead of merely proving that some SVG exists.

Classify network failures

Separate first-party or rendering-critical failures from optional third-party requests. docusaurus-plugin-drawio may request the diagrams.net MathJax script even when a diagram contains no mathematics. If that optional request is blocked by browser ORB policy while the exact diagram title and labels render correctly:

• disclose the request and count;
• classify it separately from relevant failures;
• do not hide it;
• do not fail the architecture render verdict solely for that optional request.

Any failed first-party asset, imported Draw.io source, application JavaScript, CSS, or request needed to render diagram content remains a build/render-health failure.

Headless verification when no browser tool is exposed

Use a disposable Playwright runtime rather than weakening browser verification:

1. Set PLAYWRIGHT_BROWSERS_PATH to a writable cache directory before installing or launching Chromium. This avoids failures when Playwright's default home/cache belongs to another service account.
2. Install the matching browser with corepack pnpm dlx playwright@<version> install chromium.
3. Do not assume a package supplied by pnpm dlx is importable by an arbitrary external ESM script. If import 'playwright' cannot resolve, create a disposable directory with a minimal package.json, install Playwright there, and run the verification script from that directory. Do not modify the documentation repository's package manifest or lockfile for this test-only runtime.
4. Serve the already-built production site on loopback and first prove readiness with the exact baseUrl route.
5. For each edited page, assert HTTP 200, article heading, exact diagram title, a source-unique label, required sidebar labels, and at least one article SVG. Capture console, pageerror, requestfailed, and HTTP >=400 events.
6. Partition optional diagrams.net MathJax failures from relevant first-party failures in the test result, then delete or leave the disposable runtime outside the repository.

A successful headless test must report the exact routes and assertions; merely launching Chromium is not render evidence.

Interpret connector diagnostics

Run mandatory XML validation and label validation for every changed source. Also run connector validation, but inspect each issue rather than treating the aggregate count as a verdict.

• Actual connector crossings, a connector traversing an unrelated shape, header-edge violations, and ambiguous routing require correction or explicit review.
• Some validators report each child connector as overlapping its containing swimlane or boundary. Classify these parent-container intersections separately; they are not automatically diagram defects.
• Review non-container overlap entries individually. A warning naming an unrelated component or workload is actionable.
• Do not report a connector warning count as a publication blocker without listing and classifying the underlying issue types.

Retain the final XML validity, label counts, connector classification, rendered-page evidence, console/page errors, and relevant-versus-optional network failures in the PR evidence.