@deeeed/metamask-harness 0.12.0 → 0.14.0

package/library/actions/mobile/platform/bridge.mjs

@@ -3,9 +3,35 @@ import { execFile, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import bridgeErrors from '../../../../adapters/mobile/bridge-runtime/lib/bridge-errors.cjs';
+
+const {
+  BRIDGE_ERROR_CODES,
+  ERROR_CODE_BY_EXIT_CODE,
+  classifyBridgeErrorMessage,
+  coded,
+  parseErrorMarker,
+} = bridgeErrors;
+
+// Re-exported so the TS adapter classifies on the same code constants without a
+// second import path into the cjs bridge-runtime.
+export const MOBILE_BRIDGE_ERROR_CODES = BRIDGE_ERROR_CODES;
 
 const execFileAsync = promisify(execFile);
 
+// Recover the typed code a cdp-bridge child reported: the stderr marker is
+// authoritative (it carries the class the bridge classified at the source), the
+// coded exit status is the fallback for output-less failures, and a raw message
+// needle covers a bridge that predates the codes.
+function bridgeChildErrorCode(exitCode, output) {
+  return (
+    parseErrorMarker(output) ||
+    ERROR_CODE_BY_EXIT_CODE[exitCode] ||
+    classifyBridgeErrorMessage(output) ||
+    null
+  );
+}
+
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -169,12 +195,12 @@ export function selectBridgeStatusEntry(status, input) {
     }
     // Pinned android but no android entry answered — failing fast beats letting the
     // caller read the iOS entry and report misleading wallet state.
-    throw new Error(
+    throw coded(new Error(
       `Pinned android device ${adbSerial} has no responding bridge target.\n` +
       `  Bridge status entries:\n` +
       entries.map((entry) => `    - ${entry.deviceName ?? '?'} [${entry.platform || 'unknown'}]`).join('\n') +
       `\n  Next: mm-harness launch android   # bring the app back to the foreground`,
-    );
+    ), BRIDGE_ERROR_CODES.NO_TARGET);
   }
   if (iosSimulator) {
     const sim = entries.find((entry) => entry.deviceName === iosSimulator);
@@ -239,11 +265,16 @@ export async function bridgeCommand(input, args) {
   });
   if (result.timedOut) {
     const command = ['node', path.relative(input.context.projectRoot, script), ...redactBridgeArgs(args)].join(' ');
-    throw new Error(`Mobile CDP bridge command timed out after ${result.timeoutMs}ms: ${command}`);
+    throw coded(
+      new Error(`Mobile CDP bridge command timed out after ${result.timeoutMs}ms: ${command}`),
+      BRIDGE_ERROR_CODES.CDP_TIMEOUT,
+    );
   }
   if (result.exitCode !== 0) {
     const command = ['node', path.relative(input.context.projectRoot, script), ...redactBridgeArgs(args)].join(' ');
-    throw new Error(`Mobile CDP bridge command failed: ${command}\n${redactBridgeOutput(result.stderr || result.stdout, sensitiveBridgeArgs(args))}`);
+    const code = bridgeChildErrorCode(result.exitCode, result.stderr || result.stdout);
+    const error = new Error(`Mobile CDP bridge command failed: ${command}\n${redactBridgeOutput(result.stderr || result.stdout, sensitiveBridgeArgs(args))}`);
+    throw code ? coded(error, code) : error;
   }
   // For transient commands, stdout of '' or 'undefined' means the state is not yet
   // settled (e.g. mid-navigation). Return null so callers like waitForRoute can poll

package/library/recipes/{app-lifecycle-android-smoke.mobile.recipe.json → app/lifecycle.android-smoke.mobile.recipe.json}

@@ -68,7 +68,7 @@
         },
         "screenshot-after": {
           "action": "ui.screenshot",
-          "path": "screenshots/app-lifecycle-android-smoke.png",
+          "path": "screenshots/app.lifecycle.android-smoke.png",
           "intent": "Capture the app after Android lifecycle foreground",
           "detail": "Visual proof that the selected device is displaying the relaunched app.",
           "flow": "evidence",

package/library/recipes/{perps-performance.mobile.recipe.json → perps/performance.mobile.recipe.json}

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "title": "MetaMask Mobile Perps performance flow",
-  "description": "Canonical measured flow for MetaMask Mobile Perps: setup unlocks the wallet, startState records the stable status, then the measured workflow opens the Perps market list, reads live state, and opens a market detail. Timings live in trace.json as each node's duration; there is no built-in benchmark verb. Run pinned so numbers are comparable: `mm-harness run perps-performance --device <serial> --heal off`. Optional testnet order placement is intentionally omitted because a live order would make the flow destructive and non-repeatable; add metamask.perps.place_order + close in a personal copy when you want to measure the trade path.",
+  "description": "Canonical measured flow for MetaMask Mobile Perps: setup unlocks the wallet, startState records the stable status, then the measured workflow opens the Perps market list, reads live state, and opens a market detail. Timings live in trace.json as each node's duration; there is no built-in benchmark verb. Run pinned so numbers are comparable: `mm-harness run perps.performance --device <serial> --heal off`. Optional testnet order placement is intentionally omitted because a live order would make the flow destructive and non-repeatable; add metamask.perps.place_order + close in a personal copy when you want to measure the trade path.",
   "startState": {
     "action": "app.status",
     "intent": "Record the stable run start status after wallet setup",

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

@@ -0,0 +1,39 @@
+{
+  "schema_version": 1,
+  "title": "MetaMask core Perps smoke",
+  "description": "Non-mutating Perps domain smoke for the headless core adapter: instantiates the Perps controller and reads live positions, orders, and account state.",
+  "validate": {
+    "workflow": {
+      "entry": "status",
+      "nodes": {
+        "status": {
+          "action": "app.status",
+          "next": "read-positions",
+          "intent": "Resolve the core checkout and report headless compatibility mode"
+        },
+        "read-positions": {
+          "action": "metamask.perps.read_positions",
+          "mode": "all",
+          "next": "read-orders",
+          "intent": "Read live Perps positions from the headless controller"
+        },
+        "read-orders": {
+          "action": "metamask.perps.read_orders",
+          "mode": "all",
+          "next": "read-account",
+          "intent": "Read live Perps open orders from the headless controller"
+        },
+        "read-account": {
+          "action": "metamask.perps.read_account",
+          "next": "done",
+          "intent": "Read live Perps account state from the headless controller"
+        },
+        "done": {
+          "action": "end",
+          "status": "pass",
+          "intent": "Finish the core Perps smoke"
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,51 @@
+{
+  "schema_version": 1,
+  "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.",
+  "validate": {
+    "workflow": {
+      "entry": "status",
+      "nodes": {
+        "status": {
+          "action": "app.status",
+          "next": "cdp",
+          "intent": "Resolve the Extension checkout and adapter status before Perps proof"
+        },
+        "cdp": {
+          "action": "cdp.target",
+          "required": true,
+          "timeout_ms": 15000,
+          "next": "ensure-unlocked",
+          "intent": "Confirm the Extension CDP runtime is reachable"
+        },
+        "ensure-unlocked": {
+          "action": "metamask.wallet.ensure_unlocked",
+          "timeout_ms": 45000,
+          "next": "open-perps",
+          "intent": "Ensure the wallet is unlocked before opening Perps"
+        },
+        "open-perps": {
+          "action": "ui.navigate",
+          "page": "perps",
+          "next": "read-positions",
+          "intent": "Open the Perps page through the stable page alias"
+        },
+        "read-positions": {
+          "action": "metamask.perps.read_positions",
+          "next": "read-orders",
+          "intent": "Read live Perps positions without mutating account state"
+        },
+        "read-orders": {
+          "action": "metamask.perps.read_orders",
+          "next": "done",
+          "intent": "Read live Perps open orders without mutating account state"
+        },
+        "done": {
+          "action": "end",
+          "status": "pass",
+          "intent": "Finish the Extension Perps smoke"
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,51 @@
+{
+  "schema_version": 1,
+  "title": "MetaMask Mobile Perps smoke",
+  "description": "Non-mutating Perps domain smoke for MetaMask Mobile: verifies the live bridge, unlocks if needed, opens the Perps market list, and reads live Perps positions and orders.",
+  "validate": {
+    "workflow": {
+      "entry": "status",
+      "nodes": {
+        "status": {
+          "action": "app.status",
+          "next": "cdp",
+          "intent": "Resolve the Mobile checkout and adapter status before Perps proof"
+        },
+        "cdp": {
+          "action": "cdp.target",
+          "required": true,
+          "timeout_ms": 15000,
+          "next": "ensure-unlocked",
+          "intent": "Confirm the React Native debug bridge is reachable"
+        },
+        "ensure-unlocked": {
+          "action": "metamask.wallet.ensure_unlocked",
+          "timeout_ms": 45000,
+          "next": "open-perps",
+          "intent": "Ensure the wallet is unlocked before opening Perps"
+        },
+        "open-perps": {
+          "action": "ui.navigate",
+          "page": "perps",
+          "next": "read-positions",
+          "intent": "Open the Perps market list through the stable page alias"
+        },
+        "read-positions": {
+          "action": "metamask.perps.read_positions",
+          "next": "read-orders",
+          "intent": "Read live Perps positions without mutating account state"
+        },
+        "read-orders": {
+          "action": "metamask.perps.read_orders",
+          "next": "done",
+          "intent": "Read live Perps open orders without mutating account state"
+        },
+        "done": {
+          "action": "end",
+          "status": "pass",
+          "intent": "Finish the Mobile Perps smoke"
+        }
+      }
+    }
+  }
+}

package/library/recipes/{action-validation.extension.recipe.json → runner/action-validation.extension.recipe.json}

@@ -8,9 +8,9 @@
       "nodes": {
         "prepare-files": {
           "action": "command",
-          "cmd": "mkdir -p temp/recipe-action-validation && printf 'E2E_ACTION_VALIDATION extension\\n' > temp/recipe-action-validation/probe.txt && printf '{\"platform\":\"extension\",\"ok\":true}\n' > temp/recipe-action-validation/probe.json && printf 'extension log E2E_ACTION_VALIDATION\\n' > temp/recipe-action-validation/validation.log && echo E2E_ACTION_VALIDATION extension",
+          "cmd": "mkdir -p temp/recipe-runner.action-validation && printf 'E2E_ACTION_VALIDATION extension\\n' > temp/recipe-runner.action-validation/probe.txt && printf '{\"platform\":\"extension\",\"ok\":true}\n' > temp/recipe-runner.action-validation/probe.json && printf 'extension log E2E_ACTION_VALIDATION\\n' > temp/recipe-runner.action-validation/validation.log && echo E2E_ACTION_VALIDATION extension",
           "next": "assert-command-exit",
-          "intent": "Prepare action-validation probe files",
+          "intent": "Prepare runner.action-validation probe files",
           "detail": "Create local files used to prove command/assert/log/artifact actions.",
           "flow": "setup"
         },
@@ -35,7 +35,7 @@
         },
         "assert-file": {
           "action": "assert_file",
-          "path": "temp/recipe-action-validation/probe.txt",
+          "path": "temp/recipe-runner.action-validation/probe.txt",
           "contains": "E2E_ACTION_VALIDATION extension",
           "next": "assert-json",
           "intent": "Verify file assertions work",
@@ -44,7 +44,7 @@
         },
         "assert-json": {
           "action": "assert_json",
-          "path": "temp/recipe-action-validation/probe.json",
+          "path": "temp/recipe-runner.action-validation/probe.json",
           "assert": {
             "path": "$.platform",
             "operator": "eq",
@@ -57,7 +57,7 @@
         },
         "watch-logs": {
           "action": "watch_logs",
-          "path": "temp/recipe-action-validation/validation.log",
+          "path": "temp/recipe-runner.action-validation/validation.log",
           "contains": "E2E_ACTION_VALIDATION",
           "next": "index-artifacts",
           "intent": "Verify log watching works",
@@ -68,7 +68,7 @@
           "action": "index_artifacts",
           "artifacts": [
             {
-              "path": "temp/recipe-action-validation/probe.txt",
+              "path": "temp/recipe-runner.action-validation/probe.txt",
               "type": "log",
               "category": "debug",
               "label": "Extension action validation probe"
@@ -173,7 +173,7 @@
         },
         "ui-screenshot-perps": {
           "action": "ui.screenshot",
-          "path": "screenshots/extension-perps-action-validation.png",
+          "path": "screenshots/extension-perps-runner.action-validation.png",
           "timeout_ms": 5000,
           "next": "wallet-navigate-perps",
           "intent": "Capture Perps visual proof",

package/library/recipes/{action-validation.mobile.recipe.json → runner/action-validation.mobile.recipe.json}

@@ -8,9 +8,9 @@
       "nodes": {
         "prepare-files": {
           "action": "command",
-          "cmd": "mkdir -p temp/recipe-action-validation && printf 'E2E_ACTION_VALIDATION mobile\\n' > temp/recipe-action-validation/probe.txt && printf '{\"platform\":\"mobile\",\"ok\":true}\n' > temp/recipe-action-validation/probe.json && printf 'mobile log E2E_ACTION_VALIDATION\\n' > temp/recipe-action-validation/validation.log && echo E2E_ACTION_VALIDATION mobile",
+          "cmd": "mkdir -p temp/recipe-runner.action-validation && printf 'E2E_ACTION_VALIDATION mobile\\n' > temp/recipe-runner.action-validation/probe.txt && printf '{\"platform\":\"mobile\",\"ok\":true}\n' > temp/recipe-runner.action-validation/probe.json && printf 'mobile log E2E_ACTION_VALIDATION\\n' > temp/recipe-runner.action-validation/validation.log && echo E2E_ACTION_VALIDATION mobile",
           "next": "assert-command-exit",
-          "intent": "Prepare action-validation probe files",
+          "intent": "Prepare runner.action-validation probe files",
           "detail": "Create local files used to prove command/assert/log/artifact actions.",
           "flow": "setup"
         },
@@ -35,7 +35,7 @@
         },
         "assert-file": {
           "action": "assert_file",
-          "path": "temp/recipe-action-validation/probe.txt",
+          "path": "temp/recipe-runner.action-validation/probe.txt",
           "contains": "E2E_ACTION_VALIDATION mobile",
           "next": "assert-json",
           "intent": "Verify file assertions work",
@@ -44,7 +44,7 @@
         },
         "assert-json": {
           "action": "assert_json",
-          "path": "temp/recipe-action-validation/probe.json",
+          "path": "temp/recipe-runner.action-validation/probe.json",
           "assert": {
             "path": "$.platform",
             "operator": "eq",
@@ -57,7 +57,7 @@
         },
         "watch-logs": {
           "action": "watch_logs",
-          "path": "temp/recipe-action-validation/validation.log",
+          "path": "temp/recipe-runner.action-validation/validation.log",
           "contains": "E2E_ACTION_VALIDATION",
           "next": "index-artifacts",
           "intent": "Verify log watching works",
@@ -68,7 +68,7 @@
           "action": "index_artifacts",
           "artifacts": [
             {
-              "path": "temp/recipe-action-validation/probe.txt",
+              "path": "temp/recipe-runner.action-validation/probe.txt",
               "type": "log",
               "category": "debug",
               "label": "Mobile action validation probe"
@@ -174,7 +174,7 @@
         },
         "ui-screenshot-wallet": {
           "action": "ui.screenshot",
-          "path": "screenshots/mobile-wallet-action-validation.png",
+          "path": "screenshots/mobile-wallet-runner.action-validation.png",
           "next": "wallet-navigate-perps",
           "intent": "Capture wallet visual proof",
           "detail": "Save a screenshot artifact after generic UI actions.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -69,4 +69,4 @@
     "url": "https://github.com/MetaMask/experimental-metamask-harness/issues"
   },
   "homepage": "https://github.com/MetaMask/experimental-metamask-harness#readme"
-}
+}