@deeeed/metamask-harness 0.35.0 → 0.37.0

package/dist/run-diagnostics.js

@@ -32,7 +32,7 @@ function formatRunDiagnosticsForHuman(diagnostics, adapter) {
 async function beginRunDiagnostics(adapter, projectRoot) {
   const source = getAdapterSurface(adapter).appLogSource(projectRoot);
   if (!source) return null;
-  const mobileIssueBuffer = adapter === "mobile" && armMobileIssueBuffer(projectRoot) ? { projectRoot } : void 0;
+  const mobileIssueBuffer = adapter === "mobile" && process.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME !== "1" && armMobileIssueBuffer(projectRoot) ? { projectRoot } : void 0;
   if (adapter === "extension") {
     await ensureExtensionConsoleCapture(projectRoot).catch(() => void 0);
   }

package/docs/RECIPES.md

@@ -58,6 +58,35 @@ mm-harness run recipe.json account="Account 2" --plan
 mm-harness run recipe.json account="Account 2"
 ```
 
+Use the shared wallet setup recipe on either Mobile or Extension. `auto`
+reuses a ready fixture-backed profile and otherwise completes visible
+onboarding; `ui` requires a fresh onboarding state.
+
+```bash
+mm-harness run wallet.import method=auto
+mm-harness run wallet.import method=ui credential_source=environment
+mm-harness run wallet.import method=ui metametrics=true 'interests=["trade_perpetuals"]'
+```
+
+The UI path reads the primary mnemonic from `MM_HARNESS_WALLET_SRP` and the
+password from `MM_HARNESS_WALLET_PASSWORD`, or from the canonical wallet
+fixture. Secret values are redacted from commands and evidence. Visible imports
+default to MetaMetrics off and skip Mobile's optional interests; password terms
+are required and always accepted by the action.
+
+To prove the full real-user recovery journey, delete the current wallet through
+visible client UI and import it again:
+
+```bash
+mm-harness run wallet.reset-import credential_source=fixture
+```
+
+For fixture-backed development clients, `mm-harness fixtures reset` performs a
+clean reset and reapplies the canonical fixture. Extension resets its owned
+Chrome profile; Mobile clears only the selected app's data, preserves the
+installed build, relaunches it, and then applies the fixture. Use
+`wallet.reset-import` when the reset itself must be exercised through visible UI.
+
 ### Mobile device targeting
 
 Always pass `--device <name|udid|serial>` when more than one simulator/device may

package/docs/RELEASE-QA-CAPABILITY-MAP.md

@@ -0,0 +1,150 @@
+# Release QA capability map
+
+This document maps the Extension release checklists to durable recipe
+capabilities. The baseline is `mm-harness` 0.36.0. It is a capability map, not
+a claim that the listed release cases currently pass.
+
+Source baseline: QA repository commit
+[`77591c5`](https://github.com/MetaMask/experimental-mm-qa-ai-tasks/tree/77591c5998fcf6368417fd5be01871e6c9c3dc5b/tasks/rc-extension).
+The relevant sources are the Perps
+[`checklist`](https://github.com/MetaMask/experimental-mm-qa-ai-tasks/blob/77591c5998fcf6368417fd5be01871e6c9c3dc5b/tasks/rc-extension/perps-rc/perps-rc-regression.md)
+and
+[`runbook`](https://github.com/MetaMask/experimental-mm-qa-ai-tasks/blob/77591c5998fcf6368417fd5be01871e6c9c3dc5b/tasks/rc-extension/perps-rc/runbook.md),
+Assets
+[`checklist`](https://github.com/MetaMask/experimental-mm-qa-ai-tasks/blob/77591c5998fcf6368417fd5be01871e6c9c3dc5b/tasks/rc-extension/assets-rc/assets-rc-regression.md)
+and
+[`runbook`](https://github.com/MetaMask/experimental-mm-qa-ai-tasks/blob/77591c5998fcf6368417fd5be01871e6c9c3dc5b/tasks/rc-extension/assets-rc/runbook.md),
+Swap and Bridge
+[`checklist`](https://github.com/MetaMask/experimental-mm-qa-ai-tasks/blob/77591c5998fcf6368417fd5be01871e6c9c3dc5b/tasks/rc-extension/swap-bridge-rc/swap-bridge-rc-regression.md)
+and
+[`runbook`](https://github.com/MetaMask/experimental-mm-qa-ai-tasks/blob/77591c5998fcf6368417fd5be01871e6c9c3dc5b/tasks/rc-extension/swap-bridge-rc/runbook.md),
+and Networks
+[`checklist`](https://github.com/MetaMask/experimental-mm-qa-ai-tasks/blob/77591c5998fcf6368417fd5be01871e6c9c3dc5b/tasks/rc-extension/networks-regression-rc/networks-regression-rc.md)
+and
+[`runbook`](https://github.com/MetaMask/experimental-mm-qa-ai-tasks/blob/77591c5998fcf6368417fd5be01871e6c9c3dc5b/tasks/rc-extension/networks-regression-rc/runbook.md).
+
+Ratings:
+
+- **AVAILABLE**: a typed capability supplies the required setup, operation, or
+  machine-checkable observation.
+- **PARTIAL**: generic UI operations or a narrower domain action can perform
+  part of the case, but deterministic setup or a domain assertion is absent.
+- **MISSING**: no durable recipe capability covers the case family.
+- **TARGET**: being implemented in the current change; not present in 0.36.0.
+
+## Cross-cutting capabilities
+
+| Requirement | 0.36.0 capability | Status |
+| --- | --- | --- |
+| Discover the typed surface | `mm-harness actions --adapter extension --json` exposes the schemas in the [Extension action manifest](../library/manifests/extension.action-manifest.json), so a plan can reject unsupported domain operations before launch. | **AVAILABLE** |
+| Validate and launch the downloaded official RC artifact | Network discovery and download remain in the release-validation workflow, following the QA [`download-build.sh`](https://github.com/MetaMask/experimental-mm-qa-ai-tasks/blob/77591c5998fcf6368417fd5be01871e6c9c3dc5b/tasks/rc-extension/assets-rc/scripts/download-build.sh) contract. | **TARGET**: verify a local Extension ZIP or Android APK against its trusted digest and declared product identity, then run it without using a checkout build. Extension adds safe extraction, cached tree integrity, and isolated launch. Android adds explicit-device install and launch; release recipes use native accessibility without a development bridge, Metro, or HUD. Downloaded iOS artifacts remain unsupported. |
+| Start from an imported wallet or clean onboarding | [`metamask.wallet.import`](../library/actions/extension/wallet/import.mjs), [`metamask.wallet.reset`](../library/actions/extension/wallet/reset.mjs), and the shared [`import`](../library/recipes/wallet/import.recipe.json) and [`reset-import`](../library/recipes/wallet/reset-import.recipe.json) recipes can use visible UI and parameterized credential sources. | **AVAILABLE** |
+| Drive and observe UI | The [Extension action manifest](../library/manifests/extension.action-manifest.json) exposes typed navigation, press, input, key, scroll, wait, screenshot, surface capture, locators, and CDP target selection. | **AVAILABLE** for mechanics; domain meaning remains **PARTIAL**. |
+| Record evidence and a terminal verdict | Recipe traces, action results, screenshots, and artifact indexing exist. There is no release-plan completion gate equivalent to the QA [`validate-run-report.sh`](https://github.com/MetaMask/experimental-mm-qa-ai-tasks/blob/77591c5998fcf6368417fd5be01871e6c9c3dc5b/tasks/rc-extension/assets-rc/scripts/validate-run-report.sh), including canonical case-ID coverage and explicit remaining cases. | **PARTIAL** |
+| Parameterized environment control | Wallet import choices and Extension analytics consent are typed. Domain fixtures, service doubles, geo eligibility, network catalogs, and remote stream scenarios are not general release-plan inputs. | **MISSING** |
+
+## Perps: 64 Critical cases
+
+The existing Perps surface can prepare, read, assert, and close selected
+positions and open orders, and place a basic order. See the
+[`Extension manifest`](../library/manifests/extension.action-manifest.json) and
+[`smoke recipe`](../library/recipes/extension/perps/smoke.recipe.json). It does
+not reproduce the checklist's seeded account snapshot: balance, long and short
+positions, limit orders, take-profit/stop-loss state, activity, watchlist, and
+controlled provider responses and streams.
+
+| Case family | Required start state | Required operations and assertions | 0.36.0 coverage |
+| --- | --- | --- | --- |
+| Feature, navigation, session (4) | Feature/eligibility combinations and accounts with different Perps state | Toggle gates, lock/unlock, switch accounts, navigate back; assert gating, account isolation, and route recovery | **PARTIAL**: wallet/account and generic navigation exist; deterministic gates and Perps session assertions are missing. |
+| Perps home (8) | Seeded balance, positions, orders, watchlist, and history | Open cards and balance actions, mutate watchlist; assert all seeded summaries and recent activity | **PARTIAL**: position/order reads and assertions exist; account, market, watchlist, and activity observations are missing. |
+| Market list (4) | Controlled catalog, categories, and price updates | Search, filter, sort, open a market; assert catalog and live values | **PARTIAL**: UI mechanics only; no market catalog or price assertion. |
+| Market details (6) | Selected market data, candles, position, and market-specific order | Navigate and change chart range; assert header, stats, chart states, action mode, and selected-market orders | **PARTIAL**: route and selected order/position state only; market and chart observations are missing. |
+| Order entry (12) | Known balance, constraints, price, leverage limits, and order outcomes | Edit side, amount, percent, leverage, limit price, TP/SL; submit market/limit orders; assert validation, preview, fill, resting order, and duplicate protection | **PARTIAL**: basic placement and open-order convergence exist; rich entry controls, limit/TP-SL inputs, validation, and outcome fields are missing. |
+| Position management (11) | Seeded isolated position, margin, TP/SL, and resting order | Add/reduce exposure, add margin, edit TP/SL, cancel order; assert size, margin, liquidation price, TP/SL, and removal | **PARTIAL**: close positions/orders exists; modify, margin, TP/SL, and rich field assertions are missing. |
+| Deposit (3) | Funded wallet and known Perps balance | Enter amount/Max and confirm; assert validation, pending/success, and resulting balances/activity | **MISSING** |
+| Withdraw (4) | Known withdrawable balance | Enter amount/percent/Max and confirm; assert validation, destination, balance, and activity | **MISSING** |
+| Activity and history (6) | Seeded trades, orders, funding, deposits, and withdrawals | Filter and open details; assert type-specific rows and agreement with home | **MISSING** |
+| Streaming and resilience (4) | Controllable initial responses, updates, reconnects, and order events | Refresh, disconnect/reconnect, close/reopen; assert price, position, order, activity, and loading-state reconciliation | **MISSING** |
+| Geo/compliance (1) | Ineligible trade state | Attempt a trade; assert blocking UI and no submitted order | **MISSING** |
+| Responsive presentation (1) | Popup-width Perps views with populated content | Traverse core views and capture surfaces; assert no clipping or overlap | **PARTIAL**: screenshots and generic UI assertions exist; no reusable Perps presentation assertion. |
+
+The aggregate Extension Perps snapshot is a **TARGET**. It exposes account,
+market, position, open-order, activity, and watchlist observations in one typed,
+read-only result when the Extension background test hook is present. An
+untouched production artifact does not expose that hook, so official-artifact
+Perps assertions still require a product-supported observation boundary. The
+snapshot also does not create the required start state.
+
+## Assets: 22 Critical cases
+
+| Case family | Required start state | Required operations and assertions | 0.36.0 coverage |
+| --- | --- | --- | --- |
+| Token list, prices, details, sorting (4) | Imported account with known live holdings across networks | Open and sort token list/details; assert holdings, fiat, change, chart, and market data | **PARTIAL**: wallet import and UI mechanics only; no asset reads or assertions. |
+| Token import, hide, persistence, custom network (5) | Known ERC-20 contracts and custom network configuration | Search/import/hide/re-add/restart/remove network; assert visibility and persistence | **MISSING**: no token-list/import or custom-network domain actions. |
+| Real-time and aggregate balances (2) | Known multi-chain balances and an externally triggered update | Observe stream and aggregate; assert prompt update and total | **MISSING** |
+| EVM send and activity (3) | Two owned accounts with native/token funds and gas | Send token, native Max, and custom-gas transaction; assert confirmation, balances, gas behavior, and activity | **MISSING** |
+| NFTs (3) | Owned indexed NFT plus owned and unowned contracts | Detect/import/filter/open media; assert ownership rejection, metadata, image, and network filter | **MISSING** |
+| DeFi positions (2) | Account with known live protocol positions | Open list/details; assert protocol, supplied/borrowed assets, and USD totals | **MISSING** |
+| Solana assets and send (2) | Imported Solana account with SOL and SPL balances | Inspect assets and send SPL; assert fiat, confirmation, balances, and activity | **MISSING** |
+| Bitcoin balance (1) | Imported Bitcoin account with known balance | Open asset details; assert balance, fiat, and chart | **MISSING** |
+
+## Swap and Bridge: 39 cases (25 Critical, 14 Non-Critical)
+
+These cases intentionally form a sequential, live-funds journey. A successful
+step changes the next step's network and balances, so generic navigation alone
+cannot establish or prove the required state transitions.
+
+| Case family | Required start state | Required operations and assertions | 0.36.0 coverage |
+| --- | --- | --- | --- |
+| Random ERC-20 round trip on Ethereum (2 Critical) | Funded imported account and live token/quote services | Select eligible random token, swap amount then Max; assert quote, confirmation, balance deltas, and activity | **MISSING** |
+| WETH round trip (2 Critical) | Funded Ethereum account | Swap ETH to WETH and Max back; assert quotes, wrapping result, balance deltas, and activity | **MISSING** |
+| Gasless round trip (2 Critical) | Smart Transactions enabled and funded ETH/USDC balances | Execute full-balance gasless swaps; assert route, no stranded input, balances, and activity | **MISSING** |
+| Ethereum to native Solana (2 Critical) | Funded Ethereum source and derived Solana destination | Bridge Max and await completion; assert destination asset is native SOL, balances, and activity | **MISSING** |
+| Half/Max swaps across destination networks (12 Critical, 8 Non-Critical) | Balance delivered by the preceding bridge on each network | Pick supported random token, swap about half and Max back; assert quote/route, confirmation, balance deltas, and activity | **MISSING** |
+| Sequential onward bridges (5 Critical, 4 Non-Critical) | Source balance produced by the preceding swap | Bridge Max to the specified next network and await completion; assert source/destination assets, balances, and activity | **MISSING** |
+| Quote-only networks (2 Non-Critical) | Selected network and funded source asset | Request but do not submit a quote; assert supported routes, fees, and destination | **MISSING** |
+
+## Networks: 10 cases (7 Critical, 3 not marked Critical)
+
+| Case family | Required start state | Required operations and assertions | 0.36.0 coverage |
+| --- | --- | --- | --- |
+| Custom-network asset rendering (4) | HyperEVM, INK, and XDC configurations plus known token contracts/balances | Add/select networks and tokens; assert decimals, render stability, logos, and token rows | **MISSING** |
+| Fiat and price APIs (2) | Custom networks with supported native assets and conversion responses | Refresh/select network; assert conversion rates and fiat values | **MISSING** |
+| Send Max and activity (2) | Funded HyperEVM/INK accounts and recipient | Send native Max; assert review amount, gas handling, completion, balance, and activity | **MISSING** |
+| Bridge label, tracking, details (2) | Funded Monad account and a completed bridge route | Submit/open bridge activity; assert label, status tracking, route, fees, and details | **MISSING** |
+
+## Prioritized delivery order
+
+1. **Downloaded official artifact validation and launch — current target.**
+   Accept a local ZIP, trusted digest, and requested version from the
+   release-validation workflow; validate the manifest and extracted tree,
+   reuse a validated cache, and launch without modifying the source checkout
+   or original artifact. Prove onboarding, visible wallet import, normal popup
+   operation, and side-panel operation.
+2. **Aggregate Extension Perps snapshot — current target.** Add a typed,
+   read-only result for account, markets, positions, open orders, activity, and
+   watchlist, with selectors suitable for machine assertions. It is usable in
+   source-built runtimes that expose the background test hook; an untouched
+   production artifact must fail explicitly until it has a supported read-only
+   observation boundary.
+3. **Deterministic Perps start state.** Add setup-time, trace-visible provider
+   doubles and seeded balance, positions, limit orders, TP/SL, activity, and
+   watchlist. Keep setup outside the proof window and never mutate product
+   state to manufacture an assertion.
+4. **Complete Perps operations and assertions.** Add parameterized feature and
+   eligibility control, watchlist, rich order entry, position changes, margin,
+   TP/SL, deposits, withdrawals, activity filters, and stream recovery. Extend
+   shared Mobile/Extension vocabulary where both clients support the behavior.
+5. **Release-plan completion gate.** Validate canonical case IDs, verdict
+   counts, required evidence, and explicit remaining cases before reporting a
+   terminal result.
+6. **Assets and Networks domain surfaces.** Add shared network selection and
+   custom-network state first, then typed assets, balances, token import,
+   transaction/activity, NFT, DeFi, and non-EVM observations.
+7. **Swap and Bridge domain surface.** Add quote, route, submit, status,
+   balance-delta, and activity actions with explicit live-funds safeguards and
+   resumable sequential state.
+
+Completing the two current targets does **not** provide full Perps parity. The
+64-case plan still depends on deterministic domain state, controlled provider
+behavior, richer mutations and assertions, and a canonical completion gate.

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

@@ -1,5 +1,6 @@
 import { pathToFileURL } from 'node:url';
 import { dataTestId, marketSymbol, normalizeMarketSymbol, runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+import { readSnapshot } from './read_snapshot.mjs';
 import { readPerpsRuntimeStateExpression } from './state.mjs';
 
 function sleep(ms) {
@@ -832,6 +833,7 @@ export async function teardownState(input) {
 }
 
 const DIRECT_ACTIONS = new Map([
+  ['metamask.perps.read_snapshot', readSnapshot],
   ['metamask.perps.read_positions', readPositions],
   ['metamask.perps.read_orders', readOrders],
   ['metamask.perps.close_positions', closePositions],