Wallet connections fail in predictable places: an unsupported browser, an expired session, a broken mobile deep link, or a network mismatch discovered only after launch. This guide provides a reusable WalletConnect integration testing checklist for desktop, mobile, QR, deep-link, NFT checkout, and Web3 payment flows, including a compatibility matrix, state-transition tests, troubleshooting steps, and a release sign-off template.
Overview
A reliable Web3 wallet integration is more than displaying a “Connect wallet” button. Your application must handle the complete connection lifecycle: presenting available options, opening the selected wallet, establishing a session, requesting accounts and networks, reacting to user decisions, and recovering when the session ends unexpectedly.
Wallet behavior can vary by wallet, operating system, browser, device, supported chain, and integration library version. Treat every combination as a test case rather than assuming that a successful desktop connection proves mobile compatibility. This is especially important for NFT payments, NFT checkout, and applications that use a crypto wallet for NFTs to sign messages or approve transactions.
Before testing, record the exact inputs used by the build:
- Wallet integration or SDK version and its configuration.
- Supported chains, network identifiers, methods, and events.
- Desktop browsers, mobile browsers, operating systems, and wallet applications in scope.
- Whether the flow uses a QR code, a mobile deep link, an in-app browser, or a browser extension.
- Expected behavior for account changes, network changes, rejection, disconnection, and session expiration.
Keep test transactions separate from production funds. Use a controlled test environment where possible, confirm every destination and network before signing, and never ask testers to share seed phrases or private keys.
Checklist by scenario
Desktop browser and extension flow
- Open the application in each supported desktop browser and confirm that the connection modal renders without layout or accessibility failures.
- Test a browser-extension wallet and a QR-based wallet path if both are offered.
- Verify that the selected account appears correctly and that the application does not silently substitute a previously connected account.
- Request a signature and a transaction separately. Confirm that the interface explains the purpose of each request before the wallet prompt opens.
- Reject the request in the wallet and verify that the application returns to a recoverable state rather than showing indefinite loading.
- Change accounts in the wallet, then confirm that the application updates its account-dependent data and permissions.
- Change networks, including to an unsupported network, and verify that the application explains the required action.
Mobile QR flow
- Display the QR code at a size that is scannable on another phone and provide a clear fallback for users who cannot scan it.
- Scan with at least two supported wallet applications or wallet versions where practical.
- Confirm that the QR payload is current, expires as intended, and cannot be reused after the session is closed.
- Lock the phone or switch applications during connection, then return to the browser and verify the resulting state.
- Test cancellation from the wallet and timeout from the browser.
- Confirm that a user can start a new connection without refreshing the page after a failed attempt.
Mobile deep-link flow
- Test from a mobile browser, not only from an in-app browser.
- Verify that the correct wallet opens when the user taps the deep-link option.
- Test both an installed wallet and a device without that wallet installed. The latter should receive a clear installation or alternative-connection message.
- Return to the original browser after approving, rejecting, or abandoning the request.
- Test when the browser tab is backgrounded, suspended, or reloaded during the handoff.
- Confirm that repeated taps do not create duplicate connection attempts or confusing stacked prompts.
NFT checkout and payment flow
- Connect the wallet before checkout and also begin checkout while disconnected.
- Verify collection, token, amount, chain, recipient, and fee information before the signing prompt.
- Test insufficient funds, rejected signatures, rejected transactions, pending transactions, and completed transactions.
- Confirm that the checkout does not mark an NFT as paid based solely on a wallet approval or client-side event.
- Test a wallet connected to the wrong network and provide an explicit recovery path.
- After a transaction completes, refresh the page and confirm that the order state remains consistent.
Compatibility matrix
Use a simple matrix to make coverage visible. Mark each cell as Pass, Fail, Blocked, or Not in scope, and attach a reproducible issue for every failure.
| Environment | Connect | Sign | Network change | Reject and recover | Disconnect |
|---|---|---|---|---|---|
| Desktop browser and extension | |||||
| Desktop browser and QR | |||||
| Mobile browser and deep link | |||||
| Mobile in-app browser |
What to double-check
Connection states and events
Document the expected application state for each stage: idle, connecting, connected, signing, transaction pending, rejected, disconnected, and expired. Then test every transition deliberately. A spinner should not continue indefinitely after a user closes the wallet, and a stale connected state should not remain after an account or network change.
Check that listeners are registered once and cleaned up when the page or component is unmounted. Duplicate listeners can produce repeated notifications, duplicate API calls, or conflicting UI states. Also test a page refresh and a second browser tab. Decide whether an existing session should be restored and how the application should behave when the account differs between tabs.
Session expiration and recovery
Do not treat session expiration as an exceptional edge case. Simulate it by closing the wallet, disconnecting the session, clearing relevant permissions in the test wallet, or waiting for the configured timeout where available. The application should:
- Detect that the session is no longer usable.
- Clear stale account and chain data from the interface.
- Explain what happened without exposing technical secrets.
- Offer a fresh connection path.
- Prevent signing or payment actions until a valid session is restored.
Deep-link troubleshooting
| Symptom | Likely test area | Action |
|---|---|---|
| Wallet does not open | Link format, device handling, or installed-wallet detection | Capture the device, browser, operating system, and exact link behavior; test the fallback QR path. |
| Wallet opens but browser does not resume | Return URL or browser lifecycle handling | Test backgrounding, locking, and reopening the original tab before retrying. |
| Approval succeeds but app remains disconnected | Session event handling or stale state | Inspect event processing and verify that a reload or reconnect does not create duplicate sessions. |
| Wrong network appears after connection | Chain mapping or network-change handling | Compare configured identifiers with the wallet's reported network and test the unsupported-network message. |
| Repeated prompts appear | Duplicate click handlers or concurrent requests | Disable the initiating control while pending and cancel or reconcile earlier attempts. |
For payment-specific failures, pair this work with the crypto checkout failure troubleshooting guide. If your application relies on backend confirmation, test the complete event and reconciliation path using the crypto payment API webhook testing guide.
Common mistakes
- Testing only one wallet: A successful result in one wallet does not establish multichain wallet support or mobile compatibility.
- Testing only the happy path: Rejection, timeout, account switching, network switching, and interrupted deep links are core flows, not optional cases.
- Assuming connection equals authorization: A connected address may still need a fresh signature, transaction approval, or server-side verification.
- Trusting client-side payment status: Confirm transaction details through the application’s intended backend or verification process before fulfilling an order.
- Ignoring stale sessions: Cached account data can display the wrong address or permit an action against the wrong network.
- Using vague error messages: Tell the user whether to reconnect, switch networks, reject a pending prompt, or try another method.
- Updating libraries without regression testing: Re-run the matrix after integration-library, wallet, browser, or mobile operating-system changes.
For broader wallet controls, review the crypto wallet security audit checklist for NFT payment teams. Keep secrets out of logs, avoid requesting unnecessary permissions, and ensure test data cannot be confused with production transactions.
When to revisit
Revisit this checklist before each major release and whenever the workflow or tools change. Trigger a focused regression test when you add a wallet, chain, browser, mobile operating system, deep-link method, checkout feature, or integration-library version. Also repeat the relevant scenarios after a serious connection failure, a change to session handling, or a report that users are abandoning QR or mobile flows.
At release sign-off, record:
- Build identifier, integration version, and configuration revision.
- Wallets, devices, browsers, operating systems, and chains tested.
- Pass, fail, blocked, and out-of-scope results for each matrix cell.
- Known limitations, severity, owner, and planned resolution.
- Evidence for payment confirmation, session recovery, and rejected-request handling.
- Final approval from engineering and the product or operations owner.
Store the matrix with the release record so the next test cycle starts from known coverage rather than memory. This makes WalletConnect integration testing a repeatable part of Web3 release management instead of a last-minute check after an NFT checkout or payment issue reaches users.