fix(test): constrain immutable-container Chromium fallback

[BigSimmo]

Summary

• supersede closed, unmerged PR fix(test): use preinstalled Chromium in immutable containers #1504 with its reviewed implementation plus both automated P2 fixes
• keep the Playwright-managed Chromium as the preferred exact client/browser pair
• allow fallback only in the designated immutable Linux image (PLAYWRIGHT_BROWSERS_PATH=/opt/pw-browsers with downloads disabled), selecting the newest shell compatible with the current CPU architecture
• pass the selected path to the Playwright child, while generic shared and stale developer caches continue to fail closed
• archive fix(text): repair extraction glyph artifacts app-wide and route all document-derived text through formatters #121 with the actual repository-runner boundary, not a claim that the external image itself was rebuilt

Review fixes carried forward

• Linux arm64 cannot select the x64-only chrome-headless-shell-linux64 layout; it falls through to the compatible chrome-linux/headless_shell layout
• the generic PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 plus shared-cache combination is insufficient to enable fallback; /opt/pw-browsers is required

Verification

• npm run test -- tests/playwright-browser-preflight.test.ts — 1 file, 11 tests passed on the final review-fixed code
• prior exact-head fix(test): use preinstalled Chromium in immutable containers #1504 hosted run: Unit coverage, Static, Safety/config, SAST, Lighthouse, visual baselines, Production UI critical, and all three Production UI shards passed before the review fixes
• original local full proof: npm run verify:cheap — 443 files, 4,631 tests passed, 3 skipped
• real fallback launch with a simulated older container revision — Chromium launched and rendered the expected 48px element
• identity-checked focused production runner — 1 passed (26.9s); verified local server stopped afterward
• npm run check:rag:fixtures — 36 golden cases, 23 suites passed
• focused ESLint and Prettier checks
• npm run check:outstanding-issues -- --base-ref origin/main
• npm run check:branch-review-ledger
• git diff --check origin/main...HEAD

Fresh exact-head hosted CI is required for this replacement PR; the prior #1504 result is supporting evidence only.

Risk and rollback

Low-to-moderate test-infrastructure risk. The fallback may intentionally use an older image browser than the client, but it is restricted to the known immutable image root, architecture-filtered, and logged. Revert this PR to restore strict exact-revision failure and the manual executable override requirement.

RAG impact: no retrieval behaviour change — Playwright browser discovery and test documentation only.

Summary by CodeRabbit

• Bug Fixes

  • Improved automated browser test reliability when the managed Chromium download is unavailable.
  • Tests can now use a compatible preinstalled Chromium browser in supported container environments.
  • Added architecture-aware browser selection to avoid incompatible binaries.

• Documentation

  • Updated testing guidance for browser fallback behavior.
  • Archived the resolved browser-build compatibility issue.
  • Refreshed review and reconciliation records.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 9 minutes

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 10c7c42c-0b82-4ad4-abfa-0f8ca00426ad

📥 Commits

Reviewing files that changed from the base of the PR and between 83e81fe and 064b429.

📒 Files selected for processing (1)

• docs/branch-review-ledger.md

📝 Walkthrough

Walkthrough

Changes

The Playwright runner now discovers compatible preinstalled Chromium shells in the designated container browser root when managed downloads are disabled. Resolution is platform- and architecture-aware, with tests and documentation updated. Review ledger and outstanding-issue records were also reconciled.

Playwright browser fallback

Layer / File(s)	Summary
Browser discovery and resolution scripts/playwright-browser-preflight.mjs	Scans designated browser roots, selects the newest compatible headless shell, and preserves managed-path fallback behavior.
Runner executable wiring scripts/run-playwright.mjs, tests/test-runner-safety.test.ts	Applies detected executable metadata to Playwright when no override exists and verifies the environment configuration.
Fallback validation and documentation tests/playwright-browser-preflight.test.ts, docs/testing.md, docs/outstanding-issues.md	Tests revision, root, and architecture selection; documents and archives the resolved browser fallback behavior.

Review documentation reconciliation

Layer / File(s)	Summary
Review ledger record updates docs/branch-review-ledger.md	Reorders and adds review records covering synchronization, parity, issue archival, CI, browser fallback, and documentation automation.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant PlaywrightRunner
  participant resolvePlaywrightBrowserExecutable
  participant FileSystem
  PlaywrightRunner->>resolvePlaywrightBrowserExecutable: Resolve Chromium executable
  resolvePlaywrightBrowserExecutable->>FileSystem: Scan designated browser root
  FileSystem-->>resolvePlaywrightBrowserExecutable: Return newest compatible shell
  resolvePlaywrightBrowserExecutable-->>PlaywrightRunner: Return executable path and provenance

Loading

Possibly related PRs

• BigSimmo/Database#592: Related Chromium executable-path handling in the Playwright runner.
• BigSimmo/Database#705: Earlier Playwright browser-runner changes extended by this fallback implementation.
• BigSimmo/Database#1432: Earlier Playwright preflight functionality extended with container-browser fallback behavior.

Suggested reviewers: cursoragent, claude

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the constrained Chromium fallback implemented by the pull request.
Description check	✅ Passed	The description covers the summary, implementation constraints, verification evidence, risks, rollback, and production impact; applicable template sections are addressed.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

_{Comment @coderabbitai help to get the list of available commands.}

[BigSimmo]

Temporarily paused during the owner-authorized ordered merge sweep so main cannot move between exact-head review and merge. This appears to overlap the reviewed #1504 portability repair; the stronger unique delta will be consolidated before final disposition.

[supabase]

This pull request has been ignored for the connected project sjrfecxgysukkwxsowpy because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[BigSimmo]

@cursoragent resolve merge conflict

[cursor]

Taking a look!

  

[BigSimmo]

@cursoragent resolve failing CI

[cursor]

CI is green and PR #1507 is merged.

What was failing: PR mergeability (real conflict with main in docs/outstanding-issues.md). That was fixed by merging origin/main and keeping #110/#126 archived from main plus #121 archived by this PR.

Exact-head CI then completed successfully — including Static PR checks, Unit coverage, all Production UI shards, and PR required — and the PR merged at 064b4297.