web-test-wallet-sign

Handle MetaMask signature and transaction popups during Web3 DApp testing - approve signatures, send transactions, call contracts. Detects popup type and handles gas errors.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

This Claude skill automates MetaMask interactions during Web3 DApp testing, enabling seamless handling of signature requests and transaction popups. It solves the common bottleneck of manual wallet intervention in automated QA pipelines by auto-detecting popup types, managing gas errors, and providing detailed execution logs for Playwright-based testing environments.

Use Cases

  • Automating end-to-end (E2E) testing for decentralized applications (DApps) that require frequent wallet signatures (personal_sign, signTypedData).
  • Simulating user transactions and contract calls in a CI/CD pipeline to ensure smart contract interactions work as expected without manual oversight.
  • Testing application resilience by simulating edge cases such as transaction rejections or insufficient gas errors.
  • Streamlining the QA process for DeFi platforms where multiple approval and confirmation steps are required for a single user flow.
nameweb-test-wallet-sign
descriptionHandle MetaMask signature and transaction popups during Web3 DApp testing - approve signatures, send transactions, call contracts. Detects popup type and handles gas errors.
licenseMIT
compatibilityNode.js 18+, Playwright
authorAI Agent
version1.0.0
allowed-toolsBash Read

Wallet Sign

Handle MetaMask signature requests and transaction popups during Web3 DApp testing.

When to Use This Skill

  • During web-test execution when MetaMask popup appears
  • When DApp requests signature (personal_sign, signTypedData)
  • When DApp sends transaction (eth_sendTransaction)
  • When DApp calls contract (write operations)

Prerequisites

  1. web-test-wallet-setup completed
  2. web-test-wallet-connect completed (wallet connected to DApp)
  3. Browser session active with wallet

Quick Start

SKILL_DIR="<path-to-this-skill>"

# Handle any MetaMask popup (auto-detects type)
node $SKILL_DIR/scripts/wallet-sign-helper.js wallet-sign --wallet --headed --keep-open

1. Sign Message (personal_sign)

  • Action: Auto-approve
  • Risk: Low (read-only, no gas)
  • Result: Always succeeds

2. Sign Typed Data (signTypedData_v4)

  • Action: Auto-approve
  • Risk: Low (read-only, no gas)
  • Result: Always succeeds

3. Send Transaction (eth_sendTransaction)

  • Action: Check gas, then approve/reject
  • Risk: Medium (costs gas, transfers value)
  • Result: Fails if insufficient gas

4. Contract Call (write operations)

  • Action: Check gas, then approve/reject
  • Risk: Medium (costs gas)
  • Result: Fails if insufficient gas

Instructions

Detect and Handle Popup

SKILL_DIR="<path-to-this-skill>"

# Auto-detect popup type and handle appropriately
node $SKILL_DIR/scripts/wallet-sign-helper.js wallet-sign --wallet --headed --keep-open

Output for Signature:

{
  "success": true,
  "type": "signature",
  "subtype": "personal_sign",
  "action": "approved",
  "message": "Signature request approved"
}

Output for Transaction (success):

{
  "success": true,
  "type": "transaction",
  "action": "approved",
  "txHash": "0x...",
  "message": "Transaction sent successfully"
}

Output for Transaction (gas error):

{
  "success": false,
  "type": "transaction",
  "action": "failed",
  "error": "insufficient_gas",
  "message": "Transaction failed: insufficient funds for gas"
}

Force Reject

# Reject any popup (for testing negative flows)
node $SKILL_DIR/scripts/wallet-sign-helper.js wallet-reject --wallet --headed --keep-open

Check Popup Status

# Check if there's a pending popup without acting
node $SKILL_DIR/scripts/wallet-sign-helper.js wallet-check --wallet --headed --keep-open

Command Reference

Command Description
wallet-sign Auto-detect and handle popup (approve signatures, check gas for tx)
wallet-reject Reject any pending popup
wallet-check Check popup status without acting

Error Handling

Gas Errors (Test Failure)

When a transaction or contract call fails due to insufficient gas:

{
  "success": false,
  "type": "transaction",
  "error": "insufficient_gas",
  "details": {
    "required": "0.01 ETH",
    "available": "0.001 ETH"
  },
  "action": "test_failed",
  "message": "Insufficient funds for gas - test marked as FAILED"
}

Important: Gas errors should fail the current test case in web-test.

Network Errors

{
  "success": false,
  "error": "network_error",
  "message": "Failed to broadcast transaction"
}

Integration with web-test

During test execution, when a MetaMask popup is detected:

  1. Pause test execution
  2. Call wallet-sign
  3. Check result:
    • If success: true → continue test
    • If success: false with error: insufficient_gas → FAIL test
    • If success: false with other errors → retry or fail based on test config
  • web-test-wallet-setup - Must complete first
  • web-test-wallet-connect - Must connect before signing
  • web-test - Main test runner that uses this skill
  • web-test-cleanup - Clean up after testing

MetaMask UI Detection

The skill detects popup type by analyzing the MetaMask notification page:

  • Signature Request: Contains "Sign" button, "Message" text, no gas info
  • Transaction: Contains "Confirm" button, gas fee display, value transfer
  • Contract Call: Contains "Confirm" button, gas fee, function call data

Notes

  • Signatures (personal_sign, signTypedData) never fail - always approve
  • Transactions and contract calls check for gas errors before approval
  • If gas error detected, popup is rejected and test is marked as failed
  • Screenshots are taken at each step for debugging