chore(appium): harden local runner with preflights and clearer docs

[nan-li]

Summary

Makes appium/scripts/run-local.sh surface setup problems early with actionable messages (or recover automatically) instead of failing late with cryptic errors, based on issues hit running the suite on a fresh machine. Also clarifies the docs. Local-only: CI calls vpx wdio run directly and does not use this script, so none of these changes affect CI behavior.

run-local.sh

• Fail-fast preflight for appium, the platform driver (xcuitest/uiautomator2), and vpx, plus auto-install of node_modules when missing — each with the exact remediation command.
• Node 26+ workaround: auto-exports WDIO_USE_NATIVE_FETCH=1 when local Node ≥ 26 (webdriverio's undici dispatcher is rejected by Node 26's fetch). CI on Node 24 is unaffected.
• Credentials required: missing ONESIGNAL_APP_ID/ONESIGNAL_API_KEY now fails fast, directing users to the OneSignal app dedicated to Appium tests — not a general/shared app, whose live in-app campaigns can cover the UI and cause misleading "element not displayed" failures.
• iOS simulator/runtime fallback: uses the booted simulator, else the newest installed iOS runtime + a matching device, realigning DEVICE/OS_VERSION/IOS_RUNTIME so the Appium session matches.
• Notification-permission reset: reset_app now uninstalls the app on iOS so the permission prompt reappears (it can't be reset via simctl privacy), which the local-only notification tests depend on.

Docs

• Document the Vite+/vpx prerequisite and Node version expectations.
• Note to use the dedicated Appium test app for credentials.
• Explain CI-vs-local notification-test gating (itSkipBsIos / isBrowserStackIos) and the Enterprise signing-cert reason behind the BrowserStack iOS skips.

Test plan

• Missing appium/driver/vpx: script exits early with the correct install command.
• Missing node_modules: script auto-installs before proceeding.
• Node 26+ host: WDIO_USE_NATIVE_FETCH=1 is set automatically; Node 24 unaffected.
• Missing credentials: script fails fast pointing at the dedicated Appium test app.
• No matching simulator runtime: falls back to booted/newest available and runs.
• iOS push specs after a prior run: notification prompt reappears (no --skip/--skip-reset).
• CI unaffected (this script is not used by CI).

Made with Cursor