hermes-config/skills/software-development/web-ui-repair/references/reference-build-parity-and-live-validation.md

Reference-build parity + live runtime validation (ShopProQuote-style migrations)

Use this when the user asks to make a target web app behave the same as a known-good reference build (especially after backend swaps like Firebase → PocketBase).

1) Fastest parity path for HTML interaction bugs

If target pages have accumulated inline fallbacks (onclick handlers, duplicate modal managers, auth guard snippets) and behavior diverges from reference:

1. Back up target HTML files (*.bak.*).
2. Copy reference HTML files over target for the relevant pages.
3. Apply only deterministic backend bootstrap rewrites (e.g. src="firebase.js" → src="pocketbase.js").
4. Verify parity by diffing with normalization (reference content + the one allowed rewrite).

This is usually faster and safer than manually removing dozens of injected handlers one-by-one.

2) Evidence-first runtime validation checklist

After parity sync, run real click-path checks and report explicit pass/fail evidence per action:

• Dashboard: open/close key modals (financial, tasks, create task)
• Repair Orders: tab switching (active/history/quote generator)
• Quote form: clear/save click-path (look for API request signals)
• Appointments: create modal open/submit/close + created item visible
• Customers: search/filter clear and edit/open flows (or report blocked by dataset)

Evidence format should include:

• button id clicked
• modal/content visibility before/after
• URL after navigation/login
• request counts or concrete DOM text signals

3) Environment workaround: Playwright on Ubuntu 26

On Ubuntu 26, python -m playwright install chromium may fail with unsupported-browser errors.

Reliable fallback used in-session:

1. python3 -m pip install playwright
2. python3 -m playwright install chrome
3. Launch with channel Chrome:

browser = p.chromium.launch(channel='chrome', headless=True, args=['--ignore-certificate-errors'])
page = browser.new_page(ignore_https_errors=True)

Use this for local HTTPS self-signed targets like https://127.0.0.1:3447.

4) Flake-resistant validation for edit/delete flows

UI-only assertions are not enough for list/card actions (especially appointments/customers edit/delete). Use a two-layer check:

1. Network assertion: capture the expected request (e.g., DELETE /api/collections/appointments/records/{id}) and status.
2. State assertion: verify post-action backend state (GET returns 404 for deleted id) plus UI disappearance.

Also use robust targeting for action menus:

• re-query visible cards right before click (avoid stale handles)
• open action menu, then wait for concrete menu item visibility
• after click, wait for either success toast OR API-state change

If a run is inconsistent, report as automation flake unless backend state disproves deletion.

5) Reporting discipline

If blocked (auth/data/permissions), mark checks as blocked with exact reason. Do not claim pass without concrete runtime evidence.