@deeeed/metamask-harness 0.36.0 → 0.38.0

package/library/actions/extension/assets/send.mjs

@@ -0,0 +1,104 @@
+import { dataTestId } from '../platform/cdp.mjs';
+
+export async function visible(page, selector) {
+  return page.evaluate(`(() => {
+    const element = document.querySelector(${JSON.stringify(selector)});
+    if (!element) return false;
+    const style = getComputedStyle(element);
+    const rect = element.getBoundingClientRect();
+    return style.display !== 'none' && style.visibility !== 'hidden' && rect.width > 0 && rect.height > 0;
+  })()`);
+}
+
+export async function waitFor(page, predicate, message, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const value = await predicate();
+    if (value) return value;
+    await new Promise((resolve) => setTimeout(resolve, 150));
+  }
+  throw new Error(message);
+}
+
+export async function tokenRow(page, symbol) {
+  const marker = `mm-harness-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  return page.evaluate(`(() => {
+    const symbol = ${JSON.stringify(symbol.toUpperCase())};
+    const marker = ${JSON.stringify(marker)};
+    for (const row of document.querySelectorAll('[data-testid="multichain-token-list-button"]')) {
+      const amount = String(row.querySelector('[data-testid="multichain-token-list-item-value"]')?.innerText || '').replace(/\\s+/gu, ' ').trim();
+      const observed = amount.match(/\\b([A-Za-z][A-Za-z0-9]{1,11})$/u)?.[1]?.toUpperCase();
+      if (observed !== symbol) continue;
+      const style = getComputedStyle(row);
+      const rect = row.getBoundingClientRect();
+      if (style.display === 'none' || style.visibility === 'hidden' || rect.width <= 0 || rect.height <= 0) continue;
+      row.setAttribute('data-mm-harness-target', marker);
+      return {
+        selector: '[data-mm-harness-target="' + marker + '"]',
+        name: String(row.querySelector('[data-testid="multichain-token-list-item-token-name"]')?.innerText || '').trim(),
+        amount,
+        fiat: String(row.querySelector('[data-testid="multichain-token-list-item-secondary-value"]')?.innerText || '').trim(),
+      };
+    }
+    return null;
+  })()`);
+}
+
+export async function bodyState(page) {
+  return page.evaluate(`(() => ({
+    route: location.hash,
+    text: String(document.body?.innerText || '').replace(/\\s+/gu, ' ').trim().slice(0, 20_000),
+  }))()`);
+}
+
+export async function transactionState(page) {
+  return page.evaluate(`(async () => {
+    const hooks = globalThis.stateHooks || {};
+    const root = (await hooks.getCleanAppState?.()) || hooks.store?.getState?.() || null;
+    const transactions = root?.metamask?.transactions;
+    if (!Array.isArray(transactions)) return { available: false, transactions: [] };
+    return {
+      available: true,
+      transactions: transactions.slice(0, 500).map((transaction) => ({
+        id: transaction?.id == null ? null : String(transaction.id),
+        hash: transaction?.hash == null ? null : String(transaction.hash),
+        status: transaction?.status == null ? null : String(transaction.status),
+        chainId: transaction?.chainId == null ? null : String(transaction.chainId),
+        recipient: transaction?.txParams?.to == null ? null : String(transaction.txParams.to),
+        time: Number(transaction?.time ?? 0),
+      })).filter((transaction) => transaction.id),
+    };
+  })()`);
+}
+
+export async function activityItem(page, symbol, amount) {
+  const marker = `mm-harness-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  return page.evaluate(`(() => {
+    const symbol = ${JSON.stringify(symbol.toUpperCase())};
+    const amount = ${JSON.stringify(String(amount))};
+    const marker = ${JSON.stringify(marker)};
+    for (const row of document.querySelectorAll('[data-testid="activity-list-item"]')) {
+      const label = String(row.innerText || row.textContent || '').replace(/\\s+/gu, ' ').trim();
+      if (!label.toUpperCase().includes(symbol) || (amount.toLowerCase() !== 'max' && !label.includes(amount))) continue;
+      const style = getComputedStyle(row);
+      const rect = row.getBoundingClientRect();
+      if (style.display === 'none' || style.visibility === 'hidden' || rect.width <= 0 || rect.height <= 0) continue;
+      row.setAttribute('data-mm-harness-target', marker);
+      return { selector: '[data-mm-harness-target="' + marker + '"]', label: label.slice(0, 1000) };
+    }
+    return null;
+  })()`);
+}
+
+export const selectors = {
+  send: dataTestId('eth-overview-send'),
+  nativeSend: dataTestId('coin-overview-send'),
+  recipient: dataTestId('recipient-address-input'),
+  amount: dataTestId('send-amount-input'),
+  continue: dataTestId('send-continue-button'),
+  alert: dataTestId('send-alert-modal-acknowledge-button'),
+  confirm: dataTestId('confirm-footer-button'),
+  cancel: dataTestId('confirm-footer-cancel-button'),
+  activity: dataTestId('bottom-nav-activity'),
+  home: dataTestId('bottom-nav-home'),
+};

package/library/actions/extension/assets/set_custom_gas.mjs

@@ -0,0 +1,56 @@
+import { dataTestId, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+import { bodyState, visible, waitFor } from './send.mjs';
+
+runAdapter(async (input) => withExtensionPage(input, async (page) => {
+  const gasLimit = String(input.node?.gas_limit || '').trim();
+  const timeoutMs = Number(input.node?.timeout_ms ?? 30_000);
+  if (!/^\d+$/u.test(gasLimit) || Number(gasLimit) <= 0) {
+    throw new Error('metamask.assets.set_custom_gas requires a positive integer gas_limit.');
+  }
+  const edit = dataTestId('edit-gas-fee-icon');
+  const advanced = dataTestId('gas-option-advanced');
+  const modal = dataTestId('gas-fee-advanced-eip1559-modal');
+  const gasInput = '#gas-input';
+  const maxFeeInput = '#max-base-fee-input';
+  const priorityFeeInput = '#priority-fee-input';
+  const save = dataTestId('gas-fee-modal-save-button');
+  if (!(await visible(page, modal))) {
+    await waitFor(page, async () => {
+      if (await visible(page, modal)) return true;
+      const control = (await visible(page, advanced)) ? advanced : (await visible(page, edit)) ? edit : null;
+      if (control) {
+        try {
+          await page.click(control);
+        } catch {
+          return null;
+        }
+      }
+      return null;
+    }, 'Advanced gas editor did not become visible.', timeoutMs);
+  }
+  await waitFor(page, () => visible(page, gasInput), 'Gas limit input did not become visible.', timeoutMs);
+  const fees = await page.evaluate(`(() => ({
+    maxFee: document.querySelector(${JSON.stringify(maxFeeInput)})?.value || '',
+    priorityFee: document.querySelector(${JSON.stringify(priorityFeeInput)})?.value || '',
+  }))()`);
+  if (!(Number(fees.priorityFee) > 0)) {
+    const maxFee = Number(fees.maxFee);
+    if (!(maxFee > 0)) throw new Error('Advanced gas editor did not expose a positive max base fee.');
+    await page.setInput(priorityFeeInput, String(Math.min(maxFee / 2, 0.01)));
+  }
+  await page.setInput(gasInput, gasLimit);
+  await waitFor(page, () => page.evaluate(`document.querySelector(${JSON.stringify(save)})?.disabled === false`), 'Custom gas values did not enable Save.', timeoutMs);
+  await page.click(save);
+  const state = await waitFor(page, async () => {
+    const current = await bodyState(page);
+    return !(await visible(page, modal)) && /Speed Advanced/u.test(current.text) ? current : null;
+  }, 'Custom gas was not applied to the confirmation.', timeoutMs);
+  return {
+    action: input.action,
+    gasLimit,
+    maxFeeGwei: fees.maxFee,
+    priorityFeeGwei: Number(fees.priorityFee) > 0 ? fees.priorityFee : String(Math.min(Number(fees.maxFee) / 2, 0.01)),
+    ...state,
+    proofPath: 'trusted-pointer-visible-ui',
+  };
+}));

package/library/actions/extension/assets/set_token_visibility.mjs

@@ -0,0 +1,129 @@
+import { dataTestId, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+
+const OPTIONS = dataTestId('asset-list-control-bar-action-button');
+const MANAGE = dataTestId('manageTokens__button');
+const PAGE = dataTestId('token-management-page');
+const SEARCH = dataTestId('token-management-search-input');
+const BACK = dataTestId('token-management-header-back-button');
+const LOW_VALUE = dataTestId('low-value-assets-toggle');
+
+async function visible(page, selector) {
+  return page.evaluate(`(() => {
+    const element = document.querySelector(${JSON.stringify(selector)});
+    if (!element) return false;
+    const style = getComputedStyle(element);
+    const rect = element.getBoundingClientRect();
+    return style.display !== 'none' && style.visibility !== 'hidden' && rect.width > 0 && rect.height > 0;
+  })()`);
+}
+
+async function waitFor(page, predicate, message, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const value = await predicate();
+    if (value) return value;
+    await page.evaluate('new Promise((resolve) => setTimeout(resolve, 150))');
+  }
+  throw new Error(message);
+}
+
+async function matchingToggle(page, query) {
+  return page.evaluate(`(() => {
+    const query = ${JSON.stringify(query.toLowerCase())};
+    const candidates = [...document.querySelectorAll('[data-testid^="token-management-cell-search-"][data-testid$="-toggle-control"]')];
+    for (const element of candidates) {
+      const testId = element.getAttribute('data-testid');
+      const row = document.querySelector('[data-testid="' + testId.slice(0, -'-toggle-control'.length) + '"]');
+      const label = String(row?.innerText || element.innerText || '').replace(/\\s+/gu, ' ').trim().slice(0, 500);
+      const words = label.toLowerCase().split(/[^a-z0-9]+/u).filter(Boolean);
+      if (!words.includes(query) && !label.toLowerCase().includes(query)) continue;
+      const style = getComputedStyle(element);
+      const rect = element.getBoundingClientRect();
+      if (style.display === 'none' || style.visibility === 'hidden' || rect.width <= 0 || rect.height <= 0) continue;
+      return {
+        testId,
+        label,
+        enabled: Boolean(element.querySelector('.toggle-button--on')),
+      };
+    }
+    return null;
+  })()`);
+}
+
+async function homeToken(page, query) {
+  return page.evaluate(`(() => {
+    const query = ${JSON.stringify(query.toLowerCase())};
+    for (const row of document.querySelectorAll('[data-testid="multichain-token-list-button"]')) {
+      const name = String(row.querySelector('[data-testid="multichain-token-list-item-token-name"]')?.innerText || '').replace(/\\s+/gu, ' ').trim();
+      const amount = String(row.querySelector('[data-testid="multichain-token-list-item-value"]')?.innerText || '').replace(/\\s+/gu, ' ').trim();
+      const symbol = amount.match(/\\b([A-Za-z][A-Za-z0-9]{1,11})$/u)?.[1] || '';
+      if (symbol.toLowerCase() === query || name.toLowerCase().includes(query)) {
+        return { name, symbol: symbol.toUpperCase(), amount };
+      }
+    }
+    return null;
+  })()`);
+}
+
+runAdapter(async (input) => withExtensionPage(input, async (page) => {
+  const query = String(input.node?.query || '').trim();
+  if (!query || query.length > 50) {
+    throw new Error('metamask.assets.set_token_visibility requires query with 1-50 characters.');
+  }
+  if (typeof input.node?.visible !== 'boolean') {
+    throw new Error('metamask.assets.set_token_visibility requires visible=true or visible=false.');
+  }
+  const requested = input.node.visible;
+  const requireUnchanged = input.node?.require_unchanged === true;
+  const timeoutMs = Number(input.node?.timeout_ms ?? 45_000);
+
+  if (!(await visible(page, MANAGE))) await page.click(OPTIONS);
+  await waitFor(page, () => visible(page, MANAGE), 'Manage tokens did not become visible.', timeoutMs);
+  await page.click(MANAGE);
+  await waitFor(page, () => visible(page, PAGE), 'Token management did not open.', timeoutMs);
+  await page.setInput(SEARCH, query);
+  const before = await waitFor(
+    page,
+    () => matchingToggle(page, query),
+    `Token management returned no visible result for ${query}.`,
+    timeoutMs,
+  );
+  if (requireUnchanged && before.enabled !== requested) {
+    throw new Error(`${query} token visibility did not persist as ${requested ? 'enabled' : 'disabled'}.`);
+  }
+  if (before.enabled !== requested) {
+    await page.click(dataTestId(before.testId));
+  }
+  const after = await waitFor(
+    page,
+    async () => {
+      const state = await matchingToggle(page, query);
+      return state?.enabled === requested ? state : null;
+    },
+    `${query} token visibility did not become ${requested ? 'enabled' : 'disabled'}.`,
+    timeoutMs,
+  );
+  await page.click(BACK);
+  await waitFor(page, () => visible(page, OPTIONS), 'Token list did not reopen.', timeoutMs);
+
+  if (requested && (await visible(page, LOW_VALUE))) {
+    const expanded = await page.evaluate(`document.querySelector(${JSON.stringify(LOW_VALUE)})?.getAttribute('aria-expanded') === 'true'`);
+    if (!expanded) await page.click(LOW_VALUE);
+  }
+  const token = requested
+    ? await waitFor(page, () => homeToken(page, query), `${query} did not appear in the token list.`, timeoutMs)
+    : await homeToken(page, query);
+  if (!requested && token) throw new Error(`${query} remained visible after disabling it.`);
+
+  return {
+    action: input.action,
+    query,
+    requested,
+    requireUnchanged,
+    changed: before.enabled !== after.enabled,
+    searchResult: after.label,
+    toggleTestId: after.testId,
+    token,
+    proofPath: 'trusted-pointer-visible-ui',
+  };
+}));

package/library/actions/extension/assets/verify_sorting.mjs

@@ -0,0 +1,89 @@
+import { dataTestId, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+
+const TOGGLE = dataTestId('sort-by-popover-toggle');
+const ALPHABETICAL = dataTestId('sortByAlphabetically__button');
+const DECLINING = dataTestId('sortByDecliningBalance__button');
+
+async function readRows(page) {
+  return page.evaluate(`(() => [...document.querySelectorAll('[data-testid="multichain-token-list-button"]')]
+    .filter((element) => {
+      const style = getComputedStyle(element);
+      const rect = element.getBoundingClientRect();
+      return style.display !== 'none' && style.visibility !== 'hidden' && rect.width > 0 && rect.height > 0;
+    })
+    .map((element) => ({
+      name: String(element.querySelector('[data-testid="multichain-token-list-item-token-name"]')?.innerText || '').replace(/\\s+/gu, ' ').trim(),
+      fiat: String(element.querySelector('[data-testid="multichain-token-list-item-secondary-value"]')?.innerText || '').replace(/\\s+/gu, ' ').trim(),
+    })))()`);
+}
+
+function fiatNumber(value) {
+  const sanitized = String(value).replace(/[^0-9.-]/gu, '');
+  if (!/\d/u.test(sanitized)) return null;
+  const parsed = Number(sanitized);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function assertAlphabetical(rows) {
+  const names = rows.map((row) => row.name).filter(Boolean);
+  if (names.length < 2) {
+    throw new Error(`Asset A-Z sorting requires at least two named rows, but observed ${names.length}.`);
+  }
+  const expected = [...names].sort((left, right) => left.localeCompare(right, 'en', { sensitivity: 'base' }));
+  if (names.some((name, index) => name !== expected[index])) {
+    throw new Error(`Asset names are not sorted A-Z: ${names.join(', ')}.`);
+  }
+}
+
+function assertDeclining(rows) {
+  const values = rows.map((row) => fiatNumber(row.fiat)).filter((value) => value !== null);
+  if (values.length < 2) {
+    throw new Error(`Asset balance sorting requires at least two comparable fiat rows, but observed ${values.length}.`);
+  }
+  if (values.some((value, index) => index > 0 && values[index - 1] < value)) {
+    throw new Error(`Asset fiat values are not sorted high-low: ${values.join(', ')}.`);
+  }
+}
+
+async function choose(page, selector) {
+  const isVisible = async () => page.evaluate(`(() => {
+    const element = document.querySelector(${JSON.stringify(selector)});
+    if (!element) return false;
+    const style = getComputedStyle(element);
+    const rect = element.getBoundingClientRect();
+    return style.display !== 'none' && style.visibility !== 'hidden' && rect.width > 0 && rect.height > 0;
+  })()`);
+  if (!(await isVisible())) await page.click(TOGGLE);
+  const deadline = Date.now() + 5_000;
+  while (!(await isVisible())) {
+    if (Date.now() >= deadline) throw new Error('Asset sort menu did not become visible.');
+    await page.evaluate('new Promise((resolve) => setTimeout(resolve, 100))');
+  }
+  await page.click(selector);
+  await page.evaluate('new Promise((resolve) => setTimeout(resolve, 500))');
+}
+
+runAdapter(async (input) => withExtensionPage(input, async (page) => {
+  if (!String(await page.evaluate('location.hash')).startsWith('#/')) {
+    throw new Error('metamask.assets.verify_sorting requires the wallet home token list.');
+  }
+
+  await choose(page, ALPHABETICAL);
+  const alphabetical = await readRows(page);
+  assertAlphabetical(alphabetical);
+
+  await choose(page, DECLINING);
+  const declining = await readRows(page);
+  assertDeclining(declining);
+
+  return {
+    action: input.action,
+    source: 'visible-ui',
+    platform: 'extension',
+    surface: 'token-list',
+    alphabetical: alphabetical.map((row) => row.name),
+    decliningFiat: declining.map((row) => row.fiat),
+    restoredSort: 'declining-balance',
+    proofPath: 'trusted-pointer-visible-ui',
+  };
+}));

package/library/actions/extension/networks/add_chainlist.mjs

@@ -0,0 +1,94 @@
+import { dataTestId, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+import {
+  findNetworkItem,
+  openNetworkManager,
+  selectHomeNetwork,
+  waitFor,
+} from './custom_network.mjs';
+
+const ADD_CUSTOM = dataTestId('networks-page-add-custom-network-button');
+const ADD_CHAINLIST = dataTestId('network-form-add-from-chainlist');
+const CHAINLIST_SEARCH = dataTestId('networks-page-chainlist-search');
+const CHAINLIST_ROW = '[data-testid="networks-page-chainlist-network"]';
+const SAVE = dataTestId('page-container-footer-next');
+
+runAdapter(async (input) => withExtensionPage(input, async (page) => {
+  const network = String(input.node?.network || '').trim();
+  const query = String(input.node?.query || network).trim();
+  const chainId = Number(input.node?.chain_id);
+  const symbol = String(input.node?.symbol || '').trim().toUpperCase();
+  const timeoutMs = Number(input.node?.timeout_ms ?? 60_000);
+  if (!network || !query || !Number.isInteger(chainId) || chainId <= 0 || !symbol) {
+    throw new Error('metamask.networks.add_chainlist requires network, query, positive chain_id, and symbol.');
+  }
+
+  const chainlistOpen = await page.evaluate(`Boolean(document.querySelector(${JSON.stringify(CHAINLIST_SEARCH)}))`);
+  if (!chainlistOpen) await openNetworkManager(page, timeoutMs);
+  let item = chainlistOpen ? null : await findNetworkItem(page, network, chainId);
+  let added = false;
+  if (!item) {
+    if (!chainlistOpen) {
+      await page.click(ADD_CUSTOM);
+      await waitFor(page, () => page.evaluate(`Boolean(document.querySelector(${JSON.stringify(ADD_CHAINLIST)}))`), 'Add from ChainList did not become visible.', timeoutMs);
+    }
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      if (await page.evaluate(`Boolean(document.querySelector(${JSON.stringify(CHAINLIST_SEARCH)}))`)) break;
+      if (await page.evaluate(`Boolean(document.querySelector(${JSON.stringify(ADD_CHAINLIST)}))`)) {
+        await page.click(ADD_CHAINLIST);
+      }
+      await page.evaluate('new Promise((resolve) => setTimeout(resolve, 500))');
+    }
+    await waitFor(page, () => page.evaluate(`Boolean(document.querySelector(${JSON.stringify(CHAINLIST_SEARCH)}))`), 'ChainList network search did not become visible.', timeoutMs);
+    await page.setInput(`${CHAINLIST_SEARCH} input`, query);
+    const row = await waitFor(page, () => page.evaluate(`(() => {
+      const expectedName = ${JSON.stringify(network.toLowerCase())};
+      const expectedSymbol = ${JSON.stringify(symbol.toLowerCase())};
+      const expectedId = ${JSON.stringify(String(chainId))};
+      for (const element of document.querySelectorAll(${JSON.stringify(CHAINLIST_ROW)})) {
+        const text = String(element.innerText || element.textContent || '').replace(/\\s+/gu, ' ').trim();
+        const normalized = text.toLowerCase();
+        if (!normalized.includes(expectedName) || !normalized.includes('symbol: ' + expectedSymbol) || !normalized.includes('id: ' + expectedId)) continue;
+        element.setAttribute('data-mm-harness-chainlist-row', 'true');
+        return { selector: '[data-mm-harness-chainlist-row="true"]', text: text.slice(0, 500) };
+      }
+      return null;
+    })()`), `${network} (ID ${chainId}) did not appear in ChainList results.`, timeoutMs);
+    await page.click(row.selector);
+    let enabledSince = 0;
+    await waitFor(page, async () => {
+      const enabled = await page.evaluate(`(() => {
+        const button = document.querySelector(${JSON.stringify(SAVE)});
+        return Boolean(button && !button.disabled && button.getAttribute('aria-disabled') !== 'true');
+      })()`);
+      if (!enabled) {
+        enabledSince = 0;
+        return false;
+      }
+      if (enabledSince === 0) enabledSince = Date.now();
+      return Date.now() - enabledSince >= 1500;
+    }, 'ChainList network Save did not remain enabled after prefilling.', timeoutMs);
+    await waitFor(page, async () => {
+      const stillOpen = await page.evaluate(`Boolean(document.querySelector(${JSON.stringify(SAVE)}))`);
+      if (!stillOpen) return true;
+      await page.click(SAVE);
+      await page.evaluate('new Promise((resolve) => setTimeout(resolve, 500))');
+      return false;
+    }, 'ChainList network Save did not close the prefilled form.', timeoutMs);
+    item = await waitFor(page, () => findNetworkItem(page, network, chainId), `${network} did not appear after the ChainList save.`, timeoutMs);
+    added = true;
+  }
+
+  await page.click(dataTestId('page-header-back-button'));
+  await waitFor(page, () => page.evaluate(`Boolean(document.querySelector(${JSON.stringify(dataTestId('sort-by-networks'))}))`), 'Wallet home did not reopen after ChainList network management.', timeoutMs);
+  await selectHomeNetwork(page, network, chainId, timeoutMs);
+  return {
+    action: input.action,
+    network,
+    chainId,
+    symbol,
+    query,
+    added,
+    item,
+    proofPath: 'trusted-pointer-chainlist-ui',
+  };
+}));

package/library/actions/extension/networks/add_custom.mjs

@@ -0,0 +1,123 @@
+import { dataTestId, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+import {
+  findNetworkItem,
+  openNetworkManager,
+  selectHomeNetwork,
+  semanticButton,
+  semanticButtonOrNull,
+  waitFor,
+} from './custom_network.mjs';
+
+runAdapter(async (input) => withExtensionPage(input, async (page) => {
+  const network = String(input.node?.network || '').trim();
+  const rpcUrl = String(input.node?.rpc_url || '').trim();
+  const chainId = Number(input.node?.chain_id);
+  const symbol = String(input.node?.symbol || '').trim();
+  const explorerUrl = String(input.node?.explorer_url || '').trim();
+  const timeoutMs = Number(input.node?.timeout_ms ?? 60_000);
+  if (!network || !/^https?:\/\//u.test(rpcUrl) || !Number.isInteger(chainId) || chainId <= 0 || !symbol) {
+    throw new Error('metamask.networks.add_custom requires network, rpc_url, positive chain_id, and symbol.');
+  }
+
+  await openNetworkManager(page, timeoutMs);
+  let item = await findNetworkItem(page, network, chainId);
+  let added = false;
+  if (!item) {
+    await page.click(dataTestId('networks-page-add-custom-network-button'));
+    await waitFor(
+      page,
+      () => page.evaluate(`Boolean(document.querySelector(${JSON.stringify(dataTestId('network-form-network-name'))}))`),
+      'Custom network form did not open.',
+      timeoutMs,
+    );
+    await page.setInput(dataTestId('network-form-network-name'), network);
+    await page.setInput(dataTestId('network-form-chain-id'), chainId);
+    await page.setInput(dataTestId('network-form-ticker-input'), symbol);
+
+    await page.evaluate('new Promise((resolve) => setTimeout(resolve, 1000))');
+    let addRpc;
+    for (let attempt = 0; attempt < 3 && !addRpc; attempt += 1) {
+      await page.click(dataTestId('test-add-rpc-drop-down'));
+      await page.evaluate('new Promise((resolve) => setTimeout(resolve, 250))');
+      addRpc = await semanticButtonOrNull(page, 'Add RPC URL');
+    }
+    if (!addRpc) throw new Error('Visible button "Add RPC URL" was not found after opening the RPC menu.');
+    await page.click(addRpc);
+    await page.setInput(dataTestId('rpc-url-input-test'), rpcUrl);
+    await page.click(dataTestId('page-container-footer-next'));
+    await waitFor(
+      page,
+      () => page.evaluate(`!document.querySelector(${JSON.stringify(dataTestId('rpc-url-input-test'))})`),
+      'RPC URL form did not close after adding the URL.',
+      timeoutMs,
+    );
+
+    if (explorerUrl) {
+      await page.evaluate('new Promise((resolve) => setTimeout(resolve, 1000))');
+      let addExplorer;
+      for (let attempt = 0; attempt < 3 && !addExplorer; attempt += 1) {
+        await page.click(dataTestId('test-explorer-drop-down'));
+        await page.evaluate('new Promise((resolve) => setTimeout(resolve, 250))');
+        addExplorer = await semanticButtonOrNull(page, 'Add a block explorer URL');
+      }
+      if (!addExplorer) throw new Error('Visible button "Add a block explorer URL" was not found after opening the explorer menu.');
+      await page.click(addExplorer);
+      await page.setInput(dataTestId('explorer-url-input'), explorerUrl);
+      await page.click(await semanticButton(page, 'Add URL'));
+      await waitFor(
+        page,
+        () => page.evaluate(`!document.querySelector(${JSON.stringify(dataTestId('explorer-url-input'))})`),
+        'Block explorer form did not close after adding the URL.',
+        timeoutMs,
+      );
+    }
+
+    let enabledSince = 0;
+    await waitFor(page, async () => {
+      const enabled = await page.evaluate(`(() => {
+        for (const element of document.querySelectorAll('button')) {
+          const text = String(element.innerText || element.textContent || '').replace(/\\s+/gu, ' ').trim();
+          const style = getComputedStyle(element);
+          const rect = element.getBoundingClientRect();
+          if (text === 'Save' && !element.disabled && element.getAttribute('aria-disabled') !== 'true' && style.display !== 'none' && style.visibility !== 'hidden' && rect.width > 0 && rect.height > 0) return true;
+        }
+        return false;
+      })()`);
+      if (!enabled) {
+        enabledSince = 0;
+        return false;
+      }
+      if (enabledSince === 0) enabledSince = Date.now();
+      return Date.now() - enabledSince >= 1500;
+    }, 'Custom network save did not remain enabled after RPC validation.', timeoutMs);
+    const save = await semanticButton(page, 'Save');
+    await page.click(save);
+    item = await waitFor(
+      page,
+      () => findNetworkItem(page, network, chainId),
+      `${network} did not appear in the network manager after save.`,
+      timeoutMs,
+    );
+    added = true;
+  }
+
+  await page.click(dataTestId('page-header-back-button'));
+  await waitFor(
+    page,
+    () => page.evaluate(`Boolean(document.querySelector(${JSON.stringify(dataTestId('sort-by-networks'))}))`),
+    'Wallet home did not reopen after network management.',
+    timeoutMs,
+  );
+  await selectHomeNetwork(page, network, chainId, timeoutMs);
+  return {
+    action: input.action,
+    network,
+    chainId,
+    symbol,
+    rpcUrl,
+    explorerUrl: explorerUrl || null,
+    added,
+    item,
+    proofPath: 'trusted-pointer-visible-ui',
+  };
+}));