77 lines
5.7 KiB
Markdown
77 lines
5.7 KiB
Markdown
# 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. |