@deeeed/metamask-harness 0.37.0 → 0.38.0

package/library/actions/shared/perps/visible-state.mjs

@@ -0,0 +1,354 @@
+const SURFACES = new Set([
+  'auto',
+  'home',
+  'market-list',
+  'market-details',
+  'order-entry',
+  'activity',
+  'funds',
+]);
+const FEATURES = new Set([
+  'activity',
+  'balance',
+  'chart',
+  'long-short',
+  'market-list',
+  'order-entry',
+  'price',
+  'price-change',
+  'stats',
+]);
+
+function boundedInteger(value, fallback, minimum, maximum, name) {
+  const resolved = value == null ? fallback : Number(value);
+  if (!Number.isInteger(resolved) || resolved < minimum || resolved > maximum) {
+    throw new Error(
+      `metamask.perps.read_visible_state ${name} must be an integer from ${minimum} to ${maximum}.`,
+    );
+  }
+  return resolved;
+}
+
+function stringList(value, name, maximum = 100) {
+  if (value == null) return [];
+  if (!Array.isArray(value)) {
+    throw new Error(`metamask.perps.read_visible_state ${name} must be an array.`);
+  }
+  const values = Array.from(new Set(value.map((entry) => String(entry).trim()).filter(Boolean)));
+  if (values.length > maximum) {
+    throw new Error(`metamask.perps.read_visible_state ${name} accepts at most ${maximum} values.`);
+  }
+  return values;
+}
+
+export function resolveVisibleStateOptions(node = {}) {
+  const surface = String(node.surface ?? 'auto').toLowerCase();
+  if (!SURFACES.has(surface)) {
+    throw new Error(
+      `metamask.perps.read_visible_state received unsupported surface ${JSON.stringify(surface)}.`,
+    );
+  }
+  const market = node.market == null ? undefined : String(node.market).trim().toUpperCase();
+  if (node.market != null && !market) {
+    throw new Error('metamask.perps.read_visible_state market must not be empty.');
+  }
+  return {
+    surface,
+    market,
+    includeOffscreen: node.include_offscreen !== false,
+    maxItems: boundedInteger(node.max_items, 100, 1, 200, 'max_items'),
+    minimumMarketCount: boundedInteger(
+      node.minimum_market_count,
+      0,
+      0,
+      200,
+      'minimum_market_count',
+    ),
+    maximumMarketCount: boundedInteger(
+      node.maximum_market_count,
+      200,
+      0,
+      200,
+      'maximum_market_count',
+    ),
+    requireTestIds: stringList(node.require_test_ids, 'require_test_ids'),
+    forbidTestIds: stringList(node.forbid_test_ids, 'forbid_test_ids'),
+    direction: node.direction == null ? undefined : String(node.direction).trim().toLowerCase(),
+    orderType: node.order_type == null ? undefined : String(node.order_type).trim().toLowerCase(),
+    amount: node.amount == null ? undefined : String(node.amount),
+    percent: node.percent == null ? undefined : String(node.percent),
+    leverage: node.leverage == null ? undefined : String(node.leverage),
+    autoClose: node.auto_close == null ? undefined : Boolean(node.auto_close),
+    submitEnabled: node.submit_enabled == null ? undefined : Boolean(node.submit_enabled),
+    requireValidationText: stringList(node.require_validation_text, 'require_validation_text', 20),
+    minimumPositionCount: boundedInteger(node.minimum_position_count, 0, 0, 200, 'minimum_position_count'),
+    maximumPositionCount: boundedInteger(node.maximum_position_count, 200, 0, 200, 'maximum_position_count'),
+    minimumOrderCount: boundedInteger(node.minimum_order_count, 0, 0, 200, 'minimum_order_count'),
+    maximumOrderCount: boundedInteger(node.maximum_order_count, 200, 0, 200, 'maximum_order_count'),
+    minimumActivityCount: boundedInteger(node.minimum_activity_count, 0, 0, 200, 'minimum_activity_count'),
+    requireNoHorizontalOverflow: node.require_no_horizontal_overflow === true,
+    requireFeatures: stringList(node.require_features, 'require_features').map((feature) => {
+      if (!FEATURES.has(feature)) {
+        throw new Error(
+          `metamask.perps.read_visible_state received unsupported feature ${JSON.stringify(feature)}.`,
+        );
+      }
+      return feature;
+    }),
+  };
+}
+
+function text(value) {
+  if (typeof value !== 'string') return undefined;
+  const normalized = value.replace(/\s+/gu, ' ').trim();
+  return normalized ? normalized.slice(0, 500) : undefined;
+}
+
+function equalNumericText(actual, expected) {
+  const left = String(actual ?? '').trim();
+  const right = String(expected ?? '').trim();
+  if (!left || !right) return left === right;
+  const leftNumber = Number(left);
+  const rightNumber = Number(right);
+  return Number.isFinite(leftNumber) && Number.isFinite(rightNumber)
+    ? leftNumber === rightNumber
+    : left === right;
+}
+
+function normalizedItem(source) {
+  const testId = text(source?.testId ?? source?.test_id ?? source?.identifier);
+  if (!testId) return undefined;
+  return {
+    testId,
+    ...(text(source?.label ?? source?.value) ? { label: text(source?.label ?? source?.value) } : {}),
+    ...(text(source?.role ?? source?.type) ? { role: text(source?.role ?? source?.type) } : {}),
+    enabled: source?.enabled !== false,
+    visible: source?.visible !== false,
+  };
+}
+
+function marketFromTestId(testId) {
+  if (testId.startsWith('market-row-ticker-')) return undefined;
+  for (const prefix of ['perps-watchlist-', 'explore-markets-', 'perps-market-row-item-', 'market-row-']) {
+    if (!testId.startsWith(prefix)) continue;
+    const raw = testId.slice(prefix.length);
+    if ((prefix === 'explore-markets-' || prefix === 'market-row-') && raw.startsWith('xyz-')) {
+      return `XYZ:${raw.slice(4).toUpperCase()}`;
+    }
+    return raw.toUpperCase();
+  }
+  return undefined;
+}
+
+function classifySurface(route, testIds) {
+  const joined = [...testIds].join('\n');
+  if (/\/perps\/trade\//u.test(route)) {
+    return 'order-entry';
+  }
+  if (/\/perps\/market\//u.test(route)) {
+    return 'market-details';
+  }
+  if (/perps-(?:order-entry|order-view|trade)/u.test(joined)) return 'order-entry';
+  if (/perps-(?:market-detail|market-details|pro-market)/u.test(joined)) return 'market-details';
+  if (/market-list-view|perps-market-list/u.test(joined)) return 'market-list';
+  if (/perps-(?:activity|transactions)/u.test(joined)) return 'activity';
+  if (/perps-(?:deposit|withdraw|add-funds)/u.test(joined)) return 'funds';
+  if (/perps-home/u.test(joined) || /perps-home|tab=perps/u.test(route)) return 'home';
+  return 'unknown';
+}
+
+function selected(items, predicate, maximum) {
+  return items.filter(predicate).slice(0, maximum);
+}
+
+function compactEntries(items, maximum) {
+  return selected(items, () => true, maximum).map((item) => ({
+    testId: item.testId,
+    ...(item.label ? { label: item.label } : {}),
+    enabled: item.enabled,
+    visible: item.visible,
+  }));
+}
+
+function visibleFeatures(items) {
+  const ids = new Set(items.map((item) => item.testId));
+  const has = (pattern) => [...ids].some((testId) => pattern.test(testId));
+  const long = has(/(?:long-cta-button|direction-long)$/u);
+  const short = has(/(?:short-cta-button|direction-short)$/u);
+  return {
+    activity: has(/^(?:transaction-card-|perps-(?:recent-activity|activity))/u),
+    balance: has(/^perps-balance-dropdown/u),
+    chart: has(/perps-(?:candlestick-chart|market-detail-chart|pro-market-chart)/u),
+    'long-short': long && short,
+    'market-list': has(/^(?:market-list-view|perps-market-list|perps-watchlist-|explore-markets-|market-row-)/u),
+    'order-entry': has(/perps-(?:order-entry|pro-order-form)/u),
+    price: has(/perps-(?:market-detail-price|pro-market-price)$/u),
+    'price-change': has(/perps-(?:market-detail-change|pro-market-price-change)$/u),
+    stats: has(/perps-(?:stats-section|market-detail-oracle-price|pro-market-stats)/u),
+  };
+}
+
+export function normalizeVisiblePerpsState(raw, options, platform) {
+  const items = [...(raw.items ?? []), ...(options.includeOffscreen ? raw.offscreenItems ?? [] : [])]
+    .map(normalizedItem)
+    .filter(Boolean);
+  const unique = Array.from(new Map(items.map((item) => [item.testId, item])).values());
+  const testIds = new Set(unique.map((item) => item.testId));
+  const route = text(raw.route) ?? '';
+  const surface = classifySurface(route, testIds);
+  const marketItems = selected(
+    unique,
+    (item) => Boolean(marketFromTestId(item.testId)),
+    options.maxItems,
+  ).map((item) => ({
+    market: marketFromTestId(item.testId),
+    testId: item.testId,
+    ...(item.label ? { label: item.label } : {}),
+    visible: item.visible,
+  }));
+  const state = {
+    source: 'visible-ui',
+    platform,
+    surface,
+    ...(route ? { route } : {}),
+    ...(text(raw.title) ? { title: text(raw.title) } : {}),
+    balance: compactEntries(
+      selected(unique, (item) => item.testId.startsWith('perps-balance-dropdown'), 1),
+      1,
+    )[0] ?? null,
+    markets: marketItems,
+    positions: compactEntries(
+      selected(unique, (item) => /^(?:position-card-|perps-position-row-|perps-position-size-value$|perps-pro-market-position-row-)/u.test(item.testId), options.maxItems),
+      options.maxItems,
+    ),
+    orders: compactEntries(
+      selected(unique, (item) => /^(?:order-card-|perps-order-row-)/u.test(item.testId), options.maxItems),
+      options.maxItems,
+    ),
+    activity: compactEntries(
+      selected(unique, (item) => /^(?:transaction-card-|perps-activity-row-)/u.test(item.testId), options.maxItems),
+      options.maxItems,
+    ),
+    orderEntry: raw.orderEntry && typeof raw.orderEntry === 'object' ? {
+      symbol: text(raw.orderEntry.symbol) ?? null,
+      direction: text(raw.orderEntry.direction) ?? null,
+      orderType: text(raw.orderEntry.orderType) ?? null,
+      amount: raw.orderEntry.amount == null ? null : String(raw.orderEntry.amount),
+      percent: raw.orderEntry.percent == null ? null : String(raw.orderEntry.percent),
+      leverage: raw.orderEntry.leverage == null ? null : String(raw.orderEntry.leverage),
+      autoClose: raw.orderEntry.autoClose === true,
+      takeProfitPrice: raw.orderEntry.takeProfitPrice == null ? null : String(raw.orderEntry.takeProfitPrice),
+      stopLossPrice: raw.orderEntry.stopLossPrice == null ? null : String(raw.orderEntry.stopLossPrice),
+      submit: raw.orderEntry.submit && typeof raw.orderEntry.submit === 'object' ? {
+        label: text(raw.orderEntry.submit.label) ?? null,
+        enabled: raw.orderEntry.submit.enabled !== false,
+      } : null,
+      limitPrice: raw.orderEntry.limitPrice == null ? null : String(raw.orderEntry.limitPrice),
+      validation: Array.isArray(raw.orderEntry.validation)
+        ? raw.orderEntry.validation.map(text).filter(Boolean).slice(0, 20)
+        : [],
+    } : null,
+    features: visibleFeatures(unique),
+    controls: compactEntries(
+      selected(
+        unique,
+        (item) => item.testId.startsWith('perps-') && !marketFromTestId(item.testId),
+        options.maxItems,
+      ),
+      options.maxItems,
+    ),
+    observedTestIds: Array.from(testIds).slice(0, options.maxItems),
+    truncated: raw.truncated === true || unique.length > options.maxItems,
+    layout: raw.layout && typeof raw.layout === 'object' ? {
+      viewportWidth: Number(raw.layout.viewportWidth ?? 0),
+      viewportHeight: Number(raw.layout.viewportHeight ?? 0),
+      contentWidth: Number(raw.layout.contentWidth ?? 0),
+      horizontalOverflow: raw.layout.horizontalOverflow === true,
+      clippedTestIds: Array.isArray(raw.layout.clippedTestIds)
+        ? raw.layout.clippedTestIds.map(text).filter(Boolean).slice(0, 100)
+        : [],
+    } : null,
+  };
+  assertVisibleState(state, options);
+  return state;
+}
+
+function assertVisibleState(state, options) {
+  if (options.requireNoHorizontalOverflow && (
+    !state.layout || state.layout.horizontalOverflow || state.layout.clippedTestIds.length > 0
+  )) {
+    throw new Error(`Visible Perps layout overflows horizontally: ${JSON.stringify(state.layout)}.`);
+  }
+  if (options.surface !== 'auto' && state.surface !== options.surface) {
+    throw new Error(
+      `Expected visible Perps surface ${options.surface}, but observed ${state.surface}.`,
+    );
+  }
+  if (state.markets.length < options.minimumMarketCount) {
+    throw new Error(
+      `Expected at least ${options.minimumMarketCount} visible Perps markets, but observed ${state.markets.length}.`,
+    );
+  }
+  if (state.markets.length > options.maximumMarketCount) {
+    throw new Error(
+      `Expected at most ${options.maximumMarketCount} visible Perps markets, but observed ${state.markets.length}.`,
+    );
+  }
+  if (state.positions.length < options.minimumPositionCount || state.positions.length > options.maximumPositionCount) {
+    throw new Error(`Expected ${options.minimumPositionCount}-${options.maximumPositionCount} visible Perps positions, but observed ${state.positions.length}.`);
+  }
+  if (state.orders.length < options.minimumOrderCount || state.orders.length > options.maximumOrderCount) {
+    throw new Error(`Expected ${options.minimumOrderCount}-${options.maximumOrderCount} visible Perps orders, but observed ${state.orders.length}.`);
+  }
+  if (state.activity.length < options.minimumActivityCount) {
+    throw new Error(`Expected at least ${options.minimumActivityCount} visible Perps activity entries, but observed ${state.activity.length}.`);
+  }
+  const observed = new Set(state.observedTestIds);
+  const missing = options.requireTestIds.filter((testId) => !observed.has(testId));
+  if (missing.length > 0) {
+    throw new Error(`Missing required visible Perps test IDs: ${missing.join(', ')}.`);
+  }
+  const forbidden = options.forbidTestIds.filter((testId) => observed.has(testId));
+  if (forbidden.length > 0) {
+    throw new Error(`Forbidden visible Perps test IDs were observed: ${forbidden.join(', ')}.`);
+  }
+  const missingFeatures = options.requireFeatures.filter((feature) => state.features[feature] !== true);
+  if (missingFeatures.length > 0) {
+    throw new Error(`Missing required visible Perps features: ${missingFeatures.join(', ')}.`);
+  }
+  if (options.market) {
+    const requested = options.market.replace(/^XYZ-/u, 'XYZ:');
+    const matched = state.markets.some((entry) => entry.market === requested) ||
+      [...state.controls, ...state.positions, ...state.orders, ...state.activity]
+        .some((entry) => String(entry.label ?? entry.testId).toUpperCase().includes(requested));
+    if (!matched) {
+      throw new Error(`Expected visible Perps market ${requested}, but it was not observed.`);
+    }
+  }
+  if (options.direction && state.orderEntry?.direction !== options.direction) {
+    throw new Error(`Expected Perps order direction ${options.direction}, but observed ${state.orderEntry?.direction ?? 'none'}.`);
+  }
+  if (options.orderType && state.orderEntry?.orderType !== options.orderType) {
+    throw new Error(`Expected Perps order type ${options.orderType}, but observed ${state.orderEntry?.orderType ?? 'none'}.`);
+  }
+  if (options.amount !== undefined && !equalNumericText(state.orderEntry?.amount, options.amount)) {
+    throw new Error(`Expected Perps order amount ${options.amount}, but observed ${state.orderEntry?.amount ?? 'none'}.`);
+  }
+  if (options.percent !== undefined && !equalNumericText(state.orderEntry?.percent, options.percent)) {
+    throw new Error(`Expected Perps order percent ${options.percent}, but observed ${state.orderEntry?.percent ?? 'none'}.`);
+  }
+  if (options.leverage !== undefined && !equalNumericText(state.orderEntry?.leverage, options.leverage)) {
+    throw new Error(`Expected Perps leverage ${options.leverage}, but observed ${state.orderEntry?.leverage ?? 'none'}.`);
+  }
+  if (options.autoClose !== undefined && state.orderEntry?.autoClose !== options.autoClose) {
+    throw new Error(`Expected Perps auto-close ${options.autoClose}, but observed ${state.orderEntry?.autoClose ?? 'none'}.`);
+  }
+  if (options.submitEnabled !== undefined && state.orderEntry?.submit?.enabled !== options.submitEnabled) {
+    throw new Error(`Expected Perps submit enabled ${options.submitEnabled}, but observed ${state.orderEntry?.submit?.enabled ?? 'none'}.`);
+  }
+  const validationText = state.orderEntry?.validation?.join(' ') ?? '';
+  const missingValidation = options.requireValidationText.filter((entry) => !validationText.includes(entry));
+  if (missingValidation.length > 0) {
+    throw new Error(`Missing required Perps validation text: ${missingValidation.join(', ')}.`);
+  }
+}

package/library/actions/shared/swap-bridge/transaction.mjs

@@ -0,0 +1,54 @@
+function requiredText(value, name) {
+  const resolved = String(value ?? '').trim();
+  if (!resolved) throw new Error(`metamask.swap_bridge ${name} is required.`);
+  return resolved;
+}
+
+function timeout(value) {
+  const resolved = Number(value ?? 60_000);
+  if (!Number.isInteger(resolved) || resolved < 1_000 || resolved > 180_000) {
+    throw new Error('metamask.swap_bridge timeout_ms must be an integer from 1000 to 180000.');
+  }
+  return resolved;
+}
+
+function plainDecimal(value) {
+  const text = String(value).trim();
+  const match = /^([+-]?)(\d+)(?:\.(\d*))?[eE]([+-]?\d+)$/u.exec(text);
+  if (!match) return text;
+  const [, sign, integer, fraction = '', exponentText] = match;
+  const digits = `${integer}${fraction}`;
+  const decimalIndex = integer.length + Number(exponentText);
+  if (decimalIndex <= 0) return `${sign}0.${'0'.repeat(-decimalIndex)}${digits}`;
+  if (decimalIndex >= digits.length) return `${sign}${digits}${'0'.repeat(decimalIndex - digits.length)}`;
+  return `${sign}${digits.slice(0, decimalIndex)}.${digits.slice(decimalIndex)}`;
+}
+
+export function resolveAssetSelectionOptions(node = {}) {
+  const sourceSymbol = requiredText(node.source_symbol, 'source_symbol').toUpperCase();
+  const destinationSymbol = requiredText(node.destination_symbol, 'destination_symbol').toUpperCase();
+  return {
+    sourceSymbol,
+    destinationSymbol,
+    sourceChain: requiredText(node.source_chain, 'source_chain'),
+    destinationChain: requiredText(node.destination_chain, 'destination_chain'),
+    sourceQuery: String(node.source_query ?? sourceSymbol).trim(),
+    destinationQuery: String(node.destination_query ?? destinationSymbol).trim(),
+    sourceAssetId: String(node.source_asset_id ?? '').trim() || undefined,
+    destinationAssetId: String(node.destination_asset_id ?? '').trim() || undefined,
+    timeoutMs: timeout(node.timeout_ms),
+  };
+}
+
+export function resolveAmountOptions(node = {}) {
+  const amount = plainDecimal(requiredText(node.amount, 'amount'));
+  const numeric = Number(amount);
+  if (!Number.isFinite(numeric) || numeric <= 0) {
+    throw new Error('metamask.swap_bridge amount must be a positive number.');
+  }
+  return {
+    amount,
+    waitForQuote: node.wait_for_quote !== false,
+    timeoutMs: timeout(node.timeout_ms),
+  };
+}

package/library/actions/shared/swap-bridge/visible-state.mjs

@@ -0,0 +1,97 @@
+function text(value) {
+  if (typeof value !== 'string') return undefined;
+  const normalized = value.replace(/\s+/gu, ' ').trim();
+  return normalized ? normalized.slice(0, 500) : undefined;
+}
+
+function symbol(value) {
+  if (value == null) return undefined;
+  const normalized = String(value).trim().toUpperCase();
+  if (!normalized) return undefined;
+  return normalized;
+}
+
+export function resolveVisibleSwapBridgeOptions(node = {}) {
+  return {
+    sourceSymbol: symbol(node.source_symbol),
+    destinationSymbol: symbol(node.destination_symbol),
+    requireAmountInputs: node.require_amount_inputs !== false,
+    requireSettings: node.require_settings === true,
+  };
+}
+
+function normalizedItem(source) {
+  const testId = text(source?.testId ?? source?.test_id ?? source?.identifier);
+  if (!testId) return undefined;
+  return {
+    testId,
+    label: text(source?.label ?? source?.text) ?? null,
+    value: text(source?.value) ?? null,
+    enabled: source?.enabled !== false,
+    visible: source?.visible !== false,
+  };
+}
+
+function tokenLabel(item) {
+  return text(item?.label ?? item?.value) ?? null;
+}
+
+function matchesSymbol(value, expected) {
+  if (!expected) return true;
+  return new RegExp(`(^|[^A-Z0-9])${expected.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&')}([^A-Z0-9]|$)`, 'u')
+    .test(String(value ?? '').toUpperCase());
+}
+
+export function normalizeVisibleSwapBridgeState(raw, options, platform) {
+  const items = [...(raw.items ?? []), ...(raw.offscreenItems ?? [])]
+    .map(normalizedItem)
+    .filter(Boolean);
+  const unique = Array.from(new Map(items.map((item) => [item.testId, item])).values());
+  const byId = new Map(unique.map((item) => [item.testId, item]));
+  const sourceAsset = tokenLabel(byId.get(platform === 'extension' ? 'bridge-source-button' : 'source-token-area'));
+  const destinationAsset = tokenLabel(byId.get(platform === 'extension' ? 'bridge-destination-button' : 'dest-token-area'));
+  const sourceInput = byId.get(platform === 'extension' ? 'from-amount' : 'source-token-area-input');
+  const destinationInput = byId.get(platform === 'extension' ? 'to-amount' : 'dest-token-area-input');
+  const settings = byId.get(platform === 'extension' ? 'bridge__header-settings-button' : 'bridge-slippage-settings-button');
+  const noQuotes = byId.get(platform === 'extension' ? 'prepare-swap-page-error' : 'bridge-no-quotes');
+  const missingPrice = byId.get(platform === 'extension' ? 'bridge-missing-price-banner' : 'bridge-missing-price-banner');
+  const state = {
+    source: 'visible-ui',
+    platform,
+    surface: 'swap',
+    ...(text(raw.route) ? { route: text(raw.route) } : {}),
+    ...(text(raw.title) ? { title: text(raw.title) } : {}),
+    sourceAsset,
+    destinationAsset,
+    sourceAmount: text(sourceInput?.value ?? sourceInput?.label) ?? null,
+    destinationAmount: text(destinationInput?.value ?? destinationInput?.label) ?? null,
+    controls: unique.slice(0, 100),
+    features: {
+      'amount-inputs': Boolean(sourceInput && destinationInput),
+      settings: Boolean(settings),
+      'asset-selectors': Boolean(sourceAsset && destinationAsset),
+    },
+    quoteState: noQuotes ? 'unavailable' : missingPrice ? 'missing-price' : 'idle-or-ready',
+    truncated: raw.truncated === true || unique.length > 100,
+  };
+  assertVisibleSwapBridgeState(state, options);
+  return state;
+}
+
+function assertVisibleSwapBridgeState(state, options) {
+  if (!state.features['asset-selectors']) {
+    throw new Error('Visible Swap source and destination token selectors were not both observed.');
+  }
+  if (options.requireAmountInputs && !state.features['amount-inputs']) {
+    throw new Error('Visible Swap source and destination amount inputs were not both observed.');
+  }
+  if (options.requireSettings && !state.features.settings) {
+    throw new Error('Visible Swap settings control was not observed.');
+  }
+  if (!matchesSymbol(state.sourceAsset, options.sourceSymbol)) {
+    throw new Error(`Expected visible Swap source ${options.sourceSymbol}, but observed ${JSON.stringify(state.sourceAsset)}.`);
+  }
+  if (!matchesSymbol(state.destinationAsset, options.destinationSymbol)) {
+    throw new Error(`Expected visible Swap destination ${options.destinationSymbol}, but observed ${JSON.stringify(state.destinationAsset)}.`);
+  }
+}