@deeeed/metamask-harness 0.42.0 → 0.44.0

package/dist/adapters/mobile/prepare.js

@@ -59,6 +59,18 @@ async function prepareMobile(target, opts = {}) {
     return { status: EXIT.runtime, output: msg };
   }
   const iosAccessibilityChanged = platform === "ios" && report.decision !== "unknown" && enableIosAccessibility(json);
+  const rebuildNative = preflightMode === "rebuild-native" || preflightMode === "clean";
+  if (report.decision === "ready" && rebuildNative) {
+    const launch = await dispatchActionSequence(
+      launchActions(path.resolve(target), clearMetro),
+      target,
+      platform,
+      json,
+      preflightMode,
+      opts.watcherPort
+    );
+    return launch.status === 0 ? startMobileConsoleForwarder(target, platform, json, opts.watcherPort) : launch;
+  }
   if (report.decision === "ready" && clearMetro) {
     const launch = await dispatchActionSequence(
       withAppRestart(

package/dist/adapters/performance/cdp-trace.js

@@ -0,0 +1,342 @@
+import {
+  summarizeFrames
+} from "../mobile/frame-metrics.js";
+import { withTimeout } from "../../async.js";
+import {
+  summarizeJavaScriptTasks
+} from "./js-task-metrics.js";
+const FRAME_BUDGET_MS = 1e3 / 60;
+const MAX_TRACE_BYTES = 64 * 1024 * 1024;
+const MAX_TRACE_EVENTS = 25e4;
+const MOBILE_TRACE_CATEGORIES = [
+  "blink.user_timing",
+  "disabled-by-default-devtools.timeline.frame"
+];
+const EXTENSION_TRACE_CATEGORIES = [
+  "blink.user_timing",
+  "devtools.timeline",
+  "disabled-by-default-devtools.timeline",
+  "disabled-by-default-devtools.timeline.frame",
+  "v8.execute"
+];
+function createCdpTraceCollector(client, platform, marker) {
+  let active;
+  const offData = client.on("Tracing.dataCollected", (params) => {
+    if (!active || !Array.isArray(params.value)) return;
+    for (const value of params.value) {
+      if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+      const event = value;
+      const bytes = Buffer.byteLength(JSON.stringify(event));
+      if (active.events.length >= MAX_TRACE_EVENTS || active.bytes + bytes > MAX_TRACE_BYTES) {
+        active.overflow = true;
+        continue;
+      }
+      active.events.push(event);
+      active.bytes += bytes;
+    }
+  });
+  const offComplete = client.on("Tracing.tracingComplete", (params) => {
+    if (!active) return;
+    active.dataLossOccurred = params.dataLossOccurred === true;
+    active.complete?.();
+  });
+  return {
+    async start(id) {
+      if (active) throw new Error("Only one CDP performance trace may be active.");
+      let complete;
+      const completePromise = new Promise((resolve) => {
+        complete = resolve;
+      });
+      active = {
+        id,
+        events: [],
+        bytes: 0,
+        overflow: false,
+        dataLossOccurred: false,
+        complete,
+        completePromise
+      };
+      let tracingStarted = false;
+      try {
+        await client.send(
+          "Tracing.start",
+          {
+            categories: (platform === "extension" ? EXTENSION_TRACE_CATEGORIES : MOBILE_TRACE_CATEGORIES).join(","),
+            transferMode: "ReportEvents"
+          },
+          15e3
+        );
+        tracingStarted = true;
+        const markerName = `mmh-clock-${id}-${Date.now()}`;
+        const sync = await marker(markerName);
+        active.markerName = markerName;
+        active.markerHostEpochMs = sync.hostEpochMs;
+        active.markerUncertaintyMs = sync.uncertaintyMs;
+      } catch (error) {
+        if (tracingStarted) {
+          await client.send("Tracing.end", {}, 5e3).catch(() => void 0);
+          await withTimeout(active.completePromise, {
+            message: "CDP tracing cleanup did not report tracingComplete.",
+            timeoutMs: 1e3
+          }).catch(() => void 0);
+        }
+        active = void 0;
+        throw error;
+      }
+    },
+    async end(id) {
+      const capture = active;
+      if (!capture || capture.id !== id) {
+        throw new Error(`Performance capture is not active: ${id}`);
+      }
+      try {
+        await client.send("Tracing.end", {}, 15e3);
+        await withTimeout(capture.completePromise, {
+          message: "CDP tracing did not report tracingComplete.",
+          timeoutMs: 3e4
+        });
+      } finally {
+        active = void 0;
+      }
+      return parseTraceCapture({
+        platform,
+        events: capture.events,
+        markerName: capture.markerName,
+        markerHostEpochMs: capture.markerHostEpochMs,
+        markerUncertaintyMs: capture.markerUncertaintyMs,
+        dataLossOccurred: capture.dataLossOccurred,
+        overflow: capture.overflow,
+        unavailableReasons: [],
+        coverageGapReasons: []
+      });
+    },
+    async close() {
+      if (active) {
+        await client.send("Tracing.end", {}, 5e3).catch(() => void 0);
+        await withTimeout(active.completePromise, {
+          message: "CDP tracing cleanup did not report tracingComplete.",
+          timeoutMs: 1e3
+        }).catch(() => void 0);
+        active = void 0;
+      }
+      offData();
+      offComplete();
+      client.close();
+    }
+  };
+}
+function parseTraceCapture(capture) {
+  const marker = findClockMarker(capture.events, capture.markerName);
+  if (capture.platform === "extension" && !finite(marker?.pid)) {
+    const reason = "Extension trace marker did not identify a renderer process.";
+    return {
+      platform: capture.platform,
+      javascript: unavailableJavaScriptSource("cdp-js-runtime-tasks", reason),
+      nativeUi: unavailableNativeUiSource("cdp-native-frame-timings", reason),
+      trace: traceEvidence(capture, "unresolved")
+    };
+  }
+  const scopedEvents = capture.platform === "extension" && finite(marker?.pid) ? capture.events.filter((event) => event.pid === marker.pid) : capture.events;
+  const scope = capture.platform !== "extension" ? "mobile-host" : finite(marker?.pid) ? "extension-renderer" : "unresolved";
+  const trace = traceEvidence(
+    { ...capture, events: scopedEvents },
+    scope,
+    finite(marker?.pid) ? marker.pid : void 0
+  );
+  if (!finite(marker?.ts) || capture.markerHostEpochMs === void 0 || capture.markerUncertaintyMs === void 0) {
+    const reason = "CDP trace clock marker was unavailable.";
+    return {
+      platform: capture.platform,
+      javascript: unavailableJavaScriptSource("cdp-js-runtime-tasks", reason),
+      nativeUi: unavailableNativeUiSource(
+        "cdp-native-frame-timings",
+        reason
+      ),
+      trace
+    };
+  }
+  const traceToEpochMs = (timestampUs) => capture.markerHostEpochMs + (timestampUs - marker.ts) / 1e3;
+  const gapReasons = [
+    ...capture.coverageGapReasons,
+    ...capture.overflow ? ["CDP trace retention limit was reached."] : [],
+    ...capture.dataLossOccurred ? ["CDP reported trace data loss."] : []
+  ];
+  const nativeSamples = nativeFrameSamples(
+    scopedEvents,
+    capture.platform,
+    traceToEpochMs
+  );
+  const javascriptSamples = javascriptTaskSamples(
+    scopedEvents,
+    traceToEpochMs
+  );
+  const status = capture.overflow || capture.dataLossOccurred ? "partial" : "complete";
+  return {
+    platform: capture.platform,
+    javascript: javascriptSourceResult(
+      "cdp-js-runtime-tasks",
+      javascriptSamples,
+      status,
+      gapReasons,
+      traceEventNames(scopedEvents),
+      capture.markerUncertaintyMs
+    ),
+    nativeUi: nativeUiSourceResult(
+      capture.platform === "extension" ? "chromium-cdp-frame-timings" : "react-native-cdp-frame-timings",
+      nativeSamples,
+      status,
+      gapReasons,
+      traceEventNames(scopedEvents),
+      capture.markerUncertaintyMs
+    ),
+    trace
+  };
+}
+function traceEvidence(capture, scope, rendererProcessId) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const event of capture.events) {
+    const name = String(event.name ?? "");
+    counts.set(name, (counts.get(name) ?? 0) + 1);
+  }
+  return {
+    beginFrameCount: counts.get("BeginFrame") ?? 0,
+    dataLossOccurred: capture.dataLossOccurred,
+    drawFrameCount: counts.get("DrawFrame") ?? 0,
+    overflow: capture.overflow,
+    profileChunkCount: counts.get("ProfileChunk") ?? 0,
+    ...rendererProcessId === void 0 ? {} : { rendererProcessId },
+    runTaskCount: counts.get("RunTask") ?? 0,
+    scope,
+    totalEventCount: capture.events.length
+  };
+}
+function nativeFrameSamples(events, platform, traceToEpochMs) {
+  const begins = /* @__PURE__ */ new Map();
+  const frames = [];
+  for (const event of events) {
+    if (event.name !== "BeginFrame" && event.name !== "DrawFrame") continue;
+    const sequence = frameSequence(event);
+    if (!sequence || !finite(event.ts)) continue;
+    if (event.name === "BeginFrame") {
+      begins.set(sequence, event);
+      continue;
+    }
+    const begin = begins.get(sequence);
+    if (!begin || !finite(begin.ts)) continue;
+    frames.push({ beginUs: begin.ts, endUs: event.ts });
+  }
+  frames.sort((first, second) => first.beginUs - second.beginUs);
+  if (platform === "ios") {
+    const samples = [];
+    for (let index = 1; index < frames.length; index += 1) {
+      const previous = frames[index - 1];
+      const current = frames[index];
+      if (!previous || !current) continue;
+      const durationMs = (current.beginUs - previous.beginUs) / 1e3;
+      if (durationMs <= 0) continue;
+      samples.push({
+        completedAtEpochMs: traceToEpochMs(current.beginUs),
+        durationMs,
+        janky: durationMs > FRAME_BUDGET_MS * 1.01
+      });
+    }
+    return samples;
+  }
+  return frames.map((frame) => {
+    const durationMs = (frame.endUs - frame.beginUs) / 1e3;
+    return {
+      completedAtEpochMs: traceToEpochMs(frame.endUs),
+      durationMs,
+      janky: durationMs > FRAME_BUDGET_MS * 1.01
+    };
+  }).filter((sample) => sample.durationMs > 0);
+}
+function javascriptTaskSamples(events, traceToEpochMs) {
+  return events.filter(
+    (event) => event.name === "RunTask" && event.ph === "X" && finite(event.ts) && finite(event.dur) && event.dur > 0
+  ).map((event) => ({
+    completedAtEpochMs: traceToEpochMs(event.ts + event.dur),
+    durationMs: event.dur / 1e3
+  }));
+}
+function findClockMarker(events, markerName) {
+  if (!markerName) return void 0;
+  return events.find(
+    (candidate) => candidate.name === markerName || asRecord(candidate.args).sync_id === markerName || asRecord(asRecord(candidate.args).data).sync_id === markerName
+  );
+}
+function frameSequence(event) {
+  const args = asRecord(event.args);
+  const value = args.frameSeqId ?? asRecord(args.data).frameSeqId;
+  return value === void 0 ? void 0 : String(value);
+}
+function javascriptSourceResult(kind, samples, status, coverageGapReasons, observedEventNames, clockSyncUncertaintyMs) {
+  return {
+    status: samples.length > 0 ? status : "partial",
+    kind,
+    unavailableReasons: [],
+    coverageGapReasons: [
+      ...coverageGapReasons,
+      ...samples.length > 0 ? [] : [
+        `No ${kind} samples were recorded. Observed trace events: ${observedEventNames.join(", ") || "none"}.`
+      ]
+    ],
+    samples,
+    summary: summarizeJavaScriptTasks(samples),
+    clockSyncUncertaintyMs
+  };
+}
+function nativeUiSourceResult(kind, samples, status, coverageGapReasons, observedEventNames, clockSyncUncertaintyMs) {
+  return {
+    status: samples.length > 0 ? status : "partial",
+    kind,
+    unavailableReasons: [],
+    coverageGapReasons: [
+      ...coverageGapReasons,
+      ...samples.length > 0 ? [] : [
+        `No ${kind} samples were recorded. Observed trace events: ${observedEventNames.join(", ") || "none"}.`
+      ]
+    ],
+    samples,
+    summary: summarizeFrames(samples),
+    clockSyncUncertaintyMs
+  };
+}
+function traceEventNames(events) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const event of events) {
+    const name = String(event.name ?? "unknown");
+    counts.set(name, (counts.get(name) ?? 0) + 1);
+  }
+  return [...counts.entries()].sort((first, second) => second[1] - first[1]).slice(0, 20).map(([name, count]) => `${name}(${count})`);
+}
+function unavailableJavaScriptSource(kind, reason) {
+  return {
+    status: "unavailable",
+    kind,
+    unavailableReasons: [reason],
+    coverageGapReasons: [],
+    samples: [],
+    summary: { taskCount: 0 }
+  };
+}
+function unavailableNativeUiSource(kind, reason) {
+  return {
+    status: "unavailable",
+    kind,
+    unavailableReasons: [reason],
+    coverageGapReasons: [],
+    samples: [],
+    summary: { frameCount: 0 }
+  };
+}
+function finite(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+export {
+  createCdpTraceCollector,
+  parseTraceCapture
+};

package/dist/adapters/performance/js-task-metrics.js

@@ -0,0 +1,35 @@
+const LONG_TASK_MS = 50;
+function summarizeJavaScriptTasks(samples) {
+  const durations = samples.map((sample) => sample.durationMs).filter((duration) => Number.isFinite(duration) && duration > 0).sort((first, second) => first - second);
+  if (durations.length === 0) return { taskCount: 0 };
+  const longTaskCount = durations.filter(
+    (duration) => duration >= LONG_TASK_MS
+  ).length;
+  return {
+    longestTaskMs: round(durations.at(-1) ?? 0),
+    longTaskCount,
+    longTaskPercent: round(longTaskCount / durations.length * 100),
+    p50TaskMs: round(percentile(durations, 0.5)),
+    p95TaskMs: round(percentile(durations, 0.95)),
+    p99TaskMs: round(percentile(durations, 0.99)),
+    taskCount: durations.length,
+    totalTaskTimeMs: round(
+      durations.reduce((total, duration) => total + duration, 0)
+    )
+  };
+}
+function percentile(sorted, quantile) {
+  if (sorted.length === 1) return sorted[0] ?? 0;
+  const position = (sorted.length - 1) * quantile;
+  const lower = Math.floor(position);
+  const upper = Math.ceil(position);
+  const lowerValue = sorted[lower] ?? 0;
+  const upperValue = sorted[upper] ?? lowerValue;
+  return lowerValue + (upperValue - lowerValue) * (position - lower);
+}
+function round(value) {
+  return Math.round(value * 1e3) / 1e3;
+}
+export {
+  summarizeJavaScriptTasks
+};

package/dist/adapters.js

@@ -13,6 +13,7 @@ import { nativeAgentDeviceStateDir } from "../library/actions/mobile/platform/na
 import { resolveMobileToolPath } from "../library/actions/mobile/platform/tool-paths.mjs";
 import { resolveWalletImportCredentials, validateWalletImportOptions } from "../library/actions/shared/wallet/import-source.mjs";
 import { handleRunNetworkAction } from "./network-observation.js";
+import { handleRunPerformanceAction } from "./performance-observation.js";
 const execFileAsync = promisify(execFile);
 const NATIVE_PROVIDER_UI_ACTIONS = /* @__PURE__ */ new Set([
   "ui.press",
@@ -107,7 +108,9 @@ const LIVE_ONLY_WALLET_ACTIONS = /* @__PURE__ */ new Set([
 const LIVE_ONLY_APP_ACTIONS = /* @__PURE__ */ new Set([
   "ui.navigate",
   "app.network_capture",
-  "app.network_assert"
+  "app.network_assert",
+  "app.performance_capture",
+  "app.performance_assert"
 ]);
 function requiresLiveAdapter(platform, action) {
   return LIVE_ONLY_ACTIONS.has(action) || platform === "core" && CORE_ONLY_PERPS_ACTIONS.has(action) || LIVE_ONLY_WALLET_ACTIONS.has(action) || LIVE_ONLY_APP_ACTIONS.has(action);
@@ -145,6 +148,13 @@ function liveAdapterPathHint(platform, action) {
   return `library/actions/${platform}/${action.replaceAll(".", "/")}.mjs`;
 }
 async function semanticResult(platform, action, node, context, forceLive = false, preparedLiveAdapters) {
+  const performanceAction = await handleRunPerformanceAction(
+    platform,
+    action,
+    node,
+    context
+  );
+  if (performanceAction) return performanceAction;
   const networkAction = await handleRunNetworkAction(
     platform,
     action,
@@ -265,7 +275,12 @@ function createMetaMaskSemanticAdapters(platform, declaredCustomActions = [], pr
   ];
   const bundledActions = [
     ...walletActions,
-    ...platform !== "core" ? ["app.network_capture", "app.network_assert"] : [],
+    ...platform !== "core" ? [
+      "app.network_capture",
+      "app.network_assert",
+      "app.performance_capture",
+      "app.performance_assert"
+    ] : [],
     "metamask.assets.read_visible_state",
     "metamask.assets.open_details",
     "metamask.assets.read_details",
@@ -511,6 +526,7 @@ const MOBILE_BRIDGE_HANDLERS = {
   status: handleMobileStatus,
   navigate: handleMobileNavigate,
   press: handleMobilePress,
+  keyPress: handleMobileKeyPress,
   setInput: handleMobileSetInput,
   scroll: handleMobileScroll,
   waitFor: handleMobileWaitFor,
@@ -570,6 +586,11 @@ async function handleMobilePress(payload, context) {
   if (text !== void 0) return bridgeCommand(input, ["press-text", target]);
   return bridgeCommand(input, [longPress ? "long-press-test-id" : "press-test-id", target]);
 }
+async function handleMobileKeyPress(payload, context) {
+  const key = scalarText(payload.key, "ui.key_press.key", "Enter");
+  const input = mobileUiInput(context, "key_press", payload);
+  return bridgeCommand(input, ["key-press", key]);
+}
 async function handleMobileSetInput(payload, context) {
   const input = mobileUiInput(context, "set_input", payload);
   const testId = firstScalarText(payload, ["test_id", "testID"], "ui.set_input");
@@ -738,7 +759,17 @@ async function handleMobileWaitFor(payload, context) {
   return waitForMobileTarget(mobileUiInput(context, "waitFor", payload), payload);
 }
 async function handleMobileHud(payload, context) {
-  const input = mobileUiInput(context, "hud", payload);
+  const automaticProgress = typeof payload.action_name === "string" || context.nodeId === "recipe-complete" && isRecord(payload.progress) && payload.progress.complete === true;
+  const captureProgress = payload.action_name === "ui.screenshot" || payload.action_name === "ui.capture_surface";
+  const input = mobileUiInput(
+    context,
+    "hud",
+    automaticProgress ? {
+      ...payload,
+      bridge_timeout_ms: captureProgress ? 1e4 : 2e3,
+      cdp_timeout_ms: captureProgress ? 1e4 : 2e3
+    } : payload
+  );
   if (payload.clear === true) {
     try {
       return await bridgeCommand(input, ["hide-step"]);
@@ -748,7 +779,10 @@ async function handleMobileHud(payload, context) {
   }
   const hud = mobileHudPayload(payload, context);
   try {
-    const result = await bridgeCommand(input, ["show-step-json", JSON.stringify(hud.step)]);
+    const result = await bridgeCommand(input, [
+      automaticProgress && !captureProgress ? "show-step-json-deferred" : "show-step-json",
+      JSON.stringify(hud.step)
+    ]);
     return { hud: true, nodeId: hud.nodeId, status: hud.status, result };
   } catch (error) {
     return mobileHudSkippedOrThrow(error, { nodeId: hud.nodeId, status: hud.status });
@@ -762,7 +796,7 @@ async function hideMobileHudOnTeardown(projectRoot, env = {}) {
     context: { nodeId: "teardown", projectRoot, artifactsDir: projectRoot, env }
   };
   try {
-    await bridgeCommand(input, ["hide-step"]);
+    await bridgeCommand(input, ["hide-step-deferred"]);
   } catch {
   }
 }

package/dist/artifact-files.js

@@ -0,0 +1,92 @@
+import { constants as fsConstants } from "node:fs";
+import {
+  lstat,
+  mkdir,
+  open,
+  readFile,
+  realpath,
+  writeFile
+} from "node:fs/promises";
+import path from "node:path";
+async function writeContainedArtifact(artifactsDir, relativePath, value, label) {
+  const file = resolveContainedArtifact(artifactsDir, relativePath, label);
+  await mkdir(path.dirname(file), { recursive: true });
+  await assertContainedParent(artifactsDir, file, label);
+  await assertNotSymlink(file, label);
+  const handle = await open(
+    file,
+    fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_TRUNC | fsConstants.O_NOFOLLOW,
+    384
+  );
+  try {
+    await handle.writeFile(value);
+  } finally {
+    await handle.close();
+  }
+}
+async function readContainedJsonArtifact(artifactsDir, relativePath, maxBytes, label) {
+  const file = resolveContainedArtifact(artifactsDir, relativePath, label);
+  await assertContainedParent(artifactsDir, file, label);
+  await assertNotSymlink(file, label);
+  const handle = await open(file, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+  try {
+    const info = await handle.stat();
+    if (!info.isFile() || info.size > maxBytes) {
+      throw new Error(`${label} is not a bounded regular file.`);
+    }
+    return JSON.parse(await handle.readFile("utf8"));
+  } finally {
+    await handle.close();
+  }
+}
+async function indexArtifactManifest(manifestPath, entries) {
+  const parsed = JSON.parse(await readFile(manifestPath, "utf8"));
+  const manifest = asRecord(parsed);
+  const replacementPaths = new Set(entries.map((entry) => entry.path));
+  const current = Array.isArray(manifest.artifacts) ? manifest.artifacts.filter(
+    (artifact) => !replacementPaths.has(String(asRecord(artifact).path ?? ""))
+  ) : [];
+  await writeFile(
+    manifestPath,
+    `${JSON.stringify(
+      { ...manifest, artifacts: [...current, ...entries] },
+      null,
+      2
+    )}
+`
+  );
+}
+function resolveContainedArtifact(artifactsDir, relativePath, label) {
+  const root = path.resolve(artifactsDir);
+  const file = path.resolve(root, relativePath);
+  const relative = path.relative(root, file);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`${label} path must stay inside artifactsDir.`);
+  }
+  return file;
+}
+async function assertContainedParent(artifactsDir, file, label) {
+  const root = await realpath(artifactsDir);
+  const parent = await realpath(path.dirname(file));
+  const relative = path.relative(root, parent);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`${label} parent must stay inside artifactsDir.`);
+  }
+}
+async function assertNotSymlink(file, label) {
+  try {
+    if ((await lstat(file)).isSymbolicLink()) {
+      throw new Error(`${label} must not be a symbolic link.`);
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+}
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+export {
+  indexArtifactManifest,
+  readContainedJsonArtifact,
+  writeContainedArtifact
+};

package/dist/async.js

@@ -0,0 +1,19 @@
+async function withTimeout(promise, options) {
+  let timer;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+          options.onTimeout?.();
+          reject(new Error(options.message));
+        }, options.timeoutMs);
+      })
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+export {
+  withTimeout
+};