@bugmole/cli 0.4.0 → 0.6.0

package/src/runtime/planner.ts

@@ -5,6 +5,7 @@ import { createProjectObjectStore } from "../storage/create-object-store.js";
 import { projectPrefix } from "../storage/keys.js";
 import { ControlPlaneClient } from "../registry/control-plane-client.js";
 import { nextJourneyTask } from "./journey-editor.js";
+import { projectActorProblem, projectRoles, rolesClient } from "./project-roles.js";
 
 /** Drivers that can actually operate each kind of target. */
 const DRIVERS_BY_PLATFORM: Record<string, string[]> = {
@@ -36,6 +37,8 @@ interface PlanOptions {
   journeyId: string;
   actor: string;
   revision?: number;
+  /** Where the registry's role decisions come from; null skips the registry. Defaults to this machine's API key. */
+  rolesClient?: Pick<ControlPlaneClient, "listRoles"> | null;
 }
 
 interface PlanResult {
@@ -82,17 +85,10 @@ export async function plan(cfg: any, options: PlanOptions): Promise<PlanResult>
         nextSteps: ["Select an existing journey or record the selected journey before planning."],
       };
     }
-    if (selectedJourney.stability !== "stable" || selectedJourney.linkedToGraph !== true) {
-      return {
-        status: "error",
-        error: `Journey "${journeyId}" is not stabilized. Execute and adjust the canonical flow until it is stable before planning.`,
-        nextSteps: [
-          `Run the canonical flow "${journeyId}"`,
-          "Adjust the flow for any failures and rerun it",
-          "Mark the verified run as the stabilized canonical flow",
-        ],
-      };
-    }
+    // A draft journey can be planned: running its plan is how it becomes
+    // stable (bugmole_journey_stabilize takes that run's ID). Requiring
+    // "stable" first left no way to make the run that proves it.
+    const isStable = selectedJourney.stability === "stable" && selectedJourney.linkedToGraph === true;
     const flowState = nextJourneyTask(cfg, journeyId);
     if (flowState.status === "actionable") {
       return {
@@ -123,17 +119,18 @@ export async function plan(cfg: any, options: PlanOptions): Promise<PlanResult>
         nextSteps: ["Create roles.yaml from the guided testing workflow, then retry planning."],
       };
     }
-    const roles = YAML.parse(fs.readFileSync(rolesPath, "utf-8"));
-    const knownActors = Array.isArray(roles?.roles)
-      ? roles.roles.map((role: any) => role?.name).filter((name: unknown): name is string => typeof name === "string")
-      : [];
-    if (!knownActors.includes(actor)) {
+    // Only a role a person confirmed may be planned for: Bugmole suggests
+    // roles, people decide them (src/registry/roles.ts, docs/public/roles.md).
+    const roles = await projectRoles(cfg, options.rolesClient === undefined ? rolesClient(cfg) : options.rolesClient);
+    const actorIssue = projectActorProblem(roles, actor);
+    if (actorIssue) {
       return {
         status: "error",
-        error: `Actor "${actor}" is not defined in roles.yaml.`,
+        error: actorIssue,
         nextSteps: [
-          `Read roles.yaml and choose one of: ${knownActors.join(", ") || "(none defined)"}`,
-          "Retry planning with a defined actor",
+          `Plan with a confirmed role: ${roles.usable.join(", ") || "(none confirmed yet)"}`,
+          ...(roles.suggested.length ? [`Ask a person to confirm or reject the suggested roles on the dashboard's Roles page: ${roles.suggested.join(", ")}`] : []),
+          "If the journey really needs a new role, suggest it with bugmole_role_propose and wait for a person to confirm it",
         ],
       };
     }
@@ -169,6 +166,25 @@ export async function plan(cfg: any, options: PlanOptions): Promise<PlanResult>
     const steps = graphSteps;
     const planId = journeyId.replace(/[^a-z0-9._-]/gi, "_").toLowerCase();
     const planPath = path.join(plansDir, `${planId}.flow.yaml`);
+    const platform = cfg.project?.platform || "web";
+    // Without a flow a plan has nothing to run. On the web, write one from
+    // the journey itself: open its first screen, then follow each recorded
+    // transition, checking every screen it reaches.
+    const configuredFlow: string | undefined = cfg.execution?.maestro?.flow || undefined;
+    let generatedFlow: string | null = null;
+    if (!configuredFlow && platform === "web") {
+      const reference = `flows/journeys/${planId}.yaml`;
+      if (fs.existsSync(path.join(specDir, reference))) {
+        generatedFlow = reference;
+      } else {
+        const content = journeyFlow(selectedJourney, discoveredNodes, discoveredEdges);
+        if (content) {
+          generatedFlow = reference;
+          fs.mkdirSync(path.join(specDir, "flows", "journeys"), { recursive: true });
+          fs.writeFileSync(path.join(specDir, reference), content, "utf-8");
+        }
+      }
+    }
 
     const plan = {
       version: 2,
@@ -176,14 +192,14 @@ export async function plan(cfg: any, options: PlanOptions): Promise<PlanResult>
       name: `Journey: ${journeyId}`,
       description: `Generated plan for journey ${journeyId} with actor ${actor}`,
       driver: driverForPlatform(cfg.execution?.driver, cfg.project?.platform || "web"),
-      platform: cfg.project?.platform || "web",
+      platform,
       target: {
         base_url: cfg.project?.base_url || cfg.execution?.playwright?.base_url,
         app_id: cfg.project?.app_id,
         device_id: cfg.project?.device_id,
         serial: cfg.project?.serial,
       },
-      flow: cfg.execution?.maestro?.flow || null,
+      flow: configuredFlow || generatedFlow,
       recovery: {
         enabled: cfg.execution?.recovery?.enabled === true,
         max_attempts: cfg.execution?.recovery?.max_attempts ?? 1,
@@ -200,7 +216,7 @@ export async function plan(cfg: any, options: PlanOptions): Promise<PlanResult>
               actor: actor,
               goal: `Complete journey: ${journeyId}`,
               capabilities_required: [],
-              preconditions: ["Test tenant / sandbox is active", "Actor account exists"],
+              preconditions: [`Signed in as ${actor}, or signed out if that's who the journey is for`],
               steps,
             },
           ],
@@ -263,7 +279,13 @@ export async function plan(cfg: any, options: PlanOptions): Promise<PlanResult>
       status: "success",
       planId: planId,
       planPath: `plans/${planId}.flow.yaml`,
-      message: `Plan created at ${planPath}. Review and customize as needed.${apiKey && registryUrl ? " Published to the dashboard." : ""}`,
+      ...(plan.flow ? { flow: plan.flow } : {}),
+      message: `Plan created at ${planPath}${generatedFlow ? `, with its flow at ${path.join(specDir, generatedFlow)}` : ""}.`
+        + (plan.flow ? "" : " It has no flow to run yet: set execution.maestro.flow, or record the journey's screens with their routes and plan again.")
+        + (apiKey && registryUrl ? " Published to the dashboard." : ""),
+      nextSteps: isStable
+        ? [`Run it: bugmole_run with planId ${planId}`]
+        : [`Run it: bugmole_run with planId ${planId}`, `When that run passes, call bugmole_journey_stabilize with journeyId ${journeyId} and the run's ID`],
     };
   } catch (error: any) {
     return {
@@ -272,3 +294,46 @@ export async function plan(cfg: any, options: PlanOptions): Promise<PlanResult>
     };
   }
 }
+
+/**
+ * A web flow that walks a journey: open the first screen, then follow each
+ * transition in order, tapping its label when it has one and opening the
+ * next screen's route otherwise. Null when there is nothing to open.
+ */
+export function journeyFlow(
+  journey: { id: string; name?: string; startNodeId?: string; nodeIds?: string[]; edgeIds?: string[] },
+  nodes: Array<{ id: string; route?: string; title?: string }>,
+  edges: Array<{ id: string; from: string; to: string; label?: string }>,
+): string | null {
+  const byId = new Map(nodes.map((node) => [node.id, node]));
+  const opens = (route?: string) => typeof route === "string" && route.startsWith("/") && !/[:\[*]/.test(route);
+  const quote = (text: string) => JSON.stringify(text);
+  const startId = journey.startNodeId || journey.nodeIds?.[0];
+  const start = startId ? byId.get(startId) : undefined;
+  const steps: string[] = ["- launchApp"];
+  if (start && opens(start.route) && start.route !== "/") steps.push(`- openLink: ${quote(start.route!)}`);
+  else if (!start || !opens(start.route)) {
+    const first = (journey.nodeIds ?? []).map((id) => byId.get(id)).find((node) => opens(node?.route));
+    if (!first) return null;
+    if (first.route !== "/") steps.push(`- openLink: ${quote(first.route!)}`);
+  }
+  steps.push("- assertLayout");
+  const journeyEdges = (journey.edgeIds ?? []).map((id) => edges.find((edge) => edge.id === id)).filter((edge): edge is NonNullable<typeof edge> => Boolean(edge));
+  for (const edge of journeyEdges) {
+    const target = byId.get(edge.to);
+    const label = typeof edge.label === "string" ? edge.label.trim() : "";
+    if (label && label.length <= 80 && !/^(navigate|dom|link)[:-]/i.test(label)) steps.push(`- tapOn: ${quote(label)}`);
+    else if (opens(target?.route)) steps.push(`- openLink: ${quote(target!.route!)}`);
+    else continue;
+    steps.push("- assertLayout");
+  }
+  return [
+    `# Written by bugmole_plan from journey ${journey.id}. Edit it freely:`,
+    "# the plan runs this file, and planning again won't overwrite your changes",
+    "# unless you delete it.",
+    `name: ${quote(journey.name || journey.id)}`,
+    "---",
+    ...steps,
+    "",
+  ].join("\n");
+}

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

@@ -91,3 +91,167 @@ test("a worker without Playwright's ffmpeg loses the video, not the run", () =>
   assert.equal(isMissingVideoEncoder(new Error("Executable doesn't exist at /ms-playwright/chromium-1234/chrome-linux/chrome")), false);
   assert.equal(isMissingVideoEncoder(new Error("net::ERR_CONNECTION_REFUSED")), false);
 });
+
+// ── Page checks: assertLayout and assertLinks ──
+
+import http from "node:http";
+import type { AddressInfo } from "node:net";
+import { chromium } from "playwright";
+import { brokenStatus, checkLayout, checkLinks, hideFocusedFieldText } from "./playwright-driver.js";
+
+async function browserOrSkip(t: { skip: (m: string) => void }) {
+  try {
+    return await chromium.launch();
+  } catch {
+    t.skip("Chromium is not installed");
+    return null;
+  }
+}
+
+const CARD = (height: string) => `<!doctype html><meta name="viewport" content="width=device-width">
+<style>body{margin:0;font:16px/1.5 sans-serif}.card{display:flex;gap:30px;${height};padding:0 18px;background:#fff;box-shadow:0 1px 3px #0002;margin:12px}</style>
+<div class="card"><span>icon</span><div><b>UI changes break tests</b><p>Locators and selectors become stale after every redesign of the product.</p></div></div>`;
+
+test("assertLayout catches text running out of a fixed-height card on a phone, and passes when it grows", async (t) => {
+  const browser = await browserOrSkip(t);
+  if (!browser) return;
+  try {
+    const page = await browser.newPage({ viewport: { width: 360, height: 800 } });
+    await page.setContent(CARD("height:60px"));
+    const problems = await checkLayout(page);
+    assert.equal(problems.length, 1);
+    assert.match(problems[0]!, /^Text runs out of its box: “icon UI changes break tests.*” \(div\.card\)/);
+    await page.setContent(CARD("min-height:60px"));
+    assert.deepEqual(await checkLayout(page), []);
+  } finally {
+    await browser.close();
+  }
+});
+
+test("assertLayout catches a page that scrolls sideways and text cut off without an ellipsis", async (t) => {
+  const browser = await browserOrSkip(t);
+  if (!browser) return;
+  try {
+    const page = await browser.newPage({ viewport: { width: 360, height: 800 } });
+    await page.setContent(`<!doctype html><body style="margin:0"><p style="width:600px">A paragraph wider than the phone</p>
+      <div style="width:120px;height:20px;overflow:hidden">A label much too long for its little box here</div>
+      <div style="width:120px;overflow:hidden;white-space:nowrap;text-overflow:ellipsis">An ellipsis is a deliberate cut</div>
+      <div style="overflow-x:auto"><div style="width:900px">A carousel scrolls on purpose</div></div></body>`);
+    const problems = await checkLayout(page);
+    assert.equal(problems.length, 2, problems.join("\n"));
+    assert.match(problems[0]!, /^The page scrolls sideways: it is 600px wide on a 360px screen, because of “A paragraph wider than the phone” \(p\)/);
+    assert.match(problems[1]!, /^Text is cut off: “A label much too long/);
+  } finally {
+    await browser.close();
+  }
+});
+
+test("assertLinks reports links that don't answer, and doesn't count robots being turned away elsewhere", async (t) => {
+  assert.equal(brokenStatus(404, true), true);
+  assert.equal(brokenStatus(403, true), true);
+  assert.equal(brokenStatus(403, false), false);
+  assert.equal(brokenStatus(429, false), false);
+  assert.equal(brokenStatus(410, false), true);
+  assert.equal(brokenStatus(503, false), false);
+  assert.equal(brokenStatus(504, false), false);
+  assert.equal(brokenStatus(500, false), true);
+  assert.equal(brokenStatus(503, true), true);
+  const browser = await browserOrSkip(t);
+  if (!browser) return;
+  const unsafeHits: string[] = [];
+  const server = http.createServer((req, res) => {
+    if (req.url === "/") {
+      res.setHeader("content-type", "text/html");
+      res.end(`<a href="/ok">ok</a><a href="/gone">gone</a><a href="/ok#part">same page</a><a href="mailto:a@b.c">mail</a>
+        <a href="/api/auth/logout">Sign out</a><a href="/items/9?action=delete">x</a>`);
+    } else if (req.url === "/api/auth/logout" || req.url?.includes("delete")) { unsafeHits.push(req.url); res.end("bye"); }
+    else if (req.url === "/ok") res.end("fine");
+    else { res.statusCode = 404; res.end("no"); }
+  });
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  try {
+    const page = await browser.newPage();
+    await page.goto(`http://127.0.0.1:${(server.address() as AddressInfo).port}/`);
+    const broken = await checkLinks(page, false);
+    assert.deepEqual(broken.map((b) => b.replace(/^http:\/\/127\.0\.0\.1:\d+/, "")), ["/gone (404)"]);
+    assert.deepEqual(unsafeHits, [], "a link check must never sign out or delete");
+  } finally {
+    await browser.close();
+    server.close();
+  }
+});
+
+test("flows can ask for the page checks by name", () => {
+  const flow = parseMaestroStyleFlow("url: https://example.com\n---\n- launchApp\n- assertLayout\n- assertLinks\n- assertLinks:\n    external: true\n");
+  assert.deepEqual(flow.steps.slice(1), [{ type: "assertLayout" }, { type: "assertLinks", external: false }, { type: "assertLinks", external: true }]);
+});
+
+test("assertLayout also checks with a phone's larger text, and restores the page afterwards", async (t) => {
+  const browser = await browserOrSkip(t);
+  if (!browser) return;
+  try {
+    const page = await browser.newPage({ viewport: { width: 412, height: 800 } });
+    // Fits at normal size with a little room; not once text is 30% larger.
+    await page.setContent(`<!doctype html><body style="margin:0;font:16px/20px sans-serif">
+      <div style="height:48px;background:#eee;margin:8px"><b>Important flows get missed</b><br>Journeys are not tested.</div></body>`);
+    const problems = await checkLayout(page);
+    assert.equal(problems.length, 1, problems.join("\n"));
+    assert.match(problems[0]!, /^Text runs out of its box: .* with text 130% \(a phone's larger font setting\)$/);
+    assert.equal(await page.evaluate(`getComputedStyle(document.querySelector("b")).fontSize`), "16px");
+    assert.deepEqual(await checkLayout(page, 1), []);
+  } finally {
+    await browser.close();
+  }
+});
+
+test("a page too tall for one screenshot still gets evidence, and its flow isn't failed for it", async () => {
+  const { screenshotWholePage } = await import("./playwright-driver.js");
+  const shots: Array<boolean | undefined> = [];
+  const page = {
+    screenshot: async (options: { fullPage?: boolean }) => {
+      shots.push(options.fullPage);
+      if (options.fullPage) throw new Error("page.screenshot: Cannot take screenshot larger than 32767 pixels on any dimension");
+    },
+  };
+  const log: string[] = [];
+  await screenshotWholePage(page as never, "/tmp/x.png", log);
+  assert.deepEqual(shots, [true, false]);
+  assert.match(log[0]!, /too tall for one screenshot/);
+  const broken = { screenshot: async () => { throw new Error("Target closed"); } };
+  await assert.rejects(screenshotWholePage(broken as never, "/tmp/x.png"), /Target closed/);
+});
+
+test("assertClickable scrolls to a button below the fold, but still fails one that is covered", async (t) => {
+  const browser = await browserOrSkip(t);
+  if (!browser) return;
+  try {
+    const { waitForClickable } = await import("./playwright-driver.js");
+    const page = await browser.newPage({ viewport: { width: 393, height: 659 } });
+    await page.setContent(`<!doctype html><body style="margin:0">
+      <div style="height:1200px">Tall content</div>
+      <button id="below">Explore this URL</button>
+      <div style="position:relative;height:60px"><button id="covered">Covered</button>
+        <div style="position:absolute;inset:0;background:#fff"></div></div></body>`);
+    await waitForClickable(page, page.locator("#below"), "Explore this URL", 2_000);
+    await assert.rejects(waitForClickable(page, page.locator("#covered"), "Covered", 1_000), /something else is on top/);
+  } finally {
+    await browser.close();
+  }
+});
+
+
+test("a secret typed into a plain text field is invisible on screen but keeps its value", async (t) => {
+  const browser = await browserOrSkip(t);
+  if (!browser) return;
+  try {
+    const page = await browser.newPage();
+    await page.setContent(`<input id="token" type="text" style="color:#111">`);
+    await page.focus("#token");
+    await hideFocusedFieldText(page);
+    await page.keyboard.type("s3cr3t-value");
+    assert.equal(await page.inputValue("#token"), "s3cr3t-value");
+    assert.equal(await page.evaluate(`getComputedStyle(document.getElementById("token")).color`), "rgba(0, 0, 0, 0)");
+  } finally {
+    await browser.close();
+  }
+});