tomevault-io Wallet Connect
Connect MetaMask wallet to a Web3 DApp.
CRITICAL RULE - USE dapp-click WITH SELECTORS
┌────────────────────────────────────────────────────────────────────┐
│ ALWAYS USE dapp-click COMMAND FOR CLICKING BUTTONS! │
│ │
│ ✅ CORRECT (Use text/css/id selectors): │
│ dapp-click "Connect Wallet" --wallet --headed --keep-open │
│ dapp-click "MetaMask" --wallet --headed --keep-open │
│ dapp-click --css "button[data-testid='connect']" │
│ dapp-click --id "connect-btn" --wallet --headed --keep-open │
│ │
│ dapp-click uses text/CSS/ID selectors which are RELIABLE. │
│ It will: │
│ 1. Try text selector first (e.g., "Connect Wallet") │
│ 2. Try CSS selector (e.g., "button.connect-btn") │
│ 3. Try ID selector (e.g., "#connect-btn") │
│ │
└────────────────────────────────────────────────────────────────────┘
When to Use This Skill
- As a test case (WALLET-001) - Connecting wallet is itself a testable feature
- As a precondition - When other test cases require wallet to be connected
- When wallet gets disconnected - Re-establish connection during test execution
Usage Modes
Mode 1: As a Test Case
When tests/test-cases.yaml contains a wallet connection test case (e.g., WALLET-001), this skill is invoked to execute that test.
Mode 2: As a Precondition
When a test case has preconditions: [WALLET-001 passed] or similar, the test executor should:
- Check if wallet is already connected
- If not, invoke this skill to connect the wallet first
Prerequisites
- web-test-wallet-setup must have been executed if
web3.enabled: truein config - DApp is running and accessible
- Wallet extension is initialized with funds (if needed)
Quick Start
SKILL_DIR="<path-to-this-skill>"
# Navigate to DApp with wallet
node $SKILL_DIR/scripts/wallet-connect-helper.js wallet-navigate "http://localhost:3000" --wallet --headed --keep-open
# Click Connect Wallet button using text selector (PREFERRED METHOD)
node $SKILL_DIR/scripts/wallet-connect-helper.js dapp-click "Connect Wallet" --wallet --headed --keep-open
# If wallet modal appears, click MetaMask option
node $SKILL_DIR/scripts/wallet-connect-helper.js dapp-click "MetaMask" --wallet --headed --keep-open
# Approve connection in MetaMask popup
node $SKILL_DIR/scripts/wallet-connect-helper.js wallet-approve --wallet --headed --keep-open
# Verify connection
node $SKILL_DIR/scripts/wallet-connect-helper.js screenshot after-connect.jpg --wallet --headed --keep-open
Instructions
Step 1: Navigate to DApp
SKILL_DIR="<path-to-this-skill>"
DAPP_URL="http://localhost:3000" # Your DApp URL
# Navigate to DApp with wallet extension loaded
node $SKILL_DIR/scripts/wallet-connect-helper.js wallet-navigate "$DAPP_URL" --wallet --headed --keep-open
Expected Output:
{
"success": true,
"url": "http://localhost:3000",
"screenshot": "dapp-home.jpg"
}
Step 2: Click Connect Wallet Button
Use dapp-click with text selector - this is the PREFERRED method:
SKILL_DIR="<path-to-this-skill>"
# Try common button text labels
node $SKILL_DIR/scripts/wallet-connect-helper.js dapp-click "Connect Wallet" --wallet --headed --keep-open
# If that doesn't work, try other common labels:
# dapp-click "Connect" --wallet --headed --keep-open
# dapp-click "Sign In" --wallet --headed --keep-open
# dapp-click "Connect wallet" --wallet --headed --keep-open
Common Connect Button Labels (try in order):
- "Connect Wallet"
- "Connect"
- "Connect wallet"
- "Sign In"
- "Login"
If text selector fails, use CSS selector:
# Try CSS selectors
node $SKILL_DIR/scripts/wallet-connect-helper.js dapp-click --css "button[data-testid='connect']" --wallet --headed --keep-open
node $SKILL_DIR/scripts/wallet-connect-helper.js dapp-click --css ".connect-button" --wallet --headed --keep-open
ONLY as last resort - use coordinates with fallback:
# Take screenshot first to find coordinates
node $SKILL_DIR/scripts/wallet-connect-helper.js screenshot before-connect.jpg --wallet --headed --keep-open
# Then use dapp-click with fallback coordinates
node $SKILL_DIR/scripts/wallet-connect-helper.js dapp-click "Connect Wallet" --fallback-x 900 --fallback-y 50 --wallet --headed --keep-open
Step 3: Handle Wallet Selection Modal
Many DApps show a wallet selection modal (Rainbow Kit, Privy, etc.):
Use dapp-click to select MetaMask option:
SKILL_DIR="<path-to-this-skill>"
# Try common MetaMask button labels
node $SKILL_DIR/scripts/wallet-connect-helper.js dapp-click "MetaMask" --wallet --headed --keep-open
# If that doesn't work, try other common labels:
# dapp-click "Injected Wallet" --wallet --headed --keep-open
# dapp-click "Browser Wallet" --wallet --headed --keep-open
# dapp-click "Injected" --wallet --headed --keep-open
Common Modal Options (try in order):
- "MetaMask"
- "Injected Wallet"
- "Browser Wallet"
- "Injected"
- "Rabby"
If text selector fails, use fallback coordinates:
# Take screenshot to find coordinates
node $SKILL_DIR/scripts/wallet-connect-helper.js screenshot wallet-modal.jpg --wallet --headed --keep-open
# Use dapp-click with fallback
node $SKILL_DIR/scripts/wallet-connect-helper.js dapp-click "MetaMask" --fallback-x 400 --fallback-y 300 --wallet --headed --keep-open
Step 4: Approve Connection in MetaMask
SKILL_DIR="<path-to-this-skill>"
# Auto-approve the MetaMask connection popup
node $SKILL_DIR/scripts/wallet-connect-helper.js wallet-approve --wallet --headed --keep-open
What this does:
- Detects MetaMask popup window
- Takes screenshot of popup
- Clicks "Connect" or "Confirm" button
- Waits for popup to close
Step 5: Verify Connection
SKILL_DIR="<path-to-this-skill>"
# Take screenshot to verify wallet is connected
node $SKILL_DIR/scripts/wallet-connect-helper.js screenshot after-connect.jpg --wallet --headed --keep-open
Verification Criteria:
- Wallet address (0x...) visible on page
- "Connect Wallet" button replaced with address/avatar
- Account menu or profile icon appears
Step 6: Handle Failures
If connection fails, retry up to 3 times:
# Attempt 1 failed? Try again
node $SKILL_DIR/scripts/wallet-connect-helper.js wallet-navigate "$DAPP_URL" --wallet --headed --keep-open
# ... repeat steps 2-6
# After 3 failures, STOP and report error
Complete Flow Example
SKILL_DIR="<path-to-this-skill>"
DAPP_URL="http://localhost:3000"
# 1. Navigate to DApp
node $SKILL_DIR/scripts/wallet-connect-helper.js wallet-navigate "$DAPP_URL" --wallet --headed --keep-open
# 2. Click Connect Wallet using text selector (PREFERRED)
node $SKILL_DIR/scripts/wallet-connect-helper.js dapp-click "Connect Wallet" --wallet --headed --keep-open
# Output: { "success": true, "method": "text selector: button:has-text(\"Connect Wallet\")" }
# 3. If wallet modal appears, click MetaMask option
node $SKILL_DIR/scripts/wallet-connect-helper.js wait 1000 --wallet --headed --keep-open
node $SKILL_DIR/scripts/wallet-connect-helper.js dapp-click "MetaMask" --wallet --headed --keep-open
# Output: { "success": true, "method": "text selector: text=\"MetaMask\"" }
# 4. Approve in MetaMask
node $SKILL_DIR/scripts/wallet-connect-helper.js wallet-approve --wallet --headed --keep-open
# 5. Verify connection
node $SKILL_DIR/scripts/wallet-connect-helper.js screenshot connected.jpg --wallet --headed --keep-open
# AI verifies: "Wallet address 0x1234...abcd visible - SUCCESS"
Fallback Example (when text selectors fail)
# If dapp-click "Connect Wallet" fails, use fallback coordinates:
node $SKILL_DIR/scripts/wallet-connect-helper.js screenshot find-button.jpg --wallet --headed --keep-open
# AI analyzes screenshot: "Connect button at x=900, y=50"
node $SKILL_DIR/scripts/wallet-connect-helper.js dapp-click "Connect Wallet" --fallback-x 900 --fallback-y 50 --wallet --headed --keep-open
Command Reference
Primary Commands (Use These!)
| Command | Description |
|---|---|
dapp-click "<text>" |
PREFERRED - Click element by text (e.g., "Connect Wallet", "MetaMask") |
dapp-click --css "<selector>" |
Click element by CSS selector |
dapp-click "<text>" --fallback-x X --fallback-y Y |
Click with coordinate fallback |
wallet-navigate <url> |
Navigate to DApp with wallet extension |
wallet-approve |
Auto-approve MetaMask popup |
Secondary Commands
| Command | Description |
|---|---|
wallet-switch-network <name> |
Switch network |
wallet-get-address |
Get connected address |
screenshot [name] |
Take screenshot for AI analysis |
wait <ms> |
Wait milliseconds |
dapp-click Examples
# By text (try multiple labels)
dapp-click "Connect Wallet" --wallet --headed --keep-open
dapp-click "MetaMask" --wallet --headed --keep-open
# By CSS selector
dapp-click --css "button[data-testid='connect']" --wallet --headed --keep-open
dapp-click --css ".connect-button" --wallet --headed --keep-open
# With fallback coordinates (when selectors fail)
dapp-click "Connect" --fallback-x 900 --fallback-y 50 --wallet --headed --keep-open
Troubleshooting
"Connect button not found"
- Try different text labels: "Connect Wallet", "Connect", "Connect wallet", "Sign In"
- Use CSS selector:
dapp-click --css "button.connect-btn" - Add wait time before clicking:
wait 2000 - As last resort, take screenshot and use fallback coordinates
"Wallet modal doesn't appear"
- dapp-click may not have found the button - check output for method used
- If it says "coordinates", the text selector failed - try different text or CSS
"MetaMask popup not detected"
- Extension may not be properly loaded
- Check
./test-output/extensions/metamask/exists
"Connection rejected"
- Check if DApp requires specific network
- Switch network before connecting
Related Skills
- web-test-wallet-setup - Required first if
web3.enabled: truein config - web-test - Executes test cases (may call this skill as precondition)
- web-test-report - Generate report after testing
- web-test-cleanup - Clean up after testing
Next Steps
After wallet connection is verified:
- Proceed to web-test skill to execute test cases
- Handle wallet transaction popups during tests with
wallet-approve
Notes
- Keep browser open (
--keep-open) for subsequent test steps - Always use
--wallet --headedflags for wallet operations - Max 3 retry attempts for connection
- If all retries fail, stop testing and report error
Converted and distributed by TomeVault — claim your Tome and manage your conversions.