@qawolf/cli 1.18.0 → 1.19.1

package/dist/cli.js

@@ -325822,6 +325822,7 @@ var authMessages = {
     },
     request: {
       rejected401: (noun) => `QA Wolf API rejected the${noun ? ` ${noun}` : ""} request (HTTP 401). Check your API key.`,
+      rejected402: (noun) => `QA Wolf API refused the${noun ? ` ${noun}` : ""} request (HTTP 402): billing prevented it.`,
       rejected403: (noun) => `QA Wolf API rejected the${noun ? ` ${noun}` : ""} request (HTTP 403). Check that your API key has access to this environment.`,
       notFound404: (noun) => `QA Wolf API could not find ${noun ? `${noun} for that environment` : "that environment"} (HTTP 404). Check the --env value.`,
       failedWithStatus: (status, noun) => `QA Wolf API${noun ? ` ${noun}` : ""} request failed (HTTP ${status}).`,
@@ -326107,6 +326108,8 @@ var interactMessages = {
   inspectNeedsABrowserRunner: "This runner is a mobile device, and element and page HTML are a browser's shapes. Retrying will never help. Launch a playwright runner to inspect one.",
   nothingToInspect: (errorMessage2) => `The runner had nothing to inspect${errorMessage2 === undefined ? "" : `: ${errorMessage2}`}. There is no live page, nothing matched the selector, or no variable has that name; a runner cannot tell those apart. Run a flow on it first, or check the selector or name.`,
   inspectAnsweredUnknown: (failureReason) => `The runner answered "${failureReason}", which this version of the CLI does not know how to report. Upgrade with npm install -g @qawolf/cli.`,
+  inspectMobileAnsweredUnknown: (failureReason) => `The runner answered "${failureReason}", which this version of the CLI does not know how to report. Upgrade with npm install -g @qawolf/cli.`,
+  runnerIsNotMobile: "This runner is not a mobile device, so there is nothing here to inspect. Retrying will never help: launch an android or ios runner instead.",
   screenNeedsARun: "This runner has not run anything yet, so its screen has never started. Waiting will not clear this and there is nothing to retry: run a flow on it with qawolf runner run, then ask again. Evaluating a snippet does not start a screen.",
   screenNotReady: "The runner has a screen and cannot serve this yet. Its virtual desktop restarts when a run changes the display size, and it serves one request at a time, so something already in flight is the usual reason. Retry in a second or two.",
   screenshotNotAnImage: "The screen was captured but did not arrive as a JPEG, so nothing was written. Nothing about the command needs changing: try it again, and report it if it keeps happening.",
@@ -326143,6 +326146,7 @@ var lifecycleMessages = {
   alreadyRunning: (id) => `Runner ${id} was already running.`,
   defaultNotRemembered: (id) => `Runner ${id} could not be written to .qawolf as this directory's default, so later commands will not find it on their own. Pass --runner ${id}, or set QAWOLF_RUNNER_ID=${id}.`,
   defaultNotForgotten: (id) => `Runner ${id} was terminated, but it could not be removed from .qawolf as this directory's default, so later commands will still be sent to it. Pass --runner, or launch a new runner.`,
+  envRunnerIdShadowsLaunch: (launchedId, envId) => `QAWOLF_RUNNER_ID=${envId} is still set, so commands that omit --runner will keep targeting it instead of the runner just launched. Pass --runner ${launchedId}, or export QAWOLF_RUNNER_ID=${launchedId}.`,
   keptAlive: (id) => `Runner ${id} is alive, and its inactivity clock has been reset.`,
   launchFailed: (id, error) => `Launching runner ${id} failed. ${error}`,
   launchLost: (id, error) => `Launching runner ${id} failed. ${error}. The request may still have reached QA Wolf and started a runner, so relaunch the same id with qawolf runner launch --id ${id} to attach to it rather than start a second one, or terminate it with qawolf runner terminate --runner ${id}.`,
@@ -326379,7 +326383,8 @@ var exitCodes = {
   auth: 3,
   network: 4,
   config: 5,
-  timeout: 6
+  timeout: 6,
+  payment: 7
 };
 function exit(code, message, proc = process) {
   if (message !== undefined && message.length > 0) {
@@ -341063,6 +341068,12 @@ function describeRequestError(err, baseUrl, noun) {
         exitCode: exitCodes.auth,
         ...body
       };
+    if (err.status === 402)
+      return {
+        error: m.request.rejected402(noun),
+        exitCode: exitCodes.payment,
+        ...body
+      };
     if (err.status === 403)
       return { error: m.request.rejected403(noun), ...body };
     if (err.status === 404)
@@ -342551,7 +342562,6 @@ var makeInspectMobileOnRunnerContract = () => {
     output
   };
 };
-
 // node_modules/@qawolf/api-contracts/dist/v1/runner/journal.js
 var journalEntrySchema = exports_external.object({
   payload: exports_external.unknown(),
@@ -346126,7 +346136,7 @@ function startUpdateCheck(deps) {
 // package.json
 var package_default = {
   name: "@qawolf/cli",
-  version: "1.18.0",
+  version: "1.19.1",
   description: "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   keywords: [
     "automation",
@@ -356706,7 +356716,7 @@ async function launchRunner(ctx, options) {
   if (!result.ok) {
     return {
       ...failureFields(result),
-      exitCode: exitCodes.network,
+      exitCode: result.exitCode ?? exitCodes.network,
       mayHaveArrived: result.mayHaveArrived ?? false,
       ok: false
     };
@@ -357346,7 +357356,10 @@ async function handleRunnerImportPackage(ctx, options, deps) {
     packageVersion
   }, runnerCallOptions);
   if (!result.ok) {
-    return { ...failureFields(result), exitCode: exitCodes.network };
+    return {
+      ...failureFields(result),
+      exitCode: result.exitCode ?? exitCodes.network
+    };
   }
   if (result.value.outcome === "failure") {
     const failure = result.value;
@@ -357446,14 +357459,190 @@ async function handleRunnerInspect(ctx, options, deps) {
   return;
 }
 
+// src/core/interactiveRunner/inspectMobileRequest.ts
+function toNumber(value) {
+  return value.trim() === "" ? Number.NaN : Number(value);
+}
+function buildInspectMobileRequest(what, flags) {
+  if (flags.by === "point" && (flags.text !== undefined || flags.partial !== undefined)) {
+    return {
+      error: "--by point matches by pixel, so --text/--partial would be ignored rather than searching by text. Pass --by text instead, or drop --text/--partial.",
+      ok: false
+    };
+  }
+  if (flags.by === "text" && (flags.x !== undefined || flags.y !== undefined)) {
+    return {
+      error: "--by text matches by text, so --x/--y would be ignored rather than matching a point. Pass --by point instead, or drop --x/--y.",
+      ok: false
+    };
+  }
+  const candidate = {
+    what,
+    ...flags.by === undefined ? {} : { by: flags.by },
+    ...flags.context === undefined ? {} : { context: flags.context },
+    ...flags.partial === undefined ? {} : { partial: flags.partial },
+    ...flags.text === undefined ? {} : { text: flags.text },
+    ...flags.x === undefined ? {} : { x: toNumber(flags.x) },
+    ...flags.y === undefined ? {} : { y: toNumber(flags.y) }
+  };
+  const parsed = inspectMobileRequestSchema.safeParse(candidate);
+  if (!parsed.success) {
+    return { error: exports_external.prettifyError(parsed.error), ok: false };
+  }
+  return { ok: true, request: parsed.data };
+}
+
+// src/domains/interactiveRunner/inspectMobile.ts
+function describeSession(session) {
+  switch (session.type) {
+    case "ready":
+      return session.deviceName === undefined ? `Session ready: ${session.platformName} (${session.sessionId}).` : `Session ready: ${session.platformName} on ${session.deviceName} (${session.sessionId}).`;
+    case "unreachable":
+      return `Session unreachable: ${session.error}`;
+    case "ambiguous":
+      return `${String(session.sessionCount)} Appium sessions are live; expected one.`;
+    case "no-session":
+      return "No Appium session is live.";
+  }
+}
+function streamLine(value) {
+  switch (value.what) {
+    case "contexts":
+      return JSON.stringify({
+        contexts: value.contexts,
+        current: value.current
+      });
+    case "page":
+      return JSON.stringify({
+        context: value.context,
+        orientation: value.orientation,
+        pageSource: value.pageSource
+      });
+    case "elements":
+      return JSON.stringify({ matches: value.matches });
+  }
+}
+async function handleRunnerInspectMobile(ctx, options, deps) {
+  const built = buildInspectMobileRequest(options.what, options.flags);
+  if (!built.ok)
+    return { error: built.error, exitCode: exitCodes.invalidArgs };
+  const resolved = await resolveRunner(ctx, {
+    autoLaunch: false,
+    noRunnerIdMessage: interactiveRunnerMessages.noRunnerIdForInspect,
+    runner: options.runner
+  }, deps);
+  if (resolved.type === "failed") {
+    return { ...failureFields(resolved), exitCode: resolved.exitCode };
+  }
+  const result = await ctx.platformClient.callPublicApi(publicContractsV1.runner.inspectMobile, { id: resolved.runnerId, request: built.request }, runnerCallOptions);
+  if (!result.ok) {
+    return { ...failureFields(result), exitCode: exitCodes.network };
+  }
+  if (result.value.outcome === "success") {
+    const value = result.value;
+    if (value.what === "session") {
+      ctx.ui.output(value, describeSession(value.session));
+    } else {
+      ctx.ui.stream(value, streamLine(value));
+    }
+    return;
+  }
+  const { failureReason } = result.value;
+  switch (failureReason) {
+    case "runner-is-not-mobile":
+      return {
+        error: interactiveRunnerMessages.runnerIsNotMobile,
+        exitCode: exitCodes.invalidArgs
+      };
+    case "screen-needs-a-run":
+      return {
+        error: interactiveRunnerMessages.screenNeedsARun,
+        exitCode: exitCodes.invalidArgs
+      };
+    case "screen-not-ready":
+      return {
+        error: interactiveRunnerMessages.screenNotReady,
+        exitCode: exitCodes.network
+      };
+    case "runner-unreachable":
+      return {
+        error: interactiveRunnerMessages.runnerUnreachable,
+        exitCode: exitCodes.network
+      };
+    default: {
+      return {
+        error: interactiveRunnerMessages.inspectMobileAnsweredUnknown(failureReason),
+        exitCode: exitCodes.network
+      };
+    }
+  }
+}
+
+// src/commands/runner/inspectMobile.register.ts
+function registerRunnerInspectMobileCommands(inspect, signals) {
+  declareCommandKind(inspect.command("session"), "read").description("Print the Appium session's status: ready, or why not").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerInspectMobile(ctx, {
+    flags: {
+      by: undefined,
+      context: undefined,
+      partial: undefined,
+      text: undefined,
+      x: undefined,
+      y: undefined
+    },
+    runner: opts.runner,
+    what: "session"
+  }, runnerDeps(ctx)))(opts, command));
+  declareCommandKind(inspect.command("contexts"), "read").description("List the WebView contexts available, and which is current").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerInspectMobile(ctx, {
+    flags: {
+      by: undefined,
+      context: undefined,
+      partial: undefined,
+      text: undefined,
+      x: undefined,
+      y: undefined
+    },
+    runner: opts.runner,
+    what: "contexts"
+  }, runnerDeps(ctx)))(opts, command));
+  declareCommandKind(inspect.command("page-source"), "read").description("Print the current context's page source, as a tree").option("--context <name>", "Read this context instead of the current one").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerInspectMobile(ctx, {
+    flags: {
+      by: undefined,
+      context: opts.context,
+      partial: undefined,
+      text: undefined,
+      x: undefined,
+      y: undefined
+    },
+    runner: opts.runner,
+    what: "page"
+  }, runnerDeps(ctx)))(opts, command));
+  declareCommandKind(inspect.command("elements"), "read").description("Find elements at a screen point, or elements carrying some text").requiredOption("--by <by>", "point or text").option("--context <name>", "Read this context instead of the current one").option("--partial", "text: match text containing this, rather than exactly this").option("--runner <id>", runnerFlagDescription).option("--text <text>", "text: the text to match").option("--x <pixels>", "point: whole pixels on the device's own screen").option("--y <pixels>", "point: whole pixels on the device's own screen").action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerInspectMobile(ctx, {
+    flags: {
+      by: opts.by,
+      context: opts.context,
+      partial: opts.partial,
+      text: opts.text,
+      x: opts.x,
+      y: opts.y
+    },
+    runner: opts.runner,
+    what: "elements"
+  }, runnerDeps(ctx)))(opts, command));
+}
+
 // src/commands/runner/inspect.register.ts
 var inspectExamples = `
 Examples:
   $ qawolf runner inspect element-html --selector "#email"
   $ qawolf runner inspect page-html > page.html
-  $ qawolf runner inspect variable --name cart | jq .total`;
+  $ qawolf runner inspect variable --name cart | jq .total
+  $ qawolf runner inspect session
+  $ qawolf runner inspect contexts
+  $ qawolf runner inspect page-source --context WEBVIEW_1
+  $ qawolf runner inspect elements --by point --x 200 --y 400
+  $ qawolf runner inspect elements --by text --text "Sign in" --partial`;
 function registerRunnerInspectCommands(runner, signals) {
-  const inspect = runner.command("inspect").description("Read one thing off a runner's live page").addHelpText("after", inspectExamples);
+  const inspect = runner.command("inspect").description("Read one thing off a runner's live page (browser) or Appium session (mobile)").addHelpText("after", inspectExamples);
   declareCommandKind(inspect.command("element-html"), "read").description("Print the HTML of the first element a selector matches").requiredOption("--selector <selector>", "Playwright selector to inspect").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerInspect(ctx, {
     flags: { name: undefined, selector: opts.selector },
     runner: opts.runner,
@@ -357469,6 +357658,7 @@ function registerRunnerInspectCommands(runner, signals) {
     runner: opts.runner,
     what: "variable"
   }, runnerDeps(ctx)))(opts, command));
+  registerRunnerInspectMobileCommands(inspect, signals);
 }
 
 // src/core/interactiveRunner/runFiles.ts
@@ -357580,7 +357770,10 @@ async function handleRunnerExec(ctx, options, deps) {
     ...scope.files === undefined ? {} : { files: scope.files }
   }, runnerCallOptions);
   if (!result.ok) {
-    return { ...failureFields(result), exitCode: exitCodes.network };
+    return {
+      ...failureFields(result),
+      exitCode: result.exitCode ?? exitCodes.network
+    };
   }
   if (result.value.outcome === "failure") {
     result.value.failureReason;
@@ -357606,46 +357799,6 @@ async function handleRunnerExec(ctx, options, deps) {
   }
 }
 
-// src/core/interactiveRunner/browserAction.ts
-function parseJsonPath(path9) {
-  try {
-    return { ok: true, value: JSON.parse(path9) };
-  } catch {
-    return {
-      error: `--path must be a JSON array of points, for example '[{"x":10,"y":20},{"x":80,"y":90}]'.`,
-      ok: false
-    };
-  }
-}
-function toNumber(value) {
-  return value.trim() === "" ? Number.NaN : Number(value);
-}
-function buildBrowserAction(type, flags) {
-  const parsedPath = flags.path === undefined ? undefined : parseJsonPath(flags.path);
-  if (parsedPath !== undefined && !parsedPath.ok)
-    return parsedPath;
-  const candidate = {
-    type,
-    ...flags.button === undefined ? {} : { button: flags.button },
-    ...flags.keys === undefined ? {} : { keys: flags.keys },
-    ...parsedPath === undefined ? {} : { path: parsedPath.value },
-    ...flags.scrollX === undefined ? {} : { scroll_x: toNumber(flags.scrollX) },
-    ...flags.scrollY === undefined ? {} : { scroll_y: toNumber(flags.scrollY) },
-    ...flags.text === undefined ? {} : { text: flags.text },
-    ...flags.url === undefined ? {} : { url: flags.url },
-    ...flags.x === undefined ? {} : { x: toNumber(flags.x) },
-    ...flags.y === undefined ? {} : { y: toNumber(flags.y) }
-  };
-  return parseBrowserAction(candidate);
-}
-function parseBrowserAction(candidate) {
-  const parsed = browserActionSchema.safeParse(candidate);
-  if (!parsed.success) {
-    return { error: exports_external.prettifyError(parsed.error), ok: false };
-  }
-  return { action: parsed.data, ok: true };
-}
-
 // src/domains/interactiveRunner/performActionFailure.ts
 function describePerformActionFailure(options) {
   const { actionType, failure } = options;
@@ -357690,7 +357843,47 @@ function describePerformActionFailure(options) {
   }
 }
 
-// src/domains/interactiveRunner/performAction.ts
+// src/core/interactiveRunner/browserAction.ts
+function parseJsonPath(path9) {
+  try {
+    return { ok: true, value: JSON.parse(path9) };
+  } catch {
+    return {
+      error: `--path must be a JSON array of points, for example '[{"x":10,"y":20},{"x":80,"y":90}]'.`,
+      ok: false
+    };
+  }
+}
+function toNumber2(value) {
+  return value.trim() === "" ? Number.NaN : Number(value);
+}
+function buildBrowserAction(type, flags) {
+  const parsedPath = flags.path === undefined ? undefined : parseJsonPath(flags.path);
+  if (parsedPath !== undefined && !parsedPath.ok)
+    return parsedPath;
+  const candidate = {
+    type,
+    ...flags.button === undefined ? {} : { button: flags.button },
+    ...flags.keys === undefined ? {} : { keys: flags.keys },
+    ...parsedPath === undefined ? {} : { path: parsedPath.value },
+    ...flags.scrollX === undefined ? {} : { scroll_x: toNumber2(flags.scrollX) },
+    ...flags.scrollY === undefined ? {} : { scroll_y: toNumber2(flags.scrollY) },
+    ...flags.text === undefined ? {} : { text: flags.text },
+    ...flags.url === undefined ? {} : { url: flags.url },
+    ...flags.x === undefined ? {} : { x: toNumber2(flags.x) },
+    ...flags.y === undefined ? {} : { y: toNumber2(flags.y) }
+  };
+  return parseBrowserAction(candidate);
+}
+function parseBrowserAction(candidate) {
+  const parsed = browserActionSchema.safeParse(candidate);
+  if (!parsed.success) {
+    return { error: exports_external.prettifyError(parsed.error), ok: false };
+  }
+  return { action: parsed.data, ok: true };
+}
+
+// src/domains/interactiveRunner/readAction.ts
 var stdinArgument2 = "-";
 async function readAction(type, flags, deps) {
   if (type !== stdinArgument2)
@@ -357708,6 +357901,8 @@ async function readAction(type, flags, deps) {
     return { error: interactiveRunnerMessages.actionNotJson, ok: false };
   }
 }
+
+// src/domains/interactiveRunner/performAction.ts
 async function handleRunnerAct(ctx, options, deps) {
   const built = await readAction(options.type, options.flags, deps);
   if (!built.ok)
@@ -357821,7 +358016,7 @@ Examples:
   $ qawolf runner exec snippet.ts --file flows/checkout.flow.ts`;
 function registerRunnerInteractCommands(runner, signals) {
   declareCommandKind(runner.command("screenshot"), "read").description("Save a JPEG of an interactive runner's screen to a file").option("--out <path>", "File to write the image to", defaultScreenshotPath).option("--runner <id>", runnerFlagDescription).addHelpText("after", screenshotExamples).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerScreenshot(ctx, { out: opts.out, runner: opts.runner }, runnerDeps(ctx)))(opts, command));
-  declareCommandKind(runner.command("act <action>"), "write").description("Perform one raw action on a runner's screen: click, double_click, scroll, move, drag, keypress, navigate or type. Use - to read a whole action as JSON from stdin").option("--button <button>", "click: left, right, wheel, back or forward").option("--keys <keys...>", "keypress: modifiers and the key, e.g. Control a").option("--path <json>", "drag: JSON array of points to drag through").option("--runner <id>", runnerFlagDescription).option("--scroll-x <delta>", "scroll: horizontal wheel delta").option("--scroll-y <delta>", "scroll: vertical wheel delta").option("--text <text>", "type: the text to type").option("--url <url>", "navigate: the http or https URL to go to").option("--x <pixels>", "pointer x, in screenshot pixels").option("--y <pixels>", "pointer y, in screenshot pixels").addHelpText("after", actExamples).action((action2, opts, command) => withAuthContext(signals, (ctx) => handleRunnerAct(ctx, {
+  declareCommandKind(runner.command("act <action>"), "write").description("Perform one raw action on a runner's screen: click, double_click, scroll, move, drag, keypress, navigate or type. Use - to read a whole action as JSON from stdin. On a mobile runner only click (button left), drag and type have a touchscreen equivalent; the rest answer action-not-supported-on-mobile").option("--button <button>", "click: left, right, wheel, back or forward (mobile: left only)").option("--keys <keys...>", "keypress: modifiers and the key, e.g. Control a").option("--path <json>", "drag: JSON array of points to drag through (mobile: only the first and last are used)").option("--runner <id>", runnerFlagDescription).option("--scroll-x <delta>", "scroll: horizontal wheel delta").option("--scroll-y <delta>", "scroll: vertical wheel delta").option("--text <text>", "type: the text to type").option("--url <url>", "navigate: the http or https URL to go to").option("--x <pixels>", "pointer x, in screenshot pixels").option("--y <pixels>", "pointer y, in screenshot pixels").addHelpText("after", actExamples).action((action2, opts, command) => withAuthContext(signals, (ctx) => handleRunnerAct(ctx, {
     flags: {
       button: opts.button,
       keys: opts.keys,
@@ -357902,6 +358097,10 @@ async function handleRunnerLaunch(ctx, options, deps) {
   if (!launched.ok) {
     return { ...failureFields(launched), exitCode: launched.exitCode };
   }
+  const envRunnerId = deps.env[runnerIdEnvironmentVariable]?.trim();
+  if (envRunnerId && envRunnerId !== launched.value.id) {
+    ctx.ui.warn(interactiveRunnerMessages.envRunnerIdShadowsLaunch(launched.value.id, envRunnerId));
+  }
   ctx.ui.output(launched.value, launched.value.alreadyRunning ? interactiveRunnerMessages.alreadyRunning(launched.value.id) : interactiveRunnerMessages.launched(launched.value.id));
   return;
 }
@@ -358616,7 +358815,10 @@ async function sendRunFlowRequest(ctx, options, delta) {
   }, runnerCallOptions);
   if (!result.ok) {
     return {
-      failure: { ...failureFields(result), exitCode: exitCodes.network },
+      failure: {
+        ...failureFields(result),
+        exitCode: result.exitCode ?? exitCodes.network
+      },
       type: "failed"
     };
   }
@@ -358828,4 +359030,4 @@ createProgram({ signals }).parseAsync().catch(() => {
     process.exitCode = 1;
 }).finally(() => flushAndExit(typeof process.exitCode === "number" ? process.exitCode : 0));
 
-//# debugId=B6D9FB052BE12D6D64756E2164756E21
+//# debugId=F98A1DC596D4CF4664756E2164756E21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qawolf/cli",
-  "version": "1.18.0",
+  "version": "1.19.1",
   "description": "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   "keywords": [
     "automation",

package/skills/qawolf-cli/SKILL.md

@@ -155,13 +155,17 @@ that `url`; never guess a route and never send a repository link in its place.
 | `qawolf run find` | read | List an environment's recent runs, newest first. |
 | `qawolf run get` | read | Get a run's status, per-flow results, and links. |
 | `qawolf run reattempt` | write | Request new attempts for a run's flows, in the same run. A flow is eligible once its result is failed or canceled and QA Wolf's automatic retries have finished. A fully investigated run no longer accepts reattempts. Attempts run with the latest flow code. Poll run.get for results. |
-| `qawolf runner act` | write | Perform one raw action on a runner's screen: click, double_click, scroll, move, drag, keypress, navigate or type. Use - to read a whole action as JSON from stdin |
+| `qawolf runner act` | write | Perform one raw action on a runner's screen: click, double_click, scroll, move, drag, keypress, navigate or type. Use - to read a whole action as JSON from stdin. On a mobile runner only click (button left), drag and type have a touchscreen equivalent; the rest answer action-not-supported-on-mobile |
 | `qawolf runner events` | read | Print a runner's journal, one entry per line. QA Wolf writes console, recorder, run-events, run-logs, run-status |
 | `qawolf runner exec` | write | Evaluate a snippet against a runner's live page. Use - to read the snippet from stdin |
 | `qawolf runner highlight-selector` | write | Highlight what a selector matches on a runner's live page, so the next screenshot shows it. Omit the selector to clear the highlight |
 | `qawolf runner import-package` | write | Install a package into a runner's live run, so a snippet or a selection can import it |
+| `qawolf runner inspect contexts` | read | List the WebView contexts available, and which is current |
 | `qawolf runner inspect element-html` | read | Print the HTML of the first element a selector matches |
+| `qawolf runner inspect elements` | read | Find elements at a screen point, or elements carrying some text |
 | `qawolf runner inspect page-html` | read | Print the page's HTML, simplified for a model to read |
+| `qawolf runner inspect page-source` | read | Print the current context's page source, as a tree |
+| `qawolf runner inspect session` | read | Print the Appium session's status: ready, or why not |
 | `qawolf runner inspect variable` | read | Print a top-level variable's value from the running workflow |
 | `qawolf runner keepalive` | read | Reset a runner's inactivity clock, for a caller that pauses between actions |
 | `qawolf runner launch` | write | Launch an interactive runner and make it this directory's default |

package/skills/qawolf-cli/references/runner.md

@@ -41,6 +41,15 @@ No `read` command ever launches a runner. `screenshot`, `events` and `keepalive`
 tell you there is no runner rather than quietly billing one, and so does
 `terminate`, since starting a pod in order to end it would be absurd.
 
+`--name` also chooses between a browser and a mobile device:
+`qawolf runner launch --name android` or `--name ios` starts an Appium session
+instead of a browser. A command built for the other kind answers a
+`failureReason` naming the mismatch rather than doing something approximate —
+`runner-is-not-mobile` from `inspect session`/`contexts`/`page-source`/`elements`
+on a browser runner, `runner-is-not-a-browser` from `inspect element-html`/
+`page-html` on a mobile one — so launch the right family up front rather than
+discovering it from a refusal mid-session.
+
 ## Knowing what you are holding
 
 `qawolf runner list` names the runners this directory has launched that are
@@ -138,6 +147,14 @@ taken effect. On a `4` from `act`, take a screenshot before repeating a click.
 looks the same from outside, so treat a `4` from a snippet that changes something
 as "may have run" rather than "did not run".
 
+A mobile runner has a touchscreen, not a mouse, so only three of the eight
+actions have a touchscreen equivalent and go through: `click` with
+`button: "left"` taps, `drag` swipes, and `type` types into whatever the last
+tap focused. The rest — `double_click`, `scroll`, `move`, `keypress`,
+`navigate` — answer `action-not-supported-on-mobile` rather than doing
+something approximate. `navigate` is the one to watch for, since it works on a
+browser runner without a run first but has no meaning on mobile at all.
+
 ## The recorder: what you cannot get from pixels
 
 `qawolf runner events recorder` is the capability that has no equivalent in a
@@ -185,6 +202,52 @@ Use `inspect` before reaching for `exec`. Reading a value through a snippet
 means printing it and then fishing it back out of the `console` stream, which is
 two calls and a marker; `inspect variable` is one call and the value.
 
+## Reading a mobile screen: `inspect session`/`contexts`/`page-source`/`elements`
+
+`element-html`, `page-html` and `variable` are a browser's shapes. A mobile
+runner answers four different ones instead, one subcommand per question:
+
+```sh
+qawolf runner inspect session
+qawolf runner inspect contexts
+qawolf runner inspect page-source
+qawolf runner inspect page-source --context WEBVIEW_1     # a specific context, not the current one
+qawolf runner inspect elements --by point --x 240 --y 480
+qawolf runner inspect elements --by text --text "Sign in" --partial
+```
+
+`session` prints one summary line — ready, or why not — because that line is
+the whole answer. `contexts`, `page-source` and `elements` instead print their
+answer as JSON on stdout, on its own like `inspect element-html`, so you can
+redirect or pipe it (`| jq .current`, `| jq .matches`, `| jq .pageSource`)
+rather than getting a count with no way to see what was actually found.
+
+`session` is also the one subcommand that never answers `screen-needs-a-run`:
+readiness is the question it exists to answer, so it reports one of `ready`
+(with the platform, device and session id), `unreachable`, `ambiguous` (more
+than one session is somehow live) or `no-session`, rather than refusing until a
+run has happened. The other three need a live session first and share the same
+readiness contract `act` and `screenshot` use on a browser runner:
+`screen-needs-a-run` exits `2` and means no Appium session has started on this
+runner yet — run a flow that opens one, then inspect again; `screen-not-ready`
+exits `4` and means the session exists but did not answer this instant, or more
+than one is somehow live — retry once, and relaunch the runner if it persists.
+
+`elements` takes one of two ways to search, chosen with `--by`: `point` needs
+whole-pixel `--x`/`--y` on the device's own screen, the same coordinates a
+screenshot is measured in; `text` needs `--text` and matches it exactly unless
+`--partial` is passed. The two do not mix — `--by point` with `--text` set, or
+`--by text` with `--x`/`--y` set, is refused before a runner is addressed
+rather than silently searching by the one it picked, since the schema itself
+just strips whichever field the chosen `by` does not define. `--context` on
+`page-source` or `elements` reads a context other than the current one —
+useful once `contexts` has told you which are available.
+
+A browser runner answers `runner-is-not-mobile` to all four, exit `2`, since
+retrying never helps: launch with `--name android` or `--name ios` instead.
+`runner-unreachable` exits `4` and is worth retrying, same as everywhere else
+on this surface.
+
 ## Checking a selector: `highlight-selector`
 
 `inspect element-html` tells you what a selector matched. `highlight-selector`