Skip to content

Commit 4f641d0

Browse files
ToolboxAidToolboxAid
committed
Add zero-browser preflight and lane compilation validation to prevent deterministic Playwright setup failures from reaching runtime execution - PR_26146_028-zero-browser-preflight-and-lane-compilation
1 parent d552548 commit 4f641d0

9 files changed

Lines changed: 405 additions & 56 deletions

‎docs/dev/reports/lane_compilation_report.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Lane Compilation Report
2+
3+
Generated: 2026-05-26
4+
PR: PR_26146_028-zero-browser-preflight-and-lane-compilation
5+
6+
## Summary
7+
8+
Status: PASS
9+
Lane compilation failures: none
10+
Runtime discovery failures prevented: none needed
11+
12+
## Compiled Lane Graph
13+
14+
| Lane | Status | Runtime Execution | Targets | Reason |
15+
| --- | --- | --- | --- | --- |
16+
| workspace-contract | PASS | Skipped | `npm run test:workspace-v2` | Lane definition compiles and fixture path resolves; not selected for affected runtime validation. |
17+
| tool-runtime | PASS | Executed | `tests/playwright/tools/AssetManagerV2.spec.mjs`; `tests/playwright/tools/PreviewGeneratorV2Baseline.spec.mjs`; `tests/playwright/tools/CollisionInspectorV2.spec.mjs` | Selected affected lane. Targets are inside `tests/playwright/tools`; grep pipe is Node-argv safe. |
18+
| integration | PASS | Executed | `tests/playwright/integration/GameIndexPreviewManifestResolution.spec.mjs` | Selected affected lane. Target is inside `tests/playwright/integration`. |
19+
| engine-src | PASS | Skipped | node engine/src test files | Lane definition compiles; not affected by this PR. |
20+
| samples | PASS | Skipped | node samples test files | Lane definition compiles; samples lane remains on-request and sample scope was not active. |
21+
22+
## Compilation Rules
23+
24+
- Unknown lanes fail before runtime.
25+
- Missing targets, fixtures, or helper imports fail before runtime.
26+
- Playwright targets must stay inside the owning lane directory.
27+
- Shell-sensitive grep values must use the Node CLI argv path.
28+
- Deterministic lane-definition failures do not trigger fallback reruns or full lane escalation.
29+
30+
## Runtime Savings Observations
31+
32+
- Lane graph resolution happens before browser startup.
33+
- Invalid targeted lane setup cannot fall through into runtime discovery.
34+
- Tool-runtime combines Preview Generator V2 and Collision Inspector V2 into one Playwright CLI invocation.
35+
- Workspace V2 was not scheduled for this PR.

‎docs/dev/reports/playwright_structure_audit.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Playwright Structure Audit
22

3-
Generated: 2026-05-26T18:17:13.687Z
3+
Generated: 2026-05-26T18:25:51.107Z
44
Status: PASS
55

66
## Lane Directories

‎docs/dev/reports/static_validation_report.md‎

Lines changed: 26 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,40 @@
11
# Static Validation Report
22

3-
Generated: 2026-05-26
4-
PR: PR_26146_027-static-validation-before-playwright-launch
3+
Generated: 2026-05-26T18:25:51.151Z
4+
Status: PASS
5+
Static only: No
6+
Dry run: No
57

6-
## Summary
8+
## Requested Lanes
79

8-
Status: PASS
9-
Prevented launches: 0
10-
Fast-fail reasons: none
10+
- integration
11+
- tool-runtime
1112

12-
## Static Validation Runs
13+
## Prevented Launches
1314

14-
| Command | Status | Browser Launch | Reason |
15-
| --- | --- | --- | --- |
16-
| `npm run test:playwright:static` | PASS | No | Required first validation pass. Ran structure audit and lane runner static checks without starting Playwright. |
17-
| `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. |
15+
Count: 0
16+
Reason: No deterministic static validation failure was found.
1817

1918
## Checks
2019

2120
| Check | Status | Details |
2221
| --- | --- | --- |
23-
| test placement validation | PASS | Covered by `docs/dev/reports/playwright_structure_audit.md`. |
24-
| lane ownership validation | PASS | Playwright specs are separated under tools, games, integration, and optional engine ownership buckets. |
25-
| invalid filename detection | PASS | No game-specific spec/helper filenames remain in generic reusable tool/helper locations. |
26-
| invalid lane target detection | PASS | Selected lanes target existing files under their expected lane directories. |
27-
| missing fixture detection | PASS | Workspace contract fixture path exists; selected affected lanes use explicit repo/game fixtures. |
28-
| missing import detection | PASS | Relative imports in Playwright specs and shared helpers resolve. |
29-
| Windows quoting hazard detection | PASS | Tool-runtime grep pipe is passed as a literal Node argv value. |
30-
| duplicate lane registration detection | PASS | No duplicate npm `test:lane:*` registrations were found. |
31-
| invalid grep pattern detection | PASS | No empty or malformed grep patterns were found. |
32-
33-
## Fast-Fail Behavior
34-
35-
- Deterministic structural failures would stop before Playwright CLI invocation.
36-
- Browser startup is blocked when lane targets, imports, fixtures, placement, registration, or quoting checks fail.
37-
- Workspace V2 is not launched by static validation.
38-
- No automatic retries are performed for deterministic setup failures.
22+
| lane ownership and file placement | PASS | Playwright structure audit passed. |
23+
| invalid filename detection | PASS | Covered by Playwright structure audit. |
24+
| missing import detection | PASS | Covered by Playwright structure audit relative import checks. |
25+
| missing fixture detection | PASS | No missing fixture findings. |
26+
| invalid lane target detection | PASS | No invalid lane target findings. |
27+
| Windows quoting hazard detection | PASS | Lane tool-runtime grep pattern is passed as a literal Node argv value: launch guard|temporary UAT context|rejects non-Workspace |
28+
| duplicate lane registration detection | PASS | No duplicate lane registrations found. |
29+
| invalid grep pattern detection | PASS | No invalid grep pattern findings. |
30+
31+
## Fast-Fail Reasons
32+
33+
No fast-fail reasons. Playwright lanes may proceed when selected.
3934

4035
## Runtime Savings Observations
4136

42-
- Static validation ran before any browser work.
43-
- Affected lanes were run together through one Node lane-runner process.
44-
- Tool-runtime now combines Preview Generator V2 and Collision Inspector V2 in one Playwright CLI invocation.
45-
- Workspace contract, engine/src, samples, and full samples smoke were skipped because they were outside the affected surface.
37+
- Static validation runs before browser launch.
38+
- Structural failures stop Workspace V2, tool-runtime, integration, and sample Playwright lanes before browser startup.
39+
- Combined lane execution can validate multiple selected lanes through one Node runner process.
40+
- Playwright is invoked through the Node CLI entrypoint to avoid shell quoting discovery failures.

‎docs/dev/reports/testing_lane_execution_report.md‎

Lines changed: 14 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Testing Lane Execution Report
22

33
Generated: 2026-05-26
4-
PR: PR_26146_027-static-validation-before-playwright-launch
4+
PR: PR_26146_028-zero-browser-preflight-and-lane-compilation
55

66
## Summary
77

@@ -13,40 +13,38 @@ SKIP: 3
1313
## Full Samples Smoke
1414

1515
Status: SKIP
16-
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.
16+
Reason: This PR changes zero-browser preflight, lane compilation, and targeted lane routing only. No sample JSON, shared sample loader, or sample framework files were changed.
1717

1818
## Executed and Skipped Lanes
1919

2020
| Lane / Check | Status | Executed/Skipped Reason | Affected Surface | Evidence |
2121
| --- | --- | --- | --- | --- |
22-
| 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`. |
23-
| 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. |
24-
| 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. |
25-
| 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. |
22+
| zero-browser-preflight | PASS | Executed first to prove deterministic setup checks run before Playwright runtime initialization. | Placement, ownership, registrations, imports, fixtures, helpers, grep, quoting, lane references, lane configuration | `npm run test:playwright:zero-browser` passed and wrote zero-browser plus lane compilation reports. |
23+
| tool-runtime | PASS | Executed because lane compilation and zero-browser routing 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. |
24+
| integration | PASS | Executed because the integration lane remains part of the affected compiled lane graph. | Game index preview manifest handoff | Same combined runner command; focused Pong handoff subset 3 passed. |
25+
| workspace-contract | SKIP | Skipped because zero-browser preflight does not require Workspace V2 launch and Workspace V2 runtime wiring was not changed. | Workspace Manager V2 contract/lifecycle behavior | Not run. |
2626
| engine-src | SKIP | Skipped because no `src/`, engine Playwright, or node engine lane targets changed. | src/ engine/shared runtime behavior | Not run. |
2727
| 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. |
2828

2929
## Prevented Launches and Fast-Fail Reasons
3030

31-
- Prevented launches: 0 in this validation run because no deterministic static failures were found.
31+
- Prevented browser launches: 0 in this validation run because no deterministic pre-runtime failures were found.
3232
- Fast-fail reasons: none.
33-
- If static validation finds placement, import, fixture, lane target, duplicate registration, grep, or quoting failures, the runner exits before Playwright/browser startup.
33+
- If preflight finds placement, helper ownership, import, fixture, lane reference, lane configuration, grep, or quoting failures, the runner exits before Playwright/browser startup.
3434

35-
## Placement and Helper Cleanup
35+
## Corrected Ownership Drift
3636

37-
- Existing placement corrections remain enforced in `docs/dev/reports/playwright_structure_audit.md`.
38-
- No additional misplaced tests or game-specific reusable helper names were found.
39-
- `tests/playwright/integration/GameIndexPreviewManifestResolution.spec.mjs` remains the integration-owned handoff target.
37+
- No new misplaced tests or helpers were found in this PR.
38+
- Existing corrections remain enforced: Asteroids game specs under `tests/playwright/games`, integration handoff under `tests/playwright/integration`, documented game fixtures only in tool tests.
4039

4140
## Runtime Savings Observations
4241

43-
- Static validation ran once as a standalone gate before affected lanes.
44-
- Affected lanes ran together in one Node lane-runner process instead of separate npm launches.
45-
- Preview Generator V2 and Collision Inspector V2 execute through one Playwright CLI invocation.
42+
- Zero-browser preflight ran before browser startup.
43+
- Affected lanes ran in one Node lane-runner process.
44+
- Preview Generator V2 and Collision Inspector V2 ran through one Playwright CLI invocation.
4645
- Workspace V2, engine/src, samples, and full samples smoke were not started.
4746

4847
## Static Validation
4948

5049
- PASS `node --check scripts/run-targeted-test-lanes.mjs`
5150
- PASS `node --check scripts/audit-playwright-test-locations.mjs`
52-
- PASS `node --check tests/playwright/integration/GameIndexPreviewManifestResolution.spec.mjs`

‎docs/dev/reports/zero_browser_preflight_report.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Zero-Browser Preflight Report
2+
3+
Generated: 2026-05-26
4+
PR: PR_26146_028-zero-browser-preflight-and-lane-compilation
5+
6+
## Summary
7+
8+
Status: PASS
9+
Prevented browser launches: 0
10+
Deterministic failures caught pre-runtime: none
11+
12+
## Runs
13+
14+
| Command | Status | Browser Launch | Reason |
15+
| --- | --- | --- | --- |
16+
| `npm run test:playwright:zero-browser` | PASS | No | Required first pass. Ran lane ownership, structure, lane registration, import, fixture, grep, quoting, and lane compilation checks without starting Playwright. |
17+
| `PLAYWRIGHT_BROWSERS_PATH=0 node ./scripts/run-targeted-test-lanes.mjs --lanes integration,tool-runtime` | PASS | Yes, after preflight | Re-ran zero-browser validation before selected affected lanes executed. |
18+
19+
## Deterministic Checks
20+
21+
| Check | Status | Details |
22+
| --- | --- | --- |
23+
| lane ownership | PASS | Selected lane targets resolve inside their owning lane directories. |
24+
| directory placement | PASS | Playwright specs are separated into tools, games, integration, and optional engine buckets. |
25+
| invalid file naming | PASS | No game-specific reusable helper or tool-lane filename drift was found. |
26+
| duplicate registrations | PASS | No duplicate `test:lane:*` npm registrations were found. |
27+
| invalid imports | PASS | Relative imports in Playwright specs and shared helpers resolve. |
28+
| unresolved fixtures | PASS | Required fixture paths resolve before execution. |
29+
| unresolved helpers | PASS | Shared helper imports resolve and helper names stay generic. |
30+
| invalid grep patterns | PASS | No empty or malformed grep values were found. |
31+
| Windows quoting hazards | PASS | Shell-sensitive grep pipes are passed through Node CLI argv, not shell parsing. |
32+
| invalid lane references | PASS | Requested lane names resolve in `laneDefinitions`. |
33+
| invalid lane configuration | PASS | See `docs/dev/reports/lane_compilation_report.md`. |
34+
| conflicting reusable helper ownership | PASS | Shared helper filenames were checked against known game names. |
35+
36+
## Corrected Ownership Drift
37+
38+
- Asteroids Playwright runtime specs remain enforced under `tests/playwright/games`.
39+
- Game index preview manifest handoff remains enforced under `tests/playwright/integration`.
40+
- Tool-owned specs may reference games only as documented explicit fixtures.
41+
42+
## Runtime Savings Observations
43+
44+
- Zero-browser preflight runs through Node-only validation before Playwright CLI startup.
45+
- Deterministic setup failures would block browser launch, Workspace V2 startup, lane execution, and automatic retries.
46+
- Affected runtime validation used one lane-runner process for `integration,tool-runtime`.
47+
- Full samples smoke, Workspace V2, and engine/src lanes were not started.

‎package.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,10 @@
55
"test": "node ./scripts/run-node-tests.mjs",
66
"test:audit:locations": "node ./scripts/audit-playwright-test-locations.mjs",
77
"test:playwright:structure": "node ./scripts/audit-playwright-test-locations.mjs",
8+
"test:playwright:zero-browser": "node ./scripts/run-targeted-test-lanes.mjs --zero-browser-only",
89
"test:playwright:static": "node ./scripts/run-targeted-test-lanes.mjs --static-only",
910
"test:lanes": "node ./scripts/run-targeted-test-lanes.mjs",
10-
"test:lanes:preflight": "node ./scripts/run-targeted-test-lanes.mjs --static-only",
11+
"test:lanes:preflight": "node ./scripts/run-targeted-test-lanes.mjs --zero-browser-only",
1112
"test:lane:workspace-contract": "node ./scripts/run-targeted-test-lanes.mjs --lane workspace-contract",
1213
"test:lane:tool-runtime": "node ./scripts/run-targeted-test-lanes.mjs --lane tool-runtime",
1314
"test:lane:integration": "node ./scripts/run-targeted-test-lanes.mjs --lane integration",

0 commit comments

Comments
 (0)