|
| 1 | +# Browser environment matrices |
| 2 | + |
| 3 | +`wp-codebox/browser-environment-matrix/v1` expands hostile browser conditions |
| 4 | +into deterministic, bounded cells. It composes existing probe, action, adaptive, |
| 5 | +visual, accessibility, and multi-actor executors through one callback rather |
| 6 | +than duplicating their execution logic. |
| 7 | + |
| 8 | +```ts |
| 9 | +const matrix = browserEnvironmentMatrix({ |
| 10 | + id: "responsive-accessibility", |
| 11 | + seed: "ci-42", |
| 12 | + dimensions: [ |
| 13 | + { id: "viewport", values: [ |
| 14 | + { id: "desktop", environment: { viewport: { width: 1280, height: 720 } } }, |
| 15 | + { id: "mobile", environment: { viewport: { width: 320, height: 640 }, isMobile: true, hasTouch: true } }, |
| 16 | + ] }, |
| 17 | + { id: "preferences", values: [ |
| 18 | + { id: "default", environment: { colorScheme: "light", reducedMotion: "no-preference" } }, |
| 19 | + { id: "hostile", environment: { colorScheme: "dark", reducedMotion: "reduce", forcedColors: "active" } }, |
| 20 | + ] }, |
| 21 | + ], |
| 22 | + limits: { |
| 23 | + maxCells: 4, |
| 24 | + maxDurationMs: 120_000, |
| 25 | + maxCellDurationMs: 30_000, |
| 26 | + maxArtifactBytes: 50 * 1024 * 1024, |
| 27 | + }, |
| 28 | +}) |
| 29 | +``` |
| 30 | + |
| 31 | +## Expansion and bounds |
| 32 | + |
| 33 | +Dimension and value ids are sorted before cartesian expansion, so declaration |
| 34 | +or object insertion order cannot change cell order. Each cell derives its id and |
| 35 | +seed from the matrix seed, selected value ids, and canonical requested |
| 36 | +environment. Conflicting assignments from two dimensions are rejected. |
| 37 | + |
| 38 | +Construction fails before execution when the cartesian product exceeds |
| 39 | +`maxCells` or when `cells * maxCellDurationMs` exceeds `maxDurationMs`. Execution |
| 40 | +is sequential by default. The runner additionally stops on wall-time, |
| 41 | +interruption, or aggregate artifact-byte exhaustion while preserving every |
| 42 | +completed cell report. |
| 43 | + |
| 44 | +## Capabilities and fidelity |
| 45 | + |
| 46 | +Values declare `requiredCapabilities` and `optionalCapabilities` using generic |
| 47 | +runtime capability ids. A required unsupported capability fails the cell closed |
| 48 | +without executing it. An optional unsupported capability executes when safe and |
| 49 | +marks an otherwise passing cell `inconclusive`. Every cell records `exact`, |
| 50 | +`emulated`, or `unsupported` fidelity and a reason. |
| 51 | + |
| 52 | +The Playwright adapter included with WP Codebox 0.15 applies: |
| 53 | + |
| 54 | +- viewport, named device, DPR, mobile, touch, and orientation context options; |
| 55 | +- color scheme, reduced motion, forced colors, and contrast media features; |
| 56 | +- locale, timezone, and online/offline state; |
| 57 | +- fixed or realtime browser clock behavior; |
| 58 | +- page-scale zoom with explicitly `emulated` fidelity; |
| 59 | +- caller-declared CPU and network profiles through the browser debugging |
| 60 | + protocol with explicitly `emulated` fidelity; |
| 61 | +- caller-declared generic capability state through an immutable page global. |
| 62 | + |
| 63 | +Unknown device, CPU, or network profiles are unsupported rather than silently |
| 64 | +falling back. OS-level zoom, browser chrome, server clocks, and transport-level |
| 65 | +socket faults are not claimed. Transport degradation continues to use the |
| 66 | +existing transport-fault contract. |
| 67 | + |
| 68 | +## Evidence and replay |
| 69 | + |
| 70 | +Callers provide a safe `runId`. Cell evidence belongs under: |
| 71 | + |
| 72 | +```text |
| 73 | +browser-matrices/<matrix-id>/<run-id>/cells/<index>-<cell-id>/ |
| 74 | +``` |
| 75 | + |
| 76 | +The Playwright adapter writes `matrix-report.json` beside the `cells` directory. |
| 77 | +Each cell includes requested and effective environments, selected dimensions, |
| 78 | +provider/browser/version provenance, capability fidelity, status, findings, |
| 79 | +timing, artifact references, and an exact replay contract. Environment cell |
| 80 | +identity participates in default finding fingerprints. |
| 81 | + |
| 82 | +`browserEnvironmentMatrixFailed(report)` preserves fail-on-finding behavior: |
| 83 | +incomplete runs always fail, while findings fail unless the declaration sets |
| 84 | +`failOnFinding: false`. Completed evidence remains available in either case. |
| 85 | + |
| 86 | +For multi-actor scenarios, resolve the shared cell once and create one context |
| 87 | +per actor from that resolution. Explicitly different actor environments should |
| 88 | +be represented as separate named dimensions and resolved before constructing |
| 89 | +actor clients; never mix undeclared context settings inside one cell. |
0 commit comments