Add static validation gates before Playwright launch to prevent wasted browser startup and repeated deterministic failures - PR_26146_027-static-validation-before-playwright-launch

Author: ToolboxAid

docs/dev/reports/playwright_structure_audit.md

@@ -1,6 +1,6 @@
 # Playwright Structure Audit
 
-Generated: 2026-05-26T18:07:59.062Z
+Generated: 2026-05-26T18:17:13.687Z
 Status: PASS
 
 ## Lane Directories

docs/dev/reports/static_validation_report.md

@@ -0,0 +1,45 @@
+# Static Validation Report
+
+Generated: 2026-05-26
+PR: PR_26146_027-static-validation-before-playwright-launch
+
+## Summary
+
+Status: PASS
+Prevented launches: 0
+Fast-fail reasons: none
+
+## Static Validation Runs
+
+| Command | Status | Browser Launch | Reason |
+| --- | --- | --- | --- |
+| `npm run test:playwright:static` | PASS | No | Required first validation pass. Ran structure audit and lane runner static checks without starting Playwright. |
+| `PLAYWRIGHT_BROWSERS_PATH=0 node ./scripts/run-targeted-test-lanes.mjs --lanes integration,tool-runtime` | PASS | Yes, after static pass | Re-ran the same static gate inside the lane runner before affected Playwright lanes started. |
+
+## Checks
+
+| Check | Status | Details |
+| --- | --- | --- |
+| test placement validation | PASS | Covered by `docs/dev/reports/playwright_structure_audit.md`. |
+| lane ownership validation | PASS | Playwright specs are separated under tools, games, integration, and optional engine ownership buckets. |
+| invalid filename detection | PASS | No game-specific spec/helper filenames remain in generic reusable tool/helper locations. |
+| invalid lane target detection | PASS | Selected lanes target existing files under their expected lane directories. |
+| missing fixture detection | PASS | Workspace contract fixture path exists; selected affected lanes use explicit repo/game fixtures. |
+| missing import detection | PASS | Relative imports in Playwright specs and shared helpers resolve. |
+| Windows quoting hazard detection | PASS | Tool-runtime grep pipe is passed as a literal Node argv value. |
+| duplicate lane registration detection | PASS | No duplicate npm `test:lane:*` registrations were found. |
+| invalid grep pattern detection | PASS | No empty or malformed grep patterns were found. |
+
+## Fast-Fail Behavior
+
+- Deterministic structural failures would stop before Playwright CLI invocation.
+- Browser startup is blocked when lane targets, imports, fixtures, placement, registration, or quoting checks fail.
+- Workspace V2 is not launched by static validation.
+- No automatic retries are performed for deterministic setup failures.
+
+## Runtime Savings Observations
+
+- Static validation ran before any browser work.
+- Affected lanes were run together through one Node lane-runner process.
+- Tool-runtime now combines Preview Generator V2 and Collision Inspector V2 in one Playwright CLI invocation.
+- Workspace contract, engine/src, samples, and full samples smoke were skipped because they were outside the affected surface.

docs/dev/reports/testing_lane_execution_report.md

@@ -1,7 +1,7 @@
 # Testing Lane Execution Report
 
 Generated: 2026-05-26
-PR: PR_26146_026-playwright-structure-enforcement-and-fast-fail-routing
+PR: PR_26146_027-static-validation-before-playwright-launch
 
 ## Summary
 
@@ -13,49 +13,40 @@ SKIP: 3
 ## Full Samples Smoke
 
 Status: SKIP
-Reason: This PR changes Playwright structure enforcement, preflight validation, runner routing, and test placement only. No sample JSON, shared sample loader, or sample framework files were changed.
+Reason: This PR changes static validation, structural preflight routing, and targeted lane execution only. No sample JSON, shared sample loader, or sample framework files were changed.
 
 ## Executed and Skipped Lanes
 
 | Lane / Check | Status | Executed/Skipped Reason | Affected Surface | Evidence |
 | --- | --- | --- | --- | --- |
-| playwright-structure-preflight | PASS | Executed first because structural enforcement now gates expensive Playwright lanes. | Playwright lane ownership, file placement, imports, fixture documentation | `npm run test:lanes:preflight` passed and wrote `docs/dev/reports/playwright_structure_audit.md`. |
-| integration | PASS | Executed because `GameIndexPreviewManifestResolution.spec.mjs` moved from `games/` to `integration/` and the lane target changed. | Game index preview manifest handoff | `PLAYWRIGHT_BROWSERS_PATH=0 npm run test:lane:integration`; preflight passed, focused Pong handoff subset 3 passed. |
-| tool-runtime | PASS | Executed because runner preflight and Windows-safe Playwright argv handling changed. | Asset Manager V2, Preview Generator V2, Collision Inspector V2 runtime tests | `PLAYWRIGHT_BROWSERS_PATH=0 npm run test:lane:tool-runtime`; preflight passed, Asset Manager focused subset 5 passed, Preview Generator 7 passed, Collision Inspector 4 passed. |
-| workspace-contract | SKIP | Skipped because `npm run test:workspace-v2` compatibility was preserved and Workspace V2 wiring was not changed. | Workspace Manager V2 contract/lifecycle behavior | Not run. |
+| static-validation | PASS | Executed first to prove deterministic checks run before browser startup. | Placement, ownership, filenames, lane targets, fixtures, imports, grep, quoting, duplicate registrations | `npm run test:playwright:static` passed and wrote `docs/dev/reports/static_validation_report.md`. |
+| tool-runtime | PASS | Executed because runner static validation and Playwright invocation behavior changed. | Asset Manager V2, Preview Generator V2, Collision Inspector V2 runtime tests | `PLAYWRIGHT_BROWSERS_PATH=0 node ./scripts/run-targeted-test-lanes.mjs --lanes integration,tool-runtime`; Asset Manager focused subset 5 passed, Preview Generator and Collision Inspector combined run 11 passed. |
+| integration | PASS | Executed because the integration lane target remains part of the affected Playwright routing surface. | Game index preview manifest handoff | Same combined runner command; focused Pong handoff subset 3 passed. |
+| workspace-contract | SKIP | Skipped because static validation does not require Workspace V2 launch and Workspace V2 wiring was not changed. | Workspace Manager V2 contract/lifecycle behavior | Not run. |
 | engine-src | SKIP | Skipped because no `src/`, engine Playwright, or node engine lane targets changed. | src/ engine/shared runtime behavior | Not run. |
 | samples | SKIP | Skipped because samples are on-request or affected-sample only and this PR did not impact samples. | On-request samples lane | Not run. |
 
-## Fast-Fail Coverage
+## Prevented Launches and Fast-Fail Reasons
 
-- Runner preflight validates selected lane targets before Playwright starts.
-- Structural audit validates lane ownership, file placement, missing relative imports, documented game fixtures, and shared helper naming.
-- Missing target files, invalid lane targets, invalid empty grep patterns, missing fixtures, or Windows shell quoting hazards fail before browser execution.
-- No deterministic setup failures were found in this run, so no lanes were fast-failed.
+- Prevented launches: 0 in this validation run because no deterministic static failures were found.
+- Fast-fail reasons: none.
+- If static validation finds placement, import, fixture, lane target, duplicate registration, grep, or quoting failures, the runner exits before Playwright/browser startup.
 
-## Placement Corrections
+## Placement and Helper Cleanup
 
-- `tests/playwright/tools/AsteroidsBackgroundAssetResolution.spec.mjs` -> `tests/playwright/games/AsteroidsBackgroundAssetResolution.spec.mjs`
-- `tests/playwright/tools/AsteroidsBeatTiming.spec.mjs` -> `tests/playwright/games/AsteroidsBeatTiming.spec.mjs`
-- `tests/playwright/tools/AsteroidsGameSceneCleanup.spec.mjs` -> `tests/playwright/games/AsteroidsGameSceneCleanup.spec.mjs`
-- `tests/playwright/tools/AsteroidsShipStateVisuals.spec.mjs` -> `tests/playwright/games/AsteroidsShipStateVisuals.spec.mjs`
-- `tests/playwright/games/GameIndexPreviewManifestResolution.spec.mjs` -> `tests/playwright/integration/GameIndexPreviewManifestResolution.spec.mjs`
-
-## Quoting Corrections
-
-- Playwright lane commands invoke `node node_modules/@playwright/test/cli.js` instead of shelling through a platform command wrapper.
-- Grep patterns such as `launch guard|temporary UAT context|rejects non-Workspace` are passed as literal argv values on Windows.
-- Runner command display quotes shell-sensitive argv values for readability without using shell interpretation for Playwright.
+- Existing placement corrections remain enforced in `docs/dev/reports/playwright_structure_audit.md`.
+- No additional misplaced tests or game-specific reusable helper names were found.
+- `tests/playwright/integration/GameIndexPreviewManifestResolution.spec.mjs` remains the integration-owned handoff target.
 
 ## Runtime Savings Observations
 
-- Structural failures now stop before browser boot.
-- Unselected lanes are skipped before command construction reaches Playwright execution.
-- Workspace contract, engine/src, samples, and full samples smoke were not run because they were outside the affected surface.
-- Focused integration validation used the targeted Pong handoff subset instead of broad all-game coverage.
+- Static validation ran once as a standalone gate before affected lanes.
+- Affected lanes ran together in one Node lane-runner process instead of separate npm launches.
+- Preview Generator V2 and Collision Inspector V2 execute through one Playwright CLI invocation.
+- Workspace V2, engine/src, samples, and full samples smoke were not started.
 
 ## Static Validation
 
-- PASS `node --check scripts/audit-playwright-test-locations.mjs`
 - PASS `node --check scripts/run-targeted-test-lanes.mjs`
+- PASS `node --check scripts/audit-playwright-test-locations.mjs`
 - PASS `node --check tests/playwright/integration/GameIndexPreviewManifestResolution.spec.mjs`

package.json

@@ -5,8 +5,9 @@
     "test": "node ./scripts/run-node-tests.mjs",
     "test:audit:locations": "node ./scripts/audit-playwright-test-locations.mjs",
     "test:playwright:structure": "node ./scripts/audit-playwright-test-locations.mjs",
+    "test:playwright:static": "node ./scripts/run-targeted-test-lanes.mjs --static-only",
     "test:lanes": "node ./scripts/run-targeted-test-lanes.mjs",
-    "test:lanes:preflight": "node ./scripts/audit-playwright-test-locations.mjs",
+    "test:lanes:preflight": "node ./scripts/run-targeted-test-lanes.mjs --static-only",
     "test:lane:workspace-contract": "node ./scripts/run-targeted-test-lanes.mjs --lane workspace-contract",
     "test:lane:tool-runtime": "node ./scripts/run-targeted-test-lanes.mjs --lane tool-runtime",
     "test:lane:integration": "node ./scripts/run-targeted-test-lanes.mjs --lane integration",