UI-licious Documentation

Appearance

Testing Web3 Applications with MetaMask ​

Decentralized applications (dApps), DeFi platforms, and NFT marketplaces rely on browser extension wallets like MetaMask to authenticate user identities and sign blockchain transactions.

UI-licious provides native support for Web3 testing by pairing a dedicated MetaMask browser runner with a built-in metamask plugin (TEST.loadPlugin("metamask")). Together, they eliminate the complexity of automating browser extensions, enabling you to test wallet onboarding, network switching, and transaction confirmations in clean, reliable scripts.

MetaMask Test Runner Add-On

Running tests with the MetaMask browser extension requires the MetaMask Test Runner, available as an add-on for your UI-licious workspace.

To request a trial or add this to your subscription, contact our team at [email protected] or visit uilicious.com/contact-sales.

How Web3 Testing Works in UI-licious ​

Automating a Web3 test in UI-licious consists of two parts:

  1. The Test Runner Environment: In UI-licious Studio, select MetaMask from the browser dropdown (or specify --browser metamask via the CLI). The test browser launches with the official MetaMask extension installed and active.
  2. The metamask Plugin: In your test script, load the built-in plugin with let metamask = TEST.loadPlugin("metamask") to automate onboarding, seed phrase imports, RPC configuration, and dialog interactions.

Recommendation: Use Testnets & Disposable Wallets

Never connect wallets containing real cryptocurrency or mainnet assets to automated test runs. Instead, use disposable testnet wallets funded via faucets on public testnets (e.g. Sepolia, Holesky) or private local testnets (e.g. Hardhat, Anvil, BuildBear).

Step 1: Initialize the Wallet ​

At the start of your test script, load the plugin and initialize MetaMask using metamask.setup().

Option A: Create a Fresh Wallet ​

If your test does not require a pre-funded wallet, call setup() without arguments. The plugin automatically accepts terms, sets a temporary device password, verifies the recovery phrase, and dismisses onboarding walkthroughs:

js
// Load the plugin
let metamask = TEST.loadPlugin("metamask")

// Create a new wallet on Ethereum Mainnet
metamask.setup()

If you need the recovery phrase for debugging, you can retrieve it with metamask.getPassphrase():

js
TEST.log.info("Wallet Passphrase: ", metamask.getPassphrase())

Option B: Import an Existing Testnet Wallet ​

If your test needs a wallet with pre-funded testnet tokens, pass the secret recovery seed phrase to setup():

js
let metamask = TEST.loadPlugin("metamask")

metamask.setup({
    wallet: {
        passphrase: DATA.test_wallet_passphrase // 12 or 24-word seed phrase
    }
})

Step 2: Configure a Testnet or Custom RPC ​

By default, MetaMask connects to Ethereum Mainnet. To run transactions on a testnet, provide the network details during setup():

js
let metamask = TEST.loadPlugin("metamask")

metamask.setup({
    wallet: {
        passphrase: DATA.test_wallet_passphrase
    },
    network: {
        name: "Sepolia Testnet",
        rpcURL: "https://rpc.sepolia.org",
        chainID: 11155111,
        currencySymbol: "SEP",
        explorerURL: "https://sepolia.etherscan.io"
    }
})

If you need to switch networks later in the test, call metamask.addNetwork():

js
metamask.addNetwork({
    name: "Sepolia Testnet",
    rpcURL: "https://rpc.sepolia.org",
    chainID: 11155111,
    currencySymbol: "SEP"
})

Step 3: Connect Wallet to Your dApp ​

Once MetaMask is initialized, navigate to your dApp and trigger the wallet connection modal:

js
// Navigate to the dApp
I.goTo("https://app.example.com")

// Trigger wallet connection
I.click("Connect Wallet")
I.click("MetaMask")

When the dApp requests access, MetaMask opens a pop-up window. Use standard UI-licious commands to approve the connection:

js
// Select account and authorize connection
I.click("Next")
I.click("Connect")

// Confirm that your dApp updates to the connected state
I.see("Connected")

Step 4: Approve On-Chain Transactions ​

When an action triggers a smart contract call, token transfer, or swap, MetaMask displays a confirmation dialog with gas fee estimates. Approve the transaction using I.click():

js
// Trigger a transaction within your dApp
I.click("Transfer Tokens")
I.fill("Recipient Address", DATA.recipient_address)
I.fill("Amount", "0.05")
I.click("Submit Transfer")

// Approve transaction in the MetaMask dialog
I.click("Confirm")

// Validate transaction receipt on the application
I.see("Transaction Confirmed")

Complete Example ​

Here is a complete end-to-end test script:

js
// 1. Initialize MetaMask with an existing testnet wallet and custom RPC
let metamask = TEST.loadPlugin("metamask")

metamask.setup({
    wallet: {
        passphrase: DATA.test_wallet_passphrase
    },
    network: {
        name: "Sepolia Testnet",
        rpcURL: "https://rpc.sepolia.org",
        chainID: 11155111,
        currencySymbol: "SEP"
    }
})

// 2. Navigate to dApp and initiate wallet connection
I.goTo("https://app.example.com")
I.click("Connect Wallet")
I.click("MetaMask")

// 3. Authorize connection in MetaMask dialog
I.click("Next")
I.click("Connect")
I.see("Connected")

// 4. Initiate payment / contract transaction
I.fill("Recipient", DATA.recipient_address)
I.fill("Amount", "0.01")
I.click("Send Payment")

// 5. Approve transaction in MetaMask dialog
I.click("Confirm")

// 6. Assert success on the dApp
I.see("Payment Sent Successfully")

See Also ​