mobile-wallet-e2e

Mobile (non-desktop) QA/SDET showcase for Web3 apps:

• A WalletConnect v2 mobile regression matrix (what to test on iOS/Android)
• A minimal, CI-friendly automation sample: Appium drives Android Chrome; a deterministic Mock Wallet (Node) pairs via WalletConnect and signs a message, so the flow is stable and does not depend on real wallet app UI.

What This Demonstrates

• Mobile web automation with Appium + UiAutomator2
• WalletConnect v2 session lifecycle: display_uri → pair → approve → request/response
• Deterministic crypto assertions: signature is verified (no “just clicks”)
• A practical mobile WalletConnect test matrix for real wallets (MetaMask/Rainbow/etc.)

Architecture (high-level)

flowchart TB
  subgraph Local["Local / CI runner"]
    Runner["pnpm mobile:e2e"]
    Vite["Vite demo dApp (:5173)"]
    Appium["Appium server (:4723)"]
    Test["WDIO test (Node)"]
    Mock["Mock Wallet (Node)"]

    Runner --> Vite
    Runner --> Appium
    Runner --> Test
    Test --> Mock
  end

  subgraph Android["Android emulator"]
    Chrome["Chrome (Appium-driven)"]
  end

  Appium -->|WebDriver| Chrome
  Chrome -->|loads| Vite
  Chrome -->|reads wc: URI + shows signature| Test

  Relay["WalletConnect relay"]
  Vite <--> Relay
  Mock <--> Relay

  Test --> Verify["ethers verifyMessage"]

Loading

Repo Layout

• dapp/: Vite demo dApp (WalletConnect connect + sign message)
• src/mock-wallet.ts: WalletConnect v2 mock wallet (approve + personal_sign)
• tests/mobile/wc-connect-and-sign.ts: Appium test (Android Chrome) + on-chain-like signature verification
• docs/walletconnect-mobile-regression-matrix.md: Mobile WalletConnect regression matrix

Quick Start (Local)

1) Prereqs

• Node 20+ (Node 24 is fine)
• Android Studio + Android SDK + an emulator image with Chrome
• Appium 2 + driver:
  • pnpm exec appium driver install uiautomator2

2) Install

pnpm install

3) Configure WalletConnect Project ID

WalletConnect v2 uses a project id for the relay.

1. Copy .env.example to .env
2. Set WC_PROJECT_ID

4) Run the mobile E2E

Start an Android emulator first, then:

pnpm mobile:e2e

This will:

1. Start the demo dApp (Vite on :5173)
2. Start Appium server (with chromedriver_autodownload enabled)
3. Run the Appium test:
   • open dApp in Android Chrome (http://10.0.2.2:5173)
   • fetch WalletConnect pairing URI from the page
   • pair + approve via Mock Wallet
   • request personal_sign, verify recovered address

CI (Optional)

See .github/workflows/mobile-e2e.yml for a manual-dispatch workflow.

You need to add GitHub secret: WC_PROJECT_ID.

Notes

• This repo intentionally avoids automating a real wallet app UI in CI (too flaky). The matrix doc covers real-wallet scenarios; you can add “real wallet” tests later as @manual suites.
• If you want to showcase real mobile wallet automation anyway, see docs/real-wallet-appium-notes.md.