@deeeed/metamask-harness 0.64.0 → 0.66.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## Unreleased
 
+## 0.66.0 - 2026-09-25
+
+### Added
+
+- Observe Top Movers pills and visible counts separately from ordinary market rows.
+- Expose market-filter selection matches from observed controls for composable proof assertions.
+
+### Fixed
+
+- Give Extension Perps smoke its own runtime assertions and refuse a visible tutorial gate.
+- Refuse absence claims on truncated Perps observations and exclude pills clipped by the viewport or scroll containers from Top Movers visible counts.
+- Capture the driven market-search page through the existing surface-capture action.
+
+## 0.65.0 - 2026-09-25
+
+### Added
+
+- Explicit Extension `wallet.accept-terms` setup recipe with caller-authorized consent and enabled-state checks.
+- Structured visible market-detail identity and price observations, with null for missing or ambiguous fields.
+
+### Fixed
+
+- Give bundled market-detail and search recipes portable runtime assertions so composed QA cases can validate their existing behavioral contract.
+
 ## 0.64.0 - 2026-09-25
 
 ### Added

package/README.md

@@ -226,6 +226,8 @@ mm-harness run --list
 mm-harness run perps.smoke --describe
 mm-harness run wallet.smoke --describe
 mm-harness run wallet.import method=auto
+# When a visible Terms of Use gate follows import and acceptance is authorized:
+mm-harness run wallet.accept-terms accept=true
 
 # Use visible client UI to delete and import the wallet again.
 mm-harness run wallet.reset-import

package/library/actions/extension/perps/read_visible_state.mjs

@@ -12,6 +12,12 @@ function pointInside(point, left, top, right, bottom) {
   return point && point.x >= left && point.x <= right && point.y >= top && point.y <= bottom;
 }
 
+export function topMoverFitsVisibleBounds(rect, bounds) {
+  return rect.width > 0 && rect.height > 0 && bounds.every((clip) =>
+    rect.left >= clip.left - 1 && rect.right <= clip.right + 1 &&
+    rect.top >= clip.top - 1 && rect.bottom <= clip.bottom + 1);
+}
+
 export function classifyActionableControlLayout(controls) {
   const bounded = Array.isArray(controls) ? controls.slice(0, 200) : [];
   return {
@@ -42,6 +48,26 @@ export async function readVisiblePerpsState(page, node = {}) {
   const raw = await page.evaluate(`(() => {
     const includeOffscreen = ${JSON.stringify(options.includeOffscreen)};
     const maximum = ${JSON.stringify(options.maxItems)};
+    const topMoverFitsVisibleBounds = ${topMoverFitsVisibleBounds.toString()};
+    const topMoverVisible = (element, rect) => {
+      const bounds = [{ left: 0, top: 0, right: innerWidth, bottom: innerHeight }];
+      for (let ancestor = element.parentElement; ancestor; ancestor = ancestor.parentElement) {
+        const style = getComputedStyle(ancestor);
+        const clipsX = /^(hidden|clip|scroll|auto|overlay)$/.test(style.overflowX);
+        const clipsY = /^(hidden|clip|scroll|auto|overlay)$/.test(style.overflowY);
+        if (!clipsX && !clipsY) continue;
+        const box = ancestor.getBoundingClientRect();
+        const left = box.left + ancestor.clientLeft;
+        const top = box.top + ancestor.clientTop;
+        bounds.push({
+          left: clipsX ? left : -Infinity,
+          right: clipsX ? left + ancestor.clientWidth : Infinity,
+          top: clipsY ? top : -Infinity,
+          bottom: clipsY ? top + ancestor.clientHeight : Infinity,
+        });
+      }
+      return topMoverFitsVisibleBounds(rect, bounds);
+    };
     const relevant = /^(?:perps-|parent-selector-perps-(?:market-list|order-entry)|explore-markets-|market-list-view|market-row-|filter-select-button|sort-dropdown-button|search-input|position-card-|order-card-|transaction-card-|bottom-nav-|back-button|direction-|order-type-|amount-|balance-percent-|leverage-|auto-close|submit-order-button|limit-price-|tp-|sl-|custom-amount-|pay-with-|confirm-footer-button|wallet-initiated-header-back-button|transaction-fee-|bridge-(?:fee|time)-|receive-(?:row|value))/u;
     const items = [];
     const offscreenItems = [];
@@ -70,7 +96,8 @@ export async function readVisiblePerpsState(page, node = {}) {
       const rendered = style.display !== 'none' && style.visibility !== 'hidden' && rect.width > 0 && rect.height > 0;
       if (!rendered) continue;
       matched += 1;
-      const visible = rect.bottom > 0 && rect.right > 0 && rect.top < innerHeight && rect.left < innerWidth;
+      const visible = rect.bottom > 0 && rect.right > 0 && rect.top < innerHeight && rect.left < innerWidth &&
+        (!testId.startsWith('perps-top-movers-pill-') || topMoverVisible(element, rect));
       if (rect.bottom > 0 && rect.top < innerHeight && (rect.left < -1 || rect.right > innerWidth + 1)) {
         clippedTestIds.push(testId);
       }

package/library/actions/extension/perps/select_market_filter.mjs

@@ -60,7 +60,7 @@ async function selectDropdownFilter(page, filter, option, timeoutMs, pollInterva
     }
     await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
   }
-  return { selectedLabel: selectedState.label, controlKind: 'dropdown', alreadySelected: false };
+  return { selectedLabel: selectedState.label, selectionMatches: selectedState.visible && selectedState.label === optionState.label, controlKind: 'dropdown', alreadySelected: false };
 }
 
 async function categoryRailState(page) {
@@ -109,7 +109,7 @@ async function selectCategoryRail(page, option, timeoutMs, pollIntervalMs) {
     await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
     selected = await categoryRailState(page);
   }
-  return { selectedLabel: selected.active[0]?.label ?? null, controlKind: 'category-rail', alreadySelected };
+  return { selectedLabel: selected.active[0]?.label ?? null, selectionMatches: matches(selected), controlKind: 'category-rail', alreadySelected };
 }
 
 export async function selectMarketFilter(page, input, pollOptions = {}) {

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

@@ -232,11 +232,34 @@ export function normalizeVisiblePerpsState(raw, options, platform) {
     ...(item.label ? { label: item.label } : {}),
     visible: item.visible,
   }));
+  const detailField = (pattern) => {
+    const matches = items.filter((item) => item.visible && pattern.test(item.testId));
+    const values = [...new Set(matches.map((item) => item.label).filter(Boolean))];
+    return values.length === 1 ? values[0] : null;
+  };
+  const detailPair = detailField(/^(?:perps-market-detail-pair|perps-(?:pro-)?market-header-subtitle)$/u);
+  const detailSymbol = detailPair?.match(/^(.+?)-(?:USDC|USD|PERP)(?:\s+perp)?$/iu)?.[1]?.toUpperCase() ?? null;
+  const moverList = items.find((item) => item.testId === 'perps-top-movers-list');
+  const moverPills = items.filter((item) => item.testId.startsWith('perps-top-movers-pill-'))
+    .map((item) => ({
+      market: marketFromTestId(item.testId.replace('perps-top-movers-pill-', 'explore-markets-')),
+      testId: item.testId,
+      label: item.label ?? null,
+      visible: item.visible,
+    }))
+    .filter((item) => item.market);
   const state = {
     source: 'visible-ui',
     platform,
     surface,
     favorite,
+    marketDetails: surface === 'market-details' ? {
+      symbol: detailSymbol,
+      pair: detailPair,
+      name: detailField(/^(?:perps-market-detail-name|perps-(?:pro-)?market-header-title)$/u),
+      price: detailField(/^perps-(?:market-detail-(?:header-)?price|market-header-price|pro-market-price)$/u),
+      priceChange: detailField(/^perps-(?:market-detail-(?:header-)?change|market-header-price-change|pro-market-price-change)$/u),
+    } : null,
     ...(route ? { route } : {}),
     ...(text(raw.title) ? { title: text(raw.title) } : {}),
     balance: compactEntries(
@@ -244,6 +267,13 @@ export function normalizeVisiblePerpsState(raw, options, platform) {
       1,
     )[0] ?? null,
     markets: marketItems,
+    marketCount: marketItems.length,
+    topMovers: moverList ? {
+      visible: moverList.visible,
+      pills: moverPills,
+      count: moverPills.length,
+      visibleCount: moverPills.filter((item) => item.visible).length,
+    } : null,
     positions: compactEntries(
       selected(unique, (item) => /^(?:position-card-(?!roe-)|perps-position-row-|perps-position-size-value$|perps-pro-market-position-row-|perps-home-position-card-)/u.test(item.testId), options.maxItems),
       options.maxItems,
@@ -306,11 +336,14 @@ export function normalizeVisiblePerpsState(raw, options, platform) {
         : [],
     } : null,
   };
-  assertVisibleState(state, options);
+  assertVisibleState(state, options, testIds);
   return state;
 }
 
-function assertVisibleState(state, options) {
+function assertVisibleState(state, options, observed) {
+  if (options.forbidTestIds.length > 0 && state.truncated) {
+    throw new Error('Cannot prove forbidden Perps controls are absent from a truncated observation.');
+  }
   if (options.requireNoHorizontalOverflow && (
     !state.layout || state.layout.horizontalOverflow || state.layout.clippedTestIds.length > 0
   )) {
@@ -346,7 +379,6 @@ function assertVisibleState(state, options) {
   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(', ')}.`);

package/library/manifests/extension.action-manifest.json

@@ -2809,7 +2809,7 @@
       ]
     },
     "metamask.perps.read_visible_state": {
-      "description": "Read and assert bounded visible Perps UI state without product background hooks. favorite is boolean only when the requested market pair and one favorite control are both visible; otherwise null, never an assumed false.",
+      "description": "Read and assert bounded visible Perps UI state without product background hooks. marketDetails exposes visible symbol, pair, name, price and priceChange as text, or null when absent/ambiguous. marketCount counts the bounded observed markets array, not an unbounded total. topMovers separately reports its bounded pills, count and visibleCount when that list is observed; otherwise null. favorite is boolean only when the requested market pair and one favorite control are both visible; otherwise null, never an assumed false.",
       "schema": {
         "type": "object",
         "properties": {
@@ -2919,6 +2919,7 @@
             "default": false
           },
           "forbid_test_ids": {
+            "description": "Requires a complete observation; truncated results fail rather than assuming these controls are absent.",
             "type": "array",
             "items": {
               "type": "string"

package/library/manifests/mobile.action-manifest.json

@@ -2178,7 +2178,7 @@
       "execution_capabilities": ["app-mutation"]
     },
     "metamask.perps.read_visible_state": {
-      "description": "Read and assert bounded visible Perps UI state through native accessibility. favorite is boolean only when the requested market pair and one favorite control are both observed as visible; otherwise null, never an assumed false.",
+      "description": "Read and assert bounded visible Perps UI state through native accessibility. favorite is boolean only when the requested market pair and one favorite control are both observed as visible; otherwise null, never an assumed false. marketDetails exposes visible symbol, pair, name, price and priceChange as text, or null when absent/ambiguous. marketCount counts the bounded observed markets array, not an unbounded total. topMovers separately reports its bounded pills, count and visibleCount when that list is observed; otherwise null.",
       "schema": {
         "type": "object",
         "properties": {
@@ -2227,6 +2227,7 @@
             "default": 0
           },
           "forbid_test_ids": {
+            "description": "Requires a complete observation; truncated results fail rather than assuming these controls are absent.",
             "type": "array",
             "items": { "type": "string" },
             "maxItems": 100

package/library/recipes/extension/perps/smoke.recipe.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",
   "title": "MetaMask Extension Perps smoke",
-  "description": "Non-mutating Perps domain smoke for MetaMask Extension: verifies CDP, unlocks if needed, opens the Perps page, and reads live Perps positions and orders.",
+  "description": "Read-only Extension Perps smoke: verifies CDP, unlocks if needed, opens Perps, proves visible home with market data, and reads positions/orders. Requires approved wallet setup and completed onboarding gates; a visible tutorial is setup, not passing smoke.",
   "workflow": {
     "entry": "status",
     "nodes": {
@@ -26,7 +26,7 @@
       "open-perps": {
         "action": "ui.navigate",
         "page": "perps",
-        "next": "read-positions",
+        "next": "read-home",
         "intent": "Show the Perps home surface"
       },
       "read-positions": {
@@ -42,7 +42,56 @@
       "done": {
         "action": "end",
         "status": "pass"
+      },
+      "read-home": {
+        "action": "metamask.perps.read_visible_state",
+        "surface": "home",
+        "minimum_market_count": 1,
+        "require_features": [
+          "balance",
+          "market-list"
+        ],
+        "intent": "Observe a populated Perps home after setup",
+        "next": "assert-home",
+        "forbid_test_ids": [
+          "perps-tutorial-skip-button"
+        ],
+        "max_items": 200
+      },
+      "assert-home": {
+        "action": "assert_output",
+        "source": "read-home",
+        "assert": {
+          "path": "$.surface",
+          "operator": "eq",
+          "value": "home"
+        },
+        "proves": [
+          "perps-home"
+        ],
+        "intent": "The observed surface is Perps home",
+        "next": "assert-markets"
+      },
+      "assert-markets": {
+        "action": "assert_output",
+        "source": "read-home",
+        "assert": {
+          "path": "$.marketCount",
+          "operator": "gte",
+          "value": 1
+        },
+        "proves": [
+          "perps-home"
+        ],
+        "intent": "Perps home contains market data rather than only a loading shell",
+        "next": "read-positions"
       }
     }
-  }
+  },
+  "proofTargets": [
+    {
+      "id": "perps-home",
+      "claim": "The unlocked Perps home has visible market data and no observed tutorial gate."
+    }
+  ]
 }

package/library/recipes/extension/wallet/accept-terms.recipe.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",
+  "title": "Accept the visible wallet Terms of Use",
+  "description": "Setup-only Extension journey for a visible Terms of Use gate. Requires explicit caller authority to accept the displayed terms. Scrolls through the agreement, checks consent and waits until Agree is enabled, then proves the gate is absent. Does not import, unlock or change network/trading state; call after wallet.import when this gate is present.",
+  "paramsSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": [
+      "accept"
+    ],
+    "properties": {
+      "accept": {
+        "type": "boolean",
+        "enum": [
+          true
+        ],
+        "description": "The caller authorizes accepting the displayed terms for this fixture."
+      },
+      "timeout_ms": {
+        "type": "integer",
+        "minimum": 1000,
+        "default": 15000
+      }
+    }
+  },
+  "proofTargets": [
+    {
+      "id": "terms-dismissed",
+      "claim": "The visible Terms of Use gate is accepted through its controls and no longer covers the wallet."
+    }
+  ],
+  "workflow": {
+    "entry": "require-terms",
+    "nodes": {
+      "require-terms": {
+        "action": "ui.wait_for",
+        "test_id": "terms-of-use-agree-button",
+        "expected": "visible",
+        "timeout_ms": "{{params.timeout_ms}}",
+        "intent": "Require the agreement to be visible before changing consent",
+        "next": "scroll-terms"
+      },
+      "scroll-terms": {
+        "action": "ui.press",
+        "test_id": "terms-of-use-scroll-button",
+        "intent": "Reach the end of the displayed agreement",
+        "next": "wait-checkbox"
+      },
+      "wait-checkbox": {
+        "action": "ui.wait_for",
+        "selector": "[data-testid=\"terms-of-use-checkbox\"]:not([disabled])",
+        "expected": "visible",
+        "timeout_ms": "{{params.timeout_ms}}",
+        "intent": "The displayed agreement allows the caller to record consent",
+        "next": "check-consent"
+      },
+      "check-consent": {
+        "action": "ui.press",
+        "test_id": "terms-of-use-checkbox",
+        "intent": "Record the caller-authorized consent through the checkbox",
+        "next": "wait-agree"
+      },
+      "wait-agree": {
+        "action": "ui.wait_for",
+        "selector": "[data-testid=\"terms-of-use-agree-button\"]:not([disabled])",
+        "expected": "visible",
+        "timeout_ms": "{{params.timeout_ms}}",
+        "intent": "The completed agreement review enables its confirmation control",
+        "next": "agree"
+      },
+      "agree": {
+        "action": "ui.press",
+        "test_id": "terms-of-use-agree-button",
+        "intent": "Accept the displayed terms for the authorized fixture",
+        "next": "verify-dismissed"
+      },
+      "verify-dismissed": {
+        "action": "ui.wait_for",
+        "test_id": "terms-of-use-agree-button",
+        "expected": "absent",
+        "timeout_ms": "{{params.timeout_ms}}",
+        "proves": [
+          "terms-dismissed"
+        ],
+        "intent": "Prove the agreement no longer covers wallet controls",
+        "next": "done"
+      },
+      "done": {
+        "action": "end",
+        "status": "pass"
+      }
+    }
+  }
+}

package/library/recipes/shared/perps/release-market-details.recipe.json

@@ -40,7 +40,9 @@
         "surface": "market-list",
         "market": "{{params.market}}",
         "minimum_market_count": 2,
-        "require_features": ["market-list"],
+        "require_features": [
+          "market-list"
+        ],
         "max_items": 100,
         "intent": "Prove the requested market appears in a populated live market list",
         "next": "open-market"
@@ -65,7 +67,7 @@
         ],
         "max_items": 100,
         "intent": "Prove the selected market, live pricing, statistics, and trade directions are visible",
-        "next": "capture-market"
+        "next": "verify-directions"
       },
       "capture-market": {
         "action": "ui.screenshot",
@@ -77,7 +79,55 @@
       "done": {
         "action": "end",
         "status": "pass"
+      },
+      "verify-price": {
+        "action": "assert_output",
+        "source": "assert-market",
+        "assert": {
+          "path": "$.features.price",
+          "operator": "eq",
+          "value": true
+        },
+        "proves": [
+          "market-details"
+        ],
+        "intent": "The requested market displays a price quote",
+        "next": "capture-market"
+      },
+      "verify-stats": {
+        "action": "assert_output",
+        "source": "assert-market",
+        "assert": {
+          "path": "$.features.stats",
+          "operator": "eq",
+          "value": true
+        },
+        "proves": [
+          "market-details"
+        ],
+        "intent": "The requested market displays its statistics",
+        "next": "verify-price"
+      },
+      "verify-directions": {
+        "action": "assert_output",
+        "source": "assert-market",
+        "assert": {
+          "path": "$.features.long-short",
+          "operator": "eq",
+          "value": true
+        },
+        "proves": [
+          "market-details"
+        ],
+        "intent": "Both trading directions are available for the requested market",
+        "next": "verify-stats"
       }
     }
-  }
+  },
+  "proofTargets": [
+    {
+      "id": "market-details",
+      "claim": "The requested market shows its live price, statistics and both trade directions."
+    }
+  ]
 }

package/library/recipes/shared/perps/release-market-search.recipe.json

@@ -45,7 +45,9 @@
         "action": "metamask.perps.read_visible_state",
         "surface": "market-list",
         "minimum_market_count": "{{params.minimum_unfiltered_results}}",
-        "require_features": ["market-list"],
+        "require_features": [
+          "market-list"
+        ],
         "max_items": 100,
         "intent": "Prove the live market list is populated before filtering",
         "next": "search"
@@ -62,13 +64,15 @@
         "market": "{{params.expected_market}}",
         "minimum_market_count": 1,
         "maximum_market_count": "{{params.maximum_results}}",
-        "require_features": ["market-list"],
+        "require_features": [
+          "market-list"
+        ],
         "max_items": 100,
         "intent": "Prove the search reduced the list and retained the requested market",
-        "next": "capture"
+        "next": "verify-result"
       },
       "capture": {
-        "action": "ui.screenshot",
+        "action": "ui.capture_surface",
         "path": "screenshots/perps-market-search.png",
         "label": "Perps release market search",
         "intent": "Preserve reviewer-visible proof of the filtered market list",
@@ -77,7 +81,55 @@
       "done": {
         "action": "end",
         "status": "pass"
+      },
+      "verify-result": {
+        "action": "assert_output",
+        "source": "assert-filtered",
+        "assert": {
+          "path": "$.markets",
+          "operator": "length_lte",
+          "value": "{{params.maximum_results}}"
+        },
+        "proves": [
+          "filtered-market"
+        ],
+        "intent": "Assert the observed filtered result count stays within the requested bounds",
+        "next": "verify-nonempty"
+      },
+      "verify-nonempty": {
+        "action": "assert_output",
+        "source": "assert-filtered",
+        "assert": {
+          "path": "$.markets",
+          "operator": "length_gte",
+          "value": 1
+        },
+        "proves": [
+          "filtered-market"
+        ],
+        "intent": "The filtered market list contains at least one result",
+        "next": "verify-reduction"
+      },
+      "verify-reduction": {
+        "action": "assert_output",
+        "source": "assert-filtered",
+        "assert": {
+          "path": "$.markets",
+          "operator": "length_lt",
+          "value": "{{outputs.assert-unfiltered.marketCount}}"
+        },
+        "proves": [
+          "filtered-market"
+        ],
+        "intent": "The query reduces the observed market list from its unfiltered count",
+        "next": "capture"
       }
     }
-  }
+  },
+  "proofTargets": [
+    {
+      "id": "filtered-market",
+      "claim": "The entered query reduces the live market list and retains the expected market."
+    }
+  ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.64.0",
+  "version": "0.66.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"