metamask.setup()

Initializes the MetaMask browser extension for testing by creating a new wallet or importing an existing wallet, and optionally configuring an RPC network.

This command is provided by the built-in metamask plugin and automates the entire MetaMask onboarding flow (terms of service, password creation, seed phrase confirmation, and introductory modal dismissals).

Paid Add-On: MetaMask Test Runner

This command requires running tests on the MetaMask browser runner, which is available as a paid add-on for your UI-licious workspace. Businesses can contact our team at [email protected] or visit uilicious.com/contact-sales to request a trial.

Load the Plugin

The metamask plugin must be loaded in your test script before calling metamask.setup():

let metamask = TEST.loadPlugin("metamask")

Usage

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

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

// 2. Import an existing wallet
metamask.setup({
    wallet: {
        passphrase: "<12 or 24-word seed phrase>"
    }
})

// 3. Import wallet and configure custom RPC network
metamask.setup({
    wallet: {
        passphrase: "<12 or 24-word seed phrase>"
    },
    network: {
        name: "Sepolia Testnet",
        rpcURL: "https://rpc.sepolia.org",
        chainID: 11155111,
        currencySymbol: "SEP"
    }
})

Parameters

Parameter	Type	Description
config	object	Optional configuration object specifying wallet and network settings (see below).

Configuration Object

Property	Type	Description
wallet	object	Optional wallet configuration. If omitted, a brand new wallet is created.
wallet.passphrase	string	The 12- or 24-word secret recovery seed phrase.
network	object | string	Optional network configuration. Can be a predefined network name (e.g. "Aurora Mainnet") or a custom RPC object (see below).
network.name	string	Required. Name of the network.
network.rpcURL	string	JSON-RPC endpoint URL for custom networks.
network.chainID	number | string	Blockchain network Chain ID.
network.currencySymbol	string	Ticker symbol for the native gas token (e.g. "ETH", "SEP").
network.explorerURL	string	Optional block explorer URL (e.g. "https://sepolia.etherscan.io").

Associated Helper Methods

When the metamask plugin is loaded, the following helper methods are also available:

Method	Return Type	Description
metamask.getPassphrase()	string	Returns the recovery seed phrase generated or imported for the active wallet.
metamask.getDevicePassword()	string	Returns the session device password generated by the plugin to unlock MetaMask.

Examples

Create a Fresh Wallet

let metamask = TEST.loadPlugin("metamask")

// Create a new wallet
metamask.setup()

// Print the generated seed phrase to the test report
TEST.log.info("Passphrase: ", metamask.getPassphrase())

Import an Existing Testnet Wallet

let metamask = TEST.loadPlugin("metamask")

metamask.setup({
    wallet: {
        passphrase: DATA.testnet_passphrase
    }
})

Setup with Custom RPC Testnet

let metamask = TEST.loadPlugin("metamask")

metamask.setup({
    wallet: {
        passphrase: DATA.testnet_passphrase
    },
    network: {
        name: "Localhost 8545",
        rpcURL: "http://127.0.0.1:8545",
        chainID: 31337,
        currencySymbol: "ETH"
    }
})

See Also

• Testing Web3 Applications with MetaMask — End-to-end guide on testing dApps and transactions.
• metamask.addNetwork() — Switch or add RPC networks after initial setup.
• metamask.open() — Reopen and unlock the MetaMask extension tab.