Skip to content
Casaconomy Book

Playwright mobile safe-area emulation extended to all viewports

Playwright mobile safe-area emulation extended to all viewports

Status: Delivered
CAS: CAS-2812
Delivered: 2026-05-14
PRs: #753

What’s new

The Playwright visual test lane now accurately emulates iPhone and iPad safe-area insets (the notch / home-indicator zones) across all mobile viewports — not just iPhone 14 Pro. This means the automated layout tests can catch the “dead band” bug class (elements placed in the safe zone but invisible on real hardware) on every device profile we test.

How to use it

The visual lane runs automatically as part of CI on any PR that touches UI code. No engineer action required.

For local verification:

Terminal window
npx playwright test --config playwright.visual.config.ts
# update baselines after a deliberate layout change:
npx playwright test --config playwright.visual.config.ts --update-snapshots

The assertSafeAreaBottomAnchor assertion now validates all mobile viewports (iphone14pro, iphoneSE, ipad). It catches elements that sit in the 0–34 px gap above the home indicator — the dead band where taps register but nothing is visible on real glass.

What changed under the hood

  • src/components/MobileNavbar.tsx, App.tsx — safe-area values now use var(--safe-area-inset-*, env(..., 0px)) CSS custom properties. On iOS the env() fallback wins natively; in Playwright the CSS vars are injected by the test helper, giving the test full control.
  • tests/helpers/tauri-mock.ts — injects --safe-area-inset-bottom: 34px / --safe-area-inset-top: 47px on all mobile viewports (≤768 px) before page scripts run.
  • tests/visual/visual-sanity.spec.ts — assertSafeAreaBottomAnchor logic corrected: flags gapToBottom > 0 && gapToBottom <= 34 (nav floating in dead band) instead of the old wrong condition. Assertion expanded from iPhone 14 Pro only to all mobile viewport projects.
  • AGENTS.md — visual lane commands and a pre-PR rule for UI changes added.

Why we built it

CAS-2585 revealed a live dead-band regression on iPhone SE that the existing test missed because the safe-area assertion only ran on iPhone 14 Pro. Extending the assertion to all mobile viewports means the same class of bug can’t ship again on any supported device size.

Known limitations / follow-on work

  • WKWebView-native contentInsetAdjustmentBehavior behaviour cannot be tested at this layer — it requires an iOS Simulator or physical device and is covered by Eivind’s UX walk.
  • Screenshot baselines are soft assertions (expect.soft): drift is reported but does not block merge. Loki handles the authoritative pixel-diff gate.