@bugmole/cli 0.4.0

package/src/runtime/appium-driver.test.ts

@@ -0,0 +1,179 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { AppiumDriver, locatorsFor } from "./appium-driver.js";
+import { normalizeTargets, targetLabel } from "./browser-matrix.js";
+import type { DeviceSessionHost } from "./device-clouds/index.js";
+import { finishedSession, startSession, uploadApp } from "../integrations/device-farm.js";
+import { ELEMENT_KEY } from "../integrations/webdriver-client.js";
+
+const PNG = Buffer.from("png").toString("base64");
+
+/** A WebDriver hub with a page that has a few labelled elements. */
+function fakeHub(elements: Record<string, { displayed: boolean }>) {
+  const calls: Array<{ method: string; path: string; body: any }> = [];
+  const typed: string[] = [];
+  const doFetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = new URL(String(input));
+    const body = init?.body ? JSON.parse(String(init.body)) : undefined;
+    const method = init?.method ?? "GET";
+    const pathname = url.pathname.replace(/^\/wd\/hub/, "");
+    calls.push({ method, path: pathname, body });
+    const ok = (value: unknown) => Response.json({ value });
+    if (pathname === "/session" && method === "POST") return ok({ sessionId: "S1", capabilities: body.capabilities.alwaysMatch });
+    if (pathname === "/session/S1/elements") {
+      const match = Object.keys(elements).find((label) => String(body.value).includes(label));
+      return ok(match ? [{ [ELEMENT_KEY]: match }] : []);
+    }
+    const element = pathname.match(/^\/session\/S1\/element\/([^/]+)\/(displayed|click|value|clear)$/);
+    if (element) {
+      if (element[2] === "displayed") return ok(elements[decodeURIComponent(element[1])]?.displayed ?? false);
+      if (element[2] === "value") typed.push(body.text);
+      return ok(null);
+    }
+    if (pathname === "/session/S1/element/active") return ok({ [ELEMENT_KEY]: "Email" });
+    if (pathname === "/session/S1/screenshot") return ok(PNG);
+    if (pathname === "/session/S1" && method === "DELETE") return ok(null);
+    if (pathname === "/session/S1/url") return ok(null);
+    return Response.json({ value: { error: "unknown command", message: pathname } }, { status: 404 });
+  }) as unknown as typeof fetch;
+  return { calls, typed, doFetch };
+}
+
+function workspace(flow: string) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "bugmole-appium-"));
+  const flowPath = path.join(dir, "flow.yaml");
+  fs.writeFileSync(flowPath, flow);
+  return { dir, flowPath };
+}
+
+const webDevice = { kind: "device", provider: "browserstack", credentialId: "cred_1", platform: "ios", deviceName: "iPhone 15", osVersion: "17", browserName: "safari" };
+
+test("device targets are validated and labelled", () => {
+  const [target] = normalizeTargets([webDevice, webDevice]);
+  assert.equal(target.id, "device-browserstack-iphone-15-17-safari");
+  assert.equal(target.browser, "webkit");
+  assert.equal(targetLabel(target), "iPhone 15 (17) · Safari");
+  assert.throws(() => normalizeTargets([{ ...webDevice, provider: "saucelabs" }]), /Unknown device cloud/);
+  assert.throws(() => normalizeTargets([{ ...webDevice, credentialId: undefined }]), /connection/);
+  assert.throws(() => normalizeTargets([{ ...webDevice, browserName: undefined }]), /browser .* or an uploaded app/);
+  assert.throws(() => normalizeTargets([{ ...webDevice, provider: "bugmole", credentialId: undefined, deviceArn: "arn:aws:s3:::bucket" }]), /isn't a Device Farm device/);
+  const bugmole = normalizeTargets([{ kind: "device", provider: "bugmole", platform: "android", deviceName: "Pixel 8", appBuildId: "app_1", real: true }])[0];
+  assert.equal(bugmole.cloud?.credentialId, undefined);
+});
+
+test("labels are found safely on the web, Android and iOS", () => {
+  const web = locatorsFor(`Don't "stop"`, "web");
+  assert.ok(web.every((locator) => locator.using === "xpath"));
+  assert.match(web[0].value, /concat\('Don', "'", 't "stop"'\)/);
+  assert.equal(locatorsFor('Say "hi"', "android")[1].value, 'new UiSelector().text("Say \\"hi\\"")');
+  assert.equal(locatorsFor("It's", "ios")[1].value, "label == 'It\\'s' OR name == 'It\\'s' OR value == 'It\\'s'");
+  assert.equal(locatorsFor("Order .*", "android")[0].value, 'new UiSelector().textMatches("Order .*")');
+});
+
+test("a mobile web flow runs on a cloud device and reports each step", async () => {
+  const hub = fakeHub({ "Sign in": { displayed: true }, Email: { displayed: true }, Welcome: { displayed: true } });
+  const finished: Array<Record<string, unknown>> = [];
+  const host: DeviceSessionHost = {
+    async open({ device }) {
+      assert.equal(device.deviceName, "iPhone 15");
+      return {
+        hubUrl: "https://user:key@hub.test/wd/hub",
+        capabilities: { platformName: "iOS", browserName: "Safari" },
+        finish: async (outcome) => {
+          finished.push(outcome);
+          return { links: [{ label: "Session", url: "https://cloud.test/s/1" }] };
+        },
+      };
+    },
+  };
+  const { dir, flowPath } = workspace(`url: https://shop.test\n---\n- launchApp\n- tapOn: "Sign in"\n- tapOn: "Email"\n- inputText: "ada@shop.test"\n- assertVisible: "Welcome"\n`);
+  const [target] = normalizeTargets([webDevice]);
+  const driver = new AppiumDriver({ fetch: hub.doFetch, sleep: async () => undefined, access: { credentials: {}, appBuilds: {}, bugmole: undefined } });
+  // The browserstack host is replaced by our fake through the access map's bugmole slot.
+  const result = await driver.run({
+    runId: "run_1", projectId: "shop", journeyId: "signin", flowPath, platform: "web", target: { baseUrl: "https://shop.test" },
+    timeoutMs: 60_000, artifactsDir: dir, runTarget: { ...target, cloud: { ...target.cloud!, provider: "bugmole" } },
+  }).catch((error) => error);
+  // Without a host for "bugmole" the run is blocked, never crashes.
+  assert.equal(result.status, "blocked");
+  assert.match(result.message, /only available to runs on Bugmole Cloud/);
+
+  const withHost = new AppiumDriver({ fetch: hub.doFetch, sleep: async () => undefined, access: { credentials: {}, appBuilds: {}, bugmole: host } });
+  const passed = await withHost.run({
+    runId: "run_1", projectId: "shop", journeyId: "signin", flowPath, platform: "web", target: { baseUrl: "https://shop.test" },
+    timeoutMs: 60_000, artifactsDir: dir, runTarget: { ...target, cloud: { ...target.cloud!, provider: "bugmole", credentialId: undefined } },
+  });
+  assert.equal(passed.status, "passed", passed.message);
+  assert.deepEqual(passed.steps?.map((step) => step.status), ["passed", "passed", "passed", "passed", "passed"]);
+  assert.deepEqual(hub.typed, ["ada@shop.test"]);
+  const create = hub.calls.find((call) => call.path === "/session")!;
+  assert.deepEqual(create.body.capabilities.alwaysMatch, { platformName: "iOS", browserName: "Safari" });
+  assert.equal(hub.calls.find((call) => call.path === "/session/S1/url")?.body.url, "https://shop.test");
+  assert.ok(hub.calls.some((call) => call.method === "DELETE"));
+  assert.deepEqual(finished, [{ passed: true, webdriverSessionId: "S1", reason: undefined }]);
+  const log = fs.readFileSync(path.join(dir, "shop", "run_1", "artifacts", passed.artifacts.at(-1)!.path.split("/artifacts/")[1]), "utf8");
+  assert.match(log, /Session: https:\/\/cloud\.test\/s\/1/);
+  assert.ok(!log.includes("ada@shop.test"), "typed text stays out of the log");
+});
+
+test("a missing element fails the step, screenshots the device, and tells the cloud", async () => {
+  const hub = fakeHub({ Hidden: { displayed: false } });
+  const outcomes: Array<{ passed: boolean }> = [];
+  const host: DeviceSessionHost = { open: async () => ({ hubUrl: "https://hub.test/wd/hub", capabilities: {}, finish: async (outcome) => { outcomes.push(outcome); return { links: [] }; } }) };
+  const { dir, flowPath } = workspace(`url: https://shop.test\n---\n- launchApp\n- tapOn: "Hidden"\n- assertVisible: "Never"\n`);
+  const [target] = normalizeTargets([{ ...webDevice, provider: "bugmole", credentialId: undefined }]);
+  const driver = new AppiumDriver({ fetch: hub.doFetch, sleep: async () => undefined, defaultTimeoutMs: 0, access: { credentials: {}, appBuilds: {}, bugmole: host } });
+  const result = await driver.run({ runId: "r", projectId: "p", journeyId: "j", flowPath, platform: "web", target: {}, timeoutMs: 1, artifactsDir: dir, runTarget: target });
+  assert.equal(result.status, "failed");
+  assert.equal(result.failureCode, "step_failed");
+  assert.match(result.message, /Couldn't find "Hidden"/);
+  assert.deepEqual(result.steps?.map((step) => step.status), ["passed", "failed"]);
+  assert.ok(result.steps?.[1].screenshotPath?.endsWith("failure.png"));
+  assert.deepEqual(outcomes.map((outcome) => outcome.passed), [false]);
+});
+
+test("a native flow without an app build is blocked before a device is booked", async () => {
+  const { dir, flowPath } = workspace(`appId: com.shop\n---\n- launchApp\n`);
+  const [target] = normalizeTargets([{ kind: "device", provider: "kobiton", credentialId: "c", platform: "android", deviceName: "Pixel 8", appBuildId: "app_missing" }]);
+  let opened = false;
+  const driver = new AppiumDriver({ access: { credentials: {}, appBuilds: {}, bugmole: { open: async () => { opened = true; throw new Error("no"); } } } });
+  const result = await driver.run({ runId: "r", projectId: "p", journeyId: "j", flowPath, platform: "android", target: {}, timeoutMs: 1, artifactsDir: dir, runTarget: target });
+  assert.equal(result.status, "blocked");
+  assert.equal(result.failureCode, "app_missing");
+  assert.equal(opened, false);
+});
+
+test("Device Farm uploads the app, waits for a device, and reports metered minutes", async () => {
+  const calls: string[] = [];
+  let polls = 0;
+  const doFetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const target = new Headers(init?.headers).get("x-amz-target")?.split(".")[1] ?? `PUT ${String(input)}`;
+    calls.push(target);
+    assert.ok(target.startsWith("PUT") || new Headers(init?.headers).get("authorization")?.startsWith("AWS4-HMAC-SHA256"));
+    const body = init?.body && !target.startsWith("PUT") ? JSON.parse(String(init.body)) : {};
+    switch (target) {
+      case "CreateUpload": return Response.json({ upload: { arn: "arn:upload", url: "https://s3.test/put" } });
+      case "GetUpload": return Response.json({ upload: { status: polls++ ? "SUCCEEDED" : "PROCESSING" } });
+      case "CreateRemoteAccessSession":
+        assert.equal(body.appArn, "arn:upload");
+        assert.deepEqual(body.configuration, { parameters: { "appium:version": "3" } });
+        return Response.json({ remoteAccessSession: { arn: "arn:session", status: "PENDING" } });
+      case "GetRemoteAccessSession":
+        return Response.json({ remoteAccessSession: calls.includes("StopRemoteAccessSession")
+          ? { arn: "arn:session", status: "COMPLETED", deviceMinutes: { metered: 4 } }
+          : { arn: "arn:session", status: "RUNNING", endpoints: { remoteDriverEndpoint: "https://appium.devicefarm.test/wd" } } });
+      case "StopRemoteAccessSession": return Response.json({});
+      default: return new Response("", { status: target.startsWith("PUT") ? 200 : 400 });
+    }
+  }) as unknown as typeof fetch;
+  const options = { credentials: { accessKeyId: "AKIA", secretAccessKey: "s" }, projectArn: "arn:aws:devicefarm:us-west-2:1:project:x", fetch: doFetch };
+  const appArn = await uploadApp(options, { name: "shop.apk", platform: "android", bytes: new Uint8Array([1]) }, 0);
+  const session = await startSession(options, { deviceArn: "arn:aws:devicefarm:us-west-2::device:ABC", name: "run", appArn }, 0);
+  assert.equal(session.remoteDriverEndpoint, "https://appium.devicefarm.test/wd");
+  await (await import("../integrations/device-farm.js")).stopSession(options, session.arn);
+  assert.equal((await finishedSession(options, session.arn, 0)).meteredMinutes, 4);
+  assert.deepEqual(calls.slice(0, 5), ["CreateUpload", "PUT https://s3.test/put", "GetUpload", "GetUpload", "CreateRemoteAccessSession"]);
+});

package/src/runtime/appium-driver.ts

@@ -0,0 +1,295 @@
+// Runs Bugmole flows on real devices and emulators in device clouds, over
+// WebDriver (Appium). Mobile web flows run in the device's browser with the
+// same step meanings as the Playwright driver; native app flows find elements
+// by their visible text or accessibility label.
+import fs from "node:fs/promises";
+import path from "node:path";
+import { WebDriverSession, type Locator } from "../integrations/webdriver-client.js";
+import type { AppDriver, DriverArtifact, DriverContext, DriverPlatform, DriverResult, DriverStepResult } from "./driver.js";
+import { hostFor, cloudDeviceLabel, type CloudDevice, type DeviceCloudAccess, type SessionReport } from "./device-clouds/index.js";
+import {
+  describeStepForLog,
+  describeStepLabel,
+  interpolateStep,
+  isPatternText,
+  parseMaestroStyleFlow,
+  resolveFlowUrl,
+  type FlowStep,
+  type ParsedFlow,
+} from "./flow-language.js";
+
+export type AppiumDriverOptions = {
+  access?: DeviceCloudAccess;
+  /** Test seams. */
+  fetch?: typeof fetch;
+  createSession?: typeof WebDriverSession.create;
+  sleep?: (ms: number) => Promise<void>;
+  defaultTimeoutMs?: number;
+};
+
+const DEFAULT_WAIT_MS = 10_000;
+const POLL_MS = 500;
+
+function xpathLiteral(text: string): string {
+  if (!text.includes("'")) return `'${text}'`;
+  if (!text.includes('"')) return `"${text}"`;
+  return `concat(${text.split("'").map((part) => `'${part}'`).join(`, "'", `)})`;
+}
+
+/** Where to look for a person-visible label, most specific first. */
+export function locatorsFor(text: string, mode: "web" | "android" | "ios"): Locator[] {
+  const pattern = isPatternText(text);
+  if (mode === "web") {
+    const literal = xpathLiteral(pattern ? text.replace(/\.\*/g, "") : text);
+    const match = pattern ? `contains(normalize-space(.), ${literal})` : `normalize-space(.)=${literal}`;
+    return [
+      { using: "xpath", value: `//*[self::a or self::button or @role='button' or @role='link' or @role='tab' or @role='menuitem'][${match}]` },
+      { using: "xpath", value: `//label[${match}]/following::*[self::input or self::textarea or self::select][1]` },
+      { using: "xpath", value: `//*[@aria-label=${literal} or @placeholder=${literal} or @title=${literal} or @alt=${literal} or @value=${literal}]` },
+      { using: "xpath", value: `//*[${match}][not(*[${match}])]` },
+    ];
+  }
+  if (mode === "android") {
+    const escaped = text.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+    return pattern
+      ? [{ using: "-android uiautomator", value: `new UiSelector().textMatches("${escaped}")` }, { using: "-android uiautomator", value: `new UiSelector().descriptionMatches("${escaped}")` }]
+      : [
+        { using: "accessibility id", value: text },
+        { using: "-android uiautomator", value: `new UiSelector().text("${escaped}")` },
+        { using: "-android uiautomator", value: `new UiSelector().description("${escaped}")` },
+        { using: "-android uiautomator", value: `new UiSelector().textContains("${escaped}")` },
+      ];
+  }
+  const escaped = text.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+  return pattern
+    ? [{ using: "-ios predicate string", value: `label MATCHES '${escaped}' OR name MATCHES '${escaped}' OR value MATCHES '${escaped}'` }]
+    : [
+      { using: "accessibility id", value: text },
+      { using: "-ios predicate string", value: `label == '${escaped}' OR name == '${escaped}' OR value == '${escaped}'` },
+      { using: "-ios predicate string", value: `label CONTAINS '${escaped}'` },
+    ];
+}
+
+const KEYS: Record<string, string> = { enter: "", tab: "", backspace: "", escape: "", back: "", "arrow down": "", "arrow up": "" };
+
+export class AppiumDriver implements AppDriver {
+  readonly id = "appium";
+
+  constructor(private readonly options: AppiumDriverOptions = {}) {}
+
+  supports(_platform: DriverPlatform): boolean {
+    return true;
+  }
+
+  async run(context: DriverContext): Promise<DriverResult> {
+    const startedAt = Date.now();
+    const device = context.runTarget?.cloud;
+    if (!device) return { status: "blocked", message: "This run target isn't a cloud device", artifacts: [], failureCode: "driver_error" };
+    const content = await fs.readFile(context.flowPath, "utf8");
+    let flow: ParsedFlow;
+    try {
+      flow = parseMaestroStyleFlow(content, context.target.baseUrl, { rebaseOrigin: context.rebaseOrigin });
+    } catch (error) {
+      return { status: "blocked", message: `The flow couldn't be read: ${error instanceof Error ? error.message : error}`, artifacts: [], failureCode: "flow_invalid" };
+    }
+    const mode: "web" | "android" | "ios" = device.browserName ? "web" : device.platform;
+    const app = device.appBuildId ? this.options.access?.appBuilds[device.appBuildId] : undefined;
+    if (mode !== "web" && !app) {
+      return { status: "blocked", message: "Upload an app build for this device, or run the flow in the device's browser", artifacts: [], failureCode: "app_missing" };
+    }
+    const outDir = path.join(context.artifactsDir, context.projectId, context.runId, "artifacts", context.runTarget?.id ?? "device");
+    await fs.mkdir(outDir, { recursive: true });
+    const artifacts: DriverArtifact[] = [];
+    const steps: DriverStepResult[] = [];
+    const log: string[] = [`Device: ${cloudDeviceLabel(device)} on ${device.provider}`];
+    const name = `${context.journeyId} · ${cloudDeviceLabel(device)}`;
+    let session: WebDriverSession | null = null;
+    let report: SessionReport | undefined;
+    let failure: { message: string; code: string } | null = null;
+    let finish: ((outcome: { passed: boolean; webdriverSessionId: string | null; reason?: string }) => Promise<SessionReport>) | undefined;
+    try {
+      const host = hostFor(this.options.access, device, this.options.fetch);
+      const opened = await host.open({ device, name, app });
+      finish = opened.finish;
+      log.push("Waiting for the device…");
+      session = await (this.options.createSession ?? WebDriverSession.create)({
+        hubUrl: opened.hubUrl,
+        capabilities: opened.capabilities,
+        authorization: opened.authorization,
+        fetch: this.options.fetch,
+      });
+      log.push(`Session ${session.id} started`);
+      const flowContext: Record<string, string> = {};
+      const runSteps = async (list: FlowStep[], counter: { n: number }): Promise<void> => {
+        for (const rawStep of list) {
+          const index = counter.n++;
+          const began = Date.now();
+          const step = interpolateStep(rawStep, flowContext);
+          try {
+            if (step.type === "retry") {
+              let lastError: unknown;
+              for (let attempt = 0; attempt <= step.maxRetries; attempt++) {
+                try {
+                  await runSteps(step.steps, { n: counter.n });
+                  lastError = undefined;
+                  break;
+                } catch (error) {
+                  lastError = error;
+                }
+              }
+              counter.n += step.steps.length;
+              if (lastError) throw lastError;
+            } else {
+              await this.step(session!, step, mode, flow, context, outDir, artifacts);
+            }
+            steps.push({ sequenceNumber: index, status: "passed", label: describeStepLabel(step), durationMs: Date.now() - began });
+            log.push(`Step ${index + 1}: ${describeStepForLog(step)} — ok`);
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            steps.push({ sequenceNumber: index, status: "failed", label: describeStepLabel(step), message, durationMs: Date.now() - began });
+            log.push(`Step ${index + 1}: ${describeStepForLog(step)} — ${message}`);
+            throw error;
+          }
+        }
+      };
+      await runSteps(flow.steps, { n: 0 });
+    } catch (error) {
+      failure = { message: error instanceof Error ? error.message : String(error), code: session ? "step_failed" : "device_unavailable" };
+      if (session) {
+        try {
+          const shot = path.join(outDir, "failure.png");
+          await fs.writeFile(shot, await session.screenshot());
+          artifacts.push({ path: shot, contentType: "image/png", name: "failure.png" });
+          steps[steps.length - 1] = { ...steps[steps.length - 1], screenshotPath: shot };
+        } catch {
+          // A device that dropped off can't take a screenshot; the log says why.
+        }
+      }
+    } finally {
+      const sessionId = session?.id ?? null;
+      await session?.delete();
+      if (finish) {
+        report = await finish({ passed: !failure, webdriverSessionId: sessionId, reason: failure?.message }).catch(() => undefined);
+      }
+    }
+    if (report?.videoUrl) {
+      try {
+        const video = await (this.options.fetch ?? fetch)(report.videoUrl);
+        if (video.ok) {
+          const file = path.join(outDir, "device.mp4");
+          await fs.writeFile(file, new Uint8Array(await video.arrayBuffer()));
+          artifacts.push({ path: file, contentType: "video/mp4", name: "device.mp4" });
+        }
+      } catch {
+        log.push("The device recording couldn't be downloaded");
+      }
+    }
+    for (const link of report?.links ?? []) log.push(`${link.label}: ${link.url}`);
+    if (report?.meteredMinutes !== undefined) log.push(`Device minutes: ${report.meteredMinutes}`);
+    const logFile = path.join(outDir, "device.log");
+    await fs.writeFile(logFile, `${log.join("\n")}\n`, "utf8");
+    artifacts.push({ path: logFile, contentType: "text/plain", name: "device.log" });
+    return {
+      status: failure ? (failure.code === "device_unavailable" ? "blocked" : "failed") : "passed",
+      message: failure ? failure.message : `Passed on ${cloudDeviceLabel(device)}`,
+      artifacts,
+      steps,
+      durationMs: Date.now() - startedAt,
+      ...(failure ? { failureCode: failure.code, recoverable: failure.code === "device_unavailable" } : {}),
+    };
+  }
+
+  private async find(session: WebDriverSession, text: string, mode: "web" | "android" | "ios", index = 0, timeoutMs = this.options.defaultTimeoutMs ?? DEFAULT_WAIT_MS): Promise<string | null> {
+    const deadline = Date.now() + timeoutMs;
+    const sleep = this.options.sleep ?? ((ms: number) => new Promise((resolve) => setTimeout(resolve, ms)));
+    for (;;) {
+      for (const locator of locatorsFor(text, mode)) {
+        const found = await session.findElements(locator).catch(() => [] as string[]);
+        const visible: string[] = [];
+        for (const element of found) {
+          if (await session.isDisplayed(element)) visible.push(element);
+          if (visible.length > index) return visible[index];
+        }
+      }
+      if (Date.now() >= deadline) return null;
+      await sleep(POLL_MS);
+    }
+  }
+
+  private async step(session: WebDriverSession, step: FlowStep, mode: "web" | "android" | "ios", flow: ParsedFlow, context: DriverContext, outDir: string, artifacts: DriverArtifact[]): Promise<void> {
+    const sleep = this.options.sleep ?? ((ms: number) => new Promise((resolve) => setTimeout(resolve, ms)));
+    switch (step.type) {
+      case "launchApp":
+        if (mode === "web") await session.navigate(flow.url);
+        return;
+      case "stopApp":
+        return;
+      case "openLink": {
+        const url = resolveFlowUrl(step.url, flow.url, flow.rebasedFrom, flow.rebasedOnto);
+        await session.navigate(url);
+        return;
+      }
+      case "tapOn": {
+        const element = await this.find(session, step.text, mode, step.index);
+        if (!element) {
+          if (step.optional) return;
+          throw new Error(`Couldn't find "${step.text}" on screen`);
+        }
+        await session.click(element);
+        return;
+      }
+      case "inputText": {
+        const focused = await session.activeElement();
+        if (focused) await session.sendKeys(focused, step.text);
+        else await session.keys(step.text);
+        return;
+      }
+      case "eraseText": {
+        const focused = await session.activeElement();
+        if (!focused) throw new Error("Nothing is focused to erase");
+        await session.clear(focused);
+        return;
+      }
+      case "pressKey":
+        await session.keys(KEYS[step.key.toLowerCase()] ?? step.key);
+        return;
+      case "assertVisible":
+      case "assertClickable": {
+        const element = await this.find(session, step.text, mode, step.type === "assertClickable" ? step.index : 0, step.timeoutMs);
+        if (!element) throw new Error(`Expected "${step.text}" to be visible`);
+        return;
+      }
+      case "assertNotVisible": {
+        const deadline = Date.now() + (step.timeoutMs ?? DEFAULT_WAIT_MS);
+        for (;;) {
+          if (!(await this.find(session, step.text, mode, 0, 0))) return;
+          if (Date.now() >= deadline) throw new Error(`Expected "${step.text}" to disappear`);
+          await sleep(POLL_MS);
+        }
+      }
+      case "scrollUntilVisible": {
+        for (let attempt = 0; attempt < 10; attempt++) {
+          if (await this.find(session, step.text, mode, 0, 0)) return;
+          if (mode === "web") await session.execute("window.scrollBy(0, Math.round(window.innerHeight * 0.8))");
+          else await session.execute("mobile: swipe", [{ direction: "up" }]).catch(() => session.execute("mobile: scroll", [{ direction: "down" }]));
+        }
+        throw new Error(`Scrolled but never found "${step.text}"`);
+      }
+      case "wait":
+        await sleep(step.ms);
+        return;
+      case "takeScreenshot": {
+        const file = path.join(outDir, `${step.name.replace(/[^a-zA-Z0-9_-]+/g, "-")}.png`);
+        await fs.writeFile(file, await session.screenshot());
+        artifacts.push({ path: file, contentType: "image/png", name: path.basename(file) });
+        return;
+      }
+      case "requestTempEmail":
+      case "openEmailLink":
+        throw new Error(`"${step.type}" isn't available on device clouds yet; run this flow in a desktop or emulated browser`);
+      default:
+        void context;
+        throw new Error(`Unsupported step`);
+    }
+  }
+}

package/src/runtime/blocker-resolution.test.ts

@@ -0,0 +1,113 @@
+import { strict as assert } from "node:assert";
+import fs from "node:fs";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import { describe, it } from "node:test";
+import {
+  blockerFingerprint,
+  readBlockerResolution,
+  writeBlockerResolution,
+} from "./blocker-resolution.js";
+
+function config(root: string, projectId = "lumis") {
+  return {
+    runtime: { artifacts_dir: root, spec_dir: path.join(root, "spec") },
+    project: { id: projectId, environment_id: "android-local" },
+  };
+}
+
+describe("blocker resolution memory", () => {
+  it("stores and reuses a project/environment-scoped clarification", async () => {
+    const root = fs.mkdtempSync(path.join(tmpdir(), "bugmole-blocker-"));
+    const cfg = config(root);
+    const input = {
+      category: "journey-access",
+      reason: "Runtime access is blocked for /account.",
+      route: "/account",
+      nodeId: "account",
+      environmentId: "android-local",
+    };
+    const resolution = await writeBlockerResolution(cfg, {
+      ...input,
+      question: "Which account should be used?",
+      resolution: "Use the authenticated owner account already configured on the device.",
+    });
+    assert.equal(resolution.fingerprint, blockerFingerprint(input));
+    assert.equal((await readBlockerResolution(cfg, input))?.resolution, resolution.resolution);
+    assert.equal(
+      await readBlockerResolution(config(root, "other-project"), input),
+      null,
+    );
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it("does not reuse expired guidance", async () => {
+    const root = fs.mkdtempSync(path.join(tmpdir(), "bugmole-blocker-expired-"));
+    const cfg = config(root);
+    const input = {
+      category: "device",
+      reason: "Device is unavailable.",
+      environmentId: "android-local",
+    };
+    await writeBlockerResolution(cfg, {
+      ...input,
+      question: "Which device should be started?",
+      resolution: "Start the configured Nokia device.",
+      expiresAt: new Date(Date.now() - 1000).toISOString(),
+    });
+    assert.equal(await readBlockerResolution(cfg, input), null);
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it("returns a clarification request and accepts the user's resolution", async () => {
+    const root = fs.mkdtempSync(path.join(tmpdir(), "bugmole-blocker-flow-"));
+    const cfg = config(root);
+    fs.mkdirSync(path.join(root, "spec"), { recursive: true });
+    fs.writeFileSync(
+      path.join(root, "spec", "journeys.graph.json"),
+      JSON.stringify({
+        version: 2,
+        projectId: "lumis",
+        journeys: [{
+          id: "account-flow",
+          name: "Account flow",
+          actor: "user",
+          nodeIds: ["account"],
+          edgeIds: [],
+          revision: 1,
+          status: "draft",
+        }],
+        nodes: [{
+          id: "account",
+          title: "Account",
+          kind: "screen",
+          route: "/account",
+          runtimeProbe: { status: "blocked" },
+        }],
+        edges: [],
+      }),
+    );
+    const { callTool } = await import("../mcp/server.js");
+    const blocked = await callTool({
+      name: "bugmole_journey_next",
+      arguments: { journeyId: "account-flow" },
+    }, cfg);
+    assert.equal(blocked.status, "blocked");
+    assert.equal(blocked.clarification.status, "needed");
+    const resolved = await callTool({
+      name: "bugmole_resolve_blocker",
+      arguments: {
+        journeyId: "account-flow",
+        category: "journey-access",
+        reason: blocked.reason,
+        route: "/account",
+        nodeId: "account",
+        question: blocked.clarification.question,
+        resolution: "Use the authenticated owner session on the configured device.",
+      },
+    }, cfg);
+    assert.equal(resolved.status, "success");
+    assert.equal(resolved.nextTask.status, "exhausted");
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+});