fix(docs-tests): tighten 404 detector to handle '404 | site' title and prose mentions

The previous three-signal detector (`.NotFound` element, `document.title
=== '404'`, body text contains `PAGE NOT FOUND`) had two real failure
modes on the VitePress build:

- The negative test on `/this-route-does-not-exist` returned no
  indicator. VitePress emits `<title>404 | MTConnect.NET</title>` into
  the static `404.html`, so the strict `=== '404'` equality never
  matches; the `.NotFound` element only appears once Vue hydrates which
  is fine but was the only remaining signal.
- The positive walk reported `/development/docs-site — body text
  contains 'PAGE NOT FOUND'`. The page legitimately quotes the phrase
  in prose (the section that documents the detector itself), so the
  body-text signal fired a false positive.

Switch to a two-signal detector — `.NotFound` element + `document.title`
starting with `404` — and update the docs-site page to describe the new
scheme. The title prefix match is robust because VitePress always emits
`<title>404 | <site-title></title>` for unmapped routes regardless of
the configured site title, and prose mentions of the literal phrase
`PAGE NOT FOUND` no longer trip the walk.

Author: ottobolyos

docs/development/docs-site.md

@@ -71,7 +71,7 @@ dotnet test tests/MTConnect.NET-Docs-Tests --filter Category=E2E
 
 On the first run the fixture installs the chromium binary the Playwright .NET binding drives (~150 MB; cached on subsequent runs) and — if `docs/.vitepress/dist/` is missing — invokes `npm ci && npm run build` from `docs/` to produce a preview-able site. Subsequent runs reuse both, so a warm working tree completes in a couple of minutes; a cold checkout takes longer because the build artefact is rebuilt from scratch.
 
-Failure output names every route that surfaced as a 404 along with which of the three signals fired — the `.NotFound` element, `document.title === '404'`, or body text containing `PAGE NOT FOUND`. Typical fixes:
+Failure output names every route that surfaced as a 404 along with which of the two signals fired—the `.NotFound` element rendered by the VitePress default theme's NotFound component, or `document.title` starting with `404` (the static `404.html` emits `<title>404 | MTConnect.NET</title>`, so a prefix match catches it regardless of the trailing site-title suffix). Typical fixes:
 
 | Symptom | Probable cause | Fix |
 | --- | --- | --- |
@@ -80,7 +80,7 @@ Failure output names every route that surfaced as a 404 along with which of the
 | "playwright install chromium exited NNN" | The chromium download was blocked or interrupted. | Re-run; if the install fails again, run `dotnet tool restore && npx playwright install chromium` manually and re-try. |
 | "port NNNN already in use" hang | Another process grabbed the free port between selection and bind (rare; mitigated by the banner-parse fallback). | Re-run the test — the next free port avoids the contended one. |
 
-The negative companion test (`A_Synthetic_Unmapped_Route_Surfaces_As_A_404`) pins the detector itself: a future Playwright or VitePress upgrade that breaks one of the three 404 signals would still see every real route render fine, but the negative test would go red and surface the regression before a real 404 slipped past.
+The negative companion test (`A_Synthetic_Unmapped_Route_Surfaces_As_A_404`) pins the detector itself: a future Playwright or VitePress upgrade that breaks one of the two 404 signals would still see every real route render fine, but the negative test would go red and surface the regression before a real 404 slipped past.
 
 ## See also
 

tests/MTConnect.NET-Docs-Tests/RouteCheckTests.cs

@@ -196,21 +196,20 @@ private static async Task AwaitDrainAsync(Task? drain)
 
     /// <summary>
     /// Negative regression for the 404 detector: visits an unmapped
-    /// route and asserts at least one of the three signals (.NotFound
-    /// element, document.title === '404', body-text 'PAGE NOT FOUND')
-    /// fires. Without this, a future Playwright / VitePress upgrade
-    /// that broke a signal would silently pass-through every real 404.
+    /// route and asserts at least one of the two signals (.NotFound
+    /// element, document.title starting with '404') fires. Without
+    /// this, a future Playwright / VitePress upgrade that broke a
+    /// signal would silently pass-through every real 404.
     /// </summary>
     [Test]
     public async Task A_Synthetic_Unmapped_Route_Surfaces_As_A_404()
     {
         // Pins the detector itself per §10a. If a future Playwright / VitePress
-        // upgrade silently breaks one of the three signals (.NotFound element,
-        // document.title === '404', body-text 'PAGE NOT FOUND'), the positive
-        // test would still pass — every real markdown-backed route would
-        // continue to render fine — but a real 404 would go undetected. This
-        // test makes sure the detector fires on a URL that has no markdown
-        // source behind it.
+        // upgrade silently breaks one of the two signals (.NotFound element,
+        // document.title startsWith '404'), the positive test would still pass
+        // — every real markdown-backed route would continue to render fine —
+        // but a real 404 would go undetected. This test makes sure the detector
+        // fires on a URL that has no markdown source behind it.
         Assert.That(_browser, Is.Not.Null, "browser was not initialised");
         var context = await _browser!.NewContextAsync();
         try
@@ -292,17 +291,29 @@ public async Task Every_Markdown_Backed_Route_Resolves_Without_A_404()
 
     // ─── Route check ─────────────────────────────────────────────────────────
 
-    // Detects VitePress's client-side 404 page. The original Node
-    // crawler used three signals; mirror them here exactly so the
-    // test's failure surface matches what the script caught.
+    // Detects VitePress's client-side 404 page. Two signals are used:
+    // the `.NotFound` element rendered by the default theme's NotFound
+    // component, and the `<title>` element — which the static 404.html
+    // emits as `404 | <site title>` (e.g. `404 | MTConnect.NET`), so a
+    // prefix match on `404` catches the title regardless of the trailing
+    // site-title suffix.
+    //
+    // The original detector also checked for body text containing
+    // `PAGE NOT FOUND`, but that signal is too loose — a real
+    // markdown-backed route may quote the phrase in prose (e.g. the
+    // docs-site page that documents this very detector). Dropping it
+    // avoids false positives without sacrificing coverage: every real
+    // VitePress 404 still renders the `.NotFound` element and the
+    // `404 | ...` title.
     //
     // WaitUntilState.Load (not NetworkIdle) is used here deliberately.
     // VitePress's SPA keeps background work running indefinitely —
     // analytics pings, web-vitals beacons, hot-reload polling — so
-    // NetworkIdle never settles within any reasonable timeout. All
-    // three 404 signals (.NotFound selector, document.title, body text)
-    // are available as soon as the DOM is fully parsed and sub-resources
-    // have finished loading, which is exactly what Load guarantees.
+    // NetworkIdle never settles within any reasonable timeout. The
+    // `<title>` signal is server-rendered into the static 404.html so
+    // it is available at Load; the `.NotFound` signal appears once Vue
+    // hydrates, which on a built site happens during the Load event's
+    // sub-resource phase.
     private static async Task<(string Route, string Indicator)?> CheckRouteAsync(IBrowserContext context, string baseUrl, string route)
     {
         var url = baseUrl + route;
@@ -317,13 +328,11 @@ public async Task Every_Markdown_Backed_Route_Resolves_Without_A_404()
 
             var detection = await page.EvaluateAsync<NotFoundDetection>(@"() => ({
                 hasClass: !!document.querySelector('.NotFound'),
-                title404: document.title === '404',
-                bodyMatches: (document.body?.innerText ?? '').toUpperCase().includes('PAGE NOT FOUND')
+                title404: (document.title ?? '').startsWith('404')
             })");
 
             if (detection.HasClass) return (route, ".NotFound element present");
-            if (detection.Title404) return (route, "document.title == '404'");
-            if (detection.BodyMatches) return (route, "body text contains 'PAGE NOT FOUND'");
+            if (detection.Title404) return (route, "document.title starts with '404'");
             return null;
         }
         finally
@@ -333,20 +342,17 @@ public async Task Every_Markdown_Backed_Route_Resolves_Without_A_404()
     }
 
     // The JS payload returned by EvaluateAsync uses camelCase keys
-    // (`hasClass`, `title404`, `bodyMatches`); pin them explicitly so
-    // a future Playwright upgrade that tightens case-insensitive
-    // deserialisation cannot silently turn every route into a
-    // no-detection pass-through (which would hide a real 404).
+    // (`hasClass`, `title404`); pin them explicitly so a future
+    // Playwright upgrade that tightens case-insensitive deserialisation
+    // cannot silently turn every route into a no-detection pass-through
+    // (which would hide a real 404).
     private sealed class NotFoundDetection
     {
         [JsonPropertyName("hasClass")]
         public bool HasClass { get; set; }
 
         [JsonPropertyName("title404")]
         public bool Title404 { get; set; }
-
-        [JsonPropertyName("bodyMatches")]
-        public bool BodyMatches { get; set; }
     }
 
     // ─── Preview server lifecycle ────────────────────────────────────────────