Define the browser matrix from kiosk requirements
An interactive museum kiosk may need to work in a maintained Chromium browser, a Firefox-based staff station, and a WebKit-based test target. A CI workflow that only tests whichever browser scripts happen to exist can look green while one supported engine has vanished from the suite. Start with a versioned, reviewed target manifest rather than a directory scan as the source of truth. Specify which versions or browser families are actually supported, what keyboard and display behavior must pass, and who can change that list. The example uses fictional kiosk fixtures and illustrative job results; it does not claim any actual compatibility testing has occurred.
Convert a reviewed job output into a matrix with fromJSON
GitHub documents a dynamic workflow pattern: one job writes a JSON value to GITHUB_OUTPUT, exports it as a job output, and a downstream job calls fromJSON(needs.generator.outputs.matrix) in its strategy.matrix definition. The data might contain an include list whose entries each name a browser target and a test configuration. Define and review that schema in source control. The generator should be a small, deterministic script that reads an approved manifest, not a free-form model answer or an untrusted issue comment. Passing valid JSON does not prove the correct browsers were included, so parsing is the beginning of validation, not the release gate.
Reject missing and unexpected browsers before the fan-out
Validate the emitted matrix against a separately approved set, for example Chromium, Firefox, and WebKit in a supported test environment. Check for missing required engines, duplicate entries, unexpected fields, and values that do not match a restricted identifier format. An empty include array should be a release error when at least one browser is mandatory. If a previous test was removed accidentally, the matrix generator must not remove that browser from the expected list as well. Keep the approved source under branch protection and have the same validation run before any browser-specific jobs are scheduled.
Keep matrix values out of executable shell fragments
Browser targets should be identifiers such as chromium or firefox, not commands copied into a shell. Resolve each approved identifier to a reviewed test script and environment in a controlled mapping. Pass values through safe environment variables or arguments and quote them correctly. Avoid embedding pull-request titles, arbitrary paths, or external JSON values in a run script. The browser-testing jobs ordinarily need read access to the repository and no deploy credentials. If external contributions can alter the generator or test code, prevent those workflows from receiving privileged secrets. A matrix defines job variation, not permission to bypass review.
Compare full coverage with a missing-engine false green
A visual comparison helps expose the dangerous failure. The expected manifest lists Chromium, Firefox, and WebKit as required test targets. A defective generator accidentally drops Firefox and runs only two browser jobs; both report green, but the test coverage is incomplete. In the corrected workflow, a comparison step detects the mismatch between the approved list and the emitted include entries and blocks deployment, even though the two available tests succeeded. These are conceptual states rather than measured GitHub run screenshots. Make the missing target visible in both the CI summary and the release discussion rather than accepting an apparently successful smaller matrix.
Gate deployment on coverage and completed test evidence
A release job should depend on two independent facts: the generated test matrix exactly covers the expected browser targets, and each required test produced an acceptable result for the intended commit. Do not use the existence of an uploaded artifact or the number of jobs visible in the GitHub UI as evidence that all browsers were tested. Inspect failed, skipped, and cancelled jobs as distinct states, and record which browser produced each artifact. Verify the status checks that branch protection actually requires; a dynamically generated name may not map to a stable required check. Treat a missing browser as a failed release condition, not a reason to shorten the required set.
Make browser tests reflect real kiosk risks
Each browser job should exercise more than a page-load smoke test. A useful matrix might check keyboard-only search, screen-reader labels in the catalog results panel, text scaling, network-error fallback, navigation focus, and the kiosk’s restricted browsing behavior. Select tests that can run against synthetic collection records and fake visitor inputs. Do not upload real patron queries or internal archive access tokens as CI artifacts. A failed test should identify the affected engine, commit, and relevant nonprivate fixture. Browser automation can flag regressions, but a qualified reviewer still needs to confirm accessibility and physical kiosk behavior on representative hardware.
Test malformed outputs and intentionally missing targets
Build fixture cases for a correct three-browser matrix, an omitted Firefox entry, a duplicated Chromium row, a malformed JSON string, an unapproved browser identifier, and a failed browser job. For each case, inspect the generator validation, the actual fan-out jobs, and the final release condition. A useful test must fail for the right reason: a missing Firefox job should be identified as a coverage failure rather than silently omitted from the matrix. Record the manifest revision, workflow commit, runner environment, browser versions, and test-artifact identifiers so staff can reproduce the result in an authorized nonproduction repository.
Review the final device and browser release record
Before publishing the kiosk interface, create a release record containing the approved browser target list, the JSON generated by the workflow, validation outcome, all required job conclusions, and their associated test artifacts. If an engine is intentionally retired, require a separate reviewed change to support policy; do not silently remove its row from the generator. Confirm that kiosk hardware, operating-system versions, and accessibility tools are represented by your test environments, because an automated browser run cannot replicate every visitor experience. Recheck GitHub’s expressions, matrix, and workflow syntax documentation after CI upgrades, and keep final deployment approval separate from the generation of the test matrix.
How We Research
We examined the named primary references for the applicable API semantics and limits: GitHub expression fromJSON reference, GitHub matrix jobs guide, GitHub workflow syntax. We compared documented options with an illustrative, fictional institutional workflow and marked failure states separately from editorial approval. No live cloud account, customer records, paid API measurements, production workload, or real service screenshots were used. Examples and diagrams are conceptual and do not represent observed accuracy, latency, cost, or compliance outcomes. Before deployment, check current regional availability, SDK and API versions, security obligations, billing, and institutional rules, then run authorized tests and obtain human signoff.
Frequently Asked Questions
It turns a JSON string from a prior job or expression into structured data usable by a downstream job matrix.
Without an independent expected list, a missing browser may remove its own test and leave the remaining jobs green.
No. Validate the emitted entries against approved targets and confirm every required job finished successfully for the right commit.
No. Validate identifiers, map them to reviewed scripts, and keep CI permissions least-privileged.
No. They catch automated regressions; staff must still review physical accessibility, input devices, and hardware-specific behavior.