|
| 1 | +# MetaMask Connect E2E Tests |
| 2 | + |
| 3 | +This directory contains Appwright-based E2E tests for MetaMask Connect flows. |
| 4 | + |
| 5 | +## Test Files |
| 6 | + |
| 7 | +| File | Description | |
| 8 | +| ------------------------------- | ----------------------------------------------------------- | |
| 9 | +| `connection-evm.spec.js` | Legacy EVM connection via Browser Playground in Chrome | |
| 10 | +| `connection-multichain.spec.js` | Multichain API connection via Browser Playground in Chrome | |
| 11 | +| `connection-wagmi.spec.js` | Wagmi connector via Browser Playground in Chrome | |
| 12 | +| `multichain-rn-connect.spec.js` | **Multichain + Solana via the React Native Playground APK** | |
| 13 | + |
| 14 | +## React Native Playground Setup |
| 15 | + |
| 16 | +The `multichain-rn-connect` test interacts with **two native Android apps** at the |
| 17 | +same time — the MetaMask wallet and the React Native Playground |
| 18 | +(`@metamask/react-native-playground`). The wallet APK is installed by Appwright; |
| 19 | +the playground APK must be **built beforehand**. The test's `beforeAll` hook |
| 20 | +automatically **uninstalls and reinstalls** it on the emulator every run. |
| 21 | + |
| 22 | +### Prerequisites |
| 23 | + |
| 24 | +| Requirement | Details | |
| 25 | +| --------------------------- | ------------------------------------------------------------ | |
| 26 | +| Android emulator | Running and reachable via `adb` | |
| 27 | +| MetaMask wallet APK | Built or pointed to via `buildPath` in `appwright.config.ts` | |
| 28 | +| `connect-monorepo` checkout | Cloned **next to** `metamask-mobile` (same parent directory) | |
| 29 | + |
| 30 | +Expected directory layout: |
| 31 | + |
| 32 | +``` |
| 33 | +Documents/MetaMask/ # or wherever you keep these repos |
| 34 | +├── metamask-mobile/ # this repo |
| 35 | +└── connect-monorepo/ # https://github.com/MetaMask/connect-monorepo |
| 36 | + └── playground/ |
| 37 | + └── react-native-playground/ |
| 38 | +``` |
| 39 | + |
| 40 | +### Build the Playground APK |
| 41 | + |
| 42 | +You must build the release APK **manually** before running the test, and |
| 43 | +**rebuild** whenever you change the playground source code. The release variant |
| 44 | +is required because the debug variant expects a Metro dev server at runtime. |
| 45 | + |
| 46 | +#### First-time setup |
| 47 | + |
| 48 | +Run all five steps below from your terminal. Each command is self-contained |
| 49 | +(no implicit working directory from a previous step). |
| 50 | + |
| 51 | +**Step 1 — Install monorepo dependencies:** |
| 52 | + |
| 53 | +```bash |
| 54 | +cd /path/to/connect-monorepo |
| 55 | +yarn install |
| 56 | +``` |
| 57 | + |
| 58 | +**Step 2 — Build all workspace packages** (so `@metamask/connect-evm`, |
| 59 | +`@metamask/playground-ui`, etc. have their `dist/` output): |
| 60 | + |
| 61 | +```bash |
| 62 | +cd /path/to/connect-monorepo |
| 63 | +yarn build |
| 64 | +``` |
| 65 | + |
| 66 | +**Step 3 — Configure your Infura API key:** |
| 67 | + |
| 68 | +The playground uses Infura RPC endpoints for blockchain requests. Copy the |
| 69 | +example `.env` file and add your key: |
| 70 | + |
| 71 | +```bash |
| 72 | +cd /path/to/connect-monorepo/playground/react-native-playground |
| 73 | +cp .env.example .env |
| 74 | +``` |
| 75 | + |
| 76 | +Then edit `.env` and set your Infura API key: |
| 77 | + |
| 78 | +``` |
| 79 | +EXPO_PUBLIC_INFURA_API_KEY=your_infura_api_key_here |
| 80 | +``` |
| 81 | + |
| 82 | +> You can reuse the same key from `metamask-mobile/.js.env` |
| 83 | +> (`MM_INFURA_PROJECT_ID`). |
| 84 | +
|
| 85 | +**Step 4 — Generate the native Android project** (only needed once, or after |
| 86 | +deleting the `android/` directory): |
| 87 | + |
| 88 | +```bash |
| 89 | +cd /path/to/connect-monorepo/playground/react-native-playground |
| 90 | +npx expo prebuild --platform android |
| 91 | +``` |
| 92 | + |
| 93 | +**Step 5 — Build the release APK:** |
| 94 | + |
| 95 | +```bash |
| 96 | +cd /path/to/connect-monorepo/playground/react-native-playground/android |
| 97 | +./gradlew assembleRelease |
| 98 | +``` |
| 99 | + |
| 100 | +The first build takes ~7 minutes. Subsequent builds are incremental and much |
| 101 | +faster. The output APK will be at: |
| 102 | + |
| 103 | +``` |
| 104 | +connect-monorepo/playground/react-native-playground/android/app/build/outputs/apk/release/app-release.apk |
| 105 | +``` |
| 106 | + |
| 107 | +#### Rebuilding after changes |
| 108 | + |
| 109 | +When you edit the playground source, run the build command again: |
| 110 | + |
| 111 | +```bash |
| 112 | +cd /path/to/connect-monorepo/playground/react-native-playground/android |
| 113 | +./gradlew assembleRelease |
| 114 | +``` |
| 115 | + |
| 116 | +If you also changed shared workspace packages (e.g. `@metamask/playground-ui`), |
| 117 | +rebuild those first: |
| 118 | + |
| 119 | +```bash |
| 120 | +cd /path/to/connect-monorepo |
| 121 | +yarn build |
| 122 | +``` |
| 123 | + |
| 124 | +Then run `./gradlew assembleRelease` as above. |
| 125 | + |
| 126 | +### Automatic Install on Each Test Run |
| 127 | + |
| 128 | +The test's `beforeAll` hook automatically **uninstalls** any existing version |
| 129 | +of the playground from the emulator and **installs** the pre-built release APK. |
| 130 | +This guarantees the device always has the latest APK you built, and avoids |
| 131 | +stale debug-vs-release mismatches. |
| 132 | + |
| 133 | +### Running the Test |
| 134 | + |
| 135 | +Before running, make sure the `mm-connect-android-local` project in |
| 136 | +`tests/appwright.config.ts` matches your local emulator: |
| 137 | + |
| 138 | +```ts |
| 139 | +// tests/appwright.config.ts — adjust to your emulator |
| 140 | +{ |
| 141 | + name: 'mm-connect-android-local', |
| 142 | + use: { |
| 143 | + device: { |
| 144 | + name: 'Samsung Galaxy S24 Ultra', // ← your AVD name |
| 145 | + osVersion: '14', // ← your AVD API level |
| 146 | + }, |
| 147 | + buildPath: 'PATH-TO-BUILD', // ← path to your MetaMask .apk |
| 148 | + }, |
| 149 | +} |
| 150 | +``` |
| 151 | + |
| 152 | +Then run: |
| 153 | + |
| 154 | +```bash |
| 155 | +# From the metamask-mobile root |
| 156 | +yarn run-appwright:mm-connect-android-local |
| 157 | +``` |
| 158 | + |
| 159 | +Or run only the RN playground spec: |
| 160 | + |
| 161 | +```bash |
| 162 | +npx appwright test tests/performance/mm-connect/multichain-rn-connect.spec.js \ |
| 163 | + --project mm-connect-android-local \ |
| 164 | + --config tests/appwright.config.ts |
| 165 | +``` |
| 166 | + |
| 167 | +### What the Test Covers |
| 168 | + |
| 169 | +The `multichain-rn-connect` test validates five areas of the multichain |
| 170 | +MetaMask Connect flow: |
| 171 | + |
| 172 | +1. **Simultaneous multi-chain connection** — connects to Ethereum, Linea, |
| 173 | + Polygon, and Solana in a single session and verifies all scope cards appear. |
| 174 | + |
| 175 | +2. **Read request routing** — invokes `eth_blockNumber` on each EVM chain and |
| 176 | + `getGenesisHash` on Solana. These are handled directly by the RPC layer |
| 177 | + without opening MetaMask. |
| 178 | + |
| 179 | +3. **Write request routing** — invokes `personal_sign` on each EVM chain and |
| 180 | + `signMessage` on Solana. Each write request opens MetaMask for approval, |
| 181 | + allowing the test to verify the request was routed to the correct network. |
| 182 | + |
| 183 | +4. **Session termination** — disconnects via the Multichain SDK |
| 184 | + (`sdk.disconnect()`, the equivalent of `wallet_revokeSession`) and verifies |
| 185 | + the session is fully terminated on both the dApp and wallet sides. |
| 186 | + |
| 187 | +### How It Works |
| 188 | + |
| 189 | +Unlike the browser-based tests (which serve a web dApp in Chrome and use |
| 190 | +WebView context switching), this test operates with **two native Android apps**: |
| 191 | + |
| 192 | +``` |
| 193 | +┌──────────────────┐ deeplink ┌──────────────────┐ |
| 194 | +│ RN Playground │ ───────────► │ MetaMask Wallet │ |
| 195 | +│ (separate APK) │ ◄────────── │ (app under test) │ |
| 196 | +│ │ callback │ │ |
| 197 | +└──────────────────┘ deeplink └──────────────────┘ |
| 198 | +``` |
| 199 | + |
| 200 | +- Both apps stay in the `NATIVE_APP` Appium context (no WebView switching). |
| 201 | +- `device.activateApp(packageId)` switches focus between the two apps. |
| 202 | +- The playground calls `Linking.openURL(metamask://…)` to open MetaMask; |
| 203 | + MetaMask sends a callback deeplink (`multichainrn://…`) to return. |
| 204 | + |
| 205 | +### Troubleshooting |
| 206 | + |
| 207 | +**`Unable to resolve the launchable activity of 'com.anonymous.multichainrnplayground'`** |
| 208 | + |
| 209 | +The playground APK is not installed on the emulator. Follow the |
| 210 | +[Build the Playground APK](#build-the-playground-apk) steps above. |
| 211 | + |
| 212 | +**`Unable to load script. Make sure you're running Metro...`** |
| 213 | + |
| 214 | +You installed the **debug** APK instead of the **release** APK. Debug builds |
| 215 | +require a live Metro dev server. Rebuild with `./gradlew assembleRelease` and |
| 216 | +reinstall (`adb install app/build/outputs/apk/release/app-release.apk`). |
| 217 | + |
| 218 | +**`RPCErr50: 401 on https://mainnet.infura.io/v3/ for method POST`** |
| 219 | + |
| 220 | +The Infura API key is missing or was not inlined during the APK build. Make |
| 221 | +sure the `.env` file in `connect-monorepo/playground/react-native-playground/` |
| 222 | +contains a valid `EXPO_PUBLIC_INFURA_API_KEY`. After updating the key you must |
| 223 | +clear the build cache and rebuild: |
| 224 | + |
| 225 | +```bash |
| 226 | +cd /path/to/connect-monorepo/playground/react-native-playground |
| 227 | +rm -rf android/app/build |
| 228 | +cd android && ./gradlew assembleRelease |
| 229 | +``` |
| 230 | + |
| 231 | +**Playground APK is installed but the test can't interact with it** |
| 232 | + |
| 233 | +Make sure only one emulator is running (`adb devices` should show a single |
| 234 | +entry). If multiple devices are connected, prefix commands with |
| 235 | +`-s emulator-5554` or similar. |
| 236 | + |
| 237 | +**Picker dropdown doesn't select the right method** |
| 238 | + |
| 239 | +The test selects methods by exact text match (`getElementByText`). If the |
| 240 | +method list in the playground changes, update the method names in the spec |
| 241 | +(e.g., `personal_sign`, `getGenesisHash`, `signMessage`). |
| 242 | + |
| 243 | +**MetaMask auto-locks during the test** |
| 244 | + |
| 245 | +The `unlockIfLockScreenVisible` helper detects the lock screen and re-enters |
| 246 | +the password. If the test consistently fails at a late step, consider |
| 247 | +increasing the wallet's auto-lock timeout in Settings before running. |
| 248 | + |
| 249 | +## Browser Playground Tests |
| 250 | + |
| 251 | +The other three spec files (`connection-evm`, `connection-multichain`, |
| 252 | +`connection-wagmi`) use a **local web server** that serves the Browser |
| 253 | +Playground dApp in Chrome. These tests do not require a separate APK — the dApp |
| 254 | +server is started automatically in `test.beforeAll`. |
| 255 | + |
| 256 | +See the [parent README](../README.md) for details on BrowserStack Local setup |
| 257 | +and other run configurations. |
0 commit comments