metamask.addNetwork()

Switches to a predefined network or adds and activates a custom RPC blockchain network in the MetaMask browser extension.

This command is provided by the built-in metamask plugin and is typically called after metamask.setup() if your test needs to switch networks dynamically.

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.addNetwork():

let metamask = TEST.loadPlugin("metamask")

Usage

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

// 1. Switch to a predefined network by name
metamask.addNetwork("Aurora Mainnet")

// Or pass an object with network.name
metamask.addNetwork({
    network: {
        name: "Aurora Mainnet"
    }
})

// 2. Add and switch to a custom RPC network
metamask.addNetwork({
    name: "Sepolia Testnet",
    rpcURL: "https://rpc.sepolia.org",
    chainID: 11155111,
    currencySymbol: "SEP",
    explorerURL: "https://sepolia.etherscan.io"
})

Parameters

Parameter	Type	Description
network	string | object	Required. The network name string, or an object containing custom RPC parameters.

Network Configuration Object

Property	Type	Description
name	string	Required. Name of the network displayed in MetaMask.
rpcURL	string	Required for custom networks. HTTP/HTTPS JSON-RPC provider endpoint.
chainID	number | string	Required for custom networks. Blockchain network Chain ID.
currencySymbol	string	Required for custom networks. Ticker symbol for the native gas token (e.g. "ETH", "SEP").
explorerURL	string	Optional block explorer URL for tracking transactions.

Examples

Switch to a Predefined Network

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

// Switch network later in the test
metamask.addNetwork("Aurora Mainnet")

Add a Private Testnet RPC

let metamask = TEST.loadPlugin("metamask")
metamask.setup({
    wallet: { passphrase: DATA.test_passphrase }
})

// Add custom local Hardhat node
metamask.addNetwork({
    name: "Hardhat Local",
    rpcURL: "http://127.0.0.1:8545",
    chainID: 31337,
    currencySymbol: "ETH"
})

See Also

• metamask.setup() — Initialize MetaMask wallet and network configuration.
• metamask.open() — Reopen the MetaMask extension tab.
• Testing Web3 Applications with MetaMask — Full guide on Web3 testing with MetaMask.