test(determinism): deterministic waits + stableShot screenshots; drop blind sleeps/ifs/retries

Make the Playwright e2e + kicad suites deterministic so screenshot flake stops
tracing to timing races.

- Blind page.waitForTimeout -> condition waits (expect.poll, web-first
  assertions, waitUntil) + readiness helpers (waitForWxApp, waitForCanvasApp).
  Remaining sleeps are documented interaction dwells (annotated).
- Defensive "if element exists" branches -> loud asserts; label-fallback chains
  -> normalized clickMenuItemByText. First-run wizard for/if loops removed by
  seeding calculator/gerbview/pcbnew HTMLs.
- Screenshots: new stableShot(page, name) settles the render in-page (canvas
  hash over rAF) then writes a raw PNG to test-results/ for the existing offline
  gate (tools/screenshots vs baseline-screenshots). Replaces toHaveScreenshot,
  which did inline compare + its own baselines and had decoupled the specs from
  the real gate. scale:'css' pinned.
- retries: 0 in both configs.
- Guard: tests/tools/lint-determinism.ts (npm run lint:determinism) bans blind
  sleeps / toHaveScreenshot / inline retries / swallowed catches in specs;
  documented exceptions carry a marker. Rules in tests/TESTING.md.

Assertions, coverage, and renders unchanged (semantic-equivalence reviewed;
captures pixel-identical modulo inherent timer/timestamp/3d-raytrace variance).
Both suites green at retries:0 (e2e 340, kicad 92); ~35-61% faster.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BVX1pHMvRPYHdp6ZfEawrk

tests/kicad/utils/pcbnew-ready.ts

@@ -23,25 +23,17 @@ export async function dismissWizardIfPresent(page: Page): Promise<void> {
 }
 
 /**
- * Wait for pcbnew to boot: 2D canvas visible, element registry populated, the
- * first-run wizard dismissed, and the main PcbFrame registered & visible.
+ * Wait for pcbnew to boot: 2D canvas visible and the main PcbFrame registered &
+ * visible. pcbnew.html seeds the config so the first-run wizard never opens —
+ * PcbFrame becoming visible is the single deterministic "editor is up" signal, so
+ * no wizard dismissal and no fixed settle sleeps are needed.
  */
 export async function waitForPcbnew(page: Page): Promise<void> {
     await expect(page.locator('#canvas')).toBeVisible({ timeout: 90000 });
-    await page.waitForFunction(() => !!window.wxElementRegistry, null, { timeout: 90000 });
-    // Registry object ≠ app booted: wait for real UI entries (wizard or main
-    // frame) before dismissing — CI boots slower and the dismiss loop is bounded.
-    await page.waitForFunction(() => {
-        const registry = window.wxElementRegistry;
-        return !!registry && registry.findAll({}).length > 0;
-    }, null, { timeout: 150000 });
-    await page.waitForTimeout(2500);
-    await dismissWizardIfPresent(page);
     await page.waitForFunction(() => {
         const registry = window.wxElementRegistry;
         if (!registry) return false;
         return registry.findAll({ visible: true })
             .some((el) => el.name === 'PcbFrame');
-    }, null, { timeout: 90000 });
-    await page.waitForTimeout(1500);
+    }, null, { timeout: 150000 });
 }

tests/kicad/utils/threed-viewer.ts

@@ -1,6 +1,6 @@
 import type { Page } from '@playwright/test';
 import { expect } from '@playwright/test';
-import { clickMenuBarItem, clickMenuItem } from '../../e2e/utils/element-tracker';
+import { clickMenuBarItem, clickMenuItemByText, waitUntil } from '../../e2e/utils/element-tracker';
 import { injectFromSubmodule } from './fs-inject';
 import { waitForBoardLoaded } from './board-ready';
 
@@ -28,15 +28,18 @@ export async function loadBoard(
         `${PROJECT_DIR_MEMFS}/${proFilename}`);
 
     expect(await clickMenuBarItem(page, 'File'), 'File menu should be findable').toBe(true);
-    await page.waitForTimeout(400);
-    expect(await clickMenuItem(page, 'Open...'), 'Open… menu item should be findable').toBe(true);
+    await clickMenuItemByText(page, 'Open');
 
     await page.waitForFunction(() => {
         const registry = window.wxElementRegistry;
         return !!registry && registry.findAll({ visible: true })
             .some((el) => el.typeName === 'wxFileDialog');
     }, null, { timeout: 15000 });
-    await page.waitForTimeout(1000);
+    // Wait for the filename text input to paint (replaces a fixed 1000ms).
+    await waitUntil(page, () => {
+        const r = window.wxElementRegistry;
+        return !!r && r.findAll({ visible: true }).some((el) => el.typeName === 'wxTextCtrl' && el.name === 'text');
+    }, 'file dialog filename input');
 
     const filenameInput = await page.evaluate(() => {
         const registry = window.wxElementRegistry;
@@ -49,11 +52,11 @@ export async function loadBoard(
     if (!filenameInput) throw new Error('filename text input not found');
 
     await page.mouse.click(filenameInput.x, filenameInput.y);
-    await page.waitForTimeout(200);
+    // Documented interaction dwells: focus + typed-text registration have no observable signal.
+    await page.waitForTimeout(200); // eslint-disable-line -- documented interaction dwell
     await page.keyboard.type(pcbFilename);
-    await page.waitForTimeout(300);
+    await page.waitForTimeout(300); // eslint-disable-line -- documented interaction dwell
     await page.keyboard.press('Enter');
-    await page.waitForTimeout(1000);
 
     const result = await waitForBoardLoaded(page, testLogger, 60000);
     console.log(`[TEST] ${DEMO.name} board-ready result: ${result}`);
@@ -99,17 +102,11 @@ export async function logThreeDDiag(page: Page, label: string): Promise<void> {
 // itself a wxGLCanvas, so the viewer is detected by the GL-canvas COUNT increasing.
 // Returns the glcanvas count after opening. `glBefore` is the count beforehand.
 export async function openThreeDViewer(page: Page, glBefore: number): Promise<number> {
-    let opened = false;
-    if (await clickMenuBarItem(page, 'View')) {
-        await page.waitForTimeout(400);
-        opened = await clickMenuItem(page, '3D Viewer');
-    }
-    if (!opened) {
-        console.log('[TEST] View → 3D Viewer not found via menu; trying Alt+3');
-        await page.keyboard.press('Escape');
-        await page.waitForTimeout(200);
-        await page.keyboard.press('Alt+3');
-    }
+    // Open View → 3D Viewer deterministically (clickMenuItemByText waits for the item to
+    // render, then clicks — no fixed post-menu sleep and no Alt+3 fallback that could mask
+    // a real menu regression).
+    expect(await clickMenuBarItem(page, 'View'), 'View menu should be findable').toBe(true);
+    await clickMenuItemByText(page, '3D Viewer');
 
     // 180s (not 60s): opening the viewer kicks the scene build + first render. On CI
     // (headless SwiftShader software WebGL, 30 contended vCPUs) the raytracer-era run