# 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.